summaryrefslogtreecommitdiffstats
path: root/doc/expr.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/expr.n')
-rw-r--r--doc/expr.n81
1 files changed, 62 insertions, 19 deletions
diff --git a/doc/expr.n b/doc/expr.n
index b43765c..c9c1f81 100644
--- a/doc/expr.n
+++ b/doc/expr.n
@@ -5,7 +5,7 @@
'\" 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.10.2.1 2003/07/04 22:25:23 dkf Exp $
+'\" RCS: @(#) $Id: expr.n,v 1.10.2.2 2004/10/27 09:35:38 dkf Exp $
'\"
.so man.macros
.TH expr n 8.4 Tcl "Tcl Built-In Commands"
@@ -19,7 +19,7 @@ expr \- Evaluate an expression
.SH DESCRIPTION
.PP
-Concatenates \fIarg\fR's (adding separator spaces between them),
+Concatenates \fIarg\fRs (adding separator spaces between them),
evaluates the result as a Tcl expression, and returns the value.
The operators permitted in Tcl expressions are a subset of
the operators permitted in C expressions, and they have the
@@ -51,9 +51,10 @@ ways accepted by an ANSI-compliant C compiler (except that the
\fBf\fR, \fBF\fR, \fBl\fR, and \fBL\fR suffixes will not be permitted in
most installations). For example, all of the
following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16.
-If no numeric interpretation is possible, then an operand is left
-as a string (and only a limited set of operators may be applied to
-it).
+If no numeric interpretation is possible (note that all literal
+operands that are not numeric or boolean must be quoted with either
+braces or with double quotes), then an operand is left as a string
+(and only a limited set of operators may be applied to it).
.PP
.VS 8.4
On 32-bit systems, integer values MAX_INT (0x7FFFFFFF) and MIN_INT
@@ -64,33 +65,34 @@ possible at all.)
.PP
Operands may be specified in any of the following ways:
.IP [1]
-As an numeric value, either integer or floating-point.
+As a numeric value, either integer or floating-point.
.IP [2]
+As a boolean value, using any form understood by \fBstring is boolean\fR.
+.IP [3]
As a Tcl variable, using standard \fB$\fR notation.
The variable's value will be used as the operand.
-.IP [3]
+.IP [4]
As a string enclosed in double-quotes.
The expression parser will perform backslash, variable, and
command substitutions on the information between the quotes,
and use the resulting value as the operand
-.IP [4]
+.IP [5]
As a string enclosed in braces.
The characters between the open brace and matching close brace
will be used as the operand without any substitutions.
-.IP [5]
+.IP [6]
As a Tcl command enclosed in brackets.
The command will be executed and its result will be used as
the operand.
-.IP [6]
+.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.
.LP
-Where substitutions occur above (e.g. inside quoted strings), they
+Where the above substitutions occur (e.g. inside quoted strings), they
are performed by the expression's instructions.
-However, an additional layer of substitution may already have
-been performed by the command parser before the expression
-processor was called.
+However, the command parser may already have performed one round of
+substitution before the expression processor was called.
As discussed below, it is usually best to enclose expressions
in braces to prevent the command parser from performing substitutions
on the contents.
@@ -113,12 +115,12 @@ The valid operators are listed below, grouped in decreasing order
of precedence:
.TP 20
\fB\-\0\0+\0\0~\0\0!\fR
-Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands
+Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators
may be applied to string operands, and bit-wise NOT may be
applied only to integers.
.TP 20
\fB*\0\0/\0\0%\fR
-Multiply, divide, remainder. None of these operands may be
+Multiply, divide, remainder. None of these operators may be
applied to string operands, and remainder may be applied only
to integers.
The remainder will always have the same sign as the divisor and
@@ -169,7 +171,7 @@ Valid for boolean and numeric (integers or floating-point) operands only.
If-then-else, as in C. If \fIx\fR
evaluates to non-zero, then the result is the value of \fIy\fR.
Otherwise the result is the value of \fIz\fR.
-The \fIx\fR operand must have a numeric value.
+The \fIx\fR operand must have a boolean or numeric value.
.LP
See the C manual for more details on the results
produced by each operator.
@@ -359,7 +361,6 @@ example,
\fBexpr 20.0/5.0\fR
.CE
returns \fB4.0\fR, not \fB4\fR.
-
.SH "STRING OPERATIONS"
.PP
String values may be used as operands of the comparison operators,
@@ -420,9 +421,51 @@ The most expensive code is required for
unbraced expressions that contain command substitutions.
These expressions must be implemented by generating new code
each time the expression is executed.
+.SH EXAMPLES
+Define a procedure that computes an "interesting" mathematical
+function:
+.CS
+proc calc {x y} {
+ \fBexpr\fR { ($x*$x - $y*$y) / exp($x*$x + $y*$y) }
+}
+.CE
+.PP
+Convert polar coordinates into cartesian coordinates:
+.CS
+# convert from ($radius,$angle)
+set x [\fBexpr\fR { $radius * cos($angle) }]
+set y [\fBexpr\fR { $radius * sin($angle) }]
+.CE
+.PP
+Convert cartesian coordinates into polar coordinates:
+.CS
+# convert from ($x,$y)
+set radius [\fBexpr\fR { hypot($y, $x) }]
+set angle [\fBexpr\fR { atan2($y, $x) }]
+.CE
+.PP
+Print a message describing the relationship of two string values to
+each other:
+.CS
+puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]"
+.CE
+.PP
+Set a variable to whether an environment variable is both defined at
+all and also set to a true boolean value:
+.CS
+set isTrue [\fBexpr\fR {
+ [info exists ::env(SOME_ENV_VAR)] &&
+ [string is true -strict $::env(SOME_ENV_VAR)]
+}]
+.CE
+.PP
+Generate a random integer in the range 0..99 inclusive:
+.CS
+set randNum [\fBexpr\fR { int(100 * rand()) }]
+.CE
.SH "SEE ALSO"
-array(n), string(n), Tcl(n)
+array(n), for(n), if(n), string(n), Tcl(n), while(n)
.SH KEYWORDS
arithmetic, boolean, compare, expression, fuzzy comparison