PageRenderTime 66ms CodeModel.GetById 12ms app.highlight 50ms RepoModel.GetById 2ms app.codeStats 0ms

/core/math/floats/floats-docs.factor

http://github.com/abeaumont/factor
Unknown | 163 lines | 140 code | 23 blank | 0 comment | 0 complexity | 211e10284aeabbcc1718d78a5e320d7c MD5 | raw file
  1USING: help.markup help.syntax math math.private ;
  2IN: math.floats
  3
  4HELP: float
  5{ $class-description "The class of double-precision floating point numbers." } ;
  6
  7HELP: >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
 11HELP: bits>double
 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
 17HELP: bits>float
 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
 21HELP: double>bits
 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
 25HELP: float>bits
 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
 30HELP: float+
 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
 35HELP: float-
 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
 40HELP: float*
 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
 45HELP: float/f
 46{ $values { "x" float } { "y" float } { "z" float } }
 47{ $description "Primitive version of " { $link /f } "." }
 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 /f } " instead." } ;
 49
 50HELP: float<
 51{ $values { "x" float } { "y" float } { "?" "a boolean" } }
 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
 55HELP: float<=
 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
 60HELP: float>
 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
 65HELP: float>=
 66{ $values { "x" float } { "y" float } { "?" "a boolean" } }
 67{ $description "Primitive version of " { $link u>= } "." }
 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 u>= } " instead." } ;
 69
 70HELP: float-u<
 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
 75HELP: float-u<=
 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
 80HELP: float-u>
 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
 85HELP: float-u>=
 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
 90ARTICLE: "math.floats.compare" "Floating point comparison operations"
 91"In mathematics, real numbers are linearly ordered; for any two numbers " { $snippet "a" } " and " { $snippet "b" } ", exactly one of the following is true:"
 92{ $code
 93    "a < b"
 94    "a = b"
 95    "a > b"
 96}
 97"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."
 98$nl
 99"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)."
100$nl
101"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."
102$nl
103"The " { $link number= } " operation performs an unordered comparison. The following set of operators also perform unordered comparisons:"
104{ $subsections
105    u<
106    u<=
107    u>
108    u>=
109}
110"A word to check if two values are unordered with respect to each other:"
111{ $subsections unordered? }
112"To test for floating point exceptions, use the " { $vocab-link "math.floats.env" } " vocabulary."
113$nl
114"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." ;
115
116ARTICLE: "math.floats.bitwise" "Bitwise operations on floats"
117"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."
118{ $subsections
119    float>bits
120    double>bits
121    bits>float
122    bits>double
123}
124"Constructing floating point NaNs:"
125{ $subsections <fp-nan> }
126"Floating point numbers are discrete:"
127{ $subsections
128    prev-float
129    next-float
130}
131"Introspection on floating point numbers:"
132{ $subsections
133    fp-special?
134    fp-nan?
135    fp-qnan?
136    fp-snan?
137    fp-infinity?
138    fp-nan-payload
139}
140"Comparing two floating point numbers for bitwise equality:"
141{ $subsections fp-bitwise= }
142{ $see-also POSTPONE: NAN: } ;
143
144ARTICLE: "floats" "Floats"
145{ $subsections float }
146"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."
147$nl
148"Introducing a floating point number in a computation forces the result to be expressed in floating point."
149{ $example "5/4 1/2 + ." "1+3/4" }
150{ $example "5/4 0.5 + ." "1.75" }
151"Floating point literal syntax is documented in " { $link "syntax-floats" } "."
152$nl
153"Integers and rationals can be converted to floats:"
154{ $subsections >float }
155"Two real numbers can be divided yielding a float result:"
156{ $subsections
157    /f
158    "math.floats.bitwise"
159    "math.floats.compare"
160}
161"The " { $vocab-link "math.floats.env" } " vocabulary provides functionality for controlling floating point exceptions, rounding modes, and denormal behavior." ;
162
163ABOUT: "floats"