core/math/floats/floats-docs.factor

   1 USING: help.markup help.syntax math math.private ;
   2 IN: math.floats
   3
   4 HELP: float
   5 { $class-description "The class of double-precision floating point numbers." } ;
   6
   7 HELP: >float
   8 { $values { "x" real } { "y" float } }
   9 { $description "Converts a real to a float. This is the identity on floats, and performs a floating point division on rationals." } ;
  10
  11 HELP: bits>double ( n -- x )
  12 { $values { "n" "a 64-bit integer representing an IEEE 754 double-precision float" } { "x" float } }
  13 { $description "Creates a " { $link float } " object from a 64-bit binary representation. This word is usually used to reconstruct floats read from streams." } ;
  14
  15 { bits>double bits>float double>bits float>bits } related-words
  16
  17 HELP: bits>float ( n -- x )
  18 { $values { "n" "a 32-bit integer representing an IEEE 754 single-precision float" } { "x" float } }
  19 { $description "Creates a " { $link float } " object from a 32-bit binary representation. This word is usually used to reconstruct floats read from streams." } ;
  20
  21 HELP: double>bits ( x -- n )
  22 { $values { "x" float } { "n" "a 64-bit integer representing an IEEE 754 double-precision float" } }
  23 { $description "Creates a 64-bit binary representation of a " { $link float } " object. This can be used in the process of writing a float to a stream." } ;
  24
  25 HELP: float>bits ( x -- n )
  26 { $values { "x" float } { "n" "a 32-bit integer representing an IEEE 754 single-precision float" } }
  27 { $description "Creates a 32-bit binary representation of a " { $link float } " object. This can be used in the process of writing a float to a stream." } ;
  28
  29 ! Unsafe primitives
  30 HELP: float+ ( x y -- z )
  31 { $values { "x" float } { "y" float } { "z" float } }
  32 { $description "Primitive version of " { $link + } "." }
  33 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
  34
  35 HELP: float- ( x y -- z )
  36 { $values { "x" float } { "y" float } { "z" float } }
  37 { $description "Primitive version of " { $link - } "." }
  38 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
  39
  40 HELP: float* ( x y -- z )
  41 { $values { "x" float } { "y" float } { "z" float } }
  42 { $description "Primitive version of " { $link * } "." }
  43 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
  44
  45 HELP: float-mod ( x y -- z )
  46 { $values { "x" float } { "y" float } { "z" float } }
  47 { $description "Primitive version of " { $link mod } "." }
  48 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ;
  49
  50 HELP: float/f ( x y -- z )
  51 { $values { "x" float } { "y" float } { "z" float } }
  52 { $description "Primitive version of " { $link /f } "." }
  53 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /f } " instead." } ;
  54
  55 HELP: float< ( x y -- ? )
  56 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  57 { $description "Primitive version of " { $link < } "." }
  58 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
  59
  60 HELP: float<= ( x y -- ? )
  61 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  62 { $description "Primitive version of " { $link <= } "." }
  63 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
  64
  65 HELP: float> ( x y -- ? )
  66 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  67 { $description "Primitive version of " { $link > } "." }
  68 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
  69
  70 HELP: float>= ( x y -- ? )
  71 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  72 { $description "Primitive version of " { $link u>= } "." }
  73 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u>= } " instead." } ;
  74
  75 HELP: float-u< ( x y -- ? )
  76 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  77 { $description "Primitive version of " { $link u< } "." }
  78 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u< } " instead." } ;
  79
  80 HELP: float-u<= ( x y -- ? )
  81 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  82 { $description "Primitive version of " { $link u<= } "." }
  83 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u<= } " instead." } ;
  84
  85 HELP: float-u> ( x y -- ? )
  86 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  87 { $description "Primitive version of " { $link u> } "." }
  88 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u> } " instead." } ;
  89
  90 HELP: float-u>= ( x y -- ? )
  91 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  92 { $description "Primitive version of " { $link u>= } "." }
  93 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u>= } " instead." } ;
  94
  95 ARTICLE: "math.floats.compare" "Floating point comparison operations"
  96 "In mathematics, real numbers are linearly ordered; for any two numbers " { $snippet "a" } " and " { $snippet "b" } ", exactly one of the following is true:"
  97 { $code
  98     "a < b"
  99     "a = b"
 100     "a > b"
 101 }
 102 "With floating point values, there is a fourth possibility; " { $snippet "a" } " and " { $snippet "b" } " may be " { $emphasis "unordered" } ". This happens if one or both values are Not-a-Number values."
 103 $nl
 104 "All comparison operators, including " { $link number= } ", return " { $link f } " in the unordered case (and in particular, this means that a NaN is not equal to itself)."
 105 $nl
 106 "The " { $emphasis "ordered" } " comparison operators set floating point exception flags if the result of the comparison is unordered. The standard comparison operators (" { $link < } ", " { $link <= } ", " { $link > } ", " { $link >= } ") perform ordered comparisons."
 107 $nl
 108 "The " { $link number= } " operation performs an unordered comparison. The following set of operators also perform unordered comparisons:"
 109 { $subsections
 110     u<
 111     u<=
 112     u>
 113     u>=
 114 }
 115 "A word to check if two values are unordered with respect to each other:"
 116 { $subsections unordered? }
 117 "To test for floating point exceptions, use the " { $vocab-link "math.floats.env" } " vocabulary."
 118 $nl
 119 "If neither input to a comparison operator is a floating point value, then " { $link u< } ", " { $link u<= } ", " { $link u> } " and " { $link u>= } " are equivalent to the ordered operators." ;
 120
 121 ARTICLE: "math.floats.bitwise" "Bitwise operations on floats"
 122 "Floating point numbers are represented internally in IEEE 754 double-precision format. This internal representation can be accessed for advanced operations and input/output purposes."
 123 { $subsections
 124     float>bits
 125     double>bits
 126     bits>float
 127     bits>double
 128 }
 129 "Constructing floating point NaNs:"
 130 { $subsections <fp-nan> }
 131 "Floating point numbers are discrete:"
 132 { $subsections
 133     prev-float
 134     next-float
 135 }
 136 "Introspection on floating point numbers:"
 137 { $subsections
 138     fp-special?
 139     fp-nan?
 140     fp-qnan?
 141     fp-snan?
 142     fp-infinity?
 143     fp-nan-payload
 144 }
 145 "Comparing two floating point numbers for bitwise equality:"
 146 { $subsections fp-bitwise= }
 147 { $see-also POSTPONE: NAN: } ;
 148
 149 ARTICLE: "floats" "Floats"
 150 { $subsections float }
 151 "Rational numbers represent " { $emphasis "exact" } " quantities. On the other hand, a floating point number is an " { $emphasis "approximate" } " value. While rationals can grow to any required precision, floating point numbers have limited precision, and manipulating them is usually faster than manipulating ratios or bignums."
 152 $nl
 153 "Introducing a floating point number in a computation forces the result to be expressed in floating point."
 154 { $example "5/4 1/2 + ." "1+3/4" }
 155 { $example "5/4 0.5 + ." "1.75" }
 156 "Floating point literal syntax is documented in " { $link "syntax-floats" } "."
 157 $nl
 158 "Integers and rationals can be converted to floats:"
 159 { $subsections >float }
 160 "Two real numbers can be divided yielding a float result:"
 161 { $subsections
 162     /f
 163     "math.floats.bitwise"
 164     "math.floats.compare"
 165 }
 166 "The " { $vocab-link "math.floats.env" } " vocabulary provides functionality for controlling floating point exceptions, rounding modes, and denormal behavior." ;
 167
 168 ABOUT: "floats"