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