factor/core/math/math.facts

USING: help kernel math sequences quotations ;

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" }
}
{ $notes "This word implements bitwise and, so applying it to booleans will throw an error. Boolean and is the " { $link and } " word." } ;

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" }
}
{ $notes "This word implements bitwise inclusive or, so applying it to booleans will throw an error. Boolean inclusive or is the " { $link and } " word." } ;

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" }
}
{ $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" "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 "This word implements bitwise not, so applying it to booleans will throw an error. Boolean not is the " { $link not } " word."
$nl
"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: round
{ $values { "x" "a real number" } { "y" "a whole real number" } }
{ $description "Outputs the whole number closest 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: power-of-2?
{ $values { "n" "an integer" } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "n" } " is a power of 2." } ;

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: 2/
{ $values { "x" integer } { "y" integer } }
{ $description "Shifts " { $snippet "x" } " to the right by one bit." }
{ $examples
    { $example "14 2/ ." "7" }
    { $example "17 2/ ." "8" }
    { $example "-17 2/ ." "-9" }
}
{ $notes "This word is not equivalent to " { $snippet "2 /" } " or " { $snippet "2 /i" } "; the name is historic and originates from the Forth programming language." } ;

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 ^" } "." } ;

HELP: zero?
{ $values { "n" number } { "?" "a boolean" } }
{ $description "Tests if the number is equal to zero." } ;

HELP: times
{ $values { "n" integer } { "quot" quotation } }
{ $description "Calls the quotation " { $snippet "n" } " times." }
{ $notes "If you need to pass the current index to the quotation, use " { $link each } "." } ;