[ Arithmetic | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# ?Result is +Expression

Evaluates the arithmetic expression Expression and unifies the resulting value with Result.

Result
  A variable or a number.
Expression
  An arithmetic expression.

## Description

is/2 is used to evaluate arithmetic expressions. An arithmetic expression is a Prolog term that is made up of variables, numbers, atoms and compound terms. If it contains variables, they must be bound to numbers at the time the evaluation takes place.

ECLiPSe distinguishes four types of numbers:

integers e.g. 12345
  Integers can be of arbitrary magnitude. Integers that fit into the word size of the machine are handled more efficiently.
rationals e.g. 3_4
  Rational numbers represent the corresponding mathematical notion (the ratio of two integers). The operations defined on rationals give precise (rational) results.
floats e.g. 3.1415
  Floats are an imprecise approximation of real numbers. They are represented as IEEE double precision floats. Floating point operations are typically subject to rounding errors. Undefined operations produce infinity results if possible, otherwise exceptions (not NaNs).
bounded reals (breal) e.g. 3.1415__3.1416
  Bounded reals are a safe representation of real numbers, characterised by a lower and upper bound in floating point format. Operations on breals are safe in the sense that the resulting bounds always enclose the precise result (interval arithmetic).

Numbers of different types do not unify. To help bug detection, the arithmetic predicates raise events when an attempt is made to unify numbers of different types.

The system performs automatic type conversions in the direction

> integer -> rational -> float -> breal.

These conversions are done (i) to make the types of two input arguments equal and (ii) to lift the type of an input argument to the one expected by the function. The result type is the lifted input type, unless otherwise specified.

A table of predefined arithmetic functions is given below. A predefined function is evaluated by first evaluating its arguments and then calling the corresponding evaluation predicate. The evaluation predicate belonging to a compound term func(a_1,..,a_n) is the predicate func/(n+1). It receives a_1,..,a_n as its first n arguments and returns a numeric result as its last argument. This result is then used in the arithmetic computation.

This evaluation mechanism outlined above is not restricted to the predefined arithmetic functors shown in the table. In fact it works for all atoms and compound terms. It is therefore possible to define a new arithmetic operation by just defining an evaluation predicate. Similarly, many ECLiPSe built-ins return numbers in the last argument and can thus be used as evaluation predicates (e.g.cputime/1, random/1, string_length/2, ...). Note that recursive evaluation of arguments is only done for the predefined arithmetic functions, for the others the arguments are simply passed to the evaluation predicate.

Most arithmetic errors will not be reported in is/2, but in the evaluation predicate where it occurred.

        Function       Description                Argument Types       Result Type
       ----------------------------------------------------------------------------
        + E            unary plus                 number               number
        - E            unary minus                number               number
        abs(E)         absolute value             number               number
        sgn(E)         sign value                 number               integer
        floor(E)       round down                 number               number
        ceiling(E)     round up                   number               number
        round(E)       round to nearest           number               number
        truncate(E)    round towards zero         number               number

        E1 + E2        addition                   number x number      number
        E1 - E2        subtraction                number x number      number
        E1 * E2        multiplication             number x number      number
        E1 / E2        division                   number x number      see below
        E1 // E2       integer division truncated integer x integer    integer
        E1 rem E2      integer remainder          integer x integer    integer
        E1 div E2      integer division floored   integer x integer    integer
        E1 mod E2      integer modulus            integer x integer    integer
        gcd(E1,E2)     greatest common divisor    integer x integer    integer
        lcm(E1,E2)     least common multiple      integer x integer    integer
        E1 ^ E2        power operation            number x number      number
        min(E1,E2)     minimum of 2 values        number x number      number
        max(E1,E2)     maximum of 2 values        number x number      number

        \ E            bitwise complement         integer              integer
        E1 /\ E2       bitwise conjunction        integer x integer    integer
        E1 \/ E2       bitwise disjunction        integer x integer    integer
        xor(E1,E2)     bitwise exclusive or       integer x integer    integer
        E1 >> E2       shift E1 right by E2 bits  integer x integer    integer
        E1 << E2       shift E1 left by E2 bits   integer x integer    integer
        setbit(E1,E2)  set bit E2 in E1           integer x integer    integer
        clrbit(E1,E2)  clear bit E2 in E1         integer x integer    integer
        getbit(E1,E2)  get of bit E2 in E1        integer x integer    integer

        sin(E)         trigonometric function     number               float or breal
        cos(E)         trigonometric function     number               float or breal
        tan(E)         trigonometric function     number               float or breal
        asin(E)        trigonometric function     number               float
        acos(E)        trigonometric function     number               float
        atan(E)        trigonometric function     number               float or breal
        atan(E1,E2)    trigonometric function     number x number      float or breal
        exp(E)         exponential function ex    number               float or breal
        ln(E)          natural logarithm          number               float or breal
        sqrt(E)        square root                number               float or breal
        pi             the constant pi            ---                  float
        e              the constant e             ---                  float

        fix(E)         truncate to integer        number               integer
        integer(E)     convert to integer         number               integer
        float(E)       convert to float           number               float
        rational(E)    convert to rational        number               rational
        rationalize(E) convert to rational        number               rational
        numerator(E)   numerator of rational      integer or rational  integer
        denominator(E) denominator of rational    integer or rational  integer
        breal(E)       convert to bounded real    number               breal
        breal_from_bounds(Lo, Hi)
                       make bounded real from bounds  number x number  breal
        breal_min(E)   lower bound of bounded real    number           float
        breal_max(E)   upper bound of bounded real    number           float

        sum(Es)        sum of list elements       list                 number
        min(Es)        minimum of list elements   list                 number
        max(Es)        maximum of list elements   list                 number
        eval(E)        eval runtime expression    term                 number

The division operator / yields either a rational or a float result, depending on the value of the global flag prefer_rationals. The same is true for the result of ^ if an integer is raised to a negative integral power.

The relation between integer divisions // and div, and remainder and modulus operations rem and mod is as follows:

        X =:= (X rem Y) + (X  // Y) * Y.
        X =:= (X mod Y) + (X div Y) * Y.

### Modes and Determinism

- is(-, +) is det
- is(+, +) is det

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

### Fail Conditions

Fails if a user-defined evaluation predicate fails

### Exceptions

(4) instantiation fault
  Expression is uninstantiated
(5) type error
  Result is neither a number nor a variable.
(5) type error
  Evaluation of Expression gives a different type than Result.
(21) undefined arithmetic expression
  An evaluation predicate in the expression is not defined.
(24) number expected
  Expression is not a valid arithmetic expression.

## Examples

       Success:
         103 is 3 + 4 * 5 ^ 2.
         X is asin(sin(pi/4)).            (gives X = 0.785398).
         Y is 2 * 3, X is 4 + Y.          (gives X = 10, Y = 6).
         X is string_length("four") + 1.  (gives X = 5).

         [eclipse]: [user].
          myconst(4.56).
          user compiled 40 bytes in 0.02 seconds
         yes.
         [eclipse]: 5.56 is myconst + 1.
         yes.
    Fail:
         3.14 is pi.                    % different values
    Error:
         X is _.                        (Error 4)
         atom is 4.                     (Error 5)
         1 is 1.0.                      (Error 5)
         X is "s".                      (Error 24)

         [eclipse]: X is undef(1).
         calling an undefined procedure undef(1, _g63) in ...

         [eclipse]: X is 3 + Y.
         instantiation fault in +(3, _g45, _g53)

## See Also

get_flag / 2, set_flag / 3, + / 2, - / 2, abs / 2, sgn / 2, ceiling / 2, floor / 2, round / 2, truncate / 2, + / 3, - / 3, * / 3, / / 3, // / 3, rem / 3, div / 3, mod / 3, ^ / 3, min / 3, max / 3, gcd / 3, lcm / 3, \ / 2, /\ / 3, \/ / 3, xor / 3, >> / 3, << / 3, clrbit / 3, getbit / 3, setbit / 3, sin / 2, cos / 2, tan / 2, asin / 2, acos / 2, atan / 2, atan / 3, exp / 2, ln / 2, sqrt / 2, fix / 2, integer / 2, float / 2, rational / 2, rationalize / 2, numerator / 2, denominator / 2, breal / 2, breal_from_bounds / 3, breal_min / 2, breal_max / 2, sum / 2, min / 2, max / 2, eval / 2, integer / 1, float / 1, rational / 1, breal / 1, number / 1