Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | '\" |
2 | '\" Copyright (c) 1993 The Regents of the University of California. | |
3 | '\" Copyright (c) 1994-2000 Sun Microsystems, Inc. | |
4 | '\" | |
5 | '\" See the file "license.terms" for information on usage and redistribution | |
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
7 | '\" | |
8 | '\" RCS: @(#) $Id: expr.n,v 1.10.2.2 2004/10/27 09:35:38 dkf Exp $ | |
9 | '\" | |
10 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
11 | '\" manual entries. | |
12 | '\" | |
13 | '\" .AP type name in/out ?indent? | |
14 | '\" Start paragraph describing an argument to a library procedure. | |
15 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
16 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
17 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
18 | '\" needed; use .AS below instead) | |
19 | '\" | |
20 | '\" .AS ?type? ?name? | |
21 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
22 | '\" name are examples of largest possible arguments that will be passed | |
23 | '\" to .AP later. If args are omitted, default tab stops are used. | |
24 | '\" | |
25 | '\" .BS | |
26 | '\" Start box enclosure. From here until next .BE, everything will be | |
27 | '\" enclosed in one large box. | |
28 | '\" | |
29 | '\" .BE | |
30 | '\" End of box enclosure. | |
31 | '\" | |
32 | '\" .CS | |
33 | '\" Begin code excerpt. | |
34 | '\" | |
35 | '\" .CE | |
36 | '\" End code excerpt. | |
37 | '\" | |
38 | '\" .VS ?version? ?br? | |
39 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
40 | '\" of man pages. The first argument is ignored and used for recording | |
41 | '\" the version when the .VS was added, so that the sidebars can be | |
42 | '\" found and removed when they reach a certain age. If another argument | |
43 | '\" is present, then a line break is forced before starting the sidebar. | |
44 | '\" | |
45 | '\" .VE | |
46 | '\" End of vertical sidebar. | |
47 | '\" | |
48 | '\" .DS | |
49 | '\" Begin an indented unfilled display. | |
50 | '\" | |
51 | '\" .DE | |
52 | '\" End of indented unfilled display. | |
53 | '\" | |
54 | '\" .SO | |
55 | '\" Start of list of standard options for a Tk widget. The | |
56 | '\" options follow on successive lines, in four columns separated | |
57 | '\" by tabs. | |
58 | '\" | |
59 | '\" .SE | |
60 | '\" End of list of standard options for a Tk widget. | |
61 | '\" | |
62 | '\" .OP cmdName dbName dbClass | |
63 | '\" Start of description of a specific option. cmdName gives the | |
64 | '\" option's name as specified in the class command, dbName gives | |
65 | '\" the option's name in the option database, and dbClass gives | |
66 | '\" the option's class in the option database. | |
67 | '\" | |
68 | '\" .UL arg1 arg2 | |
69 | '\" Print arg1 underlined, then print arg2 normally. | |
70 | '\" | |
71 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
72 | '\" | |
73 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
74 | .if t .wh -1.3i ^B | |
75 | .nr ^l \n(.l | |
76 | .ad b | |
77 | '\" # Start an argument description | |
78 | .de AP | |
79 | .ie !"\\$4"" .TP \\$4 | |
80 | .el \{\ | |
81 | . ie !"\\$2"" .TP \\n()Cu | |
82 | . el .TP 15 | |
83 | .\} | |
84 | .ta \\n()Au \\n()Bu | |
85 | .ie !"\\$3"" \{\ | |
86 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
87 | .\".b | |
88 | .\} | |
89 | .el \{\ | |
90 | .br | |
91 | .ie !"\\$2"" \{\ | |
92 | \&\\$1 \\fI\\$2\\fP | |
93 | .\} | |
94 | .el \{\ | |
95 | \&\\fI\\$1\\fP | |
96 | .\} | |
97 | .\} | |
98 | .. | |
99 | '\" # define tabbing values for .AP | |
100 | .de AS | |
101 | .nr )A 10n | |
102 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
103 | .nr )B \\n()Au+15n | |
104 | .\" | |
105 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
106 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
107 | .. | |
108 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
109 | '\" # BS - start boxed text | |
110 | '\" # ^y = starting y location | |
111 | '\" # ^b = 1 | |
112 | .de BS | |
113 | .br | |
114 | .mk ^y | |
115 | .nr ^b 1u | |
116 | .if n .nf | |
117 | .if n .ti 0 | |
118 | .if n \l'\\n(.lu\(ul' | |
119 | .if n .fi | |
120 | .. | |
121 | '\" # BE - end boxed text (draw box now) | |
122 | .de BE | |
123 | .nf | |
124 | .ti 0 | |
125 | .mk ^t | |
126 | .ie n \l'\\n(^lu\(ul' | |
127 | .el \{\ | |
128 | .\" Draw four-sided box normally, but don't draw top of | |
129 | .\" box if the box started on an earlier page. | |
130 | .ie !\\n(^b-1 \{\ | |
131 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
132 | .\} | |
133 | .el \}\ | |
134 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
135 | .\} | |
136 | .\} | |
137 | .fi | |
138 | .br | |
139 | .nr ^b 0 | |
140 | .. | |
141 | '\" # VS - start vertical sidebar | |
142 | '\" # ^Y = starting y location | |
143 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
144 | .de VS | |
145 | .if !"\\$2"" .br | |
146 | .mk ^Y | |
147 | .ie n 'mc \s12\(br\s0 | |
148 | .el .nr ^v 1u | |
149 | .. | |
150 | '\" # VE - end of vertical sidebar | |
151 | .de VE | |
152 | .ie n 'mc | |
153 | .el \{\ | |
154 | .ev 2 | |
155 | .nf | |
156 | .ti 0 | |
157 | .mk ^t | |
158 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
159 | .sp -1 | |
160 | .fi | |
161 | .ev | |
162 | .\} | |
163 | .nr ^v 0 | |
164 | .. | |
165 | '\" # Special macro to handle page bottom: finish off current | |
166 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
167 | '\" # page bottom macro. | |
168 | .de ^B | |
169 | .ev 2 | |
170 | 'ti 0 | |
171 | 'nf | |
172 | .mk ^t | |
173 | .if \\n(^b \{\ | |
174 | .\" Draw three-sided box if this is the box's first page, | |
175 | .\" draw two sides but no top otherwise. | |
176 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
178 | .\} | |
179 | .if \\n(^v \{\ | |
180 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
181 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
182 | .\} | |
183 | .bp | |
184 | 'fi | |
185 | .ev | |
186 | .if \\n(^b \{\ | |
187 | .mk ^y | |
188 | .nr ^b 2 | |
189 | .\} | |
190 | .if \\n(^v \{\ | |
191 | .mk ^Y | |
192 | .\} | |
193 | .. | |
194 | '\" # DS - begin display | |
195 | .de DS | |
196 | .RS | |
197 | .nf | |
198 | .sp | |
199 | .. | |
200 | '\" # DE - end display | |
201 | .de DE | |
202 | .fi | |
203 | .RE | |
204 | .sp | |
205 | .. | |
206 | '\" # SO - start of list of standard options | |
207 | .de SO | |
208 | .SH "STANDARD OPTIONS" | |
209 | .LP | |
210 | .nf | |
211 | .ta 5.5c 11c | |
212 | .ft B | |
213 | .. | |
214 | '\" # SE - end of list of standard options | |
215 | .de SE | |
216 | .fi | |
217 | .ft R | |
218 | .LP | |
219 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
220 | .. | |
221 | '\" # OP - start of full description for a single option | |
222 | .de OP | |
223 | .LP | |
224 | .nf | |
225 | .ta 4c | |
226 | Command-Line Name: \\fB\\$1\\fR | |
227 | Database Name: \\fB\\$2\\fR | |
228 | Database Class: \\fB\\$3\\fR | |
229 | .fi | |
230 | .IP | |
231 | .. | |
232 | '\" # CS - begin code excerpt | |
233 | .de CS | |
234 | .RS | |
235 | .nf | |
236 | .ta .25i .5i .75i 1i | |
237 | .. | |
238 | '\" # CE - end code excerpt | |
239 | .de CE | |
240 | .fi | |
241 | .RE | |
242 | .. | |
243 | .de UL | |
244 | \\$1\l'|0\(ul'\\$2 | |
245 | .. | |
246 | .TH expr n 8.4 Tcl "Tcl Built-In Commands" | |
247 | .BS | |
248 | '\" Note: do not modify the .SH NAME line immediately below! | |
249 | .SH NAME | |
250 | expr \- Evaluate an expression | |
251 | .SH SYNOPSIS | |
252 | \fBexpr \fIarg \fR?\fIarg arg ...\fR? | |
253 | .BE | |
254 | ||
255 | .SH DESCRIPTION | |
256 | .PP | |
257 | Concatenates \fIarg\fRs (adding separator spaces between them), | |
258 | evaluates the result as a Tcl expression, and returns the value. | |
259 | The operators permitted in Tcl expressions are a subset of | |
260 | the operators permitted in C expressions, and they have the | |
261 | same meaning and precedence as the corresponding C operators. | |
262 | Expressions almost always yield numeric results | |
263 | (integer or floating-point values). | |
264 | For example, the expression | |
265 | .CS | |
266 | \fBexpr 8.2 + 6\fR | |
267 | .CE | |
268 | evaluates to 14.2. | |
269 | Tcl expressions differ from C expressions in the way that | |
270 | operands are specified. Also, Tcl expressions support | |
271 | non-numeric operands and string comparisons. | |
272 | .SH OPERANDS | |
273 | .PP | |
274 | A Tcl expression consists of a combination of operands, operators, | |
275 | and parentheses. | |
276 | White space may be used between the operands and operators and | |
277 | parentheses; it is ignored by the expression's instructions. | |
278 | Where possible, operands are interpreted as integer values. | |
279 | Integer values may be specified in decimal (the normal case), in octal (if the | |
280 | first character of the operand is \fB0\fR), or in hexadecimal (if the first | |
281 | two characters of the operand are \fB0x\fR). | |
282 | If an operand does not have one of the integer formats given | |
283 | above, then it is treated as a floating-point number if that is | |
284 | possible. Floating-point numbers may be specified in any of the | |
285 | ways accepted by an ANSI-compliant C compiler (except that the | |
286 | \fBf\fR, \fBF\fR, \fBl\fR, and \fBL\fR suffixes will not be permitted in | |
287 | most installations). For example, all of the | |
288 | following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. | |
289 | If no numeric interpretation is possible (note that all literal | |
290 | operands that are not numeric or boolean must be quoted with either | |
291 | braces or with double quotes), then an operand is left as a string | |
292 | (and only a limited set of operators may be applied to it). | |
293 | .PP | |
294 | .VS 8.4 | |
295 | On 32-bit systems, integer values MAX_INT (0x7FFFFFFF) and MIN_INT | |
296 | (-0x80000000) will be represented as 32-bit values, and integer values | |
297 | outside that range will be represented as 64-bit values (if that is | |
298 | possible at all.) | |
299 | .VE 8.4 | |
300 | .PP | |
301 | Operands may be specified in any of the following ways: | |
302 | .IP [1] | |
303 | As a numeric value, either integer or floating-point. | |
304 | .IP [2] | |
305 | As a boolean value, using any form understood by \fBstring is boolean\fR. | |
306 | .IP [3] | |
307 | As a Tcl variable, using standard \fB$\fR notation. | |
308 | The variable's value will be used as the operand. | |
309 | .IP [4] | |
310 | As a string enclosed in double-quotes. | |
311 | The expression parser will perform backslash, variable, and | |
312 | command substitutions on the information between the quotes, | |
313 | and use the resulting value as the operand | |
314 | .IP [5] | |
315 | As a string enclosed in braces. | |
316 | The characters between the open brace and matching close brace | |
317 | will be used as the operand without any substitutions. | |
318 | .IP [6] | |
319 | As a Tcl command enclosed in brackets. | |
320 | The command will be executed and its result will be used as | |
321 | the operand. | |
322 | .IP [7] | |
323 | As a mathematical function whose arguments have any of the above | |
324 | forms for operands, such as \fBsin($x)\fR. See below for a list of defined | |
325 | functions. | |
326 | .LP | |
327 | Where the above substitutions occur (e.g. inside quoted strings), they | |
328 | are performed by the expression's instructions. | |
329 | However, the command parser may already have performed one round of | |
330 | substitution before the expression processor was called. | |
331 | As discussed below, it is usually best to enclose expressions | |
332 | in braces to prevent the command parser from performing substitutions | |
333 | on the contents. | |
334 | .PP | |
335 | For some examples of simple expressions, suppose the variable | |
336 | \fBa\fR has the value 3 and | |
337 | the variable \fBb\fR has the value 6. | |
338 | Then the command on the left side of each of the lines below | |
339 | will produce the value on the right side of the line: | |
340 | .CS | |
341 | .ta 6c | |
342 | \fBexpr 3.1 + $a 6.1 | |
343 | expr 2 + "$a.$b" 5.6 | |
344 | expr 4*[llength "6 2"] 8 | |
345 | expr {{word one} < "word $a"} 0\fR | |
346 | .CE | |
347 | .SH OPERATORS | |
348 | .PP | |
349 | The valid operators are listed below, grouped in decreasing order | |
350 | of precedence: | |
351 | .TP 20 | |
352 | \fB\-\0\0+\0\0~\0\0!\fR | |
353 | Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operators | |
354 | may be applied to string operands, and bit-wise NOT may be | |
355 | applied only to integers. | |
356 | .TP 20 | |
357 | \fB*\0\0/\0\0%\fR | |
358 | Multiply, divide, remainder. None of these operators may be | |
359 | applied to string operands, and remainder may be applied only | |
360 | to integers. | |
361 | The remainder will always have the same sign as the divisor and | |
362 | an absolute value smaller than the divisor. | |
363 | .TP 20 | |
364 | \fB+\0\0\-\fR | |
365 | Add and subtract. Valid for any numeric operands. | |
366 | .TP 20 | |
367 | \fB<<\0\0>>\fR | |
368 | Left and right shift. Valid for integer operands only. | |
369 | A right shift always propagates the sign bit. | |
370 | .TP 20 | |
371 | \fB<\0\0>\0\0<=\0\0>=\fR | |
372 | Boolean less, greater, less than or equal, and greater than or equal. | |
373 | Each operator produces 1 if the condition is true, 0 otherwise. | |
374 | These operators may be applied to strings as well as numeric operands, | |
375 | in which case string comparison is used. | |
376 | .TP 20 | |
377 | \fB==\0\0!=\fR | |
378 | Boolean equal and not equal. Each operator produces a zero/one result. | |
379 | Valid for all operand types. | |
380 | .VS 8.4 | |
381 | .TP 20 | |
382 | \fBeq\0\0ne\fR | |
383 | Boolean string equal and string not equal. Each operator produces a | |
384 | zero/one result. The operand types are interpreted only as strings. | |
385 | .VE 8.4 | |
386 | .TP 20 | |
387 | \fB&\fR | |
388 | Bit-wise AND. Valid for integer operands only. | |
389 | .TP 20 | |
390 | \fB^\fR | |
391 | Bit-wise exclusive OR. Valid for integer operands only. | |
392 | .TP 20 | |
393 | \fB|\fR | |
394 | Bit-wise OR. Valid for integer operands only. | |
395 | .TP 20 | |
396 | \fB&&\fR | |
397 | Logical AND. Produces a 1 result if both operands are non-zero, | |
398 | 0 otherwise. | |
399 | Valid for boolean and numeric (integers or floating-point) operands only. | |
400 | .TP 20 | |
401 | \fB||\fR | |
402 | Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. | |
403 | Valid for boolean and numeric (integers or floating-point) operands only. | |
404 | .TP 20 | |
405 | \fIx\fB?\fIy\fB:\fIz\fR | |
406 | If-then-else, as in C. If \fIx\fR | |
407 | evaluates to non-zero, then the result is the value of \fIy\fR. | |
408 | Otherwise the result is the value of \fIz\fR. | |
409 | The \fIx\fR operand must have a boolean or numeric value. | |
410 | .LP | |
411 | See the C manual for more details on the results | |
412 | produced by each operator. | |
413 | All of the binary operators group left-to-right within the same | |
414 | precedence level. For example, the command | |
415 | .CS | |
416 | \fBexpr 4*2 < 7\fR | |
417 | .CE | |
418 | returns 0. | |
419 | .PP | |
420 | The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have ``lazy | |
421 | evaluation'', just as in C, | |
422 | which means that operands are not evaluated if they are | |
423 | not needed to determine the outcome. For example, in the command | |
424 | .CS | |
425 | \fBexpr {$v ? [a] : [b]}\fR | |
426 | .CE | |
427 | only one of \fB[a]\fR or \fB[b]\fR will actually be evaluated, | |
428 | depending on the value of \fB$v\fR. Note, however, that this is | |
429 | only true if the entire expression is enclosed in braces; otherwise | |
430 | the Tcl parser will evaluate both \fB[a]\fR and \fB[b]\fR before | |
431 | invoking the \fBexpr\fR command. | |
432 | .SH "MATH FUNCTIONS" | |
433 | .PP | |
434 | Tcl supports the following mathematical functions in expressions, all | |
435 | of which work solely with floating-point numbers unless otherwise noted: | |
436 | .DS | |
437 | .ta 3c 6c 9c | |
438 | \fBabs\fR \fBcosh\fR \fBlog\fR \fBsqrt\fR | |
439 | \fBacos\fR \fBdouble\fR \fBlog10\fR \fBsrand\fR | |
440 | \fBasin\fR \fBexp\fR \fBpow\fR \fBtan\fR | |
441 | \fBatan\fR \fBfloor\fR \fBrand\fR \fBtanh\fR | |
442 | \fBatan2\fR \fBfmod\fR \fBround\fR \fBwide\fR | |
443 | \fBceil\fR \fBhypot\fR \fBsin\fR | |
444 | \fBcos\fR \fBint\fR \fBsinh\fR | |
445 | .DE | |
446 | .PP | |
447 | .TP | |
448 | \fBabs(\fIarg\fB)\fR | |
449 | Returns the absolute value of \fIarg\fR. \fIArg\fR may be either | |
450 | integer or floating-point, and the result is returned in the same form. | |
451 | .TP | |
452 | \fBacos(\fIarg\fB)\fR | |
453 | Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR] | |
454 | radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR]. | |
455 | .TP | |
456 | \fBasin(\fIarg\fB)\fR | |
457 | Returns the arc sine of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR] | |
458 | radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR]. | |
459 | .TP | |
460 | \fBatan(\fIarg\fB)\fR | |
461 | Returns the arc tangent of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR] | |
462 | radians. | |
463 | .TP | |
464 | \fBatan2(\fIy, x\fB)\fR | |
465 | Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI-pi\fR,\fIpi\fR] | |
466 | radians. \fIx\fR and \fIy\fR cannot both be 0. If \fIx\fR is greater | |
467 | than \fI0\fR, this is equivalent to \fBatan(\fIy/x\fB)\fR. | |
468 | .TP | |
469 | \fBceil(\fIarg\fB)\fR | |
470 | Returns the smallest integral floating-point value (i.e. with a zero | |
471 | fractional part) not less than \fIarg\fR. | |
472 | .TP | |
473 | \fBcos(\fIarg\fB)\fR | |
474 | Returns the cosine of \fIarg\fR, measured in radians. | |
475 | .TP | |
476 | \fBcosh(\fIarg\fB)\fR | |
477 | Returns the hyperbolic cosine of \fIarg\fR. If the result would cause | |
478 | an overflow, an error is returned. | |
479 | .TP | |
480 | \fBdouble(\fIarg\fB)\fR | |
481 | If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts | |
482 | \fIarg\fR to floating-point and returns the converted value. | |
483 | .TP | |
484 | \fBexp(\fIarg\fB)\fR | |
485 | Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR. | |
486 | If the result would cause an overflow, an error is returned. | |
487 | .TP | |
488 | \fBfloor(\fIarg\fB)\fR | |
489 | Returns the largest integral floating-point value (i.e. with a zero | |
490 | fractional part) not greater than \fIarg\fR. | |
491 | .TP | |
492 | \fBfmod(\fIx, y\fB)\fR | |
493 | Returns the floating-point remainder of the division of \fIx\fR by | |
494 | \fIy\fR. If \fIy\fR is 0, an error is returned. | |
495 | .TP | |
496 | \fBhypot(\fIx, y\fB)\fR | |
497 | Computes the length of the hypotenuse of a right-angled triangle | |
498 | \fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR. | |
499 | .TP | |
500 | \fBint(\fIarg\fB)\fR | |
501 | .VS 8.4 | |
502 | If \fIarg\fR is an integer value of the same width as the machine | |
503 | word, returns \fIarg\fR, otherwise | |
504 | converts \fIarg\fR to an integer (of the same size as a machine word, | |
505 | i.e. 32-bits on 32-bit systems, and 64-bits on 64-bit systems) by | |
506 | truncation and returns the converted value. | |
507 | .VE 8.4 | |
508 | .TP | |
509 | \fBlog(\fIarg\fB)\fR | |
510 | Returns the natural logarithm of \fIarg\fR. \fIArg\fR must be a | |
511 | positive value. | |
512 | .TP | |
513 | \fBlog10(\fIarg\fB)\fR | |
514 | Returns the base 10 logarithm of \fIarg\fR. \fIArg\fR must be a | |
515 | positive value. | |
516 | .TP | |
517 | \fBpow(\fIx, y\fB)\fR | |
518 | Computes the value of \fIx\fR raised to the power \fIy\fR. If \fIx\fR | |
519 | is negative, \fIy\fR must be an integer value. | |
520 | .TP | |
521 | \fBrand()\fR | |
522 | Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR). | |
523 | The generator algorithm is a simple linear congruential generator that | |
524 | is not cryptographically secure. Each result from \fBrand\fR completely | |
525 | determines all future results from subsequent calls to \fBrand\fR, so | |
526 | \fBrand\fR should not be used to generate a sequence of secrets, such as | |
527 | one-time passwords. The seed of the generator is initialized from the | |
528 | internal clock of the machine or may be set with the \fBsrand\fR function. | |
529 | .TP | |
530 | \fBround(\fIarg\fB)\fR | |
531 | If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts | |
532 | \fIarg\fR to integer by rounding and returns the converted value. | |
533 | .TP | |
534 | \fBsin(\fIarg\fB)\fR | |
535 | Returns the sine of \fIarg\fR, measured in radians. | |
536 | .TP | |
537 | \fBsinh(\fIarg\fB)\fR | |
538 | Returns the hyperbolic sine of \fIarg\fR. If the result would cause | |
539 | an overflow, an error is returned. | |
540 | .TP | |
541 | \fBsqrt(\fIarg\fB)\fR | |
542 | Returns the square root of \fIarg\fR. \fIArg\fR must be non-negative. | |
543 | .TP | |
544 | \fBsrand(\fIarg\fB)\fR | |
545 | The \fIarg\fR, which must be an integer, is used to reset the seed for | |
546 | the random number generator of \fBrand\fR. Returns the first random | |
547 | number (see \fBrand()\fR) from that seed. Each interpreter has its own seed. | |
548 | .TP | |
549 | \fBtan(\fIarg\fB)\fR | |
550 | Returns the tangent of \fIarg\fR, measured in radians. | |
551 | .TP | |
552 | \fBtanh(\fIarg\fB)\fR | |
553 | Returns the hyperbolic tangent of \fIarg\fR. | |
554 | .TP | |
555 | \fBwide(\fIarg\fB)\fR | |
556 | .VS 8.4 | |
557 | Converts \fIarg\fR to an integer value at least 64-bits wide (by sign-extension | |
558 | if \fIarg\fR is a 32-bit number) if it is not one already. | |
559 | .VE 8.4 | |
560 | .PP | |
561 | In addition to these predefined functions, applications may | |
562 | define additional functions using \fBTcl_CreateMathFunc\fR(). | |
563 | .SH "TYPES, OVERFLOW, AND PRECISION" | |
564 | .PP | |
565 | All internal computations involving integers are done with the C type | |
566 | \fIlong\fR, and all internal computations involving floating-point are | |
567 | done with the C type \fIdouble\fR. | |
568 | When converting a string to floating-point, exponent overflow is | |
569 | detected and results in a Tcl error. | |
570 | For conversion to integer from string, detection of overflow depends | |
571 | on the behavior of some routines in the local C library, so it should | |
572 | be regarded as unreliable. | |
573 | In any case, integer overflow and underflow are generally not detected | |
574 | reliably for intermediate results. Floating-point overflow and underflow | |
575 | are detected to the degree supported by the hardware, which is generally | |
576 | pretty reliable. | |
577 | .PP | |
578 | Conversion among internal representations for integer, floating-point, | |
579 | and string operands is done automatically as needed. | |
580 | For arithmetic computations, integers are used until some | |
581 | floating-point number is introduced, after which floating-point is used. | |
582 | For example, | |
583 | .CS | |
584 | \fBexpr 5 / 4\fR | |
585 | .CE | |
586 | returns 1, while | |
587 | .CS | |
588 | \fBexpr 5 / 4.0\fR | |
589 | \fBexpr 5 / ( [string length "abcd"] + 0.0 )\fR | |
590 | .CE | |
591 | both return 1.25. | |
592 | Floating-point values are always returned with a ``\fB.\fR'' | |
593 | or an \fBe\fR so that they will not look like integer values. For | |
594 | example, | |
595 | .CS | |
596 | \fBexpr 20.0/5.0\fR | |
597 | .CE | |
598 | returns \fB4.0\fR, not \fB4\fR. | |
599 | .SH "STRING OPERATIONS" | |
600 | .PP | |
601 | String values may be used as operands of the comparison operators, | |
602 | although the expression evaluator tries to do comparisons as integer | |
603 | or floating-point when it can, | |
604 | .VS 8.4 | |
605 | except in the case of the \fBeq\fR and \fBne\fR operators. | |
606 | .VE 8.4 | |
607 | If one of the operands of a comparison is a string and the other | |
608 | has a numeric value, the numeric operand is converted back to | |
609 | a string using the C \fIsprintf\fR format specifier | |
610 | \fB%d\fR for integers and \fB%g\fR for floating-point values. | |
611 | For example, the commands | |
612 | .CS | |
613 | \fBexpr {"0x03" > "2"}\fR | |
614 | \fBexpr {"0y" < "0x12"}\fR | |
615 | .CE | |
616 | both return 1. The first comparison is done using integer | |
617 | comparison, and the second is done using string comparison after | |
618 | the second operand is converted to the string \fB18\fR. | |
619 | Because of Tcl's tendency to treat values as numbers whenever | |
620 | possible, it isn't generally a good idea to use operators like \fB==\fR | |
621 | when you really want string comparison and the values of the | |
622 | operands could be arbitrary; it's better in these cases to use | |
623 | .VS 8.4 | |
624 | the \fBeq\fR or \fBne\fR operators, or | |
625 | .VE 8.4 | |
626 | the \fBstring\fR command instead. | |
627 | ||
628 | .SH "PERFORMANCE CONSIDERATIONS" | |
629 | .PP | |
630 | Enclose expressions in braces for the best speed and the smallest | |
631 | storage requirements. | |
632 | This allows the Tcl bytecode compiler to generate the best code. | |
633 | .PP | |
634 | As mentioned above, expressions are substituted twice: | |
635 | once by the Tcl parser and once by the \fBexpr\fR command. | |
636 | For example, the commands | |
637 | .CS | |
638 | \fBset a 3\fR | |
639 | \fBset b {$a + 2}\fR | |
640 | \fBexpr $b*4\fR | |
641 | .CE | |
642 | return 11, not a multiple of 4. | |
643 | This is because the Tcl parser will first substitute \fB$a + 2\fR for | |
644 | the variable \fBb\fR, | |
645 | then the \fBexpr\fR command will evaluate the expression \fB$a + 2*4\fR. | |
646 | .PP | |
647 | Most expressions do not require a second round of substitutions. | |
648 | Either they are enclosed in braces or, if not, | |
649 | their variable and command substitutions yield numbers or strings | |
650 | that don't themselves require substitutions. | |
651 | However, because a few unbraced expressions | |
652 | need two rounds of substitutions, | |
653 | the bytecode compiler must emit | |
654 | additional instructions to handle this situation. | |
655 | The most expensive code is required for | |
656 | unbraced expressions that contain command substitutions. | |
657 | These expressions must be implemented by generating new code | |
658 | each time the expression is executed. | |
659 | .SH EXAMPLES | |
660 | Define a procedure that computes an "interesting" mathematical | |
661 | function: | |
662 | .CS | |
663 | proc calc {x y} { | |
664 | \fBexpr\fR { ($x*$x - $y*$y) / exp($x*$x + $y*$y) } | |
665 | } | |
666 | .CE | |
667 | .PP | |
668 | Convert polar coordinates into cartesian coordinates: | |
669 | .CS | |
670 | # convert from ($radius,$angle) | |
671 | set x [\fBexpr\fR { $radius * cos($angle) }] | |
672 | set y [\fBexpr\fR { $radius * sin($angle) }] | |
673 | .CE | |
674 | .PP | |
675 | Convert cartesian coordinates into polar coordinates: | |
676 | .CS | |
677 | # convert from ($x,$y) | |
678 | set radius [\fBexpr\fR { hypot($y, $x) }] | |
679 | set angle [\fBexpr\fR { atan2($y, $x) }] | |
680 | .CE | |
681 | .PP | |
682 | Print a message describing the relationship of two string values to | |
683 | each other: | |
684 | .CS | |
685 | puts "a and b are [\fBexpr\fR {$a eq $b ? {equal} : {different}}]" | |
686 | .CE | |
687 | .PP | |
688 | Set a variable to whether an environment variable is both defined at | |
689 | all and also set to a true boolean value: | |
690 | .CS | |
691 | set isTrue [\fBexpr\fR { | |
692 | [info exists ::env(SOME_ENV_VAR)] && | |
693 | [string is true -strict $::env(SOME_ENV_VAR)] | |
694 | }] | |
695 | .CE | |
696 | .PP | |
697 | Generate a random integer in the range 0..99 inclusive: | |
698 | .CS | |
699 | set randNum [\fBexpr\fR { int(100 * rand()) }] | |
700 | .CE | |
701 | ||
702 | .SH "SEE ALSO" | |
703 | array(n), for(n), if(n), string(n), Tcl(n), while(n) | |
704 | ||
705 | .SH KEYWORDS | |
706 | arithmetic, boolean, compare, expression, fuzzy comparison |