1 | '\" |
---|
2 | '\" Copyright (c) 1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: mathfunc.n,v 1.21 2007/12/13 15:22:32 dgp Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | mathfunc \- Mathematical functions for Tcl expressions |
---|
17 | .SH SYNOPSIS |
---|
18 | package require \fBTcl 8.5\fR |
---|
19 | .sp |
---|
20 | \fB::tcl::mathfunc::abs\fR \fIarg\fR |
---|
21 | .br |
---|
22 | \fB::tcl::mathfunc::acos\fR \fIarg\fR |
---|
23 | .br |
---|
24 | \fB::tcl::mathfunc::asin\fR \fIarg\fR |
---|
25 | .br |
---|
26 | \fB::tcl::mathfunc::atan\fR \fIarg\fR |
---|
27 | .br |
---|
28 | \fB::tcl::mathfunc::atan2\fR \fIy\fR \fIx\fR |
---|
29 | .br |
---|
30 | \fB::tcl::mathfunc::bool\fR \fIarg\fR |
---|
31 | .br |
---|
32 | \fB::tcl::mathfunc::ceil\fR \fIarg\fR |
---|
33 | .br |
---|
34 | \fB::tcl::mathfunc::cos\fR \fIarg\fR |
---|
35 | .br |
---|
36 | \fB::tcl::mathfunc::cosh\fR \fIarg\fR |
---|
37 | .br |
---|
38 | \fB::tcl::mathfunc::double\fR \fIarg\fR |
---|
39 | .br |
---|
40 | .VS 8.5 |
---|
41 | \fB::tcl::mathfunc::entier\fR \fIarg\fR |
---|
42 | .br |
---|
43 | .VE 8.5 |
---|
44 | \fB::tcl::mathfunc::exp\fR \fIarg\fR |
---|
45 | .br |
---|
46 | \fB::tcl::mathfunc::floor\fR \fIarg\fR |
---|
47 | .br |
---|
48 | \fB::tcl::mathfunc::fmod\fR \fIx\fR \fIy\fR |
---|
49 | .br |
---|
50 | \fB::tcl::mathfunc::hypot\fR \fIx\fR \fIy\fR |
---|
51 | .br |
---|
52 | \fB::tcl::mathfunc::int\fR \fIarg\fR |
---|
53 | .br |
---|
54 | \fB::tcl::mathfunc::isqrt\fR \fIarg\fR |
---|
55 | .br |
---|
56 | \fB::tcl::mathfunc::log\fR \fIarg\fR |
---|
57 | .br |
---|
58 | \fB::tcl::mathfunc::log10\fR \fIarg\fR |
---|
59 | .br |
---|
60 | \fB::tcl::mathfunc::max\fR \fIarg\fR ?\fIarg\fR ...? |
---|
61 | .br |
---|
62 | \fB::tcl::mathfunc::min\fR \fIarg\fR ?\fIarg\fR ...? |
---|
63 | .br |
---|
64 | \fB::tcl::mathfunc::pow\fR \fIx\fR \fIy\fR |
---|
65 | .br |
---|
66 | \fB::tcl::mathfunc::rand\fR |
---|
67 | .br |
---|
68 | \fB::tcl::mathfunc::round\fR \fIarg\fR |
---|
69 | .br |
---|
70 | \fB::tcl::mathfunc::sin\fR \fIarg\fR |
---|
71 | .br |
---|
72 | \fB::tcl::mathfunc::sinh\fR \fIarg\fR |
---|
73 | .br |
---|
74 | \fB::tcl::mathfunc::sqrt\fR \fIarg\fR |
---|
75 | .br |
---|
76 | \fB::tcl::mathfunc::srand\fR \fIarg\fR |
---|
77 | .br |
---|
78 | \fB::tcl::mathfunc::tan\fR \fIarg\fR |
---|
79 | .br |
---|
80 | \fB::tcl::mathfunc::tanh\fR \fIarg\fR |
---|
81 | .br |
---|
82 | \fB::tcl::mathfunc::wide\fR \fIarg\fR |
---|
83 | .sp |
---|
84 | .BE |
---|
85 | .SH "DESCRIPTION" |
---|
86 | .PP |
---|
87 | The \fBexpr\fR command handles mathematical functions of the form |
---|
88 | \fBsin($x)\fR or \fBatan2($y,$x)\fR by converting them to calls of the |
---|
89 | form \fB[tcl::mathfunc::sin [expr {$x}]]\fR or |
---|
90 | \fB[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]\fR. |
---|
91 | A number of math functions are available by default within the |
---|
92 | namespace \fB::tcl::mathfunc\fR; these functions are also available |
---|
93 | for code apart from \fBexpr\fR, by invoking the given commands |
---|
94 | directly. |
---|
95 | .PP |
---|
96 | Tcl supports the following mathematical functions in expressions, all |
---|
97 | of which work solely with floating-point numbers unless otherwise noted: |
---|
98 | .DS |
---|
99 | .ta 3c 6c 9c |
---|
100 | \fBabs\fR \fBacos\fR \fBasin\fR \fBatan\fR |
---|
101 | \fBatan2\fR \fBbool\fR \fBceil\fR \fBcos\fR |
---|
102 | \fBcosh\fR \fBdouble\fR \fBentier\fR \fBexp\fR |
---|
103 | \fBfloor\fR \fBfmod\fR \fBhypot\fR \fBint\fR |
---|
104 | \fBisqrt\fR \fBlog\fR \fBlog10\fR \fBmax\fR |
---|
105 | \fBmin\fR \fBpow\fR \fBrand\fR \fBround\fR |
---|
106 | \fBsin\fR \fBsinh\fR \fBsqrt\fR \fBsrand\fR |
---|
107 | \fBtan\fR \fBtanh\fR \fBwide\fR |
---|
108 | .DE |
---|
109 | .PP |
---|
110 | In addition to these predefined functions, applications may |
---|
111 | define additional functions by using \fBproc\fR (or any other method, |
---|
112 | such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define |
---|
113 | new commands in the \fBtcl::mathfunc\fR namespace. In addition, an |
---|
114 | obsolete interface named \fBTcl_CreateMathFunc\fR() is available to |
---|
115 | extensions that are written in C. The latter interface is not recommended |
---|
116 | for new implementations. |
---|
117 | .SS "DETAILED DEFINITIONS" |
---|
118 | .TP |
---|
119 | \fBabs \fIarg\fR |
---|
120 | Returns the absolute value of \fIarg\fR. \fIArg\fR may be either |
---|
121 | integer or floating-point, and the result is returned in the same form. |
---|
122 | .TP |
---|
123 | \fBacos \fIarg\fR |
---|
124 | Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR] |
---|
125 | radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. |
---|
126 | .TP |
---|
127 | \fBasin \fIarg\fR |
---|
128 | Returns the arc sine of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] |
---|
129 | radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. |
---|
130 | .TP |
---|
131 | \fBatan \fIarg\fR |
---|
132 | Returns the arc tangent of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] |
---|
133 | radians. |
---|
134 | .TP |
---|
135 | \fBatan2 \fIy x\fR |
---|
136 | Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI\-pi\fR,\fIpi\fR] |
---|
137 | radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater |
---|
138 | than \fI0\fR, this is equivalent to |
---|
139 | .QW "\fBatan \fR[\fBexpr\fR {\fIy\fB/\fIx\fR}]" . |
---|
140 | .TP |
---|
141 | \fBbool \fIarg\fR |
---|
142 | Accepts any numeric value, or any string acceptable to |
---|
143 | \fBstring is boolean\fR, and returns the corresponding |
---|
144 | boolean value \fB0\fR or \fB1\fR. Non-zero numbers are true. |
---|
145 | Other numbers are false. Non-numeric strings produce boolean value in |
---|
146 | agreement with \fBstring is true\fR and \fBstring is false\fR. |
---|
147 | .TP |
---|
148 | \fBceil \fIarg\fR |
---|
149 | Returns the smallest integral floating-point value (i.e. with a zero |
---|
150 | fractional part) not less than \fIarg\fR. The argument may be any |
---|
151 | numeric value. |
---|
152 | .TP |
---|
153 | \fBcos \fIarg\fR |
---|
154 | Returns the cosine of \fIarg\fR, measured in radians. |
---|
155 | .TP |
---|
156 | \fBcosh \fIarg\fR |
---|
157 | Returns the hyperbolic cosine of \fIarg\fR. If the result would cause |
---|
158 | an overflow, an error is returned. |
---|
159 | .TP |
---|
160 | \fBdouble \fIarg\fR |
---|
161 | The argument may be any numeric value, |
---|
162 | If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts |
---|
163 | \fIarg\fR to floating-point and returns the converted value. May return |
---|
164 | \fBInf\fR or \fB\-Inf\fR when the argument is a numeric value that exceeds |
---|
165 | the floating-point range. |
---|
166 | .TP |
---|
167 | \fBentier \fIarg\fR |
---|
168 | .VS 8.5 |
---|
169 | The argument may be any numeric value. The integer part of \fIarg\fR |
---|
170 | is determined and returned. The integer range returned by this function |
---|
171 | is unlimited, unlike \fBint\fR and \fBwide\fR which |
---|
172 | truncate their range to fit in particular storage widths. |
---|
173 | .VE 8.5 |
---|
174 | .TP |
---|
175 | \fBexp \fIarg\fR |
---|
176 | Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR. |
---|
177 | If the result would cause an overflow, an error is returned. |
---|
178 | .TP |
---|
179 | \fBfloor \fIarg\fR |
---|
180 | Returns the largest integral floating-point value (i.e. with a zero |
---|
181 | fractional part) not greater than \fIarg\fR. The argument may be |
---|
182 | any numeric value. |
---|
183 | .TP |
---|
184 | \fBfmod \fIx y\fR |
---|
185 | Returns the floating-point remainder of the division of \fIx\fR by |
---|
186 | \fIy\fR. If \fIy\fR is 0, an error is returned. |
---|
187 | .TP |
---|
188 | \fBhypot \fIx y\fR |
---|
189 | Computes the length of the hypotenuse of a right-angled triangle |
---|
190 | .QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]". |
---|
191 | .TP |
---|
192 | \fBint \fIarg\fR |
---|
193 | The argument may be any numeric value. The integer part of \fIarg\fR |
---|
194 | is determined, and then the low order bits of that integer value up |
---|
195 | to the machine word size are returned as an integer value. For reference, |
---|
196 | the number of bytes in the machine word are stored in |
---|
197 | \fBtcl_platform(wordSize)\fR. |
---|
198 | .TP |
---|
199 | \fBisqrt \fIarg\fR |
---|
200 | Computes the integer part of the square root of \fIarg\fR. \fIArg\fR must be |
---|
201 | a positive value, either an integer or a floating point number. |
---|
202 | Unlike \fBsqrt\fR, which is limited to the precision of a floating point |
---|
203 | number, \fIisqrt\fR will return a result of arbitrary precision. |
---|
204 | .TP |
---|
205 | \fBlog \fIarg\fR |
---|
206 | Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a |
---|
207 | positive value. |
---|
208 | .TP |
---|
209 | \fBlog10 \fIarg\fR |
---|
210 | Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a |
---|
211 | positive value. |
---|
212 | .TP |
---|
213 | \fBmax \fIarg\fB \fI...\fR |
---|
214 | Accepts one or more numeric arguments. Returns the one argument |
---|
215 | with the greatest value. |
---|
216 | .TP |
---|
217 | \fBmin \fIarg\fB \fI...\fR |
---|
218 | Accepts one or more numeric arguments. Returns the one argument |
---|
219 | with the least value. |
---|
220 | .TP |
---|
221 | \fBpow \fIx y\fR |
---|
222 | Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR |
---|
223 | is negative, \fIy\fR must be an integer value. |
---|
224 | .TP |
---|
225 | \fBrand\fR |
---|
226 | Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR). |
---|
227 | The generator algorithm is a simple linear congruential generator that |
---|
228 | is not cryptographically secure. Each result from \fBrand\fR completely |
---|
229 | determines all future results from subsequent calls to \fBrand\fR, so |
---|
230 | \fBrand\fR should not be used to generate a sequence of secrets, such as |
---|
231 | one-time passwords. The seed of the generator is initialized from the |
---|
232 | internal clock of the machine or may be set with the \fBsrand\fR function. |
---|
233 | .TP |
---|
234 | \fBround \fIarg\fR |
---|
235 | If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts |
---|
236 | \fIarg\fR to integer by rounding and returns the converted value. |
---|
237 | .TP |
---|
238 | \fBsin \fIarg\fR |
---|
239 | Returns the sine of \fIarg\fR, measured in radians. |
---|
240 | .TP |
---|
241 | \fBsinh \fIarg\fR |
---|
242 | Returns the hyperbolic sine of \fIarg\fR. If the result would cause |
---|
243 | an overflow, an error is returned. |
---|
244 | .TP |
---|
245 | \fBsqrt \fIarg\fR |
---|
246 | The argument may be any non-negative numeric value. Returns a floating-point |
---|
247 | value that is the square root of \fIarg\fR. May return \fBInf\fR when the |
---|
248 | argument is a numeric value that exceeds the square of the maximum value of |
---|
249 | the floating-point range. |
---|
250 | .TP |
---|
251 | \fBsrand \fIarg\fR |
---|
252 | The \fIarg\fR, which must be an integer, is used to reset the seed for |
---|
253 | the random number generator of \fBrand\fR. Returns the first random |
---|
254 | number (see \fBrand\fR) from that seed. Each interpreter has its own seed. |
---|
255 | .TP |
---|
256 | \fBtan \fIarg\fR |
---|
257 | Returns the tangent of \fIarg\fR, measured in radians. |
---|
258 | .TP |
---|
259 | \fBtanh \fIarg\fR |
---|
260 | Returns the hyperbolic tangent of \fIarg\fR. |
---|
261 | .TP |
---|
262 | \fBwide \fIarg\fR |
---|
263 | The argument may be any numeric value. The integer part of \fIarg\fR |
---|
264 | is determined, and then the low order 64 bits of that integer value |
---|
265 | are returned as an integer value. |
---|
266 | .SH "SEE ALSO" |
---|
267 | expr(n), mathop(n), namespace(n) |
---|
268 | .SH "COPYRIGHT" |
---|
269 | .nf |
---|
270 | Copyright (c) 1993 The Regents of the University of California. |
---|
271 | Copyright (c) 1994-2000 Sun Microsystems Incorporated. |
---|
272 | Copyright (c) 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>. |
---|
273 | .fi |
---|