[25] | 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 |
---|