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" object } { "y" object } { "z" object } }
  48 { $description "Outputs the greatest of two ordered values." }
  49 { $notes "If one value is a floating point positive zero and the other is a negative zero, the result is undefined." } ;
  50
  51 HELP: min
  52 { $values { "x" object } { "y" object } { "z" object } }
  53 { $description "Outputs the smallest of two ordered values." }
  54 { $notes "If one value is a floating point positive zero and the other is a negative zero, the result is undefined." } ;
  55
  56 HELP: clamp
  57 { $values { "x" object } { "min" object } { "max" object } { "y" object } }
  58 { $description "Outputs " { $snippet "x" } " if contained in the interval " { $snippet "[min,max]" } " or outputs one of the endpoints." } ;
  59
  60 HELP: between?
  61 { $values { "x" object } { "y" object } { "z" real } { "?" "a boolean" } }
  62 { $description "Tests if " { $snippet "x" } " is in the interval " { $snippet "[y,z]" } "." }
  63 { $notes "As per the closed interval notation, the end-points are included in the interval." } ;
  64
  65 HELP: before?
  66 { $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
  67 { $description "Tests if " { $snippet "obj1" } " comes before " { $snippet "obj2" } " using an intrinsic total order." }
  68 { $notes "Implemented using " { $link <=> } "." } ;
  69
  70 HELP: after?
  71 { $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
  72 { $description "Tests if " { $snippet "obj1" } " comes after " { $snippet "obj2" } " using an intrinsic total order." }
  73 { $notes "Implemented using " { $link <=> } "." } ;
  74
  75 HELP: before=?
  76 { $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
  77 { $description "Tests if " { $snippet "obj1" } " comes before or equals " { $snippet "obj2" } " using an intrinsic total order." }
  78 { $notes "Implemented using " { $link <=> } "." } ;
  79
  80 HELP: after=?
  81 { $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
  82 { $description "Tests if " { $snippet "obj1" } " comes after or equals " { $snippet "obj2" } " using an intrinsic total order." }
  83 { $notes "Implemented using " { $link <=> } "." } ;
  84
  85 { before? after? before=? after=? } related-words
  86
  87 HELP: [-]
  88 { $values { "x" real } { "y" real } { "z" real } }
  89 { $description "Subtracts " { $snippet "y" } " from " { $snippet "x" } ". If the result is less than zero, outputs zero." } ;
  90
  91 ARTICLE: "order-specifiers" "Ordering specifiers"
  92 "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:"
  93 { $subsection +lt+ }
  94 { $subsection +eq+ }
  95 { $subsection +gt+ } ;
  96
  97 ARTICLE: "math.order.example" "Linear order example"
  98 "A tuple class which defines an ordering among instances by comparing the values of the " { $snippet "id" } " slot:"
  99 { $code
 100   "TUPLE: sprite id name bitmap ;"
 101   "M: sprite <=> [ id>> ] compare ;"
 102 } ;
 103
 104 ARTICLE: "math.order" "Linear order protocol"
 105 "Some classes define an intrinsic order amongst instances. This includes numbers, sequences (in particular, strings), and words."
 106 { $subsection <=> }
 107 { $subsection >=< }
 108 { $subsection compare }
 109 { $subsection invert-comparison }
 110 "The above words output order specifiers."
 111 { $subsection "order-specifiers" }
 112 "Utilities for comparing objects:"
 113 { $subsection after? }
 114 { $subsection before? }
 115 { $subsection after=? }
 116 { $subsection before=? }
 117 "Minimum, maximum, clamping:"
 118 { $subsection min }
 119 { $subsection max }
 120 { $subsection clamp }
 121 "Out of the above generic words, it suffices to implement " { $link <=> } " alone. The others may be provided as an optimization."
 122 { $subsection "math.order.example" }
 123 { $see-also "sequences-sorting" } ;
 124
 125 ABOUT: "math.order"