basis/math/functions/functions-docs.factor

   1 USING: help.markup help.syntax kernel math math.order
   2 sequences quotations math.functions.private ;
   3 IN: math.functions
   4
   5 ARTICLE: "integer-functions" "Integer functions"
   6 { $subsection align }
   7 { $subsection gcd }
   8 { $subsection log2 }
   9 { $subsection next-power-of-2 }
  10 "Modular exponentiation:"
  11 { $subsection ^mod }
  12 { $subsection mod-inv }
  13 "Tests:"
  14 { $subsection power-of-2? }
  15 { $subsection even? }
  16 { $subsection odd? } ;
  17
  18 ARTICLE: "arithmetic-functions" "Arithmetic functions"
  19 "Computing additive and multiplicative inverses:"
  20 { $subsection neg }
  21 { $subsection recip }
  22 "Incrementing, decrementing:"
  23 { $subsection 1+ }
  24 { $subsection 1- }
  25 "Minimum, maximum:"
  26 { $subsection min }
  27 { $subsection max }
  28 "Complex conjugation:"
  29 { $subsection conjugate }
  30 "Tests:"
  31 { $subsection zero? }
  32 { $subsection between? }
  33 "Sign:"
  34 { $subsection sgn }
  35 "Rounding:"
  36 { $subsection ceiling }
  37 { $subsection floor }
  38 { $subsection truncate }
  39 { $subsection round }
  40 "Inexact comparison:"
  41 { $subsection ~ } ;
  42
  43 ARTICLE: "power-functions" "Powers and logarithms"
  44 "Squares:"
  45 { $subsection sq }
  46 { $subsection sqrt }
  47 "Exponential and natural logarithm:"
  48 { $subsection exp }
  49 { $subsection cis }
  50 { $subsection log }
  51 "Raising a number to a power:"
  52 { $subsection ^ }
  53 "Converting between rectangular and polar form:"
  54 { $subsection abs }
  55 { $subsection absq }
  56 { $subsection arg }
  57 { $subsection >polar }
  58 { $subsection polar> } ;
  59
  60 ARTICLE: "trig-hyp-functions" "Trigonometric and hyperbolic functions"
  61 "Trigonometric functions:"
  62 { $subsection cos }
  63 { $subsection sin }
  64 { $subsection tan }
  65 "Reciprocals:"
  66 { $subsection sec }
  67 { $subsection cosec }
  68 { $subsection cot }
  69 "Inverses:"
  70 { $subsection acos }
  71 { $subsection asin }
  72 { $subsection atan }
  73 "Inverse reciprocals:"
  74 { $subsection asec }
  75 { $subsection acosec }
  76 { $subsection acot }
  77 "Hyperbolic functions:"
  78 { $subsection cosh }
  79 { $subsection sinh }
  80 { $subsection tanh }
  81 "Reciprocals:"
  82 { $subsection sech }
  83 { $subsection cosech }
  84 { $subsection coth }
  85 "Inverses:"
  86 { $subsection acosh }
  87 { $subsection asinh }
  88 { $subsection atanh }
  89 "Inverse reciprocals:"
  90 { $subsection asech }
  91 { $subsection acosech }
  92 { $subsection acoth } ;
  93
  94 ARTICLE: "math-functions" "Mathematical functions"
  95 { $subsection "integer-functions" }
  96 { $subsection "arithmetic-functions" }
  97 { $subsection "power-functions" }
  98 { $subsection "trig-hyp-functions" } ;
  99
 100 ABOUT: "math-functions"
 101
 102 HELP: (rect>)
 103 { $values { "x" real } { "y" real } { "z" number } }
 104 { $description "Creates a complex number from real and imaginary components." }
 105 { $warning "This word does not check that the arguments are real numbers, which can have undefined consequences. Use the " { $link rect> } " word instead." } ;
 106
 107 HELP: rect>
 108 { $values { "x" real } { "y" real } { "z" number } }
 109 { $description "Creates a complex number from real and imaginary components. If " { $snippet "z" } " is an integer zero, this will simply output " { $snippet "x" } "." } ;
 110
 111 HELP: >rect
 112 { $values { "z" number } { "x" real } { "y" real } }
 113 { $description "Extracts the real and imaginary components of a complex number." } ;
 114
 115 HELP: align
 116 { $values { "m" integer } { "w" "a power of 2" } { "n" "an integer multiple of " { $snippet "w" } } }
 117 { $description "Outputs the least multiple of " { $snippet "w" } " greater than " { $snippet "m" } "." }
 118 { $notes "This word will give an incorrect result if " { $snippet "w" } " is not a power of 2." } ;
 119
 120 HELP: exp
 121 { $values { "x" number } { "y" number } }
 122 { $description "Exponential function, " { $snippet "y=e^x" } "." } ;
 123
 124 HELP: log
 125 { $values { "x" number } { "y" number } }
 126 { $description "Natural logarithm function. Outputs negative infinity if " { $snippet "x" } " is 0." } ;
 127
 128 HELP: sqrt
 129 { $values { "x" number } { "y" number } }
 130 { $description "Square root function." } ;
 131
 132 HELP: cosh
 133 $values-x/y
 134 { $description "Hyperbolic cosine." } ;
 135
 136 HELP: sech
 137 $values-x/y
 138 { $description "Hyperbolic secant." } ;
 139
 140 HELP: sinh
 141 $values-x/y
 142 { $description "Hyperbolic sine." } ;
 143
 144 HELP: cosech
 145 $values-x/y
 146 { $description "Hyperbolic cosecant." } ;
 147
 148 HELP: tanh
 149 $values-x/y
 150 { $description "Hyperbolic tangent." } ;
 151
 152 HELP: coth
 153 $values-x/y
 154 { $description "Hyperbolic cotangent." } ;
 155
 156 HELP: cos
 157 $values-x/y
 158 { $description "Trigonometric cosine." } ;
 159
 160 HELP: sec
 161 $values-x/y
 162 { $description "Trigonometric secant." } ;
 163
 164 HELP: sin
 165 $values-x/y
 166 { $description "Trigonometric sine." } ;
 167
 168 HELP: cosec
 169 $values-x/y
 170 { $description "Trigonometric cosecant." } ;
 171
 172 HELP: tan
 173 $values-x/y
 174 { $description "Trigonometric tangent." } ;
 175
 176 HELP: cot
 177 $values-x/y
 178 { $description "Trigonometric cotangent." } ;
 179
 180 HELP: acosh
 181 $values-x/y
 182 { $description "Inverse hyperbolic cosine." } ;
 183
 184 HELP: asech
 185 $values-x/y
 186 { $description "Inverse hyperbolic secant." } ;
 187
 188 HELP: asinh
 189 $values-x/y
 190 { $description "Inverse hyperbolic sine." } ;
 191
 192 HELP: acosech
 193 $values-x/y
 194 { $description "Inverse hyperbolic cosecant." } ;
 195
 196 HELP: atanh
 197 $values-x/y
 198 { $description "Inverse hyperbolic tangent." } ;
 199
 200 HELP: acoth
 201 $values-x/y
 202 { $description "Inverse hyperbolic cotangent." } ;
 203
 204 HELP: acos
 205 $values-x/y
 206 { $description "Inverse trigonometric cosine." } ;
 207
 208 HELP: asec
 209 $values-x/y
 210 { $description "Inverse trigonometric secant." } ;
 211
 212 HELP: asin
 213 $values-x/y
 214 { $description "Inverse trigonometric sine." } ;
 215
 216 HELP: acosec
 217 $values-x/y
 218 { $description "Inverse trigonometric cosecant." } ;
 219
 220 HELP: atan
 221 $values-x/y
 222 { $description "Inverse trigonometric tangent." } ;
 223
 224 HELP: acot
 225 $values-x/y
 226 { $description "Inverse trigonometric cotangent." } ;
 227
 228 HELP: conjugate
 229 { $values { "z" number } { "z*" number } }
 230 { $description "Computes the complex conjugate by flipping the sign of the imaginary part of " { $snippet "z" } "." } ;
 231
 232 HELP: arg
 233 { $values { "z" number } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
 234 { $description "Computes the complex argument." } ;
 235
 236 HELP: >polar
 237 { $values { "z" number } { "abs" "a non-negative real number" } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
 238 { $description "Creates a complex number from an absolute value and argument (polar form)." } ;
 239
 240 HELP: cis
 241 { $values { "arg" "a real number" } { "z" "a complex number on the unit circle" } }
 242 { $description "Computes a point on the unit circle using Euler's formula for " { $snippet "exp(arg*i)" } "." } ;
 243
 244 { cis exp } related-words
 245
 246 HELP: polar>
 247 { $values { "z" number } { "abs" "a non-negative real number" } { "arg" real } }
 248 { $description "Converts an absolute value and argument (polar form) to a complex number." } ;
 249
 250 HELP: [-1,1]?
 251 { $values { "x" number } { "?" "a boolean" } }
 252 { $description "Tests if " { $snippet "x" } " is a real number between -1 and 1, inclusive." } ;
 253
 254 HELP: abs
 255 { $values { "x" number } { "y" "a non-negative real number" } }
 256 { $description "Computes the absolute value of a complex number." } ;
 257
 258 HELP: absq
 259 { $values { "x" number } { "y" "a non-negative real number" } }
 260 { $description "Computes the squared absolute value of a complex number. This is marginally more efficient than " { $link abs } "." } ;
 261
 262 HELP: ^
 263 { $values { "x" number } { "y" number } { "z" number } }
 264 { $description "Raises " { $snippet "x" } " to the power of " { $snippet "y" } ". If " { $snippet "y" } " is an integer the answer is computed exactly, otherwise a floating point approximation is used." }
 265 { $errors "Throws an error if " { $snippet "x" } " and " { $snippet "y" } " are both integer 0." } ;
 266
 267 HELP: gcd
 268 { $values { "x" integer } { "y" integer } { "a" integer } { "d" integer } }
 269 { $description "Computes the positive greatest common divisor " { $snippet "d" } " of " { $snippet "x" } " and " { $snippet "y" } ", and another value " { $snippet "a" } " satisfying:" { $code "a*y = d mod x" } }
 270 { $notes "If " { $snippet "d" } " is 1, then " { $snippet "a" } " is the inverse of " { $snippet "y" } " modulo " { $snippet "x" } "." } ;
 271
 272 HELP: mod-inv
 273 { $values { "x" integer } { "n" integer } { "y" integer } }
 274 { $description "Outputs an integer " { $snippet "y" } " such that " { $snippet "xy = 1 (mod n)" } "." }
 275 { $errors "Throws an error if " { $snippet "n" } " is not invertible modulo " { $snippet "n" } "." }
 276 { $examples
 277     { $example "USING: math.functions prettyprint ;" "173 1119 mod-inv ." "815" }
 278     { $example "USING: math prettyprint ;" "173 815 * 1119 mod ." "1" }
 279 } ;
 280
 281 HELP: each-bit
 282 { $values { "n" integer } { "quot" "a quotation with stack effect " { $snippet "( ? -- )" } } }
 283 { $description "Applies the quotation to each bit of the integer, starting from the least significant bit, and stopping at the last bit from which point on all bits are either clear (if the integer is positive) or all bits are set (if the integer is negataive)." }
 284 { $examples
 285     { $example "USING: math.functions make prettyprint ;" "[ BIN: 1101 [ , ] each-bit ] { } make ." "{ t f t t }" }
 286     { $example "USING: math.functions make prettyprint ;" "[ -3 [ , ] each-bit ] { } make ." "{ t f }" }
 287 } ;
 288
 289 HELP: ~
 290 { $values { "x" real } { "y" real } { "epsilon" real } { "?" "a boolean" } }
 291 { $description "Tests if " { $snippet "x" } " and " { $snippet "y" } " are approximately equal to each other. There are three possible comparison tests, chosen based on the sign of " { $snippet "epsilon" } ":"
 292     { $list
 293         { { $snippet "epsilon" } " is zero: exact comparison." }
 294         { { $snippet "epsilon" } " is positive: absolute distance test." }
 295         { { $snippet "epsilon" } " is negative: relative distance test." }
 296     }
 297 } ;
 298
 299
 300 HELP: truncate
 301 { $values { "x" real } { "y" "a whole real number" } }
 302 { $description "Outputs the number that results from subtracting the fractional component of " { $snippet "x" } "." }
 303 { $notes "The result is not necessarily an integer." } ;
 304
 305 HELP: floor
 306 { $values { "x" real } { "y" "a whole real number" } }
 307 { $description "Outputs the greatest whole number smaller than or equal to " { $snippet "x" } "." }
 308 { $notes "The result is not necessarily an integer." } ;
 309
 310 HELP: ceiling
 311 { $values { "x" real } { "y" "a whole real number" } }
 312 { $description "Outputs the least whole number greater than or equal to " { $snippet "x" } "." }
 313 { $notes "The result is not necessarily an integer." } ;
 314
 315 HELP: round
 316 { $values { "x" real } { "y" "a whole real number" } }
 317 { $description "Outputs the whole number closest to " { $snippet "x" } "." }
 318 { $notes "The result is not necessarily an integer." } ;