basis/sorting/specification/specification-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel quotations math.order
   4 sequences ;
   5 IN: sorting.specification
   6
   7 HELP: compare-with-spec
   8 { $values
   9   { "obj1" object }
  10   { "obj2" object }
  11   { "sort-spec" "a sequence of sequences of accessors and a comparator" }
  12   { "<=>" { $link +lt+ } ", " { $link +eq+ } " or " { $link +gt+ } }
  13 }
  14 { $description "Compares two objects using a chain of intrinsic linear orders such that if two objects are " { $link +eq+ } ", then the next ordering is tried." } ;
  15
  16 HELP: sort-with-spec
  17 { $values
  18     { "seq" sequence } { "sort-spec" "a sequence of sequences of accessors and a comparator" }
  19     { "seq'" sequence }
  20 }
  21 { $description "Sorts a sequence of objects by the sorting specification in " { $snippet "sort-spec" } ". A sorting specification is a sequence of sequences, each consisting of accessors and a comparator." }
  22 { $examples
  23     "Sort by slot a, then b descending:"
  24     { $example
  25         "USING: accessors math.order prettyprint sorting.specification ;"
  26         "IN: scratchpad"
  27         "TUPLE: sort-me a b ;"
  28         "{"
  29         "    T{ sort-me f 2 3 } T{ sort-me f 3 2 }"
  30         "    T{ sort-me f 4 3 } T{ sort-me f 2 1 }"
  31         "}"
  32         "{ { a>> <=> } { b>> >=< } } sort-with-spec ."
  33         "{\n    T{ sort-me { a 2 } { b 3 } }\n    T{ sort-me { a 2 } { b 1 } }\n    T{ sort-me { a 3 } { b 2 } }\n    T{ sort-me { a 4 } { b 3 } }\n}"
  34     }
  35 } ;
  36
  37 ARTICLE: "sorting.specification" "Sorting by multiple keys"
  38 "The " { $vocab-link "sorting.specification" } " vocabulary can sort objects by multiple keys in ascending or descending order, using subsequent keys as tie-breakers." $nl
  39 "Comparing two objects with a sorting specification:"
  40 { $subsections compare-with-spec }
  41 "Sorting a sequence of objects with a sorting specification:"
  42 { $subsections
  43     sort-with-spec
  44     sort-keys-with-spec
  45     sort-values-with-spec
  46 } ;
  47
  48 ABOUT: "sorting.specification"