Bug fixes for lcs.diff2html; xml.writer
[factor/jcg.git] / basis / math / functions / functions-docs.factor
blobea3da550829cebc94fab39344282fcde22320c2a
1 USING: help.markup help.syntax kernel math math.order
2 sequences quotations math.functions.private ;
3 IN: math.functions
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? } ;
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 ~ } ;
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> } ;
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 } ;
94 ARTICLE: "math-functions" "Mathematical functions"
95 { $subsection "integer-functions" }
96 { $subsection "arithmetic-functions" }
97 { $subsection "power-functions" }
98 { $subsection "trig-hyp-functions" } ;
100 ABOUT: "math-functions"
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." } ;
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" } "." } ;
111 HELP: >rect
112 { $values { "z" number } { "x" real } { "y" real } }
113 { $description "Extracts the real and imaginary components of a complex number." } ;
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." } ;
120 HELP: exp
121 { $values { "x" number } { "y" number } }
122 { $description "Exponential function, " { $snippet "y=e^x" } "." } ;
124 HELP: log
125 { $values { "x" number } { "y" number } }
126 { $description "Natural logarithm function. Outputs negative infinity if " { $snippet "x" } " is 0." } ;
128 HELP: sqrt
129 { $values { "x" number } { "y" number } }
130 { $description "Square root function." } ;
132 HELP: cosh
133 $values-x/y
134 { $description "Hyperbolic cosine." } ;
136 HELP: sech
137 $values-x/y
138 { $description "Hyperbolic secant." } ;
140 HELP: sinh
141 $values-x/y
142 { $description "Hyperbolic sine." } ;
144 HELP: cosech
145 $values-x/y
146 { $description "Hyperbolic cosecant." } ;
148 HELP: tanh
149 $values-x/y
150 { $description "Hyperbolic tangent." } ;
152 HELP: coth
153 $values-x/y
154 { $description "Hyperbolic cotangent." } ;
156 HELP: cos
157 $values-x/y
158 { $description "Trigonometric cosine." } ;
160 HELP: sec
161 $values-x/y
162 { $description "Trigonometric secant." } ;
164 HELP: sin
165 $values-x/y
166 { $description "Trigonometric sine." } ;
168 HELP: cosec
169 $values-x/y
170 { $description "Trigonometric cosecant." } ;
172 HELP: tan
173 $values-x/y
174 { $description "Trigonometric tangent." } ;
176 HELP: cot
177 $values-x/y
178 { $description "Trigonometric cotangent." } ;
180 HELP: acosh
181 $values-x/y
182 { $description "Inverse hyperbolic cosine." } ;
184 HELP: asech
185 $values-x/y
186 { $description "Inverse hyperbolic secant." } ;
188 HELP: asinh
189 $values-x/y
190 { $description "Inverse hyperbolic sine." } ;
192 HELP: acosech
193 $values-x/y
194 { $description "Inverse hyperbolic cosecant." } ;
196 HELP: atanh
197 $values-x/y
198 { $description "Inverse hyperbolic tangent." } ;
200 HELP: acoth
201 $values-x/y
202 { $description "Inverse hyperbolic cotangent." } ;
204 HELP: acos
205 $values-x/y
206 { $description "Inverse trigonometric cosine." } ;
208 HELP: asec
209 $values-x/y
210 { $description "Inverse trigonometric secant." } ;
212 HELP: asin
213 $values-x/y
214 { $description "Inverse trigonometric sine." } ;
216 HELP: acosec
217 $values-x/y
218 { $description "Inverse trigonometric cosecant." } ;
220 HELP: atan
221 $values-x/y
222 { $description "Inverse trigonometric tangent." } ;
224 HELP: acot
225 $values-x/y
226 { $description "Inverse trigonometric cotangent." } ;
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" } "." } ;
232 HELP: arg
233 { $values { "z" number } { "arg" "a number in the interval " { $snippet "(-pi,pi]" } } }
234 { $description "Computes the complex argument." } ;
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)." } ;
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)" } "." } ;
244 { cis exp } related-words
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." } ;
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." } ;
254 HELP: abs
255 { $values { "x" number } { "y" "a non-negative real number" } }
256 { $description "Computes the absolute value of a complex number." } ;
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 } "." } ;
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." } ;
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" } "." } ;
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 } ;
281 HELP: each-bit
282 { $values { "n" integer } { "quot" { $quotation "( ? -- )" } } }
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 } ;
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 } ;
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." } ;
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." } ;
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." } ;
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." } ;