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