basis/unicode/collation/collation-docs.factor

   1 USING: byte-arrays help.syntax help.markup kernel math.order
   2 strings ;
   3 IN: unicode.collation
   4
   5 ARTICLE: "unicode.collation" "Collation and weak comparison"
   6 "The " { $vocab-link "unicode.collation" } " vocabulary implements the Unicode Collation Algorithm. The Unicode Collation Algorithm (UTS #10) forms a reasonable way to sort strings when accounting for all of the characters in Unicode. It is far preferred over code point order when sorting for human consumption, in user interfaces. At the moment, only the default Unicode collation element table (DUCET) is used, but a more accurate collation would take locale into account. The following words are useful for collation directly:"
   7 { $subsections
   8     sort-strings
   9     collation-key
  10     string<=>
  11 }
  12 "Predicates for weak equality testing:"
  13 { $subsections
  14     primary=
  15     secondary=
  16     tertiary=
  17     quaternary=
  18 } ;
  19
  20 ABOUT: "unicode.collation"
  21
  22 HELP: sort-strings
  23 { $values { "strings" "a sequence of strings" } { "sorted" "the strings in lexicographical order" } }
  24 { $description "This word takes a sequence of strings and sorts them according to the Unicode Collation Algorithm with the default collation order described in the DUCET. It uses code point order as a tie-breaker." } ;
  25
  26 HELP: collation-key
  27 { $values { "string" string } { "key" byte-array } }
  28 { $description "This takes a string and gives a representation of the collation key, which can be compared with " { $link <=> } ". The representation is according to the DUCET." } ;
  29
  30 HELP: string<=>
  31 { $values { "str1" string } { "str2" string } { "<=>" "one of +lt+, +gt+ or +eq+" } }
  32 { $description "This word takes two strings and compares them using the UCA with the DUCET, using code point order as a tie-breaker." } ;
  33
  34 HELP: primary=
  35 { $values { "str1" string } { "str2" string } { "?" boolean } }
  36 { $description "This checks whether the first level of collation key is identical. This is the least specific kind of equality test. In Latin script, it can be understood as ignoring case, punctuation, whitespace and accent marks." } ;
  37
  38 HELP: secondary=
  39 { $values { "str1" string } { "str2" string } { "?" boolean } }
  40 { $description "This checks whether the first two levels of collation key are equal. For Latin script, this means accent marks are significant again, and it is otherwise similar to " { $link primary= } "." } ;
  41
  42 HELP: tertiary=
  43 { $values { "str1" string } { "str2" string } { "?" boolean } }
  44 { $description "This checks if the first three levels of collation key are equal. For Latin-based scripts, it can be understood as testing for what " { $link secondary= } " tests for, but case is significant." } ;
  45
  46 HELP: quaternary=
  47 { $values { "str1" string } { "str2" string } { "?" boolean } }
  48 { $description "This checks if the first four levels of collation key are equal. This is similar to " { $link tertiary= } " but it makes punctuation significant again, while still leaving out things like null bytes and Hebrew vowel marks, which mean absolutely nothing in collation." } ;