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 sequences ;
   4 IN: sorting.human
   5
   6 HELP: find-numbers
   7 { $values
   8      { "sequence" sequence }
   9      { "sequence'" sequence }
  10 }
  11 { $description "Splits a string on numbers and returns a sequence of sequences and integers." } ;
  12
  13 HELP: human<=>
  14 { $values
  15      { "obj1" object } { "obj2" object }
  16      { "<=>" "an ordering specifier" }
  17 }
  18 { $description "Compares two objects after converting numbers in the string into integers." } ;
  19
  20 HELP: human>=<
  21 { $values
  22      { "obj1" object } { "obj2" object }
  23      { ">=<" "an ordering specifier" }
  24 }
  25 { $description "Compares two objects using the " { $link human<=> } " word and inverts the result." } ;
  26
  27 ARTICLE: "sorting.human" "Human-friendly sorting"
  28 "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
  29 "Comparing two objects:"
  30 { $subsections
  31     human<=>
  32     human>=<
  33 }
  34 "Splitting a string into substrings and integers:"
  35 { $subsections find-numbers } ;
  36
  37 ABOUT: "sorting.human"