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