# FreeBSD Manual Pages

expr(n) Tcl Built-In Commands expr(n) ______________________________________________________________________________NAMEexpr - Evaluate an expressionSYNOPSISexprarg?argarg...? ______________________________________________________________________________DESCRIPTIONTheexprcommand concatenatesargs, separated by a space, into an ex- pression, and evaluates that expression, returning its value. The op- erators permitted in an expression include a subset of the operators permitted in C expressions. For those operators common to both Tcl and C, Tcl applies the same meaning and precedence as the corresponding C operators. The value of an expression is often a numeric result, ei- ther an integer or a floating-point value, but may also be a non-nu- meric value. For example, the expressionexpr8.2 + 6 evaluates to 14.2. Expressions differ from C expressions in the way that operands are specified. Expressions also support non-numeric op- erands, string comparisons, and some additional operators not found in C. When an expression evaluates to an integer, the value is the decimal form of the integer, and when an expression evaluates to a floating- point number, the value is the form produced by the%gformat specifier of Tcl'sformatcommand. You can use#at any point in the expression (except inside double | quotes or braces) to start a comment. Comments last to the end of the | line or the end of the expression, whichever comes first.OPERANDSAn expression consists of a combination of operands, operators, paren- theses and commas, possibly with whitespace between any of these ele- ments, which is ignored. An operand may be specified in any of the following ways: [1] As a numeric value, either integer or floating-point. [2] As a boolean value, using any form understood bystringisbool-ean. [3] As a variable, using standard$notation. The value of the variable is then the value of the operand. [4] As a string enclosed in double-quotes. Backslash, variable, and command substitution are performed as described inTcl. [5] As a string enclosed in braces. The operand is treated as a braced value as described inTcl. [6] As a Tcl command enclosed in brackets. Command substitution is performed as described inTcl. [7] As a mathematical function such assin($x), whose arguments have any of the above forms for operands. SeeMATHFUNCTIONSbelow for a discussion of how mathematical functions are handled. Becauseexprparses and performs substitutions on values that have al- ready been parsed and substituted byTcl, it is usually best to enclose expressions in braces to avoid the first round of substitutions byTcl. Below are some examples of simple expressions where the value ofais 3 and the value ofbis 6. The command on the left side of each line produces the value on the right side.expr{3.1 + $a}6.1expr{2 + "$a.$b"}5.6expr{4*[llength "6 2"]}8expr{{word one} < "word $a"}0IntegervalueAn integer operand may be specified in decimal (the normal case, the optional first two characters are0d), binary (the first two characters are0b), octal (the first two characters are0o), or hexadecimal (the first two characters are0x) form. For compatibility with older Tcl releases, an operand that begins with0is interpreted as an octal in- teger even if the second character is noto.Floating-pointvalueA floating-point number may be specified in any of several common deci- mal formats, and may use the decimal point.,eorEfor scientific no- tation, and the sign characters+and-. The following are all valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. The stringsInfandNaN, in any combination of case, are also recognized as floating point values. An operand that doesn't have a numeric interpretation must be quoted with either braces or with double quotes.BooleanvalueA boolean value may be represented by any of the values0,false,no, oroffand any of the values1,true,yes, oron.DigitSeparatorDigits in any numeric value may be separated with one or more under- score characters, "_", to improve readability. These separators may only appear between digits. The separator may not appear at the start of a numeric value, between the leading 0 and radix specifier, or at the end of a numeric value. Here are some examples:expr100_000_000100000000expr0xffff_ffff4294967295format0x%x 0b1111_1110_1101_10110xfedbOPERATORSFor operators having both a numeric mode and a string mode, the numeric mode is chosen when all operands have a numeric interpretation. The integer interpretation of an operand is preferred over the floating- point interpretation. To ensure string operations on arbitrary values it is generally a good idea to useeq,ne, or thestringcommand in- stead of more versatile operators such as==. Unless otherwise specified, operators accept non-numeric operands. The value of a boolean operation is 1 if true, 0 otherwise. See alsostringisboolean. The valid operators, most of which are also avail- able as commands in thetcl::mathopnamespace (seemathop(n)), are listed below, grouped in decreasing order of precedence:-+~!Unary minus, unary plus, bit-wise NOT, logical NOT. These operators may only be applied to numeric op- erands, and bit-wise NOT may only be applied to in- tegers.**Exponentiation. Valid for numeric operands. The maximum exponent value that Tcl can handle if the first number is an integer > 1 is 268435455.*/%Multiply and divide, which are valid for numeric operands, and remainder, which is valid for inte- gers. The remainder, an absolute value smaller than the absolute value of the divisor, has the same sign as the divisor. When applied to integers, division and remainder can be considered to partition the number line into a sequence of adjacent non-overlapping pieces, where each piece is the size of the divisor; the quotient identifies which piece the dividend lies within, and the remainder identifies where within that piece the dividend lies. A consequence of this is that the result of "-57/10" is always -6, and the result of "-57%10" is always 3.+-Add and subtract. Valid for numeric operands. << >> Left and right shift. Valid for integers. A right shift always propagates the sign bit. < > <=>=Boolean numeric-preferring comparisons: less than, greater than, less than or equal, and greater than or equal. If either argument is not numeric, the comparison is done using UNICODE string comparison, as with the string comparison operators below, which have the same precedence.ltgtlegeBoolean string comparisons: less than, greater | than, less than or equal, and greater than or | equal. These always compare values using their UNI- | CODE strings (also seestringcompare), unlike with | the numeric-preferring comparisons abov, which have | the same precedence.==!=Boolean equal and not equal.eqneBoolean string equal and string not equal.inniList containment and negated list containment. The first argument is interpreted as a string, the sec- ond as a list.intests for membership in the list, andniis the inverse. & Bit-wise AND. Valid for integer operands.^Bit-wise exclusive OR. Valid for integer operands.|Bit-wise OR. Valid for integer operands. && Logical AND. If both operands are true, the result is 1, or 0 otherwise. This operator evaluates lazily; it only evaluates its second operand if it must in order to determine its result. This opera- tor evaluates lazily; it only evaluates its second operand if it must in order to determine its re- sult.||Logical OR. If both operands are false, the result is 0, or 1 otherwise. This operator evaluates lazily; it only evaluates its second operand if it must in order to determine its result.x?y:zIf-then-else, as in C. Ifxis false , the result is the value ofy. Otherwise the result is the value ofz. This operator evaluates lazily; it evaluates only one ofyorz. The exponentiation operator promotes types in the same way that the multiply and divide operators do, and the result is is the same as the result ofpow. Exponentiation groups right-to-left within a precedence level. Other binary operators group left-to-right. For example, the value ofexpr{4*2 < 7} is 0, while the value ofexpr{2**3**2} is 512. As in C, &&,||, and?:feature "lazy evaluation", which means that op- erands are not evaluated if they are not needed to determine the out- come. For example, inexpr{$v?[a]:[b]} only one of[a]or[b]is evaluated, depending on the value of$v. This is not true of the normal Tcl parser, so it is normally recom- mended to enclose the arguments toexprin braces. Without braces, as inexpr$v ? [a] : [b] both[a]and[b]are evaluated beforeexpris even called. For more details on the results produced by each operator, see the doc- umentation for C.MATHFUNCTIONSA mathematical function such assin($x)is replaced with a call to an ordinary Tcl command in thetcl::mathfuncnamespace. The evaluation of an expression such asexpr{sin($x+$y)} is the same in every way as the evaluation ofexpr{[tcl::mathfunc::sin [expr{$x+$y}]]} which in turn is the same as the evaluation of tcl::mathfunc::sin [expr{$x+$y}]tcl::mathfunc::sinis resolved as described inNAMESPACERESOLUTIONin thenamespace(n) documentation. Given the default value ofnamespacepath,[namespacecurrent]::tcl::mathfunc::sinor::tcl::mathfunc::sinare the typical resolutions. As in C, a mathematical function may accept multiple arguments sepa- rated by commas. Thus,expr{hypot($x,$y)} becomes tcl::mathfunc::hypot $x $y See themathfunc(n) documentation for the math functions that are available by default.TYPES,OVERFLOW,ANDPRECISIONWhen needed to guarantee exact performance, internal computations in- volving integers use the LibTomMath multiple precision integer library. In Tcl releases prior to 8.5, integer calculations were performed using one of the C typeslongintorTcl_WideInt, causing implicit range truncation in those calculations where values overflowed the range of those types. Any code that relied on these implicit truncations should instead callint()orwide(), which do truncate. Internal floating-point computations are performed using thedoubleC type. When converting a string to floating-point value, exponent over- flow is detected and results in thedoublevalue ofInfor-Infas ap- propriate. Floating-point overflow and underflow are detected to the degree supported by the hardware, which is generally fairly reliable. Conversion among internal representations for integer, floating-point, and string operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is in- troduced, after which floating-point values are used. For example,expr{5 / 4} returns 1, whileexpr{5 / 4.0}expr{5 / ( [string length "abcd"] + 0.0 )} both return 1.25. A floating-point result can be distinguished from an integer result by the presence of either "." or "e"expr{20.0/5.0} returns4.0, not4.PERFORMANCE CONSIDERATIONSWhere an expression contains syntax that Tcl would otherwise perform substitutions on, enclosing an expression in braces or otherwise quot- ing it so that it's a static value allows the Tcl compiler to generate bytecode for the expression, resulting in better speed and smaller storage requirements. This also avoids issues that can arise if Tcl is allowed to perform substitution on the value beforeexpris called. In the following example, the value of the expression is 11 because the Tcl parser first substitutes$bandexprthen substitutes$aas part of evaluating the expression "$a + 2*4". Enclosing the expression in braces would result in a syntax error as$bdoes not evaluate to a nu- meric value. set a 3 set b {$a + 2}expr$b*4 When an expression is generated at runtime, like the one above is, the bytecode compiler must ensure that new code is generated each time the expression is evaluated. This is the most costly kind of expression from a performance perspective. In such cases, consider directly using the commands described in themathfunc(n) ormathop(n) documentation instead ofexpr. Most expressions are not formed at runtime, but are literal strings or contain substitutions that don't introduce other substitutions. To al- low the bytecode compiler to work with an expression as a string lit- eral at compilation time, ensure that it contains no substitutions or that it is enclosed in braces or otherwise quoted to prevent Tcl from performing substitutions, allowingexprto perform them instead. If it is necessary to include a non-constant expression string within the wider context of an otherwise-constant expression, the most effi- cient technique is to put the varying part inside a recursiveexpr, as this at least allows for the compilation of the outer part, though it does mean that the varying part must itself be evaluated as a separate expression. Thus, in this example the result is 20 and the outer ex- pression benefits from fully cached bytecode compilation. set a 3 set b {$a + 2}expr{[expr$b] * 4} In general, you should enclose your expression in braces wherever pos- sible, and where not possible, the argument toexprshould be an ex- pression defined elsewhere as simply as possible. It is usually more efficient and safer to use other techniques (e.g., the commands in thetcl::mathopnamespace) than it is to do complex expression generation.EXAMPLESA numeric comparison whose result is 1:expr{"0x03" > "2"} A string comparison whose result is 1:expr{"0y" > "0x12"} A forced string comparison whose result is 0: |expr{"0x03" gt "2"} | Define a procedure that computes an "interesting" mathematical func- tion: proc tcl::mathfunc::calc {x y} {expr{ ($x**2 - $y**2) / exp($x**2 + $y**2) } } Convert polar coordinates into cartesian coordinates: # convert from ($radius,$angle) set x [expr{ $radius * cos($angle) }] set y [expr{ $radius * sin($angle) }] Convert cartesian coordinates into polar coordinates: # convert from ($x,$y) set radius [expr{ hypot($y, $x) }] set angle [expr{ atan2($y, $x) }] Print a message describing the relationship of two string values to each other: puts "a and b are [expr{$a eq $b ? {equal} : {different}}]" Set a variable indicating whether an environment variable is defined and has value of true: set isTrue [expr{ # Does the environment variable exist, and... [info exists ::env(SOME_ENV_VAR)] && # ...does it contain a proper true value? [string is true -strict $::env(SOME_ENV_VAR)] }] Generate a random integer in the range 0..99 inclusive: set randNum [expr{ int(100 * rand()) }]SEE ALSOarray(n), for(n), if(n), mathfunc(n), mathop(n), namespace(n), proc(n), string(n), Tcl(n), while(n)KEYWORDSarithmetic, boolean, compare, expression, fuzzy comparison, integer valueCOPYRIGHTCopyright (C) 1993 The Regents of the University of California. Copyright (C) 1994-2000 Sun Microsystems Incorporated. Copyright (C) 2005 Kevin B. Kenny <kennykb@acm.org>. All rights reserved. Tcl 8.5 expr(n)

NAME | SYNOPSIS | DESCRIPTION | PERFORMANCE CONSIDERATIONS | EXAMPLES | SEE ALSO | KEYWORDS | COPYRIGHT

Want to link to this manual page? Use this URL:

<https://www.freebsd.org/cgi/man.cgi?query=expr.tcl87&manpath=FreeBSD+13.0-RELEASE+and+Ports>