core/generic/math/math-docs.factor

   1 USING: kernel generic help.markup help.syntax math classes
   2 quotations generic.math.private ;
   3 IN: generic.math
   4
   5 HELP: math-class-max
   6 { $values { "class1" class } { "class2" class } { "class" class } }
   7 { $description "Evaluates which math class is the largest." }
   8 { $examples
   9   { $example
  10     "USING: generic.math math kernel prettyprint ;"
  11     "integer float math-class-max ."
  12     "float"
  13   }
  14 } ;
  15
  16 HELP: math-upgrade
  17 { $values { "class1" class } { "class2" class } { "quot" { $quotation ( n n -- n n ) } } }
  18 { $description "Outputs a quotation for upgrading numerical 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." }
  19 { $examples { $example "USING: generic.math math kernel prettyprint ;" "fixnum bignum math-upgrade ." "[ [ >bignum ] dip ]" } } ;
  20
  21 HELP: no-math-method
  22 { $values { "left" object } { "right" object } { "generic" generic } }
  23 { $description "Throws a " { $link no-math-method } " error." }
  24 { $error-description "Thrown by generic words using the " { $link math-combination } " method combination if there is no suitable method defined for the two inputs." } ;
  25
  26 HELP: math-method
  27 { $values { "word" generic } { "class1" class } { "class2" class } { "quot" quotation } }
  28 { $description "Generates a definition for " { $snippet "word" } " when the two inputs are instances of " { $snippet "class1" } " and " { $snippet "class2" } ", respectively." }
  29 { $examples { $example "USING: generic.math math prettyprint ;" "\\ + fixnum float math-method ." "[ { fixnum float } declare [ >float ] dip M\\ float + ]" } } ;
  30
  31 HELP: math-class
  32 { $class-description "The class of subtypes of " { $link number } " which are not " { $link null } "." } ;
  33
  34 HELP: math-combination
  35 { $values { "word" generic } { "quot" quotation } }
  36 { $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."
  37 $nl
  38 "The math method combination is used for binary operators such as " { $link + } " and " { $link * } "."
  39 $nl
  40 "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:"
  41 { $code
  42     "fixnum"
  43     "bignum"
  44     "ratio"
  45     "float"
  46     "complex"
  47     "object"
  48 }
  49 "The math combination performs numerical upgrading as described in " { $link "number-protocol" } "." } ;
  50
  51 HELP: math-generic
  52 { $class-description "The class of generic words using " { $link math-combination } "." } ;