core/math/math.facts

   1 USING: help kernel math ;
   2
   3 HELP: number=
   4 { $values { "x" "a number" } { "y" "a number" } { "?" "a boolean" } }
   5 { $description "Tests if two numbers have the same numerical value." }
   6 { $notes "Do not call this word directly. Calling " { $link = } " has the same effect and is more concise." } ;
   7
   8 HELP: <
   9 { $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
  10 { $description "Tests if " { $snippet "x" } " is less than " { $snippet "y" } "." } ;
  11
  12 HELP: <=
  13 { $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
  14 { $description "Tests if " { $snippet "x" } " is less than or equal to " { $snippet "y" } "." } ;
  15
  16 HELP: >
  17 { $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
  18 { $description "Tests if " { $snippet "x" } " is greater than " { $snippet "y" } "." } ;
  19
  20 HELP: >=
  21 { $values { "x" "a real number" } { "y" "a real number" } { "?" "a boolean" } }
  22 { $description "Tests if " { $snippet "x" } " is greater than or equal to " { $snippet "y" } "." } ;
  23
  24 HELP: +
  25 { $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
  26 { $description
  27     "Adds two numbers."
  28     { $list
  29         "Addition of fixnums may overflow and convert the result to a bignum."
  30         "Addition of bignums always yields a bignum."
  31         "Addition of floats always yields a float."
  32         "Addition of ratios and complex numbers proceeds using the relevant mathematical rules."
  33     }
  34 } ;
  35
  36 HELP: -
  37 { $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
  38 { $description
  39     "Subtracts " { $snippet "y" } " from " { $snippet "x" } "."
  40     { $list
  41         "Subtraction of fixnums may overflow and convert the result to a bignum."
  42         "Subtraction of bignums always yields a bignum."
  43         "Subtraction of floats always yields a float."
  44         "Subtraction of ratios and complex numbers proceeds using the relevant mathematical rules."
  45     }
  46 } ;
  47
  48 HELP: *
  49 { $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
  50 { $description
  51     "Multiplies two numbers."
  52     { $list
  53         "Multiplication of fixnums may overflow and convert the result to a bignum."
  54         "Multiplication of bignums always yields a bignum."
  55         "Multiplication of floats always yields a float."
  56         "Multiplication of ratios and complex numbers proceeds using the relevant mathematical rules."
  57     }
  58 } ;
  59
  60 HELP: /
  61 { $values { "x" "a number" } { "y" "a number" } { "z" "a number" } }
  62 { $description
  63     "Divides " { $snippet "x" } " by " { $snippet "y" } ", retaining as much precision as possible."
  64     { $list
  65         "Division of fixnums may yield a ratio, or overflow and yield a bignum."
  66         "Division of bignums may yield a ratio."
  67         "Division of floats always yields a float."
  68         "Division of ratios and complex numbers proceeds using the relevant mathematical rules."
  69     }
  70 }
  71 { $see-also "division-by-zero" } ;
  72
  73 HELP: /i
  74 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
  75 { $description
  76     "Divides " { $snippet "x" } " by " { $snippet "y" } ", truncating the result to an integer."
  77     { $list
  78         "Integer division of fixnums may overflow and yield a bignum."
  79         "Integer division of bignums always yields a bignum."
  80         "Integer division of floats always yields a float."
  81         "Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
  82     }
  83 }
  84 { $see-also "division-by-zero" } ;
  85
  86 HELP: /f
  87 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
  88 { $description
  89     "Divides " { $snippet "x" } " by " { $snippet "y" } ", representing the result as a floating point number."
  90     { $list
  91         "Integer division of fixnums may overflow and yield a bignum."
  92         "Integer division of bignums always yields a bignum."
  93         "Integer division of floats always yields a float."
  94         "Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
  95     }
  96 }
  97 { $see-also "division-by-zero" } ;
  98
  99 HELP: mod
 100 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
 101 { $description
 102     "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder being negative if " { $snippet "x" } " is negative."
 103     { $list
 104         "Modulus of fixnums always yields a fixnum."
 105         "Modulus of bignums always yields a bignum."
 106     }
 107 }
 108 { $see-also "division-by-zero" rem } ;
 109
 110 HELP: /mod
 111 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } { "w" "an integer" } }
 112 { $description
 113     "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."
 114     { $list
 115         "The quotient of two fixnums may overflow and yield a bignum; the remainder is always a fixnum"
 116         "The quotient and remainder of two bignums is always a bignum."
 117     }
 118 }
 119 { $see-also "division-by-zero" } ;
 120
 121 HELP: bitand
 122 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
 123 { $description "Outputs a new integer where each bit is set if and only if the corresponding bit is set in both inputs." }
 124 { $examples
 125     { $example "BIN: 101 BIN: 10 bitand .b" "0" }
 126     { $example "BIN: 110 BIN: 10 bitand .b" "10" }
 127 } ;
 128
 129 HELP: bitor
 130 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
 131 { $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." }
 132 { $examples
 133     { $example "BIN: 101 BIN: 10 bitor .b" "111" }
 134     { $example "BIN: 110 BIN: 10 bitor .b" "110" }
 135 } ;
 136
 137 HELP: bitxor
 138 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
 139 { $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." }
 140 { $examples
 141     { $example "BIN: 101 BIN: 10 bitxor .b" "111" }
 142     { $example "BIN: 110 BIN: 10 bitxor .b" "100" }
 143 } ;
 144
 145 HELP: shift
 146 { $values { "x" "an integer" } { "n" "an integer" } { "y" "an integer" } }
 147 { $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." }
 148 { $examples { $example "BIN: 101 5 shift .b" "10100000" } { $example "BIN: 11111 -2 shift .b" "111" } } ;
 149
 150 HELP: bitnot
 151 { $values { "x" "an integer" } { "y" "an integer" } }
 152 { $description "Computes the bitwise complement of the input; that is, each bit in the input number is flipped." }
 153 { $notes "Due to the two's complement representation of signed integers, the following two lines are equivalent:" { $code "bitnot" "neg 1-" } } ;
 154
 155 HELP: 1+
 156 { $values { "x" "a number" } { "y" "a number" } }
 157 { $description
 158     "Increments a number by 1. The following two lines are equivalent, but the first is more efficient:"
 159     { $code "1+" "1 +" }
 160 } ;
 161
 162 HELP: 1-
 163 { $values { "x" "a number" } { "y" "a number" } }
 164 { $description
 165     "Decrements a number by 1. The following two lines are equivalent, but the first is more efficient:"
 166     { $code "1-" "1 -" }
 167 } ;
 168
 169 HELP: truncate
 170 { $values { "x" "a real number" } { "y" "a whole real number" } }
 171 { $description "Outputs the number that results from subtracting the fractional component of " { $snippet "x" } "." }
 172 { $notes "The result is not necessarily an integer." } ;
 173
 174 HELP: floor
 175 { $values { "x" "a real number" } { "y" "a whole real number" } }
 176 { $description "Outputs the greatest whole number smaller than or equal to " { $snippet "x" } "." }
 177 { $notes "The result is not necessarily an integer." } ;
 178
 179 HELP: ceiling
 180 { $values { "x" "a real number" } { "y" "a whole real number" } }
 181 { $description "Outputs the least whole number greater than or equal to " { $snippet "x" } "." }
 182 { $notes "The result is not necessarily an integer." } ;
 183
 184 HELP: abs
 185 { $values { "x" "a complex number" } { "y" "a non-negative real number" } }
 186 { $description "Computes the absolute value of a complex number." } ;
 187
 188 HELP: absq
 189 { $values { "x" "a complex number" } { "y" "a non-negative real number" } }
 190 { $description "Computes the squared absolute value of a complex number. This is marginally more efficient than " { $link abs } "." } ;
 191
 192 HELP: sq
 193 { $values { "x" "a number" } { "y" "a number" } }
 194 { $description "Multiplies a number by itself." } ;
 195
 196 HELP: neg
 197 { $values { "x" "a number" } { "-x" "a number" } }
 198 { $description "Computes a number's additive inverse." } ;
 199
 200 HELP: recip
 201 { $values { "x" "a number" } { "y" "a number" } }
 202 { $description "Computes a number's multiplicative inverse." }
 203 { $errors "Throws an error if " { $snippet "x" } " is the integer 0." } ;
 204
 205 HELP: max
 206 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
 207 { $description "Outputs the greatest of two real numbers." } ;
 208
 209 HELP: min
 210 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
 211 { $description "Outputs the smallest of two real numbers." } ;
 212
 213 HELP: between?
 214 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } { "?" "a boolean" } }
 215 { $description "Tests if " { $snippet "x" } " is in the interval " { $snippet "[y,z]" } "." }
 216 { $notes "As per the closed interval notation, the end-points are included in the interval." } ;
 217
 218 HELP: rem
 219 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
 220 { $description
 221     "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder always positive."
 222     { $list
 223         "Modulus of fixnums always yields a fixnum."
 224         "Modulus of bignums always yields a bignum."
 225     }
 226 }
 227 { $see-also "division-by-zero" mod } ;
 228
 229 HELP: sgn
 230 { $values { "x" "a real number" } { "n" "-1, 0 or 1" } }
 231 { $description
 232     "Outputs one of the following:"
 233     { $list
 234         "-1 if " { $snippet "x" } " is negative"
 235         "0 if " { $snippet "x" } " is equal to 0"
 236         "1 if " { $snippet "x" } " is positive"
 237     }
 238 } ;
 239
 240 HELP: align
 241 { $values { "m" "an integer" } { "w" "a power of 2" } { "n" "an integer multiple of " { $snippet "w" } } }
 242 { $description "Outputs the least multiple of " { $snippet "w" } " greater than " { $snippet "m" } "." }
 243 { $notes "This word will give an incorrect result if " { $snippet "w" } " is not a power of 2." } ;
 244
 245 HELP: number>string
 246 { $values { "n" "a real number" } { "str" "a string" } }
 247 { $description "Converts a real number to a string." }
 248 { $notes "Printing complex numbers requires the more general prettyprinter facility (see " { $link "prettyprint" } ")." } ;