core/math/math-docs.factor

   1 USING: help.markup help.syntax kernel sequences quotations
   2 math.private byte-arrays io.binary ;
   3 IN: math
   4
   5 HELP: number=
   6 { $values { "x" number } { "y" number } { "?" "a boolean" } }
   7 { $description "Tests if two numbers have the same numeric value." }
   8 { $notes "This word differs from " { $link = } " in that it disregards differences in type when comparing numbers." }
   9 { $examples
  10     { $example "USING: math prettyprint ;" "3.0 3 number= ." "t" }
  11     { $example "USING: kernel math prettyprint ;" "3.0 3 = ." "f" }
  12 } ;
  13
  14 HELP: <
  15 { $values { "x" real } { "y" real } { "?" boolean } }
  16 { $description "Tests if " { $snippet "x" } " is less than " { $snippet "y" } "." } ;
  17
  18 HELP: <=
  19 { $values { "x" real } { "y" real } { "?" boolean } }
  20 { $description "Tests if " { $snippet "x" } " is less than or equal to " { $snippet "y" } "." } ;
  21
  22 HELP: >
  23 { $values { "x" real } { "y" real } { "?" boolean } }
  24 { $description "Tests if " { $snippet "x" } " is greater than " { $snippet "y" } "." } ;
  25
  26 HELP: >=
  27 { $values { "x" real } { "y" real } { "?" boolean } }
  28 { $description "Tests if " { $snippet "x" } " is greater than or equal to " { $snippet "y" } "." } ;
  29
  30
  31 HELP: +
  32 { $values { "x" number } { "y" number } { "z" number } }
  33 { $description
  34     "Adds two numbers."
  35     { $list
  36         "Addition of fixnums may overflow and convert the result to a bignum."
  37         "Addition of bignums always yields a bignum."
  38         "Addition of floats always yields a float."
  39         "Addition of ratios and complex numbers proceeds using the relevant mathematical rules."
  40     }
  41 } ;
  42
  43 HELP: -
  44 { $values { "x" number } { "y" number } { "z" number } }
  45 { $description
  46     "Subtracts " { $snippet "y" } " from " { $snippet "x" } "."
  47     { $list
  48         "Subtraction of fixnums may overflow and convert the result to a bignum."
  49         "Subtraction of bignums always yields a bignum."
  50         "Subtraction of floats always yields a float."
  51         "Subtraction of ratios and complex numbers proceeds using the relevant mathematical rules."
  52     }
  53 } ;
  54
  55 HELP: *
  56 { $values { "x" number } { "y" number } { "z" number } }
  57 { $description
  58     "Multiplies two numbers."
  59     { $list
  60         "Multiplication of fixnums may overflow and convert the result to a bignum."
  61         "Multiplication of bignums always yields a bignum."
  62         "Multiplication of floats always yields a float."
  63         "Multiplication of ratios and complex numbers proceeds using the relevant mathematical rules."
  64     }
  65 } ;
  66
  67 HELP: /
  68 { $values { "x" number } { "y" number } { "z" number } }
  69 { $description
  70     "Divides " { $snippet "x" } " by " { $snippet "y" } ", retaining as much precision as possible."
  71     { $list
  72         "Division of fixnums may yield a ratio, or overflow and yield a bignum."
  73         "Division of bignums may yield a ratio."
  74         "Division of floats always yields a float."
  75         "Division of ratios and complex numbers proceeds using the relevant mathematical rules."
  76     }
  77 }
  78 { $see-also "division-by-zero" } ;
  79
  80 HELP: /i
  81 { $values { "x" real } { "y" real } { "z" integer } }
  82 { $description
  83     "Divides " { $snippet "x" } " by " { $snippet "y" } ", truncating the result to an integer."
  84 }
  85 { $see-also "division-by-zero" } ;
  86
  87 HELP: /f
  88 { $values { "x" real } { "y" real } { "z" float } }
  89 { $description
  90     "Divides " { $snippet "x" } " by " { $snippet "y" } ", representing the result as a floating point number."
  91 }
  92 { $see-also "division-by-zero" } ;
  93
  94 HELP: mod
  95 { $values { "x" rational } { "y" rational } { "z" rational } }
  96 { $description
  97     "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
  98     { $list
  99         "Modulus of fixnums always yields a fixnum."
 100         "Modulus of bignums always yields a bignum."
 101         { "Modulus of rationals always yields a rational. In this case, the remainder is computed using the formula " { $snippet "x - (x mod y) * y" } "." }
 102     }
 103 }
 104 { $see-also "division-by-zero" rem } ;
 105
 106 HELP: /mod
 107 { $values { "x" integer } { "y" integer } { "z" integer } { "w" integer } }
 108 { $description
 109     "Computes the quotient " { $snippet "z" } " and remainder " { $snippet "w" } " of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
 110     { $list
 111         "The quotient of two fixnums may overflow and yield a bignum; the remainder is always a fixnum"
 112         "The quotient and remainder of two bignums is always a bignum."
 113     }
 114 }
 115 { $see-also "division-by-zero" } ;
 116
 117 HELP: bitand
 118 { $values { "x" integer } { "y" integer } { "z" integer } }
 119 { $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in both inputs." }
 120 { $examples
 121     { $example "USING: math prettyprint ;" "BIN: 101 BIN: 10 bitand .b" "0" }
 122     { $example "USING: math prettyprint ;" "BIN: 110 BIN: 10 bitand .b" "10" }
 123 }
 124 { $notes "This word implements bitwise and, so applying it to booleans will throw an error. Boolean and is the " { $link and } " word." } ;
 125
 126 HELP: bitor
 127 { $values { "x" integer } { "y" integer } { "z" integer } }
 128 { $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in at least one of the inputs." }
 129 { $examples
 130     { $example "USING: math prettyprint ;" "BIN: 101 BIN: 10 bitor .b" "111" }
 131     { $example "USING: math prettyprint ;" "BIN: 110 BIN: 10 bitor .b" "110" }
 132 }
 133 { $notes "This word implements bitwise inclusive or, so applying it to booleans will throw an error. Boolean inclusive or is the " { $link and } " word." } ;
 134
 135 HELP: bitxor
 136 { $values { "x" integer } { "y" integer } { "z" integer } }
 137 { $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in exactly one of the inputs." }
 138 { $examples
 139     { $example "USING: math prettyprint ;" "BIN: 101 BIN: 10 bitxor .b" "111" }
 140     { $example "USING: math prettyprint ;" "BIN: 110 BIN: 10 bitxor .b" "100" }
 141 }
 142 { $notes "This word implements bitwise exclusive or, so applying it to booleans will throw an error. Boolean exclusive or is the " { $link xor } " word." } ;
 143
 144 HELP: shift
 145 { $values { "x" integer } { "n" integer } { "y" integer } }
 146 { $description "Shifts " { $snippet "x" } " to the left by " { $snippet "n" } " bits if " { $snippet "n" } " is positive, or " { $snippet "-n" } " bits to the right if " { $snippet "n" } " is negative. A left shift of a fixnum may overflow, yielding a bignum. A right shift may result in bits “falling off” the right hand side and being discarded." }
 147 { $examples { $example "USING: math prettyprint ;" "BIN: 101 5 shift .b" "10100000" } { $example "USING: math prettyprint ;" "BIN: 11111 -2 shift .b" "111" } } ;
 148
 149 HELP: bitnot
 150 { $values { "x" integer } { "y" integer } }
 151 { $description "Computes the bitwise complement of the input; that is, each bit in the input number is flipped." }
 152 { $notes "This word implements bitwise not, so applying it to booleans will throw an error. Boolean not is the " { $link not } " word."
 153 $nl
 154 "Due to the two's complement representation of signed integers, the following two lines are equivalent:" { $code "bitnot" "neg 1 -" } } ;
 155
 156 HELP: bit?
 157 { $values { "x" integer } { "n" integer } { "?" "a boolean" } }
 158 { $description "Tests if the " { $snippet "n" } "th bit of " { $snippet "x" } " is set." }
 159 { $examples { $example "USING: math prettyprint ;" "BIN: 101 2 bit? ." "t" } } ;
 160
 161 HELP: log2
 162 { $values { "x" "a positive integer" } { "n" integer } }
 163 { $description "Outputs the largest integer " { $snippet "n" } " such that " { $snippet "2^n" } " is less than or equal to " { $snippet "x" } "." }
 164 { $errors "Throws an error if " { $snippet "x" } " is zero or negative." } ;
 165
 166 HELP: ?1+
 167 { $values { "x" { $maybe number } } { "y" number } }
 168 { $description "If the input is not " { $link f } ", adds one. Otherwise, outputs a " { $snippet "0" } "." } ;
 169
 170 HELP: sq
 171 { $values { "x" number } { "y" number } }
 172 { $description "Multiplies a number by itself." } ;
 173
 174 HELP: neg
 175 { $values { "x" number } { "-x" number } }
 176 { $description "Computes a number's additive inverse." } ;
 177
 178 HELP: recip
 179 { $values { "x" number } { "y" number } }
 180 { $description "Computes a number's multiplicative inverse." }
 181 { $errors "Throws an error if " { $snippet "x" } " is the integer 0." } ;
 182
 183 HELP: rem
 184 { $values { "x" rational } { "y" rational } { "z" rational } }
 185 { $description
 186     "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder always positive."
 187     { $list
 188         "Given fixnums, always yields a fixnum."
 189         "Given bignums, always yields a bignum."
 190         "Given rationals, always yields a rational."
 191     }
 192 }
 193 { $see-also "division-by-zero" mod } ;
 194
 195 HELP: sgn
 196 { $values { "x" real } { "n" "-1, 0 or 1" } }
 197 { $description
 198     "Outputs one of the following:"
 199     { $list
 200         { "-1 if " { $snippet "x" } " is negative" }
 201         { "0 if " { $snippet "x" } " is equal to 0" }
 202         { "1 if " { $snippet "x" } " is positive" }
 203     }
 204 } ;
 205
 206 HELP: 2/
 207 { $values { "x" integer } { "y" integer } }
 208 { $description "Shifts " { $snippet "x" } " to the right by one bit." }
 209 { $examples
 210     { $example "USING: math prettyprint ;" "14 2/ ." "7" }
 211     { $example "USING: math prettyprint ;" "17 2/ ." "8" }
 212     { $example "USING: math prettyprint ;" "-17 2/ ." "-9" }
 213 }
 214 { $notes "This word is not equivalent to " { $snippet "2 /" } " or " { $snippet "2 /i" } "; the name is historic and originates from the Forth programming language." } ;
 215
 216 HELP: 2^
 217 { $values { "n" "a positive integer" } { "2^n" "a positive integer" } }
 218 { $description "Computes two to the power of " { $snippet "n" } ". This word will only give correct results if " { $snippet "n" } " is greater than zero; for the general case, use " { $snippet  "2 swap ^" } "." } ;
 219
 220 HELP: zero?
 221 { $values { "x" number } { "?" "a boolean" } }
 222 { $description "Tests if the number is equal to zero." } ;
 223
 224 HELP: if-zero
 225 { $values { "n" number } { "quot1" quotation } { "quot2" quotation } }
 226 { $description "Makes an implicit check if the number is zero. A zero is dropped and " { $snippet "quot1" } " is called. Otherwise, if the number is not zero, " { $snippet "quot2" } " is called on it." }
 227 { $example
 228     "USING: kernel math prettyprint sequences ;"
 229     "3 [ \"zero\" ] [ sq ] if-zero ."
 230     "9"
 231 } ;
 232
 233 HELP: when-zero
 234 { $values
 235      { "n" number } { "quot" "the first quotation of an " { $link if-zero } } }
 236 { $description "Makes an implicit check if the sequence is empty. A zero is dropped and the " { $snippet "quot" } " is called." }
 237 { $examples "This word is equivalent to " { $link if-zero } " with an empty second quotation:"
 238     { $example
 239     "USING: math prettyprint ;"
 240     "0 [ 4 ] [ ] if-zero ."
 241     "4"
 242     }
 243     { $example
 244     "USING: math prettyprint ;"
 245     "0 [ 4 ] when-zero ."
 246     "4"
 247     }
 248 } ;
 249
 250 HELP: unless-zero
 251 { $values
 252      { "n" number } { "quot" "the second quotation of an " { $link if-empty } } }
 253 { $description "Makes an implicit check if the number is zero. A zero is dropped. Otherwise, the " { $snippet "quot" } " is called on the number." }
 254 { $examples "This word is equivalent to " { $link if-zero } " with an empty first quotation:"
 255     { $example
 256     "USING: sequences math prettyprint ;"
 257     "3 [ ] [ sq ] if-empty ."
 258     "9"
 259     }
 260     { $example
 261     "USING: sequences math prettyprint ;"
 262     "3 [ sq ] unless-zero ."
 263     "9"
 264     }
 265 } ;
 266
 267 HELP: times
 268 { $values { "n" integer } { "quot" quotation } }
 269 { $description "Calls the quotation " { $snippet "n" } " times." }
 270 { $notes "If you need to pass the current index to the quotation, use " { $link each } "." }
 271 { $examples
 272     { $example "USING: io math ;" "3 [ \"Hi\" print ] times" "Hi\nHi\nHi" }
 273 } ;
 274
 275 HELP: fp-bitwise=
 276 { $values
 277     { "x" float } { "y" float }
 278     { "?" boolean }
 279 }
 280 { $description "Compares two floating point numbers for bit equality." }
 281 { $notes "Unlike " { $link = } " or " { $link number= } ", this word will consider NaNs with equal payloads to be equal, and positive zero and negative zero to be not equal." }
 282 { $examples
 283     "Not-a-number equality:"
 284     { $example
 285         "USING: math prettyprint ;"
 286         "0.0 0.0 / dup number= ."
 287         "f"
 288     }
 289     { $example
 290         "USING: math prettyprint ;"
 291         "0.0 0.0 / dup fp-bitwise= ."
 292         "t"
 293     }
 294     "Signed zero equality:"
 295     { $example
 296         "USING: math prettyprint ;"
 297         "-0.0 0.0 fp-bitwise= ."
 298         "f"
 299     }
 300     { $example
 301         "USING: math prettyprint ;"
 302         "-0.0 0.0 = ."
 303         "t"
 304     }
 305 } ;
 306
 307 HELP: fp-special?
 308 { $values { "x" real } { "?" "a boolean" } }
 309 { $description "Tests if " { $snippet "x" } " is an IEEE special value (Not-a-Number or Infinity). While " { $snippet "x" } " can be any real number, this word will only ever yield true if " { $snippet "x" } " is a " { $link float } "." } ;
 310
 311 HELP: fp-nan?
 312 { $values { "x" real } { "?" "a boolean" } }
 313 { $description "Tests if " { $snippet "x" } " is an IEEE Not-a-Number value. While " { $snippet "x" } " can be any real number, this word will only ever yield true if " { $snippet "x" } " is a " { $link float } "." } ;
 314
 315 HELP: fp-qnan?
 316 { $values { "x" real } { "?" "a boolean" } }
 317 { $description "Tests if " { $snippet "x" } " is an IEEE Quiet Not-a-Number value. While " { $snippet "x" } " can be any real number, this word will only ever yield true if " { $snippet "x" } " is a " { $link float } "." } ;
 318
 319 HELP: fp-snan?
 320 { $values { "x" real } { "?" "a boolean" } }
 321 { $description "Tests if " { $snippet "x" } " is an IEEE Signaling Not-a-Number value. While " { $snippet "x" } " can be any real number, this word will only ever yield true if " { $snippet "x" } " is a " { $link float } "." } ;
 322
 323 HELP: fp-infinity?
 324 { $values { "x" real } { "?" "a boolean" } }
 325 { $description "Tests if " { $snippet "x" } " is an IEEE Infinity value. While " { $snippet "x" } " can be any real number, this word will only ever yield true if " { $snippet "x" } " is a " { $link float } "." }
 326 { $examples
 327     { $example "USING: math prettyprint ;" "1/0. fp-infinity? ." "t" }
 328     { $example "USING: io kernel math ;" "-1/0. [ fp-infinity? ] [ 0 < ] bi and [ \"negative infinity\" print ] when" "negative infinity" }
 329 } ;
 330
 331 HELP: fp-nan-payload
 332 { $values { "x" real } { "bits" integer } }
 333 { $description "If " { $snippet "x" } " is an IEEE Not-a-Number value, returns the payload encoded in the value. Returns " { $link f } " if " { $snippet "x" } " is not a " { $link float } "." } ;
 334
 335 HELP: <fp-nan>
 336 { $values { "payload" integer } { "nan" float } }
 337 { $description "Constructs an IEEE Not-a-Number value with a payload of " { $snippet "payload" } "." }
 338 { $notes "A " { $snippet "payload" } " of " { $snippet "0" } " will construct an Infinity value." } ;
 339
 340 { fp-special? fp-nan? fp-qnan? fp-snan? fp-infinity? fp-nan-payload <fp-nan> } related-words
 341
 342 HELP: next-float
 343 { $values { "m" float } { "n" float } }
 344 { $description "Returns the least representable " { $link float } " value greater than " { $snippet "m" } ", or in the case of " { $snippet "-0.0" } ", returns " { $snippet "+0.0" } "." } ;
 345
 346 HELP: prev-float
 347 { $values { "m" float } { "n" float } }
 348 { $description "Returns the greatest representable " { $link float } " value less than " { $snippet "m" } ", or in the case of " { $snippet "+0.0" } ", returns " { $snippet "-0.0" } "." } ;
 349
 350 { next-float prev-float } related-words
 351
 352 HELP: real-part
 353 { $values { "z" number } { "x" real } }
 354 { $description "Outputs the real part of a complex number. This acts as the identity on real numbers." }
 355 { $examples { $example "USING: math prettyprint ; C{ 1 2 } real-part ." "1" } } ;
 356
 357 HELP: imaginary-part
 358 { $values { "z" number } { "y" real } }
 359 { $description "Outputs the imaginary part of a complex number. This outputs zero for real numbers." }
 360 { $examples
 361     { $example "USING: math prettyprint ; C{ 1 2 } imaginary-part ." "2" }
 362     { $example "USING: math prettyprint ; 3 imaginary-part ." "0" }
 363 } ;
 364
 365 HELP: real
 366 { $class-description "The class of real numbers, which is a disjoint union of rationals and floats." } ;
 367
 368 HELP: number
 369 { $class-description "The class of numbers." } ;
 370
 371 HELP: next-power-of-2
 372 { $values { "m" "a non-negative integer" } { "n" "an integer" } }
 373 { $description "Outputs the smallest power of 2 greater than " { $snippet "m" } ". The output value is always at least 1." } ;
 374
 375 HELP: power-of-2?
 376 { $values { "n" integer } { "?" "a boolean" } }
 377 { $description "Tests if " { $snippet "n" } " is a power of 2." } ;
 378
 379 HELP: each-integer
 380 { $values { "n" integer } { "quot" { $quotation "( i -- )" } } }
 381 { $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } "." }
 382 { $notes "This word is used to implement " { $link each } "." } ;
 383
 384 HELP: all-integers?
 385 { $values { "n" integer } { "quot" { $quotation "( i -- ? )" } } { "?" "a boolean" } }
 386 { $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } ". Iteration stops when the quotation outputs " { $link f } " or the end is reached. If the quotation yields a false value for some integer, this word outputs " { $link f } ". Otherwise, this word outputs " { $link t } "." }
 387 { $notes "This word is used to implement " { $link all? } "." } ;
 388
 389 HELP: find-integer
 390 { $values { "n" integer } { "quot" { $quotation "( i -- ? )" } } { "i" "an integer or " { $link f } } }
 391 { $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } ". Iterationi stops when the quotation outputs a true value or the end is reached. If the quotation yields a true value for some integer, this word outputs that integer. Otherwise, this word outputs " { $link f } "." }
 392 { $notes "This word is used to implement " { $link find } "." } ;
 393
 394 HELP: find-last-integer
 395 { $values { "n" integer } { "quot" { $quotation "( i -- ? )" } } { "i" "an integer or " { $link f } } }
 396 { $description "Applies the quotation to each integer from " { $snippet "n" } " down to 0, inclusive. Iteration stops when the quotation outputs a true value or 0 is reached. If the quotation yields a true value for some integer, the word outputs that integer. Otherwise, the word outputs " { $link f } "." }
 397 { $notes "This word is used to implement " { $link find-last } "." } ;
 398
 399 HELP: byte-array>bignum
 400 { $values { "x" byte-array } { "y" bignum } }
 401 { $description "Converts a byte-array, interpreted as little-endian, into a bignum integer. User code should call " { $link le> } " or " { $link be> } " instead." } ;
 402
 403 ARTICLE: "division-by-zero" "Division by zero"
 404 "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."
 405 $nl
 406 "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."
 407 $nl
 408 "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." ;
 409
 410 ARTICLE: "number-protocol" "Number protocol"
 411 "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."
 412 $nl
 413 "Two examples where you should note the types of the inputs and outputs:"
 414 { $example "USE: classes" "3 >fixnum 6 >bignum * class ." "bignum" }
 415 { $example "1/2 2.0 + ." "2.5" }
 416 "The following usual operations are supported by all numbers."
 417 { $subsection + }
 418 { $subsection - }
 419 { $subsection * }
 420 { $subsection / }
 421 "Non-commutative operations take operands from the stack in the natural order; " { $snippet "6 2 /" } " divides 6 by 2."
 422 { $subsection "division-by-zero" }
 423 "Real numbers (but not complex numbers) can be ordered:"
 424 { $subsection < }
 425 { $subsection <= }
 426 { $subsection > }
 427 { $subsection >= }
 428 "Numbers can be compared for equality using " { $link = } ", or a less precise test which disregards types:"
 429 { $subsection number= } ;
 430
 431 ARTICLE: "modular-arithmetic" "Modular arithmetic"
 432 { $subsection mod }
 433 { $subsection rem }
 434 { $subsection /mod }
 435 { $subsection /i }
 436 { $see-also "integer-functions" } ;
 437
 438 ARTICLE: "bitwise-arithmetic" "Bitwise arithmetic"
 439 "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" } "."
 440 { $subsection bitand }
 441 { $subsection bitor }
 442 { $subsection bitxor }
 443 { $subsection bitnot }
 444 { $subsection shift }
 445 { $subsection 2/ }
 446 { $subsection 2^ }
 447 { $subsection bit? }
 448 "Advanced topics:"
 449 { $subsection "math.bitwise" }
 450 { $subsection "math.bits" }
 451 { $see-also "booleans" } ;
 452
 453 ARTICLE: "arithmetic" "Arithmetic"
 454 "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."
 455 $nl
 456 "Math words are in the " { $vocab-link "math" } " vocabulary. Implementation details are in the " { $vocab-link "math.private" } " vocabulary."
 457 { $subsection "number-protocol" }
 458 { $subsection "modular-arithmetic" }
 459 { $subsection "bitwise-arithmetic" }
 460 { $see-also "integers" "rationals" "floats" "complex-numbers" } ;
 461
 462 ABOUT: "arithmetic"
 463