core/math/math-docs.factor

   1 USING: help.markup help.syntax kernel quotations sequences ;
   2 IN: math
   3
   4 HELP: number=
   5 { $values { "x" number } { "y" number } { "?" boolean } }
   6 { $description "Tests if two numbers have the same numeric value." }
   7 { $notes "This word differs from " { $link = } " in that it disregards differences in type when comparing numbers."
   8 $nl
   9 "This word performs an unordered comparison on floating point numbers. See " { $link "math.floats.compare" } " for an explanation." }
  10 { $examples
  11     { $example "USING: math prettyprint ;" "3.0 3 number= ." "t" }
  12     { $example "USING: kernel math prettyprint ;" "3.0 3 = ." "f" }
  13 } ;
  14
  15 HELP: <
  16 { $values { "x" real } { "y" real } { "?" boolean } }
  17 { $description "Tests if " { $snippet "x" } " is less than " { $snippet "y" } "." }
  18 { $notes "This word performs an ordered comparison on floating point numbers. See " { $link "math.floats.compare" } " for an explanation." } ;
  19
  20 HELP: <=
  21 { $values { "x" real } { "y" real } { "?" boolean } }
  22 { $description "Tests if " { $snippet "x" } " is less than or equal to " { $snippet "y" } "." }
  23 { $notes "This word performs an ordered comparison on floating point numbers. See " { $link "math.floats.compare" } " for an explanation." } ;
  24
  25 HELP: >
  26 { $values { "x" real } { "y" real } { "?" boolean } }
  27 { $description "Tests if " { $snippet "x" } " is greater than " { $snippet "y" } "." }
  28 { $notes "This word performs an ordered comparison on floating point numbers. See " { $link "math.floats.compare" } " for an explanation." } ;
  29
  30 HELP: >=
  31 { $values { "x" real } { "y" real } { "?" boolean } }
  32 { $description "Tests if " { $snippet "x" } " is greater than or equal to " { $snippet "y" } "." }
  33 { $notes "This word performs an ordered comparison on floating point numbers. See " { $link "math.floats.compare" } " for an explanation." } ;
  34
  35 HELP: unordered?
  36 { $values { "x" real } { "y" real } { "?" boolean } }
  37 { $description "Tests if " { $snippet "x" } " is unordered with respect to " { $snippet "y" } ". This can only occur if one or both values is a floating-point Not-a-Number value." } ;
  38
  39 HELP: u<
  40 { $values { "x" real } { "y" real } { "?" boolean } }
  41 { $description "Tests if " { $snippet "x" } " is less than " { $snippet "y" } "." }
  42 { $notes "This word performs an unordered comparison on floating point numbers. On rational numbers it is equivalent to " { $link < } ". See " { $link "math.floats.compare" } " for an explanation." } ;
  43
  44 HELP: u<=
  45 { $values { "x" real } { "y" real } { "?" boolean } }
  46 { $description "Tests if " { $snippet "x" } " is less than or equal to " { $snippet "y" } "." }
  47 { $notes "This word performs an unordered comparison on floating point numbers. On rational numbers it is equivalent to " { $link <= } ". See " { $link "math.floats.compare" } " for an explanation." } ;
  48
  49 HELP: u>
  50 { $values { "x" real } { "y" real } { "?" boolean } }
  51 { $description "Tests if " { $snippet "x" } " is greater than " { $snippet "y" } "." }
  52 { $notes "This word performs an unordered comparison on floating point numbers. On rational numbers it is equivalent to " { $link > } ". See " { $link "math.floats.compare" } " for an explanation." } ;
  53
  54 HELP: u>=
  55 { $values { "x" real } { "y" real } { "?" boolean } }
  56 { $description "Tests if " { $snippet "x" } " is greater than or equal to " { $snippet "y" } "." }
  57 { $notes "This word performs an unordered comparison on floating point numbers. On rational numbers it is equivalent to " { $link >= } ". See " { $link "math.floats.compare" } " for an explanation." } ;
  58
  59 HELP: +
  60 { $values { "x" number } { "y" number } { "z" number } }
  61 { $description
  62     "Adds two numbers."
  63     { $list
  64         "Addition of fixnums may overflow and convert the result to a bignum."
  65         "Addition of bignums always yields a bignum."
  66         "Addition of floats always yields a float."
  67         "Addition of ratios and complex numbers proceeds using the relevant mathematical rules."
  68     }
  69 } ;
  70
  71 HELP: -
  72 { $values { "x" number } { "y" number } { "z" number } }
  73 { $description
  74     "Subtracts " { $snippet "y" } " from " { $snippet "x" } "."
  75     { $list
  76         "Subtraction of fixnums may overflow and convert the result to a bignum."
  77         "Subtraction of bignums always yields a bignum."
  78         "Subtraction of floats always yields a float."
  79         "Subtraction of ratios and complex numbers proceeds using the relevant mathematical rules."
  80     }
  81 } ;
  82
  83 HELP: *
  84 { $values { "x" number } { "y" number } { "z" number } }
  85 { $description
  86     "Multiplies two numbers."
  87     { $list
  88         "Multiplication of fixnums may overflow and convert the result to a bignum."
  89         "Multiplication of bignums always yields a bignum."
  90         "Multiplication of floats always yields a float."
  91         "Multiplication of ratios and complex numbers proceeds using the relevant mathematical rules."
  92     }
  93 } ;
  94
  95 HELP: /
  96 { $values { "x" number } { "y" number } { "z" number } }
  97 { $description
  98     "Divides " { $snippet "x" } " by " { $snippet "y" } ", retaining as much precision as possible."
  99     { $list
 100         "Division of fixnums may yield a ratio, or overflow and yield a bignum."
 101         "Division of bignums may yield a ratio."
 102         "Division of floats always yields a float."
 103         "Division of ratios and complex numbers proceeds using the relevant mathematical rules."
 104     }
 105 }
 106 { $see-also "division-by-zero" } ;
 107
 108 HELP: /i
 109 { $values { "x" real } { "y" real } { "z" integer } }
 110 { $description
 111     "Divides " { $snippet "x" } " by " { $snippet "y" } ", truncating the result to an integer."
 112 }
 113 { $see-also "division-by-zero" } ;
 114
 115 HELP: /f
 116 { $values { "x" real } { "y" real } { "z" float } }
 117 { $description
 118     "Divides " { $snippet "x" } " by " { $snippet "y" } ", representing the result as a floating point number."
 119 }
 120 { $see-also "division-by-zero" } ;
 121
 122 HELP: mod
 123 { $values { "x" rational } { "y" rational } { "z" rational } }
 124 { $description
 125     "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
 126     { $list
 127         "Modulus of fixnums always yields a fixnum."
 128         "Modulus of bignums always yields a bignum."
 129         { "Modulus of rationals always yields a rational. In this case, the remainder is computed using the formula " { $snippet "x - (x mod y) * y" } "." }
 130     }
 131 }
 132 { $see-also "division-by-zero" rem } ;
 133
 134 HELP: /mod
 135 { $values { "x" real } { "y" real } { "z" integer } { "w" real } }
 136 { $description
 137     "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."
 138     { $list
 139         "The quotient of two fixnums may overflow and yield a bignum; the remainder is always a fixnum"
 140         "The quotient and remainder of two bignums is always a bignum."
 141     }
 142 }
 143 { $examples
 144     { $example "USING: kernel math prettyprint ;" "5 3 /mod [ . ] bi@" "1\n2" }
 145     { $example "USING: kernel math prettyprint ;" "5/2 1/3 /mod [ . ] bi@" "7\n1/6" }
 146 }
 147 { $see-also "division-by-zero" } ;
 148
 149 HELP: bitand
 150 { $values { "x" integer } { "y" integer } { "z" integer } }
 151 { $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in both inputs." }
 152 { $examples
 153     { $example "USING: math prettyprint ;" "0b101 0b10 bitand .b" "0b0" }
 154     { $example "USING: math prettyprint ;" "0b110 0b10 bitand .b" "0b10" }
 155 }
 156 { $notes "This word implements bitwise and, so applying it to booleans will throw an error. Boolean and is the " { $link and } " word." } ;
 157
 158 HELP: bitor
 159 { $values { "x" integer } { "y" integer } { "z" integer } }
 160 { $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." }
 161 { $examples
 162     { $example "USING: math prettyprint ;" "0b101 0b10 bitor .b" "0b111" }
 163     { $example "USING: math prettyprint ;" "0b110 0b10 bitor .b" "0b110" }
 164 }
 165 { $notes "This word implements bitwise inclusive or, so applying it to booleans will throw an error. Boolean inclusive or is the " { $link and } " word." } ;
 166
 167 HELP: bitxor
 168 { $values { "x" integer } { "y" integer } { "z" integer } }
 169 { $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." }
 170 { $examples
 171     { $example "USING: math prettyprint ;" "0b101 0b10 bitxor .b" "0b111" }
 172     { $example "USING: math prettyprint ;" "0b110 0b10 bitxor .b" "0b100" }
 173 }
 174 { $notes "This word implements bitwise exclusive or, so applying it to booleans will throw an error. Boolean exclusive or is the " { $link xor } " word." } ;
 175
 176 HELP: shift
 177 { $values { "x" integer } { "n" integer } { "y" integer } }
 178 { $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." }
 179 { $examples { $example "USING: math prettyprint ;" "0b101 5 shift .b" "0b10100000" } { $example "USING: math prettyprint ;" "0b11111 -2 shift .b" "0b111" } } ;
 180
 181 HELP: bitnot
 182 { $values { "x" integer } { "y" integer } }
 183 { $description "Computes the bitwise complement of the input; that is, each bit in the input number is flipped." }
 184 { $notes "This word implements bitwise not, so applying it to booleans will throw an error. Boolean not is the " { $link not } " word."
 185 $nl
 186 "Due to the two's complement representation of signed integers, the following two lines are equivalent:" { $code "bitnot" "neg 1 -" } } ;
 187
 188 HELP: bit?
 189 { $values { "x" integer } { "n" integer } { "?" boolean } }
 190 { $description "Tests if the " { $snippet "n" } "th bit of " { $snippet "x" } " is set." }
 191 { $examples { $example "USING: math prettyprint ;" "0b101 2 bit? ." "t" } } ;
 192
 193 HELP: log2
 194 { $values { "x" "a positive integer" } { "n" integer } }
 195 { $description "Outputs the largest integer " { $snippet "n" } " such that " { $snippet "2^n" } " is less than or equal to " { $snippet "x" } "." }
 196 { $errors "Throws an error if " { $snippet "x" } " is zero or negative." } ;
 197
 198 HELP: ?1+
 199 { $values { "x" { $maybe number } } { "y" number } }
 200 { $description "If the input is not " { $link f } ", adds one. Otherwise, outputs a " { $snippet "0" } "." } ;
 201
 202 HELP: sq
 203 { $values { "x" number } { "y" number } }
 204 { $description "Multiplies a number by itself." } ;
 205
 206 HELP: neg
 207 { $values { "x" number } { "-x" number } }
 208 { $description "Computes a number's additive inverse." } ;
 209
 210 HELP: recip
 211 { $values { "x" number } { "y" number } }
 212 { $description "Computes a number's multiplicative inverse." }
 213 { $errors "Throws an error if " { $snippet "x" } " is the integer 0." } ;
 214
 215 HELP: rem
 216 { $values { "x" rational } { "y" rational } { "z" rational } }
 217 { $description
 218     "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder always positive or zero."
 219     { $list
 220         "Given fixnums, always yields a fixnum."
 221         "Given bignums, always yields a bignum."
 222         "Given rationals, always yields a rational."
 223     }
 224 }
 225 { $see-also "division-by-zero" mod } ;
 226
 227 HELP: sgn
 228 { $values { "x" real } { "n" "-1, 0 or 1" } }
 229 { $description
 230     "Outputs one of the following:"
 231     { $list
 232         { "-1 if " { $snippet "x" } " is negative" }
 233         { "0 if " { $snippet "x" } " is equal to 0" }
 234         { "1 if " { $snippet "x" } " is positive" }
 235     }
 236 } ;
 237
 238 HELP: rect>
 239 { $values { "x" real } { "y" real } { "z" number } }
 240 { $description "Creates a complex number from real and imaginary components. If " { $snippet "z" } " is an integer zero, this will simply output " { $snippet "x" } "." } ;
 241
 242 HELP: >rect
 243 { $values { "z" number } { "x" real } { "y" real } }
 244 { $description "Extracts the real and imaginary components of a complex number." } ;
 245
 246 HELP: gcd
 247 { $values { "x" integer } { "y" integer } { "a" integer } { "d" integer } }
 248 { $description "Computes the positive greatest common divisor " { $snippet "d" } " of " { $snippet "x" } " and " { $snippet "y" } ", and another value " { $snippet "a" } " satisfying:" { $code "(a*x - d) mod y == 0" } }
 249 { $notes "If " { $snippet "d" } " is 1, then " { $snippet "a" } " is the inverse of " { $snippet "y" } " modulo " { $snippet "x" } "." } ;
 250
 251 HELP: lcm
 252 { $values { "a" integer } { "b" integer } { "c" integer } }
 253 { $description "Computes the least common multiple of " { $snippet "a" } " and " { $snippet "b" } ". If either of the arguments is zero, then the returned value is zero." }
 254 { $examples
 255     { $example "USING: math prettyprint ;" "10 5 lcm ." "10" }
 256     { $example "USING: math prettyprint ;" "10 3 lcm ." "30" }
 257     { $example "USING: math prettyprint ;" "10 8 lcm ." "40" }
 258     { $example "USING: math prettyprint ;" "10 0 lcm ." "0" }
 259     { $example "USING: math prettyprint ;" "0 0 lcm ." "0" }
 260     { $example "USING: math prettyprint ;" "1/3 1/6 lcm ." "1/3" }
 261 } ;
 262
 263 HELP: 2/
 264 { $values { "x" integer } { "y" integer } }
 265 { $description "Shifts " { $snippet "x" } " to the right by one bit." }
 266 { $examples
 267     { $example "USING: math prettyprint ;" "14 2/ ." "7" }
 268     { $example "USING: math prettyprint ;" "17 2/ ." "8" }
 269     { $example "USING: math prettyprint ;" "-17 2/ ." "-9" }
 270 }
 271 { $notes "This word is not equivalent to " { $snippet "2 /" } " or " { $snippet "2 /i" } "; the name is historic and originates from the Forth programming language." } ;
 272
 273 HELP: 2^
 274 { $values { "n" "a positive integer" } { "2^n" "a positive integer" } }
 275 { $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 ^" } "." } ;
 276
 277 HELP: zero?
 278 { $values { "x" number } { "?" boolean } }
 279 { $description "Tests if the number is equal to zero." } ;
 280
 281 HELP: if-zero
 282 { $values { "n" number } { "quot1" quotation } { "quot2" quotation } }
 283 { $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." }
 284 { $example
 285     "USING: kernel math prettyprint sequences ;"
 286     "3 [ \"zero\" ] [ sq ] if-zero ."
 287     "9"
 288 } ;
 289
 290 HELP: when-zero
 291 { $values
 292     { "n" number } { "quot" "the first quotation of an " { $link if-zero } } { "x" object } }
 293 { $description "Makes an implicit check if the number is zero. A zero is dropped and the " { $snippet "quot" } " is called." }
 294 { $examples "This word is equivalent to " { $link if-zero } " with an empty second quotation:"
 295     { $example
 296     "USING: math prettyprint ;"
 297     "0 [ 4 ] [ ] if-zero ."
 298     "4"
 299     }
 300     { $example
 301     "USING: math prettyprint ;"
 302     "0 [ 4 ] when-zero ."
 303     "4"
 304     }
 305 } ;
 306
 307 HELP: unless-zero
 308 { $values
 309     { "n" number } { "quot" "the second quotation of an " { $link if-zero } } }
 310 { $description "Makes an implicit check if the number is zero. A zero is dropped. Otherwise, the " { $snippet "quot" } " is called on the number." }
 311 { $examples "This word is equivalent to " { $link if-zero } " with an empty first quotation:"
 312     { $example
 313     "USING: sequences math prettyprint ;"
 314     "3 [ ] [ sq . ] if-zero"
 315     "9"
 316     }
 317     { $example
 318     "USING: sequences math prettyprint ;"
 319     "3 [ sq . ] unless-zero"
 320     "9"
 321     }
 322 } ;
 323
 324 HELP: until-zero
 325 { $values
 326     { "n" number } { "quot" { $quotation ( ... x -- ... y ) } } }
 327 { $description "Makes a check if the number is zero, and repeatedly calls " { $snippet "quot" } " until the value on the stack is zero." }
 328 { $examples
 329     { $example
 330     "USING: kernel math prettyprint ;"
 331     "15 [ dup . 2/ ] until-zero"
 332     "15\n7\n3\n1"
 333     }
 334 } ;
 335
 336 { if-zero when-zero unless-zero until-zero } related-words
 337
 338 HELP: times
 339 { $values { "n" integer } { "quot" quotation } }
 340 { $description "Calls the quotation " { $snippet "n" } " times." }
 341 { $notes "If you need to pass the current index to the quotation, use " { $link each-integer } "." }
 342 { $examples
 343     { $example "USING: io math ;" "3 [ \"Hi\" print ] times" "Hi\nHi\nHi" }
 344 } ;
 345
 346 HELP: fp-bitwise=
 347 { $values
 348     { "x" float } { "y" float }
 349     { "?" boolean }
 350 }
 351 { $description "Compares two floating point numbers for bit equality." }
 352 { $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." }
 353 { $examples
 354     "Not-a-number equality:"
 355     { $example
 356         "USING: kernel math prettyprint ;"
 357         "0.0 0.0 / dup number= ."
 358         "f"
 359     }
 360     { $example
 361         "USING: kernel math prettyprint ;"
 362         "0.0 0.0 / dup fp-bitwise= ."
 363         "t"
 364     }
 365     "Signed zero equality:"
 366     { $example
 367         "USING: math prettyprint ;"
 368         "-0.0 0.0 fp-bitwise= ."
 369         "f"
 370     }
 371     { $example
 372         "USING: math prettyprint ;"
 373         "-0.0 0.0 number= ."
 374         "t"
 375     }
 376 } ;
 377
 378 HELP: fp-special?
 379 { $values { "x" real } { "?" boolean } }
 380 { $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 } "." } ;
 381
 382 HELP: fp-nan?
 383 { $values { "x" real } { "?" boolean } }
 384 { $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 } "." } ;
 385
 386 HELP: fp-qnan?
 387 { $values { "x" real } { "?" boolean } }
 388 { $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 } "." } ;
 389
 390 HELP: fp-snan?
 391 { $values { "x" real } { "?" boolean } }
 392 { $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 } "." } ;
 393
 394 HELP: fp-infinity?
 395 { $values { "x" real } { "?" boolean } }
 396 { $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 } "." }
 397 { $examples
 398     { $example "USING: math prettyprint ;" "1/0. fp-infinity? ." "t" }
 399     { $example "USING: io kernel math ;" "-1/0. [ fp-infinity? ] [ 0 < ] bi and [ \"negative infinity\" print ] when" "negative infinity" }
 400 } ;
 401
 402 HELP: fp-sign
 403 { $values { "x" float } { "?" boolean } }
 404 { $description "Outputs the sign bit of " { $snippet "x" } ". For ordered non-zero values, this is equivalent to calling " { $snippet "0 <" } ". For zero values, this outputs the zero's sign bit." } ;
 405
 406 HELP: fp-nan-payload
 407 { $values { "x" real } { "bits" integer } }
 408 { $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 } "." } ;
 409
 410 HELP: <fp-nan>
 411 { $values { "payload" integer } { "nan" float } }
 412 { $description "Constructs an IEEE Not-a-Number value with a payload of " { $snippet "payload" } "." }
 413 { $notes "A " { $snippet "payload" } " of " { $snippet "0" } " will construct an Infinity value." } ;
 414
 415 { fp-special? fp-nan? fp-qnan? fp-snan? fp-infinity? fp-nan-payload <fp-nan> } related-words
 416
 417 HELP: next-float
 418 { $values { "m" float } { "n" float } }
 419 { $description "Returns the least representable " { $link float } " value greater than " { $snippet "m" } ", or in the case of " { $snippet "-0.0" } ", returns " { $snippet "+0.0" } "." } ;
 420
 421 HELP: prev-float
 422 { $values { "m" float } { "n" float } }
 423 { $description "Returns the greatest representable " { $link float } " value less than " { $snippet "m" } ", or in the case of " { $snippet "+0.0" } ", returns " { $snippet "-0.0" } "." } ;
 424
 425 { next-float prev-float } related-words
 426
 427 HELP: real-part
 428 { $values { "z" number } { "x" real } }
 429 { $description "Outputs the real part of a complex number. This acts as the identity on real numbers." }
 430 { $examples { $example "USING: math prettyprint ;" "C{ 1 2 } real-part ." "1" } } ;
 431
 432 HELP: imaginary-part
 433 { $values { "z" number } { "y" real } }
 434 { $description "Outputs the imaginary part of a complex number. This outputs zero for real numbers." }
 435 { $examples
 436     { $example "USING: math prettyprint ;" "C{ 1 2 } imaginary-part ." "2" }
 437     { $example "USING: math prettyprint ;" "3 imaginary-part ." "0" }
 438 } ;
 439
 440 HELP: real
 441 { $class-description "The class of real numbers, which is a disjoint union of rationals and floats." } ;
 442
 443 HELP: number
 444 { $class-description "The class of numbers." } ;
 445
 446 HELP: next-power-of-2
 447 { $values { "m" "a non-negative integer" } { "n" integer } }
 448 { $description "Outputs the smallest power of 2 greater than or equal to " { $snippet "m" } ". The output value is always at least 2." } ;
 449
 450 HELP: power-of-2?
 451 { $values { "n" integer } { "?" boolean } }
 452 { $description "Tests if " { $snippet "n" } " is a power of 2." } ;
 453
 454 HELP: each-integer
 455 { $values { "n" integer } { "quot" { $quotation ( ... i -- ... ) } } }
 456 { $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } "." }
 457 { $notes "This word is used to implement " { $link each } "." } ;
 458
 459 HELP: all-integers?
 460 { $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "?" boolean } }
 461 { $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 } "." }
 462 { $notes "This word is used to implement " { $link all? } "." } ;
 463
 464 HELP: find-integer-from
 465 { $values { "i" integer } { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i/f" { $maybe integer } } }
 466 { $description "Applies the quotation to each integer from " { $snippet "i" } " up to " { $snippet "n" } ", excluding " { $snippet "n" } ". Iteration 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 } "." }
 467 { $notes "This word is used to implement " { $link find-integer } " and " { $link find } "." } ;
 468
 469 HELP: find-integer
 470 { $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i/f" { $maybe integer } } }
 471 { $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } ". Iteration 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 } "." }
 472 { $notes "This word is used to implement " { $link find } "." } ;
 473
 474 HELP: find-last-integer
 475 { $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i/f" { $maybe integer } } }
 476 { $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 } "." }
 477 { $notes "This word is used to implement " { $link find-last } "." } ;
 478
 479 HELP: all-integers-from?
 480 { $values
 481     { "from" integer } { "to" integer } { "quot" quotation }
 482     { "?" boolean }
 483 }
 484 { $description "Applies the quotation to each integer in " { $snippet "[from..to)" } ", returning " { $link t } " if all results are true, " and { $link f } " otherwise." } ;
 485
 486 HELP: each-integer-from
 487 { $values
 488     { "from" integer } { "to" integer } { "quot" quotation }
 489 }
 490 { $description "Applies the quotation to each integer in " { $snippet "[from..to)" } " in order." } ;
 491
 492 HELP: integer>fixnum
 493 { $values
 494     { "x" object }
 495     { "y" object }
 496 }
 497 { $description "Converts a general integer to a fixed-width integer." } ;
 498
 499 HELP: integer>fixnum-strict
 500 { $values
 501     { "x" object }
 502     { "y" object }
 503 }
 504 { $description "Converts a general integer to a fixed-width integer." } ;
 505
 506 HELP: neg?
 507 { $values
 508     { "x" object }
 509     { "?" boolean }
 510 }
 511 { $description "Pushes " { $link t } " if " { $snippet "x" } " is negative, else " { $link f } } ;
 512
 513 HELP: simple-gcd
 514 { $values
 515     { "x" object } { "y" object }
 516     { "d" object }
 517 }
 518 { $description "Computes the GCD of two numbers." }
 519 { $see-also gcd } ;
 520
 521 ARTICLE: "division-by-zero" "Division by zero"
 522 "Behavior of division operations when a denominator of zero is used depends on the data types in question, as well as the platform being used."
 523 $nl
 524 "Floating point division only throws an error if the appropriate traps are enabled in the floating point environment. If traps are disabled, a Not-a-number value or an infinity is output, depending on whether the numerator is zero or non-zero."
 525 $nl
 526 "Floating point traps are disabled by default and the " { $vocab-link "math.floats.env" } " vocabulary provides words to enable them. Floating point division is performed by " { $link / } ", " { $link /f } " or " { $link mod } " if at least one of the two inputs is a float. Floating point division is always performed by " { $link /f } "."
 527 $nl
 528 "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."
 529 $nl
 530 "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." ;
 531
 532 ARTICLE: "number-protocol" "Number protocol"
 533 "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."
 534 $nl
 535 "Two examples where you should note the types of the inputs and outputs:"
 536 { $example "USE: classes" "3 >fixnum 6 >bignum * class-of ." "bignum" }
 537 { $example "1/2 2.0 + ." "2.5" }
 538 "The following usual operations are supported by all numbers."
 539 { $subsections
 540     +
 541     -
 542     *
 543     /
 544 }
 545 "Non-commutative operations take operands from the stack in the natural order; " { $snippet "6 2 /" } " divides 6 by 2."
 546 { $subsections "division-by-zero" }
 547 "Real numbers (but not complex numbers) can be ordered:"
 548 { $subsections
 549     <
 550     <=
 551     >
 552     >=
 553 }
 554 "Numbers can be compared for equality using " { $link = } ", or a less precise test which disregards types:"
 555 { $subsections number= }
 556 { $see-also "math.floats.compare" } ;
 557
 558 ARTICLE: "modular-arithmetic" "Modular arithmetic"
 559 { $subsections
 560     mod
 561     rem
 562     /mod
 563     /i
 564 }
 565 { $see-also "integer-functions" } ;
 566
 567 ARTICLE: "bitwise-arithmetic" "Bitwise arithmetic"
 568 "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" } "."
 569 { $subsections
 570     bitand
 571     bitor
 572     bitxor
 573     bitnot
 574     shift
 575     2/
 576     2^
 577     bit?
 578 }
 579 "Advanced topics:"
 580 { $subsections
 581     "math.bitwise"
 582     "math.bits"
 583 }
 584 { $see-also "booleans" } ;
 585
 586 ARTICLE: "arithmetic" "Arithmetic"
 587 "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."
 588 $nl
 589 "Math words are in the " { $vocab-link "math" } " vocabulary. Implementation details are in the " { $vocab-link "math.private" } " vocabulary."
 590 { $subsections
 591     "number-protocol"
 592     "modular-arithmetic"
 593     "bitwise-arithmetic"
 594 }
 595 { $see-also "integers" "rationals" "floats" "complex-numbers" } ;
 596
 597 ABOUT: "arithmetic"