core/generic/math/math-docs.factor

   1 USING: kernel generic help.markup help.syntax math classes
   2 sequences quotations ;
   3 IN: generic.math
   4
   5 HELP: math-upgrade
   6 { $values { "class1" class } { "class2" class } { "quot" "a quotation with stack effect " { $snippet "( n n -- n n )" } } }
   7 { $description "Outputs a quotation for upgrading numberical types. It takes two numbers on the stack, an instance of " { $snippet "class1" } ", and an instance of " { $snippet "class2" } ", and converts the one with the lower priority to the higher priority type." }
   8 { $examples { $example "USING: generic.math math kernel prettyprint ;" "fixnum bignum math-upgrade ." "[ [ >bignum ] dip ]" } } ;
   9
  10 HELP: no-math-method
  11 { $values { "left" "an object" } { "right" "an object" } { "generic" generic } }
  12 { $description "Throws a " { $link no-math-method } " error." }
  13 { $error-description "Thrown by generic words using the " { $link math-combination } " method combination if there is no suitable method defined for the two inputs." } ;
  14
  15 HELP: math-method
  16 { $values { "word" generic } { "class1" class } { "class2" class } { "quot" quotation } }
  17 { $description "Generates a definition for " { $snippet "word" } " when the two inputs are instances of " { $snippet "class1" } " and " { $snippet "class2" } ", respectively." }
  18 { $examples { $example "USING: generic.math math prettyprint ;" "\\ + fixnum float math-method ." "[ [ >float ] dip float=>+ ]" } } ;
  19
  20 HELP: math-class
  21 { $class-description "The class of subtypes of " { $link number } " which are not " { $link null } "." } ;
  22
  23 HELP: math-combination
  24 { $values { "word" generic } { "quot" quotation } }
  25 { $description "Generates a double-dispatching word definition. Only methods defined on numerical classes and " { $link object } " take effect in the math combination. Methods defined on numerical classes are guaranteed to have their two inputs upgraded to the highest priority type of the two."
  26 $nl
  27 "The math method combination is used for binary operators such as " { $link + } " and " { $link * } "."
  28 $nl
  29 "A method can only be added to a generic word using the math combination if the method specializes on one of the below classes, or a union defined over one or more of the below classes:"
  30 { $code
  31     "fixnum"
  32     "bignum"
  33     "ratio"
  34     "float"
  35     "complex"
  36     "object"
  37 }
  38 "The math combination performs numerical upgrading as described in " { $link "number-protocol" } "." } ;
  39
  40 HELP: math-generic
  41 { $class-description "The class of generic words using " { $link math-combination } "." } ;
  42
  43 HELP: last/first
  44 { $values { "seq" sequence } { "pair" "a two-element array" } }
  45 { $description "Creates an array holding the first and last element of the sequence." } ;