NAME
       expr - Evaluate an expression

SYNOPSIS
       expr arg ?arg arg ...?


DESCRIPTION
       Concatenates arg's (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  same meaning and precedence as the corre-
       sponding C operators.   Expressions  almost  always  yield
       numeric  results  (integer or floating-point values).  For
       example, the expression
              expr 8.2 + 6
       evaluates to 14.2.  Tcl expressions differ from C  expres-
       sions  in  the way that operands are specified.  Also, Tcl
       expressions support non-numeric operands and  string  com-
       parisons.

OPERANDS
       A  Tcl  expression  consists of a combination of operands,
       operators, and  parentheses.   White  space  may  be  used
       between  the operands and operators and parentheses; it is
       ignored by the expression's instructions.  Where possible,
       operands  are interpreted as integer values.  Integer val-
       ues may be specified in  decimal  (the  normal  case),  in
       octal  (if the first character of the operand is 0), or in
       hexadecimal (if the first two characters  of  the  operand
       are  0x).   If an operand does not have one of the integer
       formats given above, then it is  treated  as  a  floating-
       point  number if that is possible.  Floating-point numbers
       may be specified in any of the ways accepted by  an  ANSI-
       compliant  C compiler (except that the f, F, l, and L suf-
       fixes 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 interpre-
       tation  is  possible,  then an operand is left as a string
       (and only a limited set of operators  may  be  applied  to
       it).

       On 32-bit systems, integer values MAX_INT (0x7FFFFFFF) and
       MIN_INT (-0x80000000) will be represented as  32-bit  val-
       ues,  and integer values outside that range will be repre-
       sented as 64-bit values (if that is possible at all.)

       Operands may be specified in any of the following ways:

       [1]    As an numeric value, either  integer  or  floating-
              point.

       [2]    As  a Tcl variable, using standard $ notation.  The
              variable's value will be used as the operand.

       [3]    As a string enclosed in double-quotes.  The expres-
              sion  parser  will perform backslash, variable, and
              command substitutions on  the  information  between
              the  quotes,  and  use  the  resulting value as the
              operand

       [4]    As a string enclosed  in  braces.   The  characters
              between  the  open  brace  and matching close brace
              will be used as the operand without  any  substitu-
              tions.

       [5]    As a Tcl command enclosed in brackets.  The command
              will be executed and its result will be used as the
              operand.

       [6]    As a mathematical function whose arguments have any
              of the above forms for operands, such  as  sin($x).
              See below for a list of defined functions.

       Where   substitutions  occur  above  (e.g.  inside  quoted
       strings), they are performed by the expression's  instruc-
       tions.   However,  an additional layer of substitution may
       already have been performed by the command  parser  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.

       For some examples of simple expressions, suppose the vari-
       able a has the value 3 and the variable b has the value 6.
       Then the command on the left side of  each  of  the  lines
       below  will  produce  the  value  on the right side of the
       line:
              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
       The valid operators are listed below, grouped in  decreas-
       ing order of precedence:

       -  +  ~  !          Unary minus, unary plus, bit-wise NOT,
                           logical NOT.  None of  these  operands
                           may be applied to string operands, and
                           bit-wise NOT may be  applied  only  to
                           integers.

       *  /  %             Multiply,  divide, remainder.  None of
                           these  operands  may  be  applied   to
                           string  operands, and remainder may be
                           applied only to integers.  The remain-
                           der  will always have the same sign as
                           the  divisor  and  an  absolute  value
                           smaller than the divisor.

       +  -                Add   and  subtract.   Valid  for  any
                           numeric operands.

       <<  >>              Left and right shift.  Valid for inte-
                           ger  operands  only.   A  right  shift
                           always propagates the sign bit.

       <  >  <=  >=        Boolean less, greater,  less  than  or
                           equal,  and  greater  than  or  equal.
                           Each operator produces 1 if the condi-
                           tion  is  true,  0  otherwise.   These
                           operators may be applied to strings as
                           well  as  numeric  operands,  in which
                           case string comparison is used.

       ==  !=              Boolean equal  and  not  equal.   Each
                           operator  produces  a zero/one result.
                           Valid for all operand types.

       eq  ne              Boolean string equal  and  string  not
                           equal.    Each   operator  produces  a
                           zero/one result.   The  operand  types
                           are interpreted only as strings.

       &                   Bit-wise   AND.    Valid  for  integer
                           operands only.

       ^                   Bit-wise  exclusive  OR.   Valid   for
                           integer operands only.

       |                   Bit-wise   OR.    Valid   for  integer
                           operands only.

       &&                  Logical AND.  Produces a 1  result  if
                           both  operands  are non-zero, 0 other-
                           wise.  Valid for boolean  and  numeric
                           (integers  or floating-point) operands
                           only.

       ||                  Logical OR.  Produces a  0  result  if
                           both  operands  are zero, 1 otherwise.
                           Valid for boolean and  numeric  (inte-
                           gers or floating-point) operands only.

       x?y:z               If-then-else, as in C.  If x evaluates
                           to  non-zero,  then  the result is the
                           value of y.  Otherwise the  result  is
                           the  value  of  z.  The x operand must
                           have a numeric value.

       See the C manual for more details on the results  produced
       by each operator.  All of the binary operators group left-
       to-right within the same precedence level.   For  example,
       the command
              expr 4*2 < 7
       returns 0.

       The  &&,  ||,  and  ?: operators have ``lazy evaluation'',
       just as in C, which means that operands are not  evaluated
       if  they  are  not  needed  to determine the outcome.  For
       example, in the command
              expr {$v ? [a] : [b]}
       only one of [a] or [b] will actually be evaluated, depend-
       ing  on the value of $v.  Note, however, that this is only
       true if the entire expression is enclosed in braces;  oth-
       erwise  the  Tcl  parser  will  evaluate  both [a] and [b]
       before invoking the expr command.

MATH FUNCTIONS
       Tcl  supports  the  following  mathematical  functions  in
       expressions:

              abs         cosh        log        sqrt
              acos        double      log10      srand
              asin        exp         pow        tan
              atan        floor       rand       tanh
              atan2       fmod        round
              ceil        hypot       sin
              cos         int         sinh



       abs(arg)
              Returns  the  absolute  value  of  arg.  Arg may be
              either integer or floating-point, and the result is
              returned in the same form.

       acos(arg)
              Returns  the arc cosine of arg, in the range [0,pi]
              radians. Arg should be in the range [-1,1].

       asin(arg)
              Returns  the  arc  sine  of  arg,  in   the   range
              [-pi/2,pi/2]  radians.   Arg should be in the range
              [-1,1].

       atan(arg)
              Returns the  arc  tangent  of  arg,  in  the  range
              [-pi/2,pi/2] radians.

       atan2(y, x)
              Returns  the  arc  tangent  of  y/x,  in  the range
              [-pi,pi] radians.  x and y cannot both be 0.  If  x
              is greater than 0, this is equivalent to atan(y/x).

       ceil(arg)
              Returns the smallest integral floating point  value
              (i.e.  with  a  zero fractional part) not less than
              arg.

       cos(arg)
              Returns the cosine of arg, measured in radians.

       cosh(arg)
              Returns the  hyperbolic  cosine  of  arg.   If  the
              result   would  cause  an  overflow,  an  error  is
              returned.

       double(arg)
              If arg is a floating value, returns arg,  otherwise
              converts  arg to floating and returns the converted
              value.

       exp(arg)
              Returns the exponential of arg, defined as  e**arg.
              If  the result would cause an overflow, an error is
              returned.

       floor(arg)
              Returns the largest integral floating  point  value
              (i.e. with a zero fractional part) not greater than
              arg.

       fmod(x, y)
              Returns the floating-point remainder of  the  divi-
              sion of x by y.  If y is 0, an error is returned.

       hypot(x, y)
              Computes  the  length of the hypotenuse of a right-
              angled triangle sqrt(x*x+y*y).

       int(arg)
              If arg is an integer value, returns arg,  otherwise
              converts  arg  to an integer (of the same size as a
              machine word, i.e. 32-bits on 32-bit  systems,  and
              64-bits   on  64-bit  systems)  by  truncation  and
              returns the converted value.

       log(arg)
              Returns the natural logarithm of arg.  Arg must  be
              a positive value.

       log10(arg)
              Returns  the base 10 logarithm of arg.  Arg must be
              a positive value.

       pow(x, y)
              Computes the value of x raised to the power y.   If
              x is negative, y must be an integer value.

       rand() Returns  a  floating point number from zero to just
              less than one or, in mathematical terms, the  range
              [0,1).   The  seed comes from the internal clock of
              the machine or may be set  manual  with  the  srand
              function.

       round(arg)
              If  arg is an integer value, returns arg, otherwise
              converts arg to integer by rounding and returns the
              converted value.

       sin(arg)
              Returns the sine of arg, measured in radians.

       sinh(arg)
              Returns  the hyperbolic sine of arg.  If the result
              would cause an overflow, an error is returned.

       sqrt(arg)
              Returns the square root of arg.  Arg must  be  non-
              negative.

       srand(arg)
              The arg, which must be an integer, is used to reset
              the seed for the random number generator.   Returns
              the  first  random  number  from  that  seed.  Each
              interpreter has its own seed.

       tan(arg)
              Returns the tangent of arg, measured in radians.

       tanh(arg)
              Returns the hyperbolic tangent of arg.

       wide(arg)
              Converts arg to a value at least 64-bits  wide  (by
              sign-extension if arg is a 32-bit number.)

       In  addition  to  these predefined functions, applications
       may  define  additional  functions  using  Tcl_CreateMath-
       Func().

TYPES, OVERFLOW, AND PRECISION
       All internal computations involving integers are done with
       the C type long, and all internal  computations  involving
       floating-point are done with the C type double.  When con-
       verting a string to floating-point, exponent  overflow  is
       detected  and  results  in a Tcl error.  For conversion to
       integer from string, detection of overflow depends on  the
       behavior  of  some  routines in the local C library, so it
       should be regarded as unreliable.  In  any  case,  integer
       overflow and underflow are generally not detected reliably
       for intermediate  results.   Floating-point  overflow  and
       underflow  are  detected  to  the  degree supported by the
       hardware, which is generally pretty 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  introduced, after
       which floating-point is used.  For example,
              expr 5 / 4
       returns 1, while
              expr 5 / 4.0
              expr 5 / ( [string length "abcd"] + 0.0 )
       both  return  1.25.   Floating-point  values  are   always
       returned  with a ``.''  or an e so that they will not look
       like integer values.  For example,
              expr 20.0/5.0
       returns 4.0, not 4.


STRING OPERATIONS
       String values may be used as operands  of  the  comparison
       operators,  although  the expression evaluator tries to do
       comparisons as integer  or  floating-point  when  it  can,
       except  in the case of the eq and ne operators.  If one of
       the operands of a comparison is a string and the other has
       a  numeric value, the numeric operand is converted back to
       a string using the C sprintf format specifier %d for inte-
       gers  and  %g for floating-point values.  For example, the
       commands
              expr {"0x03" > "2"}
              expr {"0y" < "0x12"}
       both return 1.  The first comparison is done using integer
       comparison, and the second is done using string comparison
       after the second operand is converted to  the  string  18.
       Because of Tcl's tendency to treat values as numbers when-
       ever possible, it isn't generally a good idea to use oper-
       ators  like  == when you really want string comparison and
       the values of the operands could be arbitrary;  it's  bet-
       ter  in  these cases to use the eq or ne operators, or the
       string command instead.


PERFORMANCE CONSIDERATIONS
       Enclose expressions in braces for the best speed  and  the
       smallest  storage requirements.  This allows the Tcl byte-
       code compiler to generate the best code.

       As mentioned above,  expressions  are  substituted  twice:
       once  by the Tcl parser and once by the expr command.  For
       example, the commands
              set a 3
              set b {$a + 2}
              expr $b*4
       return 11, not a multiple of 4.  This is because  the  Tcl
       parser  will  first  substitute $a + 2 for the variable b,
       then the expr command will evaluate the  expression  $a  +
       2*4.

       Most  expressions do not require a second round of substi-
       tutions.  Either they are enclosed in braces or,  if  not,
       their  variable and command substitutions yield numbers or
       strings that don't themselves require substitutions.  How-
       ever,  because  a few unbraced expressions need two rounds
       of substitutions, the bytecode compiler  must  emit  addi-
       tional  instructions  to  handle this situation.  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  expres-
       sion is executed.


SEE ALSO
       array(n), string(n), Tcl(n)


KEYWORDS
