Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
expr(n)			     Tcl Built-In Commands		       expr(n)

______________________________________________________________________________

NAME
       expr - Evaluate an expression

SYNOPSIS
       expr arg	?arg arg ...?
______________________________________________________________________________

DESCRIPTION
       Concatenates args, separated by a space,	into an	expression, and	evalu-
       ates that expression, returning its value.  The operators permitted  in
       an  expression include a	subset of the operators	permitted in C expres-
       sions.  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, either	an integer  or
       a floating-point	value, but may also be a non-numeric value.  For exam-
       ple, the	expression

	      expr 8.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 %g format specifier
       of Tcl's	format command.

   OPERANDS
       An 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 integer operand may	be specified in	 deci-
       mal (the	normal case, the optional first	two characters are 0d),	binary
       (the first two characters are 0b), octal	(the first two characters  are
       0o),  or	 hexadecimal (the first	two characters are 0x) form.  For com-
       patibility with older Tcl releases, an operand that begins  with	 0  is
       interpreted  as an octal	integer	even if	the second character is	not o.
       A floating-point	number may be specified	in any of several common deci-
       mal formats, and	may use	the decimal point ., e or E for	scientific no-
       tation, and the sign characters + and -.	 The following are  all	 valid
       floating-point  numbers:	  2.1, 3., 6e4,	7.91e+16.  The strings Inf and
       NaN, 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.

       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 by string is bool-
	      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 in Tcl.

       [5]    As  a  string  enclosed  in braces.  The operand is treated as a
	      braced value as described	in Tcl.

       [6]    As a Tcl command enclosed	in brackets.  Command substitution  is
	      performed	as described in	Tcl.

       [7]    As a mathematical	function such as sin($x), whose	arguments have
	      any of the above forms for operands.  See	MATH  FUNCTIONS	 below
	      for a discussion of how mathematical functions are handled.

       Because	expr parses and	performs substitutions on values that have al-
       ready been parsed and substituted by Tcl, it is usually best to enclose
       expressions in braces to	avoid the first	round of substitutions by Tcl.

       Below are some examples of simple expressions where the value of	a is 3
       and the value of	b is 6.	 The command on	the left  side	of  each  line
       produces	the value on the right side.

	      expr 3.1 + $a			 6.1
	      expr 2 + "$a.$b"			 5.6
	      expr 4*[llength "6 2"]		 8
	      expr {{word one} < "word $a"}	 0

   OPERATORS
       For 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 use eq, ne, or	the string command 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 also
       string is boolean.  The valid operators,	most of	which are also	avail-
       able  as	 commands  in  the  tcl::mathop	namespace (see mathop(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.

       lt  gt  le  ge	   Boolean  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 see string compare), unlike with |
			   the numeric-preferring comparisons abov, which have |
			   the same precedence.

       ==  !=		   Boolean equal and not equal.

       eq  ne		   Boolean string equal	and string not equal.

       in  ni		   List	containment and	negated	list containment.  The
			   first argument is interpreted as a string, the sec-
			   ond as a list.  in  tests  for  membership  in  the
			   list, and ni	is 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 : z	   If-then-else, as in C.  If x	is false , the	result
			   is  the  value  of  y.  Otherwise the result	is the
			   value of z.	This  operator	evaluates  lazily;  it
			   evaluates only one of y or z.

       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 of pow.  Exponentiation groups right-to-left within a precedence
       level. Other binary operators group left-to-right.   For	 example,  the
       value of

	      expr {4*2	< 7}

       is 0, while the value of

	      expr {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, in

	      expr {$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	to expr	in braces.  Without braces, as
       in expr $v ? [a]	: [b] both [a] and [b] are evaluated  before  expr  is
       even called.

       For more	details	on the results produced	by each	operator, see the doc-
       umentation for C.

   MATH	FUNCTIONS
       A mathematical function such as sin($x) is replaced with	a call	to  an
       ordinary	Tcl command in the tcl::mathfunc namespace.  The evaluation of
       an expression such as

	      expr {sin($x+$y)}

       is the same in every way	as the evaluation of

	      expr {[tcl::mathfunc::sin	[expr {$x+$y}]]}

       which in	turn is	the same as the	evaluation of

	      tcl::mathfunc::sin [expr {$x+$y}]

       tcl::mathfunc::sin is resolved as described in NAMESPACE	RESOLUTION  in
       the  namespace(n) documentation.	  Given	the default value of namespace
       path, [namespace	current]::tcl::mathfunc::sin  or  ::tcl::mathfunc::sin
       are 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 the mathfunc(n) documentation  for  the  math  functions  that  are
       available by default.

   TYPES, OVERFLOW, AND	PRECISION
       When  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 types long int  or	Tcl_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 call int() or wide(), which do truncate.

       Internal	 floating-point	 computations are performed using the double C
       type.  When converting a	string to floating-point value,	exponent over-
       flow  is	detected and results in	the double value of Inf	or -Inf	as 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, while

	      expr {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}

       returns 4.0, not	4.

PERFORMANCE CONSIDERATIONS
       Where  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 before expr	is called.

       In the following	example, the value of the expression is	11 because the
       Tcl parser first	substitutes $b and expr	then substitutes $a as part of
       evaluating the expression "$a +	2*4".	Enclosing  the	expression  in
       braces  would result in a syntax	error as $b does 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 the mathfunc(n)  or  mathop(n)	 documentation
       instead of expr.

       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, allowing expr to 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 recursive expr,  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 to expr should 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 the
       tcl::mathop namespace) than it is to do complex expression generation.

EXAMPLES
       A 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 {
		  [info	exists ::env(SOME_ENV_VAR)] &&
		  [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 ALSO
       array(n), for(n), if(n),	mathfunc(n), mathop(n),	namespace(n), proc(n),
       string(n), Tcl(n), while(n)

KEYWORDS
       arithmetic, boolean, compare, expression, fuzzy comparison

COPYRIGHT
       Copyright (C) 1993 The Regents of the University	of California.
       Copyright (C) 1994-2000 Sun Microsystems	Incorporated.
       Copyright (C) 2005 by 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>

home | help