Merged kennykb-numerics-branch back to the head; TIPs 132 and 232

1 files changed, 30 insertions, 129 deletions

diff --git a/doc/expr.n b/doc/expr.n
index 6779c93..55184b3 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-2000 Sun Microsystems, Inc.
+.\" Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: expr.n,v 1.18 2004/10/27 09:36:58 dkf Exp $
+'\" RCS: @(#) $Id: expr.n,v 1.19 2005/05/10 18:33:59 kennykb Exp $
 '\" 
 .so man.macros
 .TH expr n 8.5 Tcl "Tcl Built-In Commands"
@@ -84,8 +85,8 @@ The command will be executed and its result will be used as
 the operand.
 .IP [7]
 As a mathematical function whose arguments have any of the above
-forms for operands, such as \fBsin($x)\fR.  See below for a list of defined
-functions.
+forms for operands, such as \fBsin($x)\fR.  See MATH FUNCTIONS below for
+a discussion of how mathematical functions are handled.
 .LP
 Where the above substitutions occur (e.g. inside quoted strings), they
 are performed by the expression's instructions.
@@ -211,131 +212,24 @@ the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before
 invoking the \fBexpr\fR command.
 .SS "MATH FUNCTIONS"
 .PP
-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	\fBcosh\fR	\fBlog\fR	\fBsqrt\fR
-\fBacos\fR	\fBdouble\fR	\fBlog10\fR	\fBsrand\fR
-\fBasin\fR	\fBexp\fR	\fBpow\fR	\fBtan\fR
-\fBatan\fR	\fBfloor\fR	\fBrand\fR	\fBtanh\fR
-\fBatan2\fR	\fBfmod\fR	\fBround\fR	\fBwide\fR
-\fBceil\fR	\fBhypot\fR	\fBsin\fR
-\fBcos\fR	\fBint\fR	\fBsinh\fR
-.DE
-.PP
-.TP
-\fBabs(\fIarg\fB)\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
-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].
-.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].
-.TP
-\fBatan(\fIarg\fB)\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]
-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.
-.TP
-\fBceil(\fIarg\fB)\fR
-Returns the smallest integral floating-point value (i.e. with a zero
-fractional part) not less than \fIarg\fR.
-.TP
-\fBcos(\fIarg\fB)\fR
-Returns the cosine of \fIarg\fR, measured in radians.
-.TP
-\fBcosh(\fIarg\fB)\fR
-Returns the hyperbolic cosine of \fIarg\fR.  If the result would cause
-an overflow, an error is returned.
-.TP
-\fBdouble(\fIarg\fB)\fR
-If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts
-\fIarg\fR to floating-point and returns the converted value.
-.TP
-\fBexp(\fIarg\fB)\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
-Returns the largest integral floating-point value (i.e. with a zero
-fractional part) not greater than \fIarg\fR.
-.TP
-\fBfmod(\fIx, y\fB)\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.
-.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.
-.TP
-\fBlog(\fIarg\fB)\fR
-Returns the natural logarithm of \fIarg\fR.  \fIArg\fR must be a
-positive value.
-.TP
-\fBlog10(\fIarg\fB)\fR
-Returns the base 10 logarithm of \fIarg\fR.  \fIArg\fR must be a
-positive value.
-.TP
-\fBpow(\fIx, y\fB)\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
-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
-determines all future results from subsequent calls to \fBrand\fR, so
-\fBrand\fR should not be used to generate a sequence of secrets, such as
-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
-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
-Returns the sine of \fIarg\fR, measured in radians.
-.TP
-\fBsinh(\fIarg\fB)\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.
-.TP
-\fBsrand(\fIarg\fB)\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.
-.TP
-\fBtan(\fIarg\fB)\fR
-Returns the tangent of \fIarg\fR, measured in radians.
-.TP
-\fBtanh(\fIarg\fB)\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.
+When the expression parser encounters a mathematical function
+such as \fBsin($x)\fR, it replaces it with a call to an ordinary
+Tcl function in the \fBtcl::mathfunc\fR namespace.  The processing
+of an expression such as:
+.CS
+\fBexpr {sin($x+$y)}\fR
+.CE
+is the same in every way as the processing of:
+.CS
+\fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}
+.CE
+The executor will search for \fBtcl::mathfunc::sin\fR using the
+usual rules for resolving functions in namespaces. Either
+\fB::tcl::mathfunc::sin\fR or \fB[namespace current]::tcl::mathfunc::sin\fR
+will satisfy the request.
 .PP
-In addition to these predefined functions, applications may
-define additional functions using \fBTcl_CreateMathFunc\fR().
+See the \fBmathfunc(n)\fR manual page for the math functions that are
+available by default.
 .SS "TYPES, OVERFLOW, AND PRECISION"
 .PP
 All internal computations involving integers are done with the C type
@@ -430,7 +324,7 @@ each time the expression is executed.
 Define a procedure that computes an "interesting" mathematical
 function:
 .CS
-proc calc {x y} {
+proc tcl::mathfunc::calc {x y} {
     \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) }
 }
 .CE
@@ -470,7 +364,14 @@ set randNum [\fBexpr\fR { int(100 * rand()) }]
 .CE
 
 .SH "SEE ALSO"
-array(n), for(n), if(n), string(n), Tcl(n), while(n)
+array(n), for(n), if(n), mathfunc(n), namespace(n), proc(n), string(n), Tcl(n), while(n)
 
 .SH KEYWORDS
 arithmetic, boolean, compare, expression, fuzzy comparison
+
+.SH COPYRIGHT
+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.