diff options
Diffstat (limited to 'doc/mathfunc.n')
| -rw-r--r-- | doc/mathfunc.n | 219 |
1 files changed, 147 insertions, 72 deletions
diff --git a/doc/mathfunc.n b/doc/mathfunc.n index 5ea56bc..84853d8 100644 --- a/doc/mathfunc.n +++ b/doc/mathfunc.n @@ -6,10 +6,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: mathfunc.n,v 1.6 2005/06/09 14:24:06 dkf Exp $ -'\" -.so man.macros .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -37,6 +35,8 @@ package require \fBTcl 8.5\fR .br \fB::tcl::mathfunc::double\fR \fIarg\fR .br +\fB::tcl::mathfunc::entier\fR \fIarg\fR +.br \fB::tcl::mathfunc::exp\fR \fIarg\fR .br \fB::tcl::mathfunc::floor\fR \fIarg\fR @@ -47,10 +47,16 @@ package require \fBTcl 8.5\fR .br \fB::tcl::mathfunc::int\fR \fIarg\fR .br +\fB::tcl::mathfunc::isqrt\fR \fIarg\fR +.br \fB::tcl::mathfunc::log\fR \fIarg\fR .br \fB::tcl::mathfunc::log10\fR \fIarg\fR .br +\fB::tcl::mathfunc::max\fR \fIarg\fR ?\fIarg\fR ...? +.br +\fB::tcl::mathfunc::min\fR \fIarg\fR ?\fIarg\fR ...? +.br \fB::tcl::mathfunc::pow\fR \fIx\fR \fIy\fR .br \fB::tcl::mathfunc::rand\fR @@ -76,8 +82,8 @@ package require \fBTcl 8.5\fR .PP The \fBexpr\fR command handles mathematical functions of the form \fBsin($x)\fR or \fBatan2($y,$x)\fR by converting them to calls of the -form \fB[tcl::math::sin [expr {$x}]]\fR or -\fB[tcl::math::atan2 [expr {$y}] [expr {$x}]]\fR. +form \fB[tcl::mathfunc::sin [expr {$x}]]\fR or +\fB[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]\fR. A number of math functions are available by default within the namespace \fB::tcl::mathfunc\fR; these functions are also available for code apart from \fBexpr\fR, by invoking the given commands @@ -87,95 +93,156 @@ Tcl supports the following mathematical functions in expressions, all of which work solely with floating-point numbers unless otherwise noted: .DS .ta 3c 6c 9c -\fBabs\fR \fBcos\fR \fBint\fR \fBsinh\fR -\fBacos\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR -\fBasin\fR \fBdouble\fR \fBlog10\fR \fBsrand\fR -\fBatan\fR \fBexp\fR \fBpow\fR \fBtan\fR -\fBatan2\fR \fBfloor\fR \fBrand\fR \fBtanh\fR -\fBbool\fR \fBfmod\fR \fBround\fR \fBwide\fR -\fBceil\fR \fBhypot\fR \fBsin\fR +\fBabs\fR \fBacos\fR \fBasin\fR \fBatan\fR +\fBatan2\fR \fBbool\fR \fBceil\fR \fBcos\fR +\fBcosh\fR \fBdouble\fR \fBentier\fR \fBexp\fR +\fBfloor\fR \fBfmod\fR \fBhypot\fR \fBint\fR +\fBisqrt\fR \fBlog\fR \fBlog10\fR \fBmax\fR +\fBmin\fR \fBpow\fR \fBrand\fR \fBround\fR +\fBsin\fR \fBsinh\fR \fBsqrt\fR \fBsrand\fR +\fBtan\fR \fBtanh\fR \fBwide\fR .DE .PP +In addition to these predefined functions, applications may +define additional functions by using \fBproc\fR (or any other method, +such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define +new commands in the \fBtcl::mathfunc\fR namespace. In addition, an +obsolete interface named \fBTcl_CreateMathFunc\fR() is available to +extensions that are written in C. The latter interface is not recommended +for new implementations. +.SS "DETAILED DEFINITIONS" .TP -\fBabs(\fIarg\fB)\fR +\fBabs \fIarg\fR +. Returns the absolute value of \fIarg\fR. \fIArg\fR may be either integer or floating-point, and the result is returned in the same form. .TP -\fBacos(\fIarg\fB)\fR +\fBacos \fIarg\fR +. Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR] -radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR]. +radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. .TP -\fBasin(\fIarg\fB)\fR -Returns the arc sine of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR] -radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR]. +\fBasin \fIarg\fR +. +Returns the arc sine of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] +radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR]. .TP -\fBatan(\fIarg\fB)\fR -Returns the arc tangent of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR] +\fBatan \fIarg\fR +. +Returns the arc tangent of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR] radians. .TP -\fBatan2(\fIy, x\fB)\fR -Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI-pi\fR,\fIpi\fR] +\fBatan2 \fIy x\fR +. +Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI\-pi\fR,\fIpi\fR] radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater -than \fI0\fR, this is equivalent to \fBatan(\fIy/x\fB)\fR. +than \fI0\fR, this is equivalent to +.QW "\fBatan \fR[\fBexpr\fR {\fIy\fB/\fIx\fR}]" . .TP -\fBbool(\fIarg\fB)\fR -Accepts any numerical value, or any string acceptable to +\fBbool \fIarg\fR +. +Accepts any numeric value, or any string acceptable to \fBstring is boolean\fR, and returns the corresponding boolean value \fB0\fR or \fB1\fR. Non-zero numbers are true. Other numbers are false. Non-numeric strings produce boolean value in agreement with \fBstring is true\fR and \fBstring is false\fR. .TP -\fBceil(\fIarg\fB)\fR +\fBceil \fIarg\fR +. Returns the smallest integral floating-point value (i.e. with a zero -fractional part) not less than \fIarg\fR. +fractional part) not less than \fIarg\fR. The argument may be any +numeric value. .TP -\fBcos(\fIarg\fB)\fR +\fBcos \fIarg\fR +. Returns the cosine of \fIarg\fR, measured in radians. .TP -\fBcosh(\fIarg\fB)\fR +\fBcosh \fIarg\fR +. Returns the hyperbolic cosine of \fIarg\fR. If the result would cause an overflow, an error is returned. .TP -\fBdouble(\fIarg\fB)\fR +\fBdouble \fIarg\fR +. +The argument may be any numeric value, If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts -\fIarg\fR to floating-point and returns the converted value. +\fIarg\fR to floating-point and returns the converted value. May return +\fBInf\fR or \fB\-Inf\fR when the argument is a numeric value that exceeds +the floating-point range. .TP -\fBexp(\fIarg\fB)\fR +\fBentier \fIarg\fR +. +The argument may be any numeric value. The integer part of \fIarg\fR +is determined and returned. The integer range returned by this function +is unlimited, unlike \fBint\fR and \fBwide\fR which +truncate their range to fit in particular storage widths. +.TP +\fBexp \fIarg\fR +. Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR. If the result would cause an overflow, an error is returned. .TP -\fBfloor(\fIarg\fB)\fR +\fBfloor \fIarg\fR +. Returns the largest integral floating-point value (i.e. with a zero -fractional part) not greater than \fIarg\fR. +fractional part) not greater than \fIarg\fR. The argument may be +any numeric value. .TP -\fBfmod(\fIx, y\fB)\fR +\fBfmod \fIx y\fR +. Returns the floating-point remainder of the division of \fIx\fR by \fIy\fR. If \fIy\fR is 0, an error is returned. .TP -\fBhypot(\fIx, y\fB)\fR -Computes the length of the hypotenuse of a right-angled triangle -\fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR. +\fBhypot \fIx y\fR +. +Computes the length of the hypotenuse of a right-angled triangle, +approximately +.QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]" +except for being more numerically stable when the two arguments have +substantially different magnitudes. +.TP +\fBint \fIarg\fR +. +The argument may be any numeric value. The integer part of \fIarg\fR +is determined, and then the low order bits of that integer value up +to the machine word size are returned as an integer value. For reference, +the number of bytes in the machine word are stored in the \fBwordSize\fR +element of the \fBtcl_platform\fR array. .TP -\fBint(\fIarg\fB)\fR -If \fIarg\fR is an integer value of the same width as the machine -word, returns \fIarg\fR, otherwise -converts \fIarg\fR to an integer (of the same size as a machine word, -i.e. 32-bits on 32-bit systems, and 64-bits on 64-bit systems) by -truncation and returns the converted value. +\fBisqrt \fIarg\fR +. +Computes the integer part of the square root of \fIarg\fR. \fIArg\fR must be +a positive value, either an integer or a floating point number. +Unlike \fBsqrt\fR, which is limited to the precision of a floating point +number, \fIisqrt\fR will return a result of arbitrary precision. .TP -\fBlog(\fIarg\fB)\fR +\fBlog \fIarg\fR +. Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a positive value. .TP -\fBlog10(\fIarg\fB)\fR +\fBlog10 \fIarg\fR +. Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a positive value. .TP -\fBpow(\fIx, y\fB)\fR +\fBmax \fIarg\fB \fI...\fR +. +Accepts one or more numeric arguments. Returns the one argument +with the greatest value. +.TP +\fBmin \fIarg\fB \fI...\fR +. +Accepts one or more numeric arguments. Returns the one argument +with the least value. +.TP +\fBpow \fIx y\fR +. Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR is negative, \fIy\fR must be an integer value. .TP -\fBrand()\fR +\fBrand\fR +. Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR). The generator algorithm is a simple linear congruential generator that is not cryptographically secure. Each result from \fBrand\fR completely @@ -184,47 +251,55 @@ determines all future results from subsequent calls to \fBrand\fR, so one-time passwords. The seed of the generator is initialized from the internal clock of the machine or may be set with the \fBsrand\fR function. .TP -\fBround(\fIarg\fB)\fR +\fBround \fIarg\fR +. If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts \fIarg\fR to integer by rounding and returns the converted value. .TP -\fBsin(\fIarg\fB)\fR +\fBsin \fIarg\fR +. Returns the sine of \fIarg\fR, measured in radians. .TP -\fBsinh(\fIarg\fB)\fR +\fBsinh \fIarg\fR +. Returns the hyperbolic sine of \fIarg\fR. If the result would cause an overflow, an error is returned. .TP -\fBsqrt(\fIarg\fB)\fR -Returns the square root of \fIarg\fR. \fIArg\fR must be non-negative. +\fBsqrt \fIarg\fR +. +The argument may be any non-negative numeric value. Returns a floating-point +value that is the square root of \fIarg\fR. May return \fBInf\fR when the +argument is a numeric value that exceeds the square of the maximum value of +the floating-point range. .TP -\fBsrand(\fIarg\fB)\fR +\fBsrand \fIarg\fR +. The \fIarg\fR, which must be an integer, is used to reset the seed for the random number generator of \fBrand\fR. Returns the first random -number (see \fBrand()\fR) from that seed. Each interpreter has its own seed. +number (see \fBrand\fR) from that seed. Each interpreter has its own seed. .TP -\fBtan(\fIarg\fB)\fR +\fBtan \fIarg\fR +. Returns the tangent of \fIarg\fR, measured in radians. .TP -\fBtanh(\fIarg\fB)\fR +\fBtanh \fIarg\fR +. Returns the hyperbolic tangent of \fIarg\fR. .TP -\fBwide(\fIarg\fB)\fR -Converts \fIarg\fR to an integer value at least 64-bits wide (by sign-extension -if \fIarg\fR is a 32-bit number) if it is not one already. -.PP -In addition to these predefined functions, applications may -define additional functions by using \fBproc\fR (or any other method, -such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define -new commands in the \fBtcl::mathfunc\fR namespace. In addition, an -obsolete interface named \fBTcl_CreateMathFunc\fR() is available to -extensions that are written in C. The latter interface is not recommended -for new implementations.. +\fBwide \fIarg\fR +. +The argument may be any numeric value. The integer part of \fIarg\fR +is determined, and then the low order 64 bits of that integer value +are returned as an integer value. .SH "SEE ALSO" -expr(n), namespace(n) +expr(n), mathop(n), namespace(n) .SH "COPYRIGHT" +.nf Copyright (c) 1993 The Regents of the University of California. -.br Copyright (c) 1994-2000 Sun Microsystems Incorporated. -.br -Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. +Copyright (c) 2005, 2006 by Kevin B. Kenny <kennykb@acm.org>. +.fi +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: |