basis/sorting/human/human-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel math.order quotations
   4 sequences strings ;
   5 IN: sorting.human
   6
   7 HELP: find-numbers
   8 { $values
   9      { "string" string }
  10      { "seq" sequence }
  11 }
  12 { $description "Splits a string on numbers and returns a sequence of sequences and integers." } ;
  13
  14 HELP: human<=>
  15 { $values
  16      { "obj1" object } { "obj2" object }
  17      { "<=>" "an ordering specifier" }
  18 }
  19 { $description "Compares two objects after converting numbers in the string into integers." } ;
  20
  21 HELP: human>=<
  22 { $values
  23      { "obj1" object } { "obj2" object }
  24      { ">=<" "an ordering specifier" }
  25 }
  26 { $description "Compares two objects using the " { $link human<=> } " word and inverts the result." } ;
  27
  28 HELP: human-compare
  29 { $values
  30      { "obj1" object } { "obj2" object } { "quot" quotation }
  31      { "<=>" "an ordering specifier" }
  32 }
  33 { $description "Compares the results of applying the quotation to both objects via <=>." } ;
  34
  35 HELP: human-sort
  36 { $values
  37      { "seq" sequence }
  38      { "seq'" sequence }
  39 }
  40 { $description "Sorts a sequence of objects by comparing the magnitude of any integers in the input string using the <=> word." } ;
  41
  42 HELP: human-sort-keys
  43 { $values
  44      { "seq" "an alist" }
  45      { "sortedseq" "a new sorted sequence" }
  46 }
  47 { $description "Sorts the elements comparing first elements of pairs using the " { $link human<=> } " word." } ;
  48
  49 HELP: human-sort-values
  50 { $values
  51      { "seq" "an alist" }
  52      { "sortedseq" "a new sorted sequence" }
  53 }
  54 { $description "Sorts the elements comparing second elements of pairs using the " { $link human<=> } " word." } ;
  55
  56 { <=> >=< human-compare human-sort human-sort-keys human-sort-values } related-words
  57
  58 ARTICLE: "sorting.human" "sorting.human"
  59 "The " { $vocab-link "sorting.human" } " vocabulary sorts by numbers as a human would -- by comparing their magnitudes -- rather than in a lexicographic way. For example, sorting a1, a10, a03, a2 with human sort returns a1, a2, a03, a10, while sorting with natural sort returns a03, a1, a10, a2." $nl
  60 "Comparing two objects:"
  61 { $subsection human<=> }
  62 { $subsection human>=< }
  63 { $subsection human-compare }
  64 "Sort a sequence:"
  65 { $subsection human-sort }
  66 { $subsection human-sort-keys }
  67 { $subsection human-sort-values }
  68 "Splitting a string into substrings and integers:"
  69 { $subsection find-numbers } ;
  70
  71 ABOUT: "sorting.human"