{ $values { "x" rational } { "y" rational } { "z" rational } }
{ $description
"Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
- { $list
+ { $list
"Modulus of fixnums always yields a fixnum."
- "Modulus of bignums always yields a bignum."
+ "Modulus of bignums always yields a bignum."
{ "Modulus of rationals always yields a rational. In this case, the remainder is computed using the formula " { $snippet "x - (x mod y) * y" } "." }
}
}
{ $values { "x" integer } { "y" integer } { "z" integer } { "w" integer } }
{ $description
"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."
- { $list
+ { $list
"The quotient of two fixnums may overflow and yield a bignum; the remainder is always a fixnum"
- "The quotient and remainder of two bignums is always a bignum."
+ "The quotient and remainder of two bignums is always a bignum."
}
}
{ $see-also "division-by-zero" } ;
{ $values { "x" integer } { "y" integer } { "z" integer } }
{ $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in both inputs." }
{ $examples
- { $example "USING: math prettyprint ;" "BIN: 101 BIN: 10 bitand .b" "0" }
- { $example "USING: math prettyprint ;" "BIN: 110 BIN: 10 bitand .b" "10" }
+ { $example "USING: math prettyprint ;" "0b101 0b10 bitand .b" "0" }
+ { $example "USING: math prettyprint ;" "0b110 0b10 bitand .b" "10" }
}
{ $notes "This word implements bitwise and, so applying it to booleans will throw an error. Boolean and is the " { $link and } " word." } ;
{ $values { "x" integer } { "y" integer } { "z" integer } }
{ $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." }
{ $examples
- { $example "USING: math prettyprint ;" "BIN: 101 BIN: 10 bitor .b" "111" }
- { $example "USING: math prettyprint ;" "BIN: 110 BIN: 10 bitor .b" "110" }
+ { $example "USING: math prettyprint ;" "0b101 0b10 bitor .b" "111" }
+ { $example "USING: math prettyprint ;" "0b110 0b10 bitor .b" "110" }
}
{ $notes "This word implements bitwise inclusive or, so applying it to booleans will throw an error. Boolean inclusive or is the " { $link and } " word." } ;
{ $values { "x" integer } { "y" integer } { "z" integer } }
{ $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." }
{ $examples
- { $example "USING: math prettyprint ;" "BIN: 101 BIN: 10 bitxor .b" "111" }
- { $example "USING: math prettyprint ;" "BIN: 110 BIN: 10 bitxor .b" "100" }
+ { $example "USING: math prettyprint ;" "0b101 0b10 bitxor .b" "111" }
+ { $example "USING: math prettyprint ;" "0b110 0b10 bitxor .b" "100" }
}
{ $notes "This word implements bitwise exclusive or, so applying it to booleans will throw an error. Boolean exclusive or is the " { $link xor } " word." } ;
HELP: shift
{ $values { "x" integer } { "n" integer } { "y" integer } }
{ $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." }
-{ $examples { $example "USING: math prettyprint ;" "BIN: 101 5 shift .b" "10100000" } { $example "USING: math prettyprint ;" "BIN: 11111 -2 shift .b" "111" } } ;
+{ $examples { $example "USING: math prettyprint ;" "0b101 5 shift .b" "10100000" } { $example "USING: math prettyprint ;" "0b11111 -2 shift .b" "111" } } ;
HELP: bitnot
{ $values { "x" integer } { "y" integer } }
HELP: bit?
{ $values { "x" integer } { "n" integer } { "?" "a boolean" } }
{ $description "Tests if the " { $snippet "n" } "th bit of " { $snippet "x" } " is set." }
-{ $examples { $example "USING: math prettyprint ;" "BIN: 101 2 bit? ." "t" } } ;
+{ $examples { $example "USING: math prettyprint ;" "0b101 2 bit? ." "t" } } ;
HELP: log2
{ $values { "x" "a positive integer" } { "n" integer } }
HELP: rem
{ $values { "x" rational } { "y" rational } { "z" rational } }
{ $description
- "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder always positive."
- { $list
+ "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder always positive or zero."
+ { $list
"Given fixnums, always yields a fixnum."
"Given bignums, always yields a bignum."
- "Given rationals, always yields a rational."
+ "Given rationals, always yields a rational."
}
}
{ $see-also "division-by-zero" mod } ;
HELP: 2^
{ $values { "n" "a positive integer" } { "2^n" "a positive integer" } }
-{ $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 ^" } "." } ;
+{ $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 ^" } "." } ;
HELP: zero?
{ $values { "x" number } { "?" "a boolean" } }
HELP: when-zero
{ $values
{ "n" number } { "quot" "the first quotation of an " { $link if-zero } } }
-{ $description "Makes an implicit check if the sequence is empty. A zero is dropped and the " { $snippet "quot" } " is called." }
+{ $description "Makes an implicit check if the number is zero. A zero is dropped and the " { $snippet "quot" } " is called." }
{ $examples "This word is equivalent to " { $link if-zero } " with an empty second quotation:"
{ $example
"USING: math prettyprint ;"
{ $examples "This word is equivalent to " { $link if-zero } " with an empty first quotation:"
{ $example
"USING: sequences math prettyprint ;"
- "3 [ ] [ sq ] if-empty ."
+ "3 [ ] [ sq ] if-zero ."
"9"
}
{ $example
HELP: real-part
{ $values { "z" number } { "x" real } }
{ $description "Outputs the real part of a complex number. This acts as the identity on real numbers." }
-{ $examples { $example "USING: math prettyprint ; C{ 1 2 } real-part ." "1" } } ;
+{ $examples { $example "USING: math prettyprint ;" "C{ 1 2 } real-part ." "1" } } ;
HELP: imaginary-part
{ $values { "z" number } { "y" real } }
{ $description "Outputs the imaginary part of a complex number. This outputs zero for real numbers." }
{ $examples
- { $example "USING: math prettyprint ; C{ 1 2 } imaginary-part ." "2" }
- { $example "USING: math prettyprint ; 3 imaginary-part ." "0" }
+ { $example "USING: math prettyprint ;" "C{ 1 2 } imaginary-part ." "2" }
+ { $example "USING: math prettyprint ;" "3 imaginary-part ." "0" }
} ;
HELP: real
HELP: next-power-of-2
{ $values { "m" "a non-negative integer" } { "n" "an integer" } }
-{ $description "Outputs the smallest power of 2 greater than " { $snippet "m" } ". The output value is always at least 1." } ;
+{ $description "Outputs the smallest power of 2 greater than " { $snippet "m" } ". The output value is always at least 2." } ;
HELP: power-of-2?
{ $values { "n" integer } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "n" } " is a power of 2." } ;
HELP: each-integer
-{ $values { "n" integer } { "quot" { $quotation "( i -- )" } } }
+{ $values { "n" integer } { "quot" { $quotation "( ... i -- ... )" } } }
{ $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } "." }
{ $notes "This word is used to implement " { $link each } "." } ;
HELP: all-integers?
-{ $values { "n" integer } { "quot" { $quotation "( i -- ? )" } } { "?" "a boolean" } }
+{ $values { "n" integer } { "quot" { $quotation "( ... i -- ... ? )" } } { "?" "a boolean" } }
{ $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 } "." }
{ $notes "This word is used to implement " { $link all? } "." } ;
HELP: find-integer
-{ $values { "n" integer } { "quot" { $quotation "( i -- ? )" } } { "i" "an integer or " { $link f } } }
-{ $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 } "." }
+{ $values { "n" integer } { "quot" { $quotation "( ... i -- ... ? )" } } { "i" "an integer or " { $link f } } }
+{ $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 } "." }
{ $notes "This word is used to implement " { $link find } "." } ;
HELP: find-last-integer
-{ $values { "n" integer } { "quot" { $quotation "( i -- ? )" } } { "i" "an integer or " { $link f } } }
+{ $values { "n" integer } { "quot" { $quotation "( ... i -- ... ? )" } } { "i" "an integer or " { $link f } } }
{ $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 } "." }
{ $notes "This word is used to implement " { $link find-last } "." } ;
-HELP: byte-array>bignum
-{ $values { "x" byte-array } { "y" bignum } }
-{ $description "Converts a byte-array, interpreted as little-endian, into a bignum integer. User code should call " { $link le> } " or " { $link be> } " instead." } ;
-
ARTICLE: "division-by-zero" "Division by zero"
"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."
$nl
"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."
$nl
"Two examples where you should note the types of the inputs and outputs:"
-{ $example "USE: classes" "3 >fixnum 6 >bignum * class ." "bignum" }
+{ $example "USE: classes" "3 >fixnum 6 >bignum * class-of ." "bignum" }
{ $example "1/2 2.0 + ." "2.5" }
"The following usual operations are supported by all numbers."
-{ $subsection + }
-{ $subsection - }
-{ $subsection * }
-{ $subsection / }
+{ $subsections
+ +
+ -
+ *
+ /
+}
"Non-commutative operations take operands from the stack in the natural order; " { $snippet "6 2 /" } " divides 6 by 2."
-{ $subsection "division-by-zero" }
+{ $subsections "division-by-zero" }
"Real numbers (but not complex numbers) can be ordered:"
-{ $subsection < }
-{ $subsection <= }
-{ $subsection > }
-{ $subsection >= }
+{ $subsections
+ <
+ <=
+ >
+ >=
+}
"Numbers can be compared for equality using " { $link = } ", or a less precise test which disregards types:"
-{ $subsection number= }
+{ $subsections number= }
{ $see-also "math.floats.compare" } ;
ARTICLE: "modular-arithmetic" "Modular arithmetic"
-{ $subsection mod }
-{ $subsection rem }
-{ $subsection /mod }
-{ $subsection /i }
+{ $subsections
+ mod
+ rem
+ /mod
+ /i
+}
{ $see-also "integer-functions" } ;
ARTICLE: "bitwise-arithmetic" "Bitwise arithmetic"
"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" } "."
-{ $subsection bitand }
-{ $subsection bitor }
-{ $subsection bitxor }
-{ $subsection bitnot }
-{ $subsection shift }
-{ $subsection 2/ }
-{ $subsection 2^ }
-{ $subsection bit? }
+{ $subsections
+ bitand
+ bitor
+ bitxor
+ bitnot
+ shift
+ 2/
+ 2^
+ bit?
+}
"Advanced topics:"
-{ $subsection "math.bitwise" }
-{ $subsection "math.bits" }
+{ $subsections
+ "math.bitwise"
+ "math.bits"
+}
{ $see-also "booleans" } ;
ARTICLE: "arithmetic" "Arithmetic"
"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."
$nl
"Math words are in the " { $vocab-link "math" } " vocabulary. Implementation details are in the " { $vocab-link "math.private" } " vocabulary."
-{ $subsection "number-protocol" }
-{ $subsection "modular-arithmetic" }
-{ $subsection "bitwise-arithmetic" }
+{ $subsections
+ "number-protocol"
+ "modular-arithmetic"
+ "bitwise-arithmetic"
+}
{ $see-also "integers" "rationals" "floats" "complex-numbers" } ;
ABOUT: "arithmetic"
projects / factor.git / blobdiff