core/handbook/math.facts

   1 USING: help math prettyprint sequences ;
   2
   3 ARTICLE: "math" "Numbers"
   4 "Factor attempts to preserve natural mathematical semantics for numbers. Multiplying two large integers never results in overflow, and dividing two integers yields an exact ratio. Floating point numbers are also supported, along with complex numbers."
   5 $terpri
   6 "Math words are in the " { $vocab-link "math" } " vocabulary. Implementation details are in the " { $vocab-link "math-internals" } " vocabulary."
   7 { $subsection "number-protocol" }
   8 { $subsection "number-types" }
   9 { $subsection "math-functions" }
  10 { $subsection "math-constants" }
  11 { $subsection "math-vectors" }
  12 { $subsection "number-strings" } ;
  13
  14 ARTICLE: "number-types" "Types of numbers"
  15 { $subsection "integers" }
  16 { $subsection "rationals" }
  17 { $subsection "floats" }
  18 { $subsection "complex-numbers" } ;
  19
  20 ARTICLE: "division-by-zero" "Division by zero"
  21 "Floating point division never raises an error if the denominator is zero. This means that if at least one of the two inputs to " { $link / } ", " { $link /f } " or " { $link mod } " is a float, the result will be a floating point infinity or not a number value."
  22 $terpri
  23 "The behavior of integer division is hardware specific. On x86 processors, " { $link /i } " and " { $link mod } " raise an error if both inputs are integers and the denominator is zero. On PowerPC, integer division by zero yields a result of zero."
  24 $terpri
  25 "On the other hand, the " { $link / } " word, when given integer arguments, implements a much more expensive division algorithm which always yields an exact rational answer, and this word always tests for division by zero explicitly." ;
  26
  27 ARTICLE: "number-protocol" "Number protocol"
  28 "Math operations obey certain numerical upgrade rules. If one of the inputs is a bignum and the other is a fixnum, the latter is first coerced to a bignum; if one of the inputs is a float, the other is coerced to a float."
  29 $terpri
  30 "Two examples where you should note the types of the inputs and outputs:"
  31 { $example "3 >fixnum 6 >bignum * class ." "bignum" }
  32 { $example "1/2 2.0 + ." "4.5" }
  33 "The following usual operations are supported by all numbers."
  34 { $subsection + }
  35 { $subsection - }
  36 { $subsection * }
  37 { $subsection / }
  38 "Non-commutative operations take operands from the stack in the natural order; " { $snippet "6 2 /" } " divides 6 by 2."
  39 { $subsection "division-by-zero" }
  40 "Real numbers (but not complex numbers) can be ordered:"
  41 { $subsection < }
  42 { $subsection <= }
  43 { $subsection > }
  44 { $subsection >= } ;
  45
  46 ARTICLE: "integers" "Integers"
  47 { $subsection integer }
  48 "Integers come in two varieties -- fixnums and bignums. Fixnums fit in a machine word and are faster to manipulate; if the result of a fixnum operation is too large to fit in a fixnum, the result is upgraded to a bignum. Here is an example where two fixnums are multiplied yielding a bignum:"
  49 { $example "134217728 class ." "fixnum" }
  50 { $example "128 class ." "fixnum" }
  51 { $example "134217728 128 * ." "17179869184" }
  52 { $example "134217728 128 * class ." "bignum" }
  53 "Integers can be entered using a different base; see " { $link "syntax-numbers" } "."
  54 $terpri
  55 "Integers can be tested for, and real numbers can be converted to integers:"
  56 { $subsection fixnum? }
  57 { $subsection bignum? }
  58 { $subsection >fixnum }
  59 { $subsection >bignum }
  60 "The " { $link . } " word prints numbers in decimal. A set of words in the " { $vocab-link "prettyprint" } " vocabulary is provided to print integers using another base."
  61 { $subsection .b }
  62 { $subsection .o }
  63 { $subsection .h }
  64 "Some mathematical operations are only supported on integers."
  65 { $subsection "modular-arithmetic" }
  66 { $subsection "bitwise-arithmetic" }
  67 { $subsection "random-numbers" } ;
  68
  69 ARTICLE: "modular-arithmetic" "Modular arithmetic"
  70 { $subsection mod }
  71 { $subsection rem }
  72 { $subsection /mod }
  73 { $subsection /i }
  74 { $subsection gcd } ;
  75
  76 ARTICLE: "bitwise-arithmetic" "Bitwise arithmetic"
  77 "There are two ways of looking at an integer -- as an abstract mathematical entity, or as a string of bits. The latter representation motivates " { $emphasis "bitwise operations" } "."
  78 { $subsection bitand }
  79 { $subsection bitor }
  80 { $subsection bitxor }
  81 { $subsection bitnot }
  82 { $subsection shift }
  83 { $subsection log2 }
  84 { $subsection power-of-2? }
  85 { $subsection next-power-of-2 } ;
  86
  87 ARTICLE: "random-numbers" "Generating random integers"
  88 { $subsection (random-int) }
  89 { $subsection random-int } ;
  90
  91 ARTICLE: "rationals" "Rational numbers"
  92 { $subsection ratio }
  93 "When we add, subtract or multiply any two integers, the result is always an integer. However, dividing a numerator by a denominator that is not an integral divisor of the denominator yields a ratio:"
  94 { $example "1210 11 / ." "110" }
  95 { $example "100 330 / ." "10/33" }
  96 "Ratios are printed and can be input literally in the form above. Ratios are always reduced to lowest terms by factoring out the greatest common divisor of the numerator and denominator. A ratio with a denominator of 1 becomes an integer. Division with a denominator of 0 throws an error."
  97 $terpri
  98 "Ratios behave just like any other number -- all numerical operations work as you would expect."
  99 { $example "1/2 1/3 + ." "5/6" }
 100 { $example "100 6 / 3 * ." "50" }
 101 "Ratios can be taken apart:"
 102 { $subsection numerator }
 103 { $subsection denominator }
 104 { $subsection >fraction } ;
 105
 106 ARTICLE: "floats" "Floats"
 107 "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."
 108 $terpri
 109 "Floating point literals are input with a decimal point."
 110 { $example "1.23 1.5 + ." "1.73" }
 111 "Introducing a floating point number in a computation forces the result to be expressed in floating point."
 112 { $example "5/4 1/2 + ." "7/4" }
 113 { $example "5/4 0.5 + ." "1.75" }
 114 "Integers and rationals can be converted to floats:"
 115 { $subsection >float }
 116 "Two real numbers can be divided yielding a float result:"
 117 { $subsection /f }
 118 "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."
 119 { $subsection float>bits }
 120 { $subsection double>bits }
 121 { $subsection bits>float }
 122 { $subsection bits>double } ;
 123
 124 ARTICLE: "complex-numbers" "Complex numbers"
 125 { $subsection complex }
 126 "Complex numbers arise as solutions to quadratic equations whose graph does not intersect the " { $emphasis "x" } " axis. Their literal syntax is covered in " { $link "syntax-complex-numbers" } "."
 127 $terpri
 128 "Unlike math, where all real numbers are also complex numbers, Factor only considers a number to be a complex number if its imaginary part is non-zero. However, complex number operations are fully supported for real numbers; they are treated as having an imaginary part of zero."
 129 $terpri
 130 "Complex numbers can be taken apart:"
 131 { $subsection real }
 132 { $subsection imaginary }
 133 { $subsection >rect }
 134 "Complex numbers can be constructed from real numbers:"
 135 { $subsection rect> }
 136 "The polar form can be computed:"
 137 { $subsection abs }
 138 { $subsection absq }
 139 { $subsection arg }
 140 { $subsection >polar }
 141 { $subsection polar> }
 142 "Reflection in the " { $snippet "x" } " axis:"
 143 { $subsection conjugate } ;
 144
 145 ARTICLE: "math-functions" "Mathematical functions"
 146 { $subsection "arithmetic-functions" }
 147 { $subsection "power-functions" }
 148 { $subsection "trig-hyp-functions" } ;
 149
 150 ARTICLE: "arithmetic-functions" "Arithmetic functions"
 151 "Computing additive and multiplicative inverses:"
 152 { $subsection neg }
 153 { $subsection recip }
 154 "Rounding:"
 155 { $subsection ceiling }
 156 { $subsection floor }
 157 { $subsection truncate } ;
 158
 159 ARTICLE: "power-functions" "Powers and logarithms"
 160 "Squares:"
 161 { $subsection sq }
 162 { $subsection sqrt }
 163 "Exponential and natural logarithm:"
 164 { $subsection exp }
 165 { $subsection cis }
 166 { $subsection log }
 167 "Raising a number to a power:"
 168 { $subsection ^ } ;
 169
 170 ARTICLE: "trig-hyp-functions" "Trigonometric and hyperbolic functions"
 171 "Trigonometric functions:"
 172 { $subsection cos }
 173 { $subsection sin }
 174 { $subsection tan }
 175 "Reciprocals:"
 176 { $subsection sec }
 177 { $subsection cosec }
 178 { $subsection cot }
 179 "Inverses:"
 180 { $subsection acos }
 181 { $subsection asin }
 182 { $subsection atan }
 183 "Inverse reciprocals:"
 184 { $subsection asec }
 185 { $subsection acosec }
 186 { $subsection acot }
 187 "Hyperbolic functions:"
 188 { $subsection cosh }
 189 { $subsection sinh }
 190 { $subsection tanh }
 191 "Reciprocals:"
 192 { $subsection sech }
 193 { $subsection cosech }
 194 { $subsection coth }
 195 "Inverses:"
 196 { $subsection acosh }
 197 { $subsection asinh }
 198 { $subsection atanh }
 199 "Inverse reciprocals:"
 200 { $subsection asech }
 201 { $subsection acosech }
 202 { $subsection acoth } ;
 203
 204 ARTICLE: "math-constants" "Constants"
 205 { $subsection i }
 206 { $subsection -i }
 207 { $subsection e }
 208 { $subsection pi }
 209 { $subsection most-positive-fixnum }
 210 { $subsection most-negative-fixnum } ;
 211
 212 ARTICLE: "math-vectors" "Vector arithmetic"
 213 "Any Factor sequence can be used to represent a mathematical vector."
 214 $terpri
 215 "Acting on vectors by a scalar:"
 216 { $subsection vneg }
 217 { $subsection v*n }
 218 { $subsection n*v }
 219 { $subsection v/n }
 220 { $subsection n/v }
 221 "Combining two vectors to form another vector using " { $link 2map } ":"
 222 { $subsection v+ }
 223 { $subsection v- }
 224 { $subsection v* }
 225 { $subsection v/ }
 226 { $subsection vmax }
 227 { $subsection vmin }
 228 "Inner product and norm:"
 229 { $subsection v. }
 230 { $subsection norm }
 231 { $subsection norm-sq }
 232 { $subsection normalize } ;
 233
 234 ARTICLE: "number-strings" "Converting between numbers and strings"
 235 "These words only convert between real numbers and strings. Complex numbers are constructed by the parser (" { $link "parser" } ") and printed by the prettyprinter (" { $link "prettyprint" } ")."
 236 $terpri
 237 "Note that only integers can be converted to and from strings using a representation other than base 10. Calling a word such as " { $link >oct } " on a float will give a result in base 10."
 238 $terpri
 239 "Converting numbers to strings:"
 240 { $subsection number>string }
 241 { $subsection >bin }
 242 { $subsection >oct }
 243 { $subsection >hex }
 244 { $subsection >base }
 245 "Converting strings to numbers:"
 246 { $subsection string>number }
 247 { $subsection bin> }
 248 { $subsection oct> }
 249 { $subsection hex> }
 250 { $subsection base> }
 251 "You can also input literal numbers in a different base (" { $link "syntax-integers" } ")." ;