core/math/order/order-docs.factor

   1 USING: help.markup help.syntax kernel math quotations
   2 math.private words words.symbol ;
   3 IN: math.order
   4
   5 HELP: <=>
   6 { $values { "obj1" object } { "obj2" object } { "<=>" "an ordering specifier" } }
   7 { $contract
   8     "Compares two objects using an intrinsic linear order, for example, the natural order for real numbers and lexicographic order for strings."
   9     $nl
  10     "The output value is one of the following:"
  11     { $list
  12         { { $link +lt+ } " - indicating that " { $snippet "obj1" } " precedes " { $snippet "obj2" } }
  13         { { $link +eq+ } " - indicating that " { $snippet "obj1" } " is equal to " { $snippet "obj2" } }
  14         { { $link +gt+ } " - indicating that " { $snippet "obj1" } " follows " { $snippet "obj2" } }
  15     }
  16 } ;
  17
  18 HELP: >=<
  19 { $values { "obj1" object } { "obj2" object } { ">=<" "an ordering specifier" } }
  20 { $description "Compares two objects using the " { $link <=> } " comparator and inverts the output." } ;
  21
  22 { <=> >=< } related-words
  23
  24 HELP: +lt+
  25 { $description "Output by " { $link <=> } " when the first object is strictly less than the second object." } ;
  26
  27 HELP: +eq+
  28 { $description "Output by " { $link <=> } " when the first object is equal to the second object." } ;
  29
  30 HELP: +gt+
  31 { $description "Output by " { $link <=> } " when the first object is strictly greater than the second object." } ;
  32
  33 HELP: invert-comparison
  34 { $values { "<=>" symbol }
  35           { "<=>'" symbol } }
  36 { $description "Invert the comparison symbol returned by " { $link <=> } "." }
  37 { $examples
  38     { $example "USING: math.order prettyprint ;" "+lt+ invert-comparison ." "+gt+" } } ;
  39
  40 HELP: compare
  41 { $values { "obj1" object } { "obj2" object } { "quot" { $quotation "( obj -- newobj )" } } { "<=>" "an ordering specifier" } }
  42 { $description "Compares the results of applying the quotation to both objects via " { $link <=> } "." }
  43 { $examples { $example "USING: kernel math.order prettyprint sequences ;" "\"hello\" \"hi\" [ length ] compare ." "+gt+" }
  44 } ;
  45
  46 HELP: max
  47 { $values { "x" real } { "y" real } { "z" real } }
  48 { $description "Outputs the greatest of two real numbers." } ;
  49
  50 HELP: min
  51 { $values { "x" real } { "y" real } { "z" real } }
  52 { $description "Outputs the smallest of two real numbers." } ;
  53
  54 HELP: between?
  55 { $values { "x" real } { "y" real } { "z" real } { "?" "a boolean" } }
  56 { $description "Tests if " { $snippet "x" } " is in the interval " { $snippet "[y,z]" } "." }
  57 { $notes "As per the closed interval notation, the end-points are included in the interval." } ;
  58
  59 HELP: before?
  60 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  61 { $description "Tests if " { $snippet "obj1" } " comes before " { $snippet "obj2" } " using an intrinsic total order." }
  62 { $notes "Implemented using " { $link <=> } "." } ;
  63
  64 HELP: after?
  65 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  66 { $description "Tests if " { $snippet "obj1" } " comes after " { $snippet "obj2" } " using an intrinsic total order." }
  67 { $notes "Implemented using " { $link <=> } "." } ;
  68
  69 HELP: before=?
  70 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  71 { $description "Tests if " { $snippet "obj1" } " comes before or equals " { $snippet "obj2" } " using an intrinsic total order." }
  72 { $notes "Implemented using " { $link <=> } "." } ;
  73
  74 HELP: after=?
  75 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  76 { $description "Tests if " { $snippet "obj1" } " comes after or equals " { $snippet "obj2" } " using an intrinsic total order." }
  77 { $notes "Implemented using " { $link <=> } "." } ;
  78
  79 { before? after? before=? after=? } related-words
  80
  81 HELP: [-]
  82 { $values { "x" real } { "y" real } { "z" real } }
  83 { $description "Subtracts " { $snippet "y" } " from " { $snippet "x" } ". If the result is less than zero, outputs zero." } ;
  84
  85 ARTICLE: "order-specifiers" "Ordering specifiers"
  86 "Ordering words such as " { $link <=> } " output one of the following values, indicating that of two objects being compared, the first is less than the second, the two are equal, or that the first is greater than the second:"
  87 { $subsection +lt+ }
  88 { $subsection +eq+ }
  89 { $subsection +gt+ } ;
  90
  91 ARTICLE: "math.order.example" "Linear order example"
  92 "A tuple class which defines an ordering among instances by comparing the values of the " { $snippet "id" } " slot:"
  93 { $code
  94   "TUPLE: sprite id name bitmap ;"
  95   "M: sprite <=> [ id>> ] compare ;"
  96 } ;
  97
  98 ARTICLE: "math.order" "Linear order protocol"
  99 "Some classes have an intrinsic order amongst instances:"
 100 { $subsection <=> }
 101 { $subsection >=< }
 102 { $subsection compare }
 103 { $subsection invert-comparison }
 104 "The above words output order specifiers."
 105 { $subsection "order-specifiers" }
 106 "Utilities for comparing objects:"
 107 { $subsection after? }
 108 { $subsection before? }
 109 { $subsection after=? }
 110 { $subsection before=? }
 111 "Out of the above generic words, it suffices to implement " { $link <=> } " alone. The others may be provided as an optimization."
 112 { $subsection "math.order.example" }
 113 { $see-also "sequences-sorting" } ;
 114
 115 ABOUT: "math.order"