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: expr.n,v 1.34 2007/12/13 15:22:32 dgp Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH expr n 8.5 Tcl "Tcl Built-In Commands" |
---|
13 | .BS |
---|
14 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
15 | .SH NAME |
---|
16 | expr \- Evaluate an expression |
---|
17 | .SH SYNOPSIS |
---|
18 | \fBexpr \fIarg \fR?\fIarg arg ...\fR? |
---|
19 | .BE |
---|
20 | .SH DESCRIPTION |
---|
21 | .PP |
---|
22 | Concatenates \fIarg\fRs (adding separator spaces between them), |
---|
23 | evaluates the result as a Tcl expression, and returns the value. |
---|
24 | The operators permitted in Tcl expressions include a subset of |
---|
25 | the operators permitted in C expressions. For those operators |
---|
26 | common to both Tcl and C, Tcl applies the same meaning and precedence |
---|
27 | as the corresponding C operators. |
---|
28 | Expressions almost always yield numeric results |
---|
29 | (integer or floating-point values). |
---|
30 | For example, the expression |
---|
31 | .CS |
---|
32 | \fBexpr 8.2 + 6\fR |
---|
33 | .CE |
---|
34 | evaluates to 14.2. |
---|
35 | Tcl expressions differ from C expressions in the way that |
---|
36 | operands are specified. Also, Tcl expressions support |
---|
37 | non-numeric operands and string comparisons, as well as some |
---|
38 | additional operators not found in C. |
---|
39 | .SS OPERANDS |
---|
40 | .PP |
---|
41 | A Tcl expression consists of a combination of operands, operators, |
---|
42 | and parentheses. |
---|
43 | White space may be used between the operands and operators and |
---|
44 | parentheses; it is ignored by the expression's instructions. |
---|
45 | Where possible, operands are interpreted as integer values. |
---|
46 | .VS 8.5 |
---|
47 | Integer values may be specified in decimal (the normal case), in binary |
---|
48 | (if the first two characters of the operand are \fB0b\fR), in octal |
---|
49 | (if the first two characters of the operand are \fB0o\fR), or in hexadecimal |
---|
50 | (if the first two characters of the operand are \fB0x\fR). For |
---|
51 | compatibility with older Tcl releases, an octal integer value is also |
---|
52 | indicated simply when the first character of the operand is \fB0\fR, |
---|
53 | whether or not the second character is also \fBo\fR. |
---|
54 | If an operand does not have one of the integer formats given |
---|
55 | above, then it is treated as a floating-point number if that is |
---|
56 | possible. Floating-point numbers may be specified in any of several |
---|
57 | common formats making use of the decimal digits, the decimal point \fB.\fR, |
---|
58 | the characters \fBe\fR or \fBE\fR indicating scientific notation, and |
---|
59 | the sign characters \fB+\fR or \fB\-\fR. For example, all of the |
---|
60 | following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. |
---|
61 | Also recognized as floating point values are the strings \fBInf\fR |
---|
62 | and \fBNaN\fR making use of any case for each character. |
---|
63 | .VE 8.5 |
---|
64 | If no numeric interpretation is possible (note that all literal |
---|
65 | operands that are not numeric or boolean must be quoted with either |
---|
66 | braces or with double quotes), then an operand is left as a string |
---|
67 | (and only a limited set of operators may be applied to it). |
---|
68 | .PP |
---|
69 | Operands may be specified in any of the following ways: |
---|
70 | .IP [1] |
---|
71 | As a numeric value, either integer or floating-point. |
---|
72 | .IP [2] |
---|
73 | As a boolean value, using any form understood by \fBstring is boolean\fR. |
---|
74 | .IP [3] |
---|
75 | As a Tcl variable, using standard \fB$\fR notation. |
---|
76 | The variable's value will be used as the operand. |
---|
77 | .IP [4] |
---|
78 | As a string enclosed in double-quotes. |
---|
79 | The expression parser will perform backslash, variable, and |
---|
80 | command substitutions on the information between the quotes, |
---|
81 | and use the resulting value as the operand |
---|
82 | .IP [5] |
---|
83 | As a string enclosed in braces. |
---|
84 | The characters between the open brace and matching close brace |
---|
85 | will be used as the operand without any substitutions. |
---|
86 | .IP [6] |
---|
87 | As a Tcl command enclosed in brackets. |
---|
88 | The command will be executed and its result will be used as |
---|
89 | the operand. |
---|
90 | .IP [7] |
---|
91 | As a mathematical function whose arguments have any of the above |
---|
92 | forms for operands, such as \fBsin($x)\fR. See \fBMATH FUNCTIONS\fR below for |
---|
93 | a discussion of how mathematical functions are handled. |
---|
94 | .LP |
---|
95 | Where the above substitutions occur (e.g. inside quoted strings), they |
---|
96 | are performed by the expression's instructions. |
---|
97 | However, the command parser may already have performed one round of |
---|
98 | substitution before the expression processor was called. |
---|
99 | As discussed below, it is usually best to enclose expressions |
---|
100 | in braces to prevent the command parser from performing substitutions |
---|
101 | on the contents. |
---|
102 | .PP |
---|
103 | For some examples of simple expressions, suppose the variable |
---|
104 | \fBa\fR has the value 3 and |
---|
105 | the variable \fBb\fR has the value 6. |
---|
106 | Then the command on the left side of each of the lines below |
---|
107 | will produce the value on the right side of the line: |
---|
108 | .CS |
---|
109 | .ta 6c |
---|
110 | \fBexpr\fR 3.1 + $a \fI6.1\fR |
---|
111 | \fBexpr\fR 2 + "$a.$b" \fI5.6\fR |
---|
112 | \fBexpr\fR 4*[llength "6 2"] \fI8\fR |
---|
113 | \fBexpr\fR {{word one} < "word $a"} \fI0\fR |
---|
114 | .CE |
---|
115 | .SS OPERATORS |
---|
116 | .PP |
---|
117 | The valid operators (most of which are also available as commands in |
---|
118 | the \fBtcl::mathop\fR namespace; see the \fBmathop\fR(n) manual page |
---|
119 | for details) are listed below, grouped in decreasing order of precedence: |
---|
120 | .TP 20 |
---|
121 | \fB\-\0\0+\0\0~\0\0!\fR |
---|
122 | Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators |
---|
123 | may be applied to string operands, and bit-wise NOT may be |
---|
124 | applied only to integers. |
---|
125 | .TP 20 |
---|
126 | \fB**\fR |
---|
127 | .VS 8.5 |
---|
128 | Exponentiation. Valid for any numeric operands. |
---|
129 | .VE 8.5 |
---|
130 | .TP 20 |
---|
131 | \fB*\0\0/\0\0%\fR |
---|
132 | Multiply, divide, remainder. None of these operators may be |
---|
133 | applied to string operands, and remainder may be applied only |
---|
134 | to integers. |
---|
135 | The remainder will always have the same sign as the divisor and |
---|
136 | an absolute value smaller than the divisor. |
---|
137 | .TP 20 |
---|
138 | \fB+\0\0\-\fR |
---|
139 | Add and subtract. Valid for any numeric operands. |
---|
140 | .TP 20 |
---|
141 | \fB<<\0\0>>\fR |
---|
142 | Left and right shift. Valid for integer operands only. |
---|
143 | A right shift always propagates the sign bit. |
---|
144 | .TP 20 |
---|
145 | \fB<\0\0>\0\0<=\0\0>=\fR |
---|
146 | Boolean less, greater, less than or equal, and greater than or equal. |
---|
147 | Each operator produces 1 if the condition is true, 0 otherwise. |
---|
148 | These operators may be applied to strings as well as numeric operands, |
---|
149 | in which case string comparison is used. |
---|
150 | .TP 20 |
---|
151 | \fB==\0\0!=\fR |
---|
152 | Boolean equal and not equal. Each operator produces a zero/one result. |
---|
153 | Valid for all operand types. |
---|
154 | .TP 20 |
---|
155 | \fBeq\0\0ne\fR |
---|
156 | Boolean string equal and string not equal. Each operator produces a |
---|
157 | zero/one result. The operand types are interpreted only as strings. |
---|
158 | .TP 20 |
---|
159 | \fBin\0\0ni\fR |
---|
160 | .VS 8.5 |
---|
161 | List containment and negated list containment. Each operator produces |
---|
162 | a zero/one result and treats its first argument as a string and its |
---|
163 | second argument as a Tcl list. The \fBin\fR operator indicates |
---|
164 | whether the first argument is a member of the second argument list; |
---|
165 | the \fBni\fR operator inverts the sense of the result. |
---|
166 | .VE 8.5 |
---|
167 | .TP 20 |
---|
168 | \fB&\fR |
---|
169 | Bit-wise AND. Valid for integer operands only. |
---|
170 | .TP 20 |
---|
171 | \fB^\fR |
---|
172 | Bit-wise exclusive OR. Valid for integer operands only. |
---|
173 | .TP 20 |
---|
174 | \fB|\fR |
---|
175 | Bit-wise OR. Valid for integer operands only. |
---|
176 | .TP 20 |
---|
177 | \fB&&\fR |
---|
178 | Logical AND. Produces a 1 result if both operands are non-zero, |
---|
179 | 0 otherwise. |
---|
180 | Valid for boolean and numeric (integers or floating-point) operands only. |
---|
181 | .TP 20 |
---|
182 | \fB||\fR |
---|
183 | Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. |
---|
184 | Valid for boolean and numeric (integers or floating-point) operands only. |
---|
185 | .TP 20 |
---|
186 | \fIx\fB?\fIy\fB:\fIz\fR |
---|
187 | If-then-else, as in C. If \fIx\fR |
---|
188 | evaluates to non-zero, then the result is the value of \fIy\fR. |
---|
189 | Otherwise the result is the value of \fIz\fR. |
---|
190 | The \fIx\fR operand must have a boolean or numeric value. |
---|
191 | .LP |
---|
192 | See the C manual for more details on the results |
---|
193 | produced by each operator. |
---|
194 | .VS 8.5 |
---|
195 | The exponentiation operator promotes types like the multiply and |
---|
196 | divide operators, and produces a result that is the same as the output |
---|
197 | of the \fBpow\fR function (after any type conversions.) |
---|
198 | .VE 8.5 |
---|
199 | All of the binary operators group left-to-right within the same |
---|
200 | precedence level. For example, the command |
---|
201 | .CS |
---|
202 | \fBexpr\fR {4*2 < 7} |
---|
203 | .CE |
---|
204 | returns 0. |
---|
205 | .PP |
---|
206 | The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have |
---|
207 | .QW "lazy evaluation" , |
---|
208 | just as in C, which means that operands are not evaluated if they are |
---|
209 | not needed to determine the outcome. For example, in the command |
---|
210 | .CS |
---|
211 | \fBexpr {$v ? [a] : [b]}\fR |
---|
212 | .CE |
---|
213 | only one of |
---|
214 | .QW \fB[a]\fR |
---|
215 | or |
---|
216 | .QW \fB[b]\fR |
---|
217 | will actually be evaluated, |
---|
218 | depending on the value of \fB$v\fR. Note, however, that this is |
---|
219 | only true if the entire expression is enclosed in braces; otherwise |
---|
220 | the Tcl parser will evaluate both |
---|
221 | .QW \fB[a]\fR |
---|
222 | and |
---|
223 | .QW \fB[b]\fR |
---|
224 | before invoking the \fBexpr\fR command. |
---|
225 | .SS "MATH FUNCTIONS" |
---|
226 | .PP |
---|
227 | .VS 8.5 |
---|
228 | When the expression parser encounters a mathematical function |
---|
229 | such as \fBsin($x)\fR, it replaces it with a call to an ordinary |
---|
230 | Tcl function in the \fBtcl::mathfunc\fR namespace. The processing |
---|
231 | of an expression such as: |
---|
232 | .CS |
---|
233 | \fBexpr {sin($x+$y)}\fR |
---|
234 | .CE |
---|
235 | is the same in every way as the processing of: |
---|
236 | .CS |
---|
237 | \fBexpr {[tcl::mathfunc::sin [expr {$x+$y}]]}\fR |
---|
238 | .CE |
---|
239 | which in turn is the same as the processing of: |
---|
240 | .CS |
---|
241 | \fBtcl::mathfunc::sin [expr {$x+$y}]\fR |
---|
242 | .CE |
---|
243 | .PP |
---|
244 | The executor will search for \fBtcl::mathfunc::sin\fR using the usual |
---|
245 | rules for resolving functions in namespaces. Either |
---|
246 | \fB::tcl::mathfunc::sin\fR or \fB[namespace |
---|
247 | current]::tcl::mathfunc::sin\fR will satisfy the request, and others |
---|
248 | may as well (depending on the current \fBnamespace path\fR setting). |
---|
249 | .PP |
---|
250 | See the \fBmathfunc\fR(n) manual page for the math functions that are |
---|
251 | available by default. |
---|
252 | .VE 8.5 |
---|
253 | .SS "TYPES, OVERFLOW, AND PRECISION" |
---|
254 | .PP |
---|
255 | .VS 8.5 |
---|
256 | All internal computations involving integers are done calling on the |
---|
257 | LibTomMath multiple precision integer library as required so that all |
---|
258 | integer calculations are performed exactly. Note that in Tcl releases |
---|
259 | prior to 8.5, integer calculations were performed with one of the C types |
---|
260 | \fIlong int\fR or \fITcl_WideInt\fR, causing implicit range truncation |
---|
261 | in those calculations where values overflowed the range of those types. |
---|
262 | Any code that relied on these implicit truncations will need to explicitly |
---|
263 | add \fBint()\fR or \fBwide()\fR function calls to expressions at the points |
---|
264 | where such truncation is required to take place. |
---|
265 | .VE 8.5 |
---|
266 | .PP |
---|
267 | All internal computations involving floating-point are |
---|
268 | done with the C type \fIdouble\fR. |
---|
269 | When converting a string to floating-point, exponent overflow is |
---|
270 | detected and results in the \fIdouble\fR value of \fBInf\fR or |
---|
271 | \fB\-Inf\fR as appropriate. Floating-point overflow and underflow |
---|
272 | are detected to the degree supported by the hardware, which is generally |
---|
273 | pretty reliable. |
---|
274 | .PP |
---|
275 | Conversion among internal representations for integer, floating-point, |
---|
276 | and string operands is done automatically as needed. |
---|
277 | For arithmetic computations, integers are used until some |
---|
278 | floating-point number is introduced, after which floating-point is used. |
---|
279 | For example, |
---|
280 | .CS |
---|
281 | \fBexpr\fR {5 / 4} |
---|
282 | .CE |
---|
283 | returns 1, while |
---|
284 | .CS |
---|
285 | \fBexpr\fR {5 / 4.0} |
---|
286 | \fBexpr\fR {5 / ( [string length "abcd"] + 0.0 )} |
---|
287 | .CE |
---|
288 | both return 1.25. |
---|
289 | Floating-point values are always returned with a |
---|
290 | .QW \fB.\fR |
---|
291 | or an |
---|
292 | .QW \fBe\fR |
---|
293 | so that they will not look like integer values. For example, |
---|
294 | .CS |
---|
295 | \fBexpr\fR {20.0/5.0} |
---|
296 | .CE |
---|
297 | returns \fB4.0\fR, not \fB4\fR. |
---|
298 | .SS "STRING OPERATIONS" |
---|
299 | .PP |
---|
300 | String values may be used as operands of the comparison operators, |
---|
301 | although the expression evaluator tries to do comparisons as integer |
---|
302 | or floating-point when it can, |
---|
303 | except in the case of the \fBeq\fR and \fBne\fR operators. |
---|
304 | If one of the operands of a comparison is a string and the other |
---|
305 | has a numeric value, a canonical string representation of the numeric |
---|
306 | operand value is generated to compare with the string operand. |
---|
307 | Canonical string representation for integer values is a decimal string |
---|
308 | format. Canonical string representation for floating-point values |
---|
309 | is that produced by the \fB%g\fR format specifier of Tcl's |
---|
310 | \fBformat\fR command. For example, the commands |
---|
311 | .CS |
---|
312 | \fBexpr {"0x03" > "2"}\fR |
---|
313 | \fBexpr {"0y" < "0x12"}\fR |
---|
314 | .CE |
---|
315 | both return 1. The first comparison is done using integer |
---|
316 | comparison, and the second is done using string comparison after |
---|
317 | the second operand is converted to the string \fB18\fR. |
---|
318 | Because of Tcl's tendency to treat values as numbers whenever |
---|
319 | possible, it is not generally a good idea to use operators like \fB==\fR |
---|
320 | when you really want string comparison and the values of the |
---|
321 | operands could be arbitrary; it is better in these cases to use |
---|
322 | the \fBeq\fR or \fBne\fR operators, or the \fBstring\fR command instead. |
---|
323 | .SH "PERFORMANCE CONSIDERATIONS" |
---|
324 | .PP |
---|
325 | Enclose expressions in braces for the best speed and the smallest |
---|
326 | storage requirements. |
---|
327 | This allows the Tcl bytecode compiler to generate the best code. |
---|
328 | .PP |
---|
329 | As mentioned above, expressions are substituted twice: |
---|
330 | once by the Tcl parser and once by the \fBexpr\fR command. |
---|
331 | For example, the commands |
---|
332 | .CS |
---|
333 | \fBset a 3\fR |
---|
334 | \fBset b {$a + 2}\fR |
---|
335 | \fBexpr $b*4\fR |
---|
336 | .CE |
---|
337 | return 11, not a multiple of 4. |
---|
338 | This is because the Tcl parser will first substitute \fB$a + 2\fR for |
---|
339 | the variable \fBb\fR, |
---|
340 | then the \fBexpr\fR command will evaluate the expression \fB$a + 2*4\fR. |
---|
341 | .PP |
---|
342 | Most expressions do not require a second round of substitutions. |
---|
343 | Either they are enclosed in braces or, if not, |
---|
344 | their variable and command substitutions yield numbers or strings |
---|
345 | that do not themselves require substitutions. |
---|
346 | However, because a few unbraced expressions |
---|
347 | need two rounds of substitutions, |
---|
348 | the bytecode compiler must emit |
---|
349 | additional instructions to handle this situation. |
---|
350 | The most expensive code is required for |
---|
351 | unbraced expressions that contain command substitutions. |
---|
352 | These expressions must be implemented by generating new code |
---|
353 | each time the expression is executed. |
---|
354 | .VS 8.5 |
---|
355 | When the expression is unbraced to allow the substitution of a function or |
---|
356 | operator, consider using the commands documented in the \fBmathfunc\fR(n) or |
---|
357 | \fBmathop\fR(n) manual pages directly instead. |
---|
358 | .VE 8.5 |
---|
359 | .SH EXAMPLES |
---|
360 | Define a procedure that computes an |
---|
361 | .QW interesting |
---|
362 | mathematical function: |
---|
363 | .CS |
---|
364 | proc tcl::mathfunc::calc {x y} { |
---|
365 | \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) } |
---|
366 | } |
---|
367 | .CE |
---|
368 | .PP |
---|
369 | Convert polar coordinates into cartesian coordinates: |
---|
370 | .CS |
---|
371 | # convert from ($radius,$angle) |
---|
372 | set x [\fBexpr\fR { $radius * cos($angle) }] |
---|
373 | set y [\fBexpr\fR { $radius * sin($angle) }] |
---|
374 | .CE |
---|
375 | .PP |
---|
376 | Convert cartesian coordinates into polar coordinates: |
---|
377 | .CS |
---|
378 | # convert from ($x,$y) |
---|
379 | set radius [\fBexpr\fR { hypot($y, $x) }] |
---|
380 | set angle [\fBexpr\fR { atan2($y, $x) }] |
---|
381 | .CE |
---|
382 | .PP |
---|
383 | Print a message describing the relationship of two string values to |
---|
384 | each other: |
---|
385 | .CS |
---|
386 | puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]" |
---|
387 | .CE |
---|
388 | .PP |
---|
389 | Set a variable to whether an environment variable is both defined at |
---|
390 | all and also set to a true boolean value: |
---|
391 | .CS |
---|
392 | set isTrue [\fBexpr\fR { |
---|
393 | [info exists ::env(SOME_ENV_VAR)] && |
---|
394 | [string is true -strict $::env(SOME_ENV_VAR)] |
---|
395 | }] |
---|
396 | .CE |
---|
397 | .PP |
---|
398 | Generate a random integer in the range 0..99 inclusive: |
---|
399 | .CS |
---|
400 | set randNum [\fBexpr\fR { int(100 * rand()) }] |
---|
401 | .CE |
---|
402 | .SH "SEE ALSO" |
---|
403 | array(n), for(n), if(n), mathfunc(n), mathop(n), namespace(n), proc(n), |
---|
404 | string(n), Tcl(n), while(n) |
---|
405 | .SH KEYWORDS |
---|
406 | arithmetic, boolean, compare, expression, fuzzy comparison |
---|
407 | .SH COPYRIGHT |
---|
408 | .nf |
---|
409 | Copyright (c) 1993 The Regents of the University of California. |
---|
410 | Copyright (c) 1994-2000 Sun Microsystems Incorporated. |
---|
411 | Copyright (c) 2005 by Kevin B. Kenny <kennykb@acm.org>. All rights reserved. |
---|
412 | .fi |
---|