core/math/order/order-docs.factor

   1 USING: help.markup help.syntax kernel math quotations
   2 math.private words ;
   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: +lt+
  19 { $description "Output by " { $link <=> } " when the first object is strictly less than the second object." } ;
  20
  21 HELP: +eq+
  22 { $description "Output by " { $link <=> } " when the first object is equal to the second object." } ;
  23
  24 HELP: +gt+
  25 { $description "Output by " { $link <=> } " when the first object is strictly greater than the second object." } ;
  26
  27 HELP: invert-comparison
  28 { $values { "<=>" symbol }
  29           { "<=>'" symbol } }
  30 { $description "Invert the comparison symbol returned by " { $link <=> } "." }
  31 { $examples
  32     { $example "USING: math.order prettyprint ;" "+lt+ invert-comparison ." "+gt+" } } ;
  33
  34 HELP: compare
  35 { $values { "obj1" object } { "obj2" object } { "quot" { $quotation "( obj -- newobj )" } } { "<=>" "an ordering specifier" } }
  36 { $description "Compares the results of applying the quotation to both objects via " { $link <=> } "." }
  37 { $examples { $example "USING: kernel math.order prettyprint sequences ;" "\"hello\" \"hi\" [ length ] compare ." "+gt+" }
  38 } ;
  39
  40 HELP: max
  41 { $values { "x" real } { "y" real } { "z" real } }
  42 { $description "Outputs the greatest of two real numbers." } ;
  43
  44 HELP: min
  45 { $values { "x" real } { "y" real } { "z" real } }
  46 { $description "Outputs the smallest of two real numbers." } ;
  47
  48 HELP: between?
  49 { $values { "x" real } { "y" real } { "z" real } { "?" "a boolean" } }
  50 { $description "Tests if " { $snippet "x" } " is in the interval " { $snippet "[y,z]" } "." }
  51 { $notes "As per the closed interval notation, the end-points are included in the interval." } ;
  52
  53 HELP: before?
  54 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  55 { $description "Tests if " { $snippet "obj1" } " comes before " { $snippet "obj2" } " using an intrinsic total order." }
  56 { $notes "Implemented using " { $link <=> } "." } ;
  57
  58 HELP: after?
  59 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  60 { $description "Tests if " { $snippet "obj1" } " comes after " { $snippet "obj2" } " using an intrinsic total order." }
  61 { $notes "Implemented using " { $link <=> } "." } ;
  62
  63 HELP: before=?
  64 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  65 { $description "Tests if " { $snippet "obj1" } " comes before or equals " { $snippet "obj2" } " using an intrinsic total order." }
  66 { $notes "Implemented using " { $link <=> } "." } ;
  67
  68 HELP: after=?
  69 { $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
  70 { $description "Tests if " { $snippet "obj1" } " comes after or equals " { $snippet "obj2" } " using an intrinsic total order." }
  71 { $notes "Implemented using " { $link <=> } "." } ;
  72
  73 { before? after? before=? after=? } related-words
  74
  75 HELP: [-]
  76 { $values { "x" real } { "y" real } { "z" real } }
  77 { $description "Subtracts " { $snippet "y" } " from " { $snippet "x" } ". If the result is less than zero, outputs zero." } ;
  78
  79 ARTICLE: "order-specifiers" "Ordering specifiers"
  80 "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:"
  81 { $subsection +lt+ }
  82 { $subsection +eq+ }
  83 { $subsection +gt+ } ;
  84
  85 ARTICLE: "math.order" "Linear order protocol"
  86 "Some classes have an intrinsic order amongst instances:"
  87 { $subsection <=> }
  88 { $subsection compare }
  89 { $subsection invert-comparison }
  90 "The above words output order specifiers."
  91 { $subsection "order-specifiers" }
  92 "Utilities for comparing objects:"
  93 { $subsection after? }
  94 { $subsection before? }
  95 { $subsection after=? }
  96 { $subsection before=? }
  97 { $see-also "sequences-sorting" } ;
  98
  99 ABOUT: "math.order"