core/math/floats/floats-docs.factor

   1 USING: help.markup help.syntax math math.private ;
   2 IN: math.floats
   3
   4 ARTICLE: "floats" "Floats"
   5 { $subsection float }
   6 "Rational numbers represent " { $emphasis "exact" } " quantities. On the other hand, a floating point number is an " { $emphasis "approximation" } ". While rationals can grow to any required precision, floating point numbers are fixed-width, and manipulating them is usually faster than manipulating ratios or bignums (but slower than manipulating fixnums). Floating point numbers are often used to represent irrational numbers, which have no exact representation as a ratio of two integers."
   7 $nl
   8 "Introducing a floating point number in a computation forces the result to be expressed in floating point."
   9 { $example "5/4 1/2 + ." "7/4" }
  10 { $example "5/4 0.5 + ." "1.75" }
  11 "Integers and rationals can be converted to floats:"
  12 { $subsection >float }
  13 "Two real numbers can be divided yielding a float result:"
  14 { $subsection /f }
  15 "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."
  16 { $subsection float>bits }
  17 { $subsection double>bits }
  18 { $subsection bits>float }
  19 { $subsection bits>double }
  20 { $see-also "syntax-floats" } ;
  21
  22 ABOUT: "floats"
  23
  24 HELP: float
  25 { $class-description "The class of double-precision floating point numbers." } ;
  26
  27 HELP: >float ( x -- y )
  28 { $values { "x" real } { "y" float } }
  29 { $description "Converts a real to a float. This is the identity on floats, and performs a floating point division on rationals." } ;
  30
  31 HELP: bits>double ( n -- x )
  32 { $values { "n" "a 64-bit integer representing an 754 double-precision float" } { "x" float } }
  33 { $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." } ;
  34
  35 { bits>double bits>float double>bits float>bits } related-words
  36
  37 HELP: bits>float ( n -- x )
  38 { $values { "n" "a 32-bit integer representing an 754 single-precision float" } { "x" float } }
  39 { $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." } ;
  40
  41 HELP: double>bits ( x -- n )
  42 { $values { "x" float } { "n" "a 64-bit integer representing an 754 double-precision float" } }
  43 { $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." } ;
  44
  45 HELP: float>bits ( x -- n )
  46 { $values { "x" float } { "n" "a 32-bit integer representing an 754 single-precision float" } }
  47 { $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." } ;
  48
  49 ! Unsafe primitives
  50 HELP: float+ ( x y -- z )
  51 { $values { "x" float } { "y" float } { "z" float } }
  52 { $description "Primitive version of " { $link + } "." }
  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 + } " instead." } ;
  54
  55 HELP: float- ( x y -- z )
  56 { $values { "x" float } { "y" float } { "z" float } }
  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 -- z )
  61 { $values { "x" float } { "y" float } { "z" float } }
  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-mod ( x y -- z )
  66 { $values { "x" float } { "y" float } { "z" float } }
  67 { $description "Primitive version of " { $link mod } "." }
  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 mod } " instead." } ;
  69
  70 HELP: float/f ( x y -- z )
  71 { $values { "x" float } { "y" float } { "z" float } }
  72 { $description "Primitive version of " { $link /f } "." }
  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 /f } " instead." } ;
  74
  75 HELP: float< ( x y -- ? )
  76 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  77 { $description "Primitive version of " { $link < } "." }
  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 < } " instead." } ;
  79
  80 HELP: float<= ( x y -- ? )
  81 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  82 { $description "Primitive version of " { $link <= } "." }
  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 <= } " instead." } ;
  84
  85 HELP: float> ( x y -- ? )
  86 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  87 { $description "Primitive version of " { $link > } "." }
  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 > } " instead." } ;
  89
  90 HELP: float>= ( x y -- ? )
  91 { $values { "x" float } { "y" float } { "?" "a boolean" } }
  92 { $description "Primitive version of " { $link >= } "." }
  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 >= } " instead." } ;