factor/library/math/math.facts

249 lines
11 KiB
Plaintext

USING: help kernel math ;
HELP: number=
{ $values { "x" "a number" } { "y" "a number" } { "?" "a boolean" } }
{ $description "Tests if two numbers have the same numerical value." }
{ $notes "Do not call this word directly. Calling " { $link = } " has the same effect and is more concise." } ;
HELP: <
{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "x" } " is less than " { $snippet "y" } "." } ;
HELP: <=
{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "x" } " is less than or equal to " { $snippet "y" } "." } ;
HELP: >
{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "x" } " is greater than " { $snippet "y" } "." } ;
HELP: >=
{ $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "x" } " is greater than or equal to " { $snippet "y" } "." } ;
HELP: +
{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
{ $description
"Adds two numbers."
{ $list
"Addition of fixnums may overflow and convert the result to a bignum."
"Addition of bignums always yields a bignum."
"Addition of floats always yields a float."
"Addition of ratios and complex numbers proceeds using the relevant mathematical rules."
}
} ;
HELP: -
{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
{ $description
"Subtracts " { $snippet "y" } " from " { $snippet "x" } "."
{ $list
"Subtraction of fixnums may overflow and convert the result to a bignum."
"Subtraction of bignums always yields a bignum."
"Subtraction of floats always yields a float."
"Subtraction of ratios and complex numbers proceeds using the relevant mathematical rules."
}
} ;
HELP: *
{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
{ $description
"Multiplies two numbers."
{ $list
"Multiplication of fixnums may overflow and convert the result to a bignum."
"Multiplication of bignums always yields a bignum."
"Multiplication of floats always yields a float."
"Multiplication of ratios and complex numbers proceeds using the relevant mathematical rules."
}
} ;
HELP: /
{ $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
{ $description
"Divides " { $snippet "x" } " by " { $snippet "y" } ", retaining as much precision as possible."
{ $list
"Division of fixnums may yield a ratio, or overflow and yield a bignum."
"Division of bignums may yield a ratio."
"Division of floats always yields a float."
"Division of ratios and complex numbers proceeds using the relevant mathematical rules."
}
}
{ $see-also "division-by-zero" } ;
HELP: /i
{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
{ $description
"Divides " { $snippet "x" } " by " { $snippet "y" } ", truncating the result to an integer."
{ $list
"Integer division of fixnums may overflow and yield a bignum."
"Integer division of bignums always yields a bignum."
"Integer division of floats always yields a float."
"Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
}
}
{ $see-also "division-by-zero" } ;
HELP: /f
{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
{ $description
"Divides " { $snippet "x" } " by " { $snippet "y" } ", representing the result as a floating point number."
{ $list
"Integer division of fixnums may overflow and yield a bignum."
"Integer division of bignums always yields a bignum."
"Integer division of floats always yields a float."
"Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
}
}
{ $see-also "division-by-zero" } ;
HELP: mod
{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
{ $description
"Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
{ $list
"Modulus of fixnums always yields a fixnum."
"Modulus of bignums always yields a bignum."
}
}
{ $see-also "division-by-zero" rem } ;
HELP: /mod
{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } { "w" "an 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
"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."
}
}
{ $see-also "division-by-zero" } ;
HELP: bitand
{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an 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 "BIN: 101 BIN: 10 bitand .b" "0" }
{ $example "BIN: 110 BIN: 10 bitand .b" "10" }
} ;
HELP: bitor
{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an 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 "BIN: 101 BIN: 10 bitor .b" "111" }
{ $example "BIN: 110 BIN: 10 bitor .b" "110" }
} ;
HELP: bitxor
{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an 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 "BIN: 101 BIN: 10 bitxor .b" "111" }
{ $example "BIN: 110 BIN: 10 bitxor .b" "100" }
} ;
HELP: shift
{ $values { "x" "an integer" } { "n" "an integer" } { "y" "an integer" } }
{ $description "Shifts " { $snippet "x" } " to the left by " { $snippet "y" } " bits if " { $snippet "y" } " is positive, or " { $snippet "-y" } " bits to the right if " { $snippet "y" } " 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 "BIN: 101 5 shift .b" "10100000" } { $example "BIN: 11111 -2 shift .b" "111" } } ;
HELP: bitnot
{ $values { "x" "an integer" } { "y" "an integer" } }
{ $description "Computes the bitwise complement of the input; that is, each bit in the input number is flipped." }
{ $notes "Due to the two's complement representation of signed integers, the following two lines are equivalent:" { $code "bitnot" "neg 1-" } } ;
HELP: 1+
{ $values { "x" "a number" } { "y" "a number" } }
{ $description
"Increments a number by 1. The following two lines are equivalent, but the first is more efficient:"
{ $code "1+" "1 +" }
} ;
HELP: 1-
{ $values { "x" "a number" } { "y" "a number" } }
{ $description
"Decrements a number by 1. The following two lines are equivalent, but the first is more efficient:"
{ $code "1-" "1 -" }
} ;
HELP: truncate
{ $values { "x" "a real number" } { "y" "a whole real number" } }
{ $description "Outputs the number that results from subtracting the fractional component of " { $snippet "x" } "." }
{ $notes "The result is not necessarily an integer." } ;
HELP: floor
{ $values { "x" "a real number" } { "y" "a whole real number" } }
{ $description "Outputs the greatest whole number smaller than or equal to " { $snippet "x" } "." }
{ $notes "The result is not necessarily an integer." } ;
HELP: ceiling
{ $values { "x" "a real number" } { "y" "a whole real number" } }
{ $description "Outputs the least whole number greater than or equal to " { $snippet "x" } "." }
{ $notes "The result is not necessarily an integer." } ;
HELP: abs
{ $values { "x" "a complex number" } { "y" "a non-negative real number" } }
{ $description "Computes the absolute value of a complex number." } ;
HELP: absq
{ $values { "x" "a complex number" } { "y" "a non-negative real number" } }
{ $description "Computes the squared absolute value of a complex number. This is marginally more efficient than " { $link abs } "." } ;
HELP: sq
{ $values { "x" "a number" } { "y" "a number" } }
{ $description "Multiplies a number by itself." } ;
HELP: neg
{ $values { "x" "a number" } { "-x" "a number" } }
{ $description "Computes a number's additive inverse." } ;
HELP: recip
{ $values { "x" "a number" } { "y" "a number" } }
{ $description "Computes a number's multiplicative inverse." }
{ $errors "Throws an error if " { $snippet "x" } " is the integer 0." } ;
HELP: max
{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
{ $description "Outputs the greatest of two real numbers." } ;
HELP: min
{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
{ $description "Outputs the smallest of two real numbers." } ;
HELP: between?
{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "x" } " is in the interval " { $snippet "[y,z]" } "." }
{ $notes "As per the closed interval notation, the end-points are included in the interval." } ;
HELP: rem
{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
{ $description
"Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder always positive."
{ $list
"Modulus of fixnums always yields a fixnum."
"Modulus of bignums always yields a bignum."
}
}
{ $see-also "division-by-zero" mod } ;
HELP: sgn
{ $values { "x" "a real number" } { "n" "-1, 0 or 1" } }
{ $description
"Outputs one of the following:"
{ $list
"-1 if " { $snippet "x" } " is negative"
"0 if " { $snippet "x" } " is equal to 0"
"1 if " { $snippet "x" } " is positive"
}
} ;
HELP: align
{ $values { "m" "an integer" } { "w" "a power of 2" } { "n" "an integer multiple of " { $snippet "w" } } }
{ $description "Outputs the least multiple of " { $snippet "w" } " greater than " { $snippet "m" } "." }
{ $notes "This word will give an incorrect result if " { $snippet "w" } " is not a power of 2." } ;
HELP: number>string
{ $values { "n" "a real number" } { "str" "a string" } }
{ $description "Converts a real number to a string." }
{ $notes "Printing complex numbers requires the more general prettyprinter facility (see " { $link "prettyprint" } ")." } ;