% BEGIN LICENSE BLOCK
% Version: CMPL 1.1
%
% The contents of this file are subject to the Cisco-style Mozilla Public
% License Version 1.1 (the "License"); you may not use this file except
% in compliance with the License.  You may obtain a copy of the License
% at www.eclipse-clp.org/license.
% 
% Software distributed under the License is distributed on an "AS IS"
% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
% the License for the specific language governing rights and limitations
% under the License. 
% 
% The Original Code is  The ECLiPSe Constraint Logic Programming System. 
% The Initial Developer of the Original Code is  Cisco Systems, Inc. 
% Portions created by the Initial Developer are
% Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
% 
% Contributor(s): 
% 
% END LICENSE BLOCK

:- comment(alias, "Arithmetic").
:- comment(summary, "Built-ins for arithmetic computations").
:- comment(desc, html("See also the User Manual chapter on Arithmetic")).

:- tool((<) / 2).
:- tool((=:=) / 2).
:- tool((=<) / 2).
:- tool((=\=) / 2).
:- tool((>) / 2).
:- tool((>=) / 2).
:- tool(eval / 2).
:- tool((is) / 2).
:- tool(max / 2).
:- tool(min / 2).
:- tool(sum / 2).

:- comment(succ / 2, [
	summary:"Successor relation over natural numbers.",
	amode:(succ(+,-) is semidet),
	amode:(succ(-,+) is semidet),
	desc:html("\
   Successor relation over natural numbers.  Succeeds if X is an
   integer greater or equal to zero, and Y is one greater than X.
   If one of the arguments is uninstantiated, it gets computed from
   the other by adding or subtracting 1, respectively.
<P>
   If the system is in coroutining mode and both arguments are
   uninstantiated, succ/2 delays until at least one argument is known.
<P>
"),
	args:["X" : "an integer or a variable", "Y" : "an integer or a variable"],
	fail_if:"Fails if X or Y are negative integers, or if Y is 0",
	exceptions:[5 : "an argument is a non-integer number",
		4 : "both arguments are uninstantiated (non-coroutining mode only)",
		24 : "X or Y is not a number"],
	eg:"
   Success:
   	succ(0, 1).
   	succ(7, 8).
   	succ(10000000000000000000, 10000000000000000001).
   	succ(0, Y).		(gives Y=1)
   	succ(X, 3).		(gives X=2)

   Fail:
   	succ(X, 0).
   	succ(X, -5).
   	succ(-1, Y).

   Error:
   	succ(X, Y).		(error 4)
   	succ(0.0, Y).		(error 5)
   	succ(a, Y).		(error 24)
",
	see_also:[plus / 3, (+)/3, (-)/3]]).

:- comment(plus / 3, [
	summary:"Succeeds if Sum is the sum of integer arguments Add1 and Add2.

",
	amode:(plus(+,+,-) is det),
	amode:(plus(+,-,+) is det),
	amode:(plus(-,+,+) is det),
	desc:html("   Defines the arithmetic relation Add1 + Add2 = Sum.  If all arguments are
   instantiated plus/3 succeeds if this relation holds.  If one of the
   arguments is uninstantiated, it is bound to an integer such that the
   relation holds.  If the system is in coroutining mode and more than one
   argument is uninstantiated, plus/3 delays until at least two of the
   arguments are known.

<P>
"),
	args:["Add1" : "an integer or a variable", "Add2" : "an integer or a variable", "Sum" : "an integer or a variable"],
	exceptions:[5 : "an argument is neither an integer nor a variable", 4 : "more than one argument is uninstantiated (non-coroutining    mode only)"],
	eg:"
   Success:
   plus(1, 2, 3).
   plus(3, 4, Z).                   (gives Z=7)
   plus(X, 4, 7).                   (gives X=3)
   plus(3, Y, 7).                   (gives Y=4)
   Fail:
   plus(3, 4, 5).
   Error:
   plus(3.0, 4.0, 7.0).             (error 5)
   plus(2 + 3, 1, 6).               (error 5)
   plus(X, 1, Z).                   (error 4)



",
	see_also:[times / 3]]).

:- comment(times / 3, [
	summary:"Succeeds if Product is the result of multiplying integer arguments Factor1
and Factor2.

",
	amode:(times(+,+,-) is det),
	amode:(times(+,-,+) is semidet),
	amode:(times(-,+,+) is semidet),
	desc:html("   Defines the arithmetic relation Factor1 * Factor2 = Product.  If all
   arguments are instantiated times/3 succeeds if this relation holds.  If
   one of the arguments is uninstantiated, it is bound to an integer such
   that the relation holds.  Note that this is not always possible.  If the
   system is in coroutining mode and more than one argument is
   uninstantiated, times/3 delays until at least two of the arguments are
   known.

<P>
"),
	args:["Factor1" : "An integer or a variable.", "Factor2" : "An integer or a variable.", "Product" : "An integer or a variable."],
	fail_if:"Fails if it is impossible to find an integer instantiation such that\n   Factor1 * Factor2 = Product holds",
	exceptions:[4 : "more than one argument is uninstantiated (non-coroutining    mode only)", 5 : "an argument is neither an integer nor a variable"],
	eg:"
   Success:
   times(2, 3, 6).
   times(2, 3, Z).                   (gives Z=6)
   times(X, 3, 6).                   (gives X=2)
   times(2, Y, 6).                   (gives Y=3)
   Fail:
   times(3, 4, 5).
   times(3, X, 5).
   Error:
   times(2.0, 3.0, 6.0).             (error 5)
   times(1 + 4, 2, 10).              (error 5)
   times(X, 1, Z).                   (error 4)



",
	see_also:[plus / 3]]).

:- comment(between / 4, [
	summary:"Generate integer values between From and To with Step increment.

",
	amode:(between(+, +, +, -) is nondet),
	desc:html("   When first called, this predicate checks that From is less than or equal
   to To (or greater than or equal if Step is negative) and if so, it binds
   Result to From.  On backtracking it increments Result by Step until it
   is greater than To (less than To is Step is negative) and then it fails.

<P>
"),
	args:["From" : "Integer", "To" : "Integer", "Step" : "Integer", "Result" : "A variable or an integer"],
	fail_if:"Fails if To is less than From (for positive Step), or From less than To (for negative Step)",
	exceptions:[4 : "Input arguments are not instantiated.",
		5 : "An argument is not an integer.",
		6 : "Step is zero.",
		24 : "An argument is not a number."],
	eg:"
Success:
      between(1, 4, 1, X).
      between(5, 0, -2, X).
      between(2, 10, 3, 8).
      between(3, 3, 1, X).
Fail:
      between(2, 0, 1, X).
Error:
      between(1, 4, S, X).         (Error 4)
      between(1, 4, 0.1, X).       (Error 5)
      between(1, 4, 0, X).         (Error 6)
      between(1, 4, 1, a).         (Error 24)



",
	see_also:[]]).

:- comment(ceiling / 2, [
	summary:"Unifies Result with the least integral value that is greater than or equal to
Number and of the same numeric type as Number.

",
	amode:(ceiling(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to ceiling(Number, Result) is
   equivalent to
<PRE>
    Result is ceiling(Number)
</PRE>
    which should be preferred.
<P>
   This operation works on all numeric types.  The result value is the
   smallest integral value that is greater than Number (rounding up
   towards positive infinity).
<P>
   The result type is the same as the argument type.  To convert the
   type to integer, use integer/2.
<P>
   In coroutining mode, if Number is uninstantiated, the call to ceiling/2
   is delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result and Number are numbers of different types.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      ceiling(1.8, 2.0).
      ceiling(-1.8, -1.0).
      ceiling(5, 5).
      ceiling(-6.4, Result).      (gives Result = -6.0)
Fail:
      ceiling(0.0, 1.0).
Error:
      ceiling(A, 6.0).                   (Error 4).
      ceiling(0.5, 0).                   (Error 5).
      ceiling(1, r).                     (Error 24).
      ceiling(4 + 2.3, 6.0).             (Error 24).



",
	see_also:[(is) / 2, floor / 2, round/2, truncate/2, integer/2]]).

:- comment(clrbit / 3, [
	summary:"Result is Number with the Index'th bit cleared.

",
	amode:(clrbit(+,+,-) is det),
	desc:html("   Clear the Index'th bit in Number giving Result. The least significant
   bit has index zero. Two's complement representation is assumed.
   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to clrbit(Number, Index, Result) is
   equivalent to
<PRE>
    Result is clrbit(Number, Index)
</PRE>
   which should be preferred.

<P>
   In coroutining mode, if Number or Index are uninstantiated, the call
   is delayed until these variables are instantiated.

<P>
"),
	args:["Number" : "Integer.", "Index" : "Non-negative integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number or Index is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number or Index is a number but not an integer.", 24 : "Number or Index is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      clrbit(15, 3, 7).
      clrbit(40, 3, X).            gives X=32.
      X is clrbit(setbit(0,5),5).  gives X=0.



",
	see_also:[(is) / 2, setbit / 3, getbit / 3]]).

:- comment(denominator / 2, [
	summary:"Extracts the denominator of the rational Number and unifies the resulting
integer with Result.

",
	amode:(denominator(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to denominator(Number, Result) is
   equivalent to
<PRE>
    Result is denominator(Number)
</PRE>
    which should be preferred.
<P>
   In coroutining mode, if Number is uninstantiated, the call to
   denominator/2 is delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "An integer or rational number.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Number is a float or breal.", 5 : "Result is a number but not an integer.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      denominator(3_4, 4).
      denominator(9_12, 4).
      denominator(-3_4, 4).
      denominator(25, 1).
Fail:
      denominator(3_4, 3).
Error:
      denominator(A, 3).                     (Error 4).
      denominator(3.1, 3).                   (Error 5).
      denominator(3_4, 3_1).                 (Error 5).
      denominator(3_4, r).                   (Error 24).
      denominator(1_3 + 3_4, 12).            (Error 24).



",
	see_also:[(is) / 2, numerator / 2, rational / 2]]).

:- comment(eval / 2, [
	summary:"Used to evaluate eval/1 terms in arithmetic expressions.",
	amode:(eval(+,-) is det),
	desc:html("\
   This is one of the predicates used by the ECLiPSe compiler to expand
   arithmetic expressions. If an expression contains a subexpression that
   is not known at compile time, it must be wrapped in eval/1, e.g.
<PRE>
   X is eval(Expr)+1
</PRE>
   This will be compiled into the sequence
<PRE>
   eval(Expr,T1), +(T1,1,X)
</PRE>
   and eval/2 will interpret the expression Expr at runtime.
"),
	args:["Expression" : "An arithmetic expression.", "Result" : "A variable or a number."],
	exceptions:[4 : "Expression is uninstantiated.",
		5:"Result is neither a number nor a variable.",
		5 : "Evaluation of Expression gives a different type than Result.",
		21 : "An evaluation predicate in the expression is not defined.",
		24 : "Expression is not a valid arithmetic expression."],
	eg:"



",
	see_also:[(is)/2]]).

:- comment(floor / 2, [
	summary:"Unifies Result with the greatest integral value that is less or equal than
Number and of the same numeric type as Number.

",
	amode:(floor(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to floor(Number, Result) is
   equivalent to
<PRE>
    Result is floor(Number)
</PRE>
   which should be preferred for portability.
<P>
   This operation works on all numeric types. The result value is the
   largest integral value that is smaller that Number (rounding down
   towards minus infinity).
<P>
   The result type is the same as the argument type.  To convert the
   type to integer, use integer/2.
<P>
   In coroutining mode, if Number is uninstantiated, the call to floor/2
   is delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result and Number are numbers of different types.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      floor(1.8, 1.0).
      floor(-1.8, -2.0).
      floor(5, 5).
      floor(-6.4, Result).      (gives Result = -7.0)
Fail:
      floor(1.0, 0.0).
Error:
      floor(A, 6.0).                   (Error 4).
      floor(0.5, 0).                   (Error 5).
      floor(1, r).                     (Error 24).
      floor(4 + 2.3, 6.0).             (Error 24).



",
	see_also:[(is) / 2, ceiling/2, round/2, truncate/2, integer/2]]).

:- comment(truncate / 2, [
	summary:"Unifies Result with the closest integer value between 0 and
Number, and of the same numeric type as Number.

",
	amode:(truncate(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to truncate(Number, Result) is
   equivalent to
<PRE>
    Result is truncate(Number)
</PRE>
   which should be preferred for portability.
<P>
   This operation works on all numeric types. The result value is the
   closest integral value that lies between 0 and Number (rounding
   towards zero).
<P>
   The result type is the same as the argument type.  To convert the
   type to integer, use integer/2.
<P>
   In coroutining mode, if Number is uninstantiated, the call to truncate/2
   is delayed until this variable is instantiated.
<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result and Number are numbers of different types.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      X is truncate(1.8).	   (gives Result = 1.0)

      truncate(1.8, 1.0).
      truncate(-1.8, -1.0).
      truncate(5, 5).
      truncate(-6.4, Result).      (gives Result = -6.0)
Fail:
      truncate(1.0, 0.0).
Error:
      truncate(A, 6.0).                   (Error 4).
      truncate(0.5, 0).                   (Error 5).
      truncate(1, r).                     (Error 24).
      truncate(4 + 2.3, 6.0).             (Error 24).
",
	see_also:[(is) / 2, floor/2, ceiling/2, round/2, integer/2, fix/2]]).

:- comment(getbit / 3, [
	summary:"Result is the Index'th bit of Number.

",
	amode:(getbit(+,+,-) is det),
	desc:html("   Returns the Index'th bit of Number, assuming binary two's complement
   representation.  The least significant bit has index zero.
   The result is either 0 or 1.
   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to getbit(Number, Index, Result) is
   equivalent to
<PRE>
    Result is getbit(Number, Index)
</PRE>
   which should be preferred.
<P>
   In coroutining mode, if Number or Index are uninstantiated, the call
   is delayed until these variables are instantiated.

<P>
"),
	args:["Number" : "Integer.", "Index" : "Non-negative integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number or Index is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number or Index is a number but not an integer.", 24 : "Number or Index is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      getbit(10, 3, 1).
      getbit(10, 2, 0).
      getbit(10, 99, 0).



",
	see_also:[(is) / 2, clrbit / 3, setbit / 3]]).

:- comment((is) / 2, [
	summary:"Evaluates the arithmetic expression Expression and unifies the resulting
value with Result.

",
	template:"?Result is +Expression",
	amode:(is(-,+) is det),
	amode:(is(+,+) is det),	% can make extra errors!
	desc:html("\
   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.
<P>
   ECLiPSe distinguishes four types of numbers:
<DL>
    <DT><STRONG>integers</STRONG> e.g. 12345
	<DD>Integers can be of arbitrary magnitude. Integers that fit
	into the word size of the machine are handled more efficiently.
    <DT><STRONG>rationals</STRONG> e.g. 3_4
    	<DD>Rational numbers represent the corresponding mathematical
	notion (the ratio of two integers). The operations defined on
	rationals give precise (rational) results.
    <DT><STRONG>floats</STRONG> e.g. 3.1415
	<DD>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).
    <DT><STRONG>bounded reals (breal)</STRONG> e.g. 3.1415__3.1416
    	<DD>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).
</DL>
   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.
<P>
   The system performs automatic type conversions in the direction
<BLOCKQUOTE>
    integer -&gt; rational -&gt; float -&gt; breal.
</BLOCKQUOTE>
   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.
<P>
   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.
<P>
   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.
<P>
   Most arithmetic errors will not be reported in is/2, but in the
   evaluation predicate where it occurred.
<PRE>
    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 &gt;&gt; E2       shift E1 right by E2 bits  integer x integer    integer
    E1 &lt;&lt; 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
</PRE>
   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.
<P>
   The relation between integer divisions // and div, and remainder and
   modulus operations rem and mod is as follows:
<PRE>
    X =:= (X rem Y) + (X  // Y) * Y.
    X =:= (X mod Y) + (X div Y) * Y.
</PRE>
"),
	args:["Result" : "A variable or a number.", "Expression" : "An arithmetic expression."],
	fail_if:"Fails if a user-defined evaluation predicate fails",
	exceptions:[4 : "Expression is uninstantiated", 
		5:"Result is neither a number nor a variable.", 5 : "Evaluation of Expression gives a different type than Result.", 21 : "An evaluation predicate in the expression is not defined.",
24 : "Expression is not a valid arithmetic expression."],
	eg:"
   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]]).

:- comment(numerator / 2, [
	summary:"Extracts the numerator of the rational Number and unifies the resulting
integer with Result.

",
	amode:(numerator(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to numerator(Number, Result) is
   equivalent to
<PRE>
    Result is numerator(Number)
</PRE>
   which should be preferred.
<P>
   In coroutining mode, if Number is uninstantiated, the call to
   numerator/2 is delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "An integer or rational number.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Number is a float or breal.", 5 : "Result is a number but not an integer.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      numerator(3_4, 3).
      numerator(9_12, 3).
      numerator(-3_4, -3).
      numerator(25, 25).
Fail:
      numerator(3_4, 4).
Error:
      numerator(A, 3).                     (Error 4).
      numerator(3.1, 3).                   (Error 5).
      numerator(3_4, 3_1).                 (Error 5).
      numerator(3_4, r).                   (Error 24).
      numerator(1_3 + 3_4, 13).            (Error 24).



",
	see_also:[(is) / 2, denominator / 2, rational / 2]]).

:- comment(rational / 2, [
	summary:"Converts Number into a rational number and unifies it with Result.

",
	amode:(rational(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to rational(Number, Result) is
   equivalent to
<PRE>
    Result is rational(Number)
</PRE>
    which should be preferred.
<P>
   When Number is an integer, Result is a rational with denominator 1.
<P>
   When Number is already a rational, Result is identical to Number.
<P>
   When Number is a float, Result is a rational whose value is exactly equal
   to the value of the floating-point number. Since floats are usually
   approximations of the intended value, the results may look unintuitive
   and have unnecessarily large numerators and denominators. Use rationalize/2
   to produce the most compact rational that still converts back into the
   original float. rational/2 is usually faster than rationalize/2.
<P>
   Bounded reals cannot be converted to rationals.
<P>
   In coroutining mode, if Number is uninstantiated, the call to
   rational/2 is delayed until this variable is instantiated.
"),
	args:["Number" : "A number.", "Result" : "A variable or rational number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).",
	    5 : "Result is a number but not of type rational.",
	    24 : "Number is not of a numeric type.",
	    24 : "Result is neither a number nor a variable.",
	    141 : "Number is a bounded real"],
	eg:"
Success:
      rational(25, 25_1).
      rational(1.5, 3_2).
      rational(3_4,3_4).
      rational(9_12,3_4).
      rational(-6, Result).      (gives Result = -6_1)
      rational(0.1, Result).     (gives Result = 3602879701896397_36028797018963968)
Fail:
      rational(1, 2_1).
Error:
      rational(A, 1_3).                   (Error 4).
      rational(3, 3).                     (Error 5).
      rational(1, r).                     (Error 24).
      rational(4 + 2, 6_1).               (Error 24).
      rational(0.9__1.1, X).              (Error 141).



",
	see_also:[rationalize/2, (is) / 2]]).

:- comment(rationalize / 2, [
	summary:"Converts Number into a compact rational number and unifies it with Result.

",
	amode:(rationalize(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to rationalize(Number, Result) is
   equivalent to
<PRE>
    Result is rationalize(Number)
</PRE>
    which should be preferred.
<P>
   When Number is an integer, Result is a rational with denominator 1.
<P>
   When Number is already a rational, Result is identical to Number.
<P>
   When Number is a float, Result is a rational whose value approximates
   the value of the float to the accuracy of the float representation.
   rationalize/2 usually produces more compact rationals that rational/2.
   Both rationalize/2 and rational/2 produce results that convert back into
   the original float. rational/2 is usually faster than rationalize/2.
<P>
   Bounded reals cannot be converted to rationals.
<P>
   In coroutining mode, if Number is uninstantiated, the call to
   rationalize/2 is delayed until this variable is instantiated.
"),
	args:["Number" : "A number.", "Result" : "A variable or rational number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).",
	    5 : "Result is a number but not of type rational.",
	    24 : "Number is not of a numeric type.",
	    24 : "Result is neither a number nor a variable.",
	    141 : "Number is a bounded real"],
	eg:"
Success:
      rationalize(25, 25_1).
      rationalize(1.5, 3_2).
      rationalize(3_4,3_4).
      rationalize(9_12,3_4).
      rationalize(-6, Result).      (gives Result = -6_1)
      rationalize(0.1, Result).     (gives Result = 1_10)
Fail:
      rationalize(1, 2_1).
Error:
      rationalize(A, 1_3).                   (Error 4).
      rationalize(3, 3).                     (Error 5).
      rationalize(1, r).                     (Error 24).
      rationalize(4 + 2, 6_1).               (Error 24).
      rationalize(0.9__1.1, X).              (Error 141).



",
	see_also:[rational/2, (is) / 2]]).

:- comment(setbit / 3, [
	summary:"Result is Number with the Index'th bit set.

",
	amode:(setbit(+,+,-) is det),
	desc:html("   Set the Index'th bit in Number giving Result. The least significant
   bit has index zero. Two's complement representation is assumed.
   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to setbit(Number, Index, Result) is
   equivalent to
<PRE>
    Result is setbit(Number, Index)
</PRE>
   which should be preferred.
<P>
   In coroutining mode, if Number or Index are uninstantiated, the call
   is delayed until these variables are instantiated.
"),
	args:["Number" : "Integer.", "Index" : "Non-negative integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number or Index is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number or Index is a number but not an integer.", 24 : "Number or Index is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      setbit(0, 3, 8).
      setbit(1, 8, X).             gives X=257.
      X is setbit(setbit(0,3),5).  gives X=40.



",
	see_also:[(is) / 2, clrbit / 3, getbit / 3]]).

:- comment(sgn / 2, [
	summary:"Unifies Result with the sign of Number which is either -1, 0 or 1.

",
	amode:(sgn(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to sgn(Number, Result) is
   equivalent to
<PRE>
    Result is sgn(Number)
</PRE>
    which should be preferred for portability.
<P>
   sgn/2 gives the integer -1 if Number is negative, 0 if it is zero and 1
   if it is greater than zero.  It is always true that
<PRE>
    X =:= sgn(X) * abs(X)
</PRE>
   In coroutining mode, if Number is uninstantiated, the call to sgn/2 is
   delayed until this variable is instantiated.
"),
	args:["Number" : "A number.", "Result" : "A variable or an integer."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a non-integer number.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      sgn(42, 1).
      sgn(-5, Result).             (gives Result = -1)
      sgn(-6.2, Result).           (gives Result = -1)
      sgn(0.0, 0).
Fail:
      sgn(1, 0).
Error:
      sgn(A, 6).                   (Error 4).
      sgn(1, 1.0).                 (Error 5).
      sgn(4 + 2, 6).               (Error 24).
      sgn(1, r).                   (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(sum / 2, [
	summary:"Evaluates the the arithmetic expressions in ExprList and unifies their sum
with Result.

",
	amode:(sum(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
    arithmetic expressions.  So the call to sum(ExprList, Result) is
    equivalent to
<PRE>
    Result is sum(ExprList)
</PRE>
    which should be preferred.
<P>
   In coroutining mode, if the list is only partly instantiated, the
   predicate delays until the list is complete.
"),
	args:["ExprList" : "A list of arithmetic expressions.", "Result" : "A variable or number."],
	exceptions:[4 : "ExprList is a partial list (non-coroutining mode only).", 5 : "ExprList is not a proper list.", 5 : "Result is not a number."],
	eg:"
Success:
      X is sum([1,2,3]).  % gives X = 6



",
	see_also:[(is) / 2, (+) / 3]]).

:- comment(min / 2, [
	summary:"Evaluates the the arithmetic expressions in ExprList and unifies their minimum
with Result.

",
	amode:(min(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
    arithmetic expressions.  So the call to min(ExprList, Result) is
    equivalent to
<PRE>
    Result is min(ExprList)
</PRE>
    which should be preferred.
<P>
   In coroutining mode, if the list is only partly instantiated, the
   predicate delays until the list is complete.
"),
	args:["ExprList" : "A list of arithmetic expressions.", "Result" : "A variable or number."],
	exceptions:[4 : "ExprList is a partial list (non-coroutining mode only).", 5 : "ExprList is not a proper list.", 5 : "Result is not a number."],
	eg:"
Success:
      X is min([1,2,3]).    % gives X = 1
      X is min([1,2.0,3]).  % gives X = 1.0
",
	see_also:[(is) / 2, min/3, max/2]]).

:- comment(max / 2, [
	summary:"Evaluates the the arithmetic expressions in ExprList and unifies their maximum
with Result.

",
	amode:(max(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
    arithmetic expressions.  So the call to max(ExprList, Result) is
    equivalent to
<PRE>
    Result is max(ExprList)
</PRE>
    which should be preferred.
<P>
   In coroutining mode, if the list is only partly instantiated, the
   predicate delays until the list is complete.
"),
	args:["ExprList" : "A list of arithmetic expressions.", "Result" : "A variable or number."],
	exceptions:[4 : "ExprList is a partial list (non-coroutining mode only).", 5 : "ExprList is not a proper list.", 5 : "Result is not a number."],
	eg:"
Success:
      X is max([1,2,3]).    % gives X = 3
      X is max([1,2.0,3]).  % gives X = 3.0
",
	see_also:[(is) / 2, max/3, min/2]]).

:- comment(abs / 2, [
	summary:"Unifies the absolute value of Number with Result.

",
	amode:(abs(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to abs(Number, Result) is
   equivalent to
<PRE>
    Result is abs(Number)
</PRE>
   which should be preferred for portability.
<P>
   Number and Result have to be of the same type.
<P>
   In coroutining mode, if Number is uninstantiated, the call to abs/2 is
   delayed until this variable is instantiated.
"),
	args:["Number" : "A number.", "Result" : "A variable or a number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result and Number are numbers of different types.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      abs(1, 1).
      abs(-5, Result).             (gives Result = 5)
      abs(-6.2, Result).           (gives Result = 6.2)
Fail:
      abs(1, 0).
Error:
      abs(A, 6).                   (Error 4).
      abs(1, 1.0).                 (Error 5).
      abs(-1.0, 1).                (Error 5).
      abs(4 + 2, 6).               (Error 24).
      abs(1, r).                   (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(acos / 2, [
	summary:"Evaluates the trigonometric function acos(Number) and unifies the resulting
value with Result.

",
	amode:(acos(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to acos(Number, Result) is
   equivalent to
<PRE>
    Result is acos(Number)
</PRE>
   which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to acos/2 is
   delayed until this variable is instantiated.
"),
	args:["Number" : "A number.", "Result" : "A variable or float."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).",
	    5 : "Result is a number but not a float",
	    24 : "Number is not of a numeric type.",
	    24 : "Result is neither a number nor a variable.",
	    20 : "Illegal arithmetic operation: Number is greater than 1 or less than -1.",
	    141 : "Argument is of type breal"],
	eg:"
Success:
      acos(1.0, 0.0).
      acos(-0.5, Result).       (gives Result = 2.0944)
      acos(0, Result).          (gives Result = 1.5708)
Fail:
      acos(1, 1.0).
Error:
      acos(A, 6.0).             (Error 4).
      acos(1, r).               (Error 5).
      acos(1, 0).               (Error 5).
      acos(2, Result).          (Error 20).
      acos(4 - 3, 0.0).         (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((/\) / 3, [
	summary:"Evaluates the bitwise conjunction Number1 /\\ Number2 and unifies the
resulting value with Result.

",
	amode:(/\(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to /\\(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 /\\ Number2
</PRE>
   which should be preferred for portability.
<P>
   This operation behaves as if operating on an unlimited length two's
   complement representation.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to /\\/3 is delayed until these variables are instantiated.
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number1 or Number2 is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      /\\(11, 7, 3).
      /\\(-11, 7, Result).       (gives Result = 5)
Fail:
      /\\(1, 2, 3).
Error:
      /\\(A, 2, 6).              (Error 4).
      /\\(5, 2, r).              (Error 5).
      /\\(6, 2.0, 2.0).          (Error 5).
      /\\(4 + 2, 2, 2).          (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(asin / 2, [
	summary:"Evaluates the trigonometric function asin(Number) and unifies the resulting
value with Result.

",
	amode:(asin(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to asin(Number, Result) is
   equivalent to
<PRE>
    Result is asin(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to asin/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or float."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).",
	    5 : "Result is a number but not a float",
	    24 : "Number is not of a numeric type.",
	    24 : "Result is neither a number nor a variable.",
	    20 : "Illegal arithmetic operation: Number is greater than 1 or less than -1.",
	    141 : "Argument is of type breal"],
	eg:"
Success:
      asin(1.0, Result).           (gives Result = 1.5708)
      asin(-0,5, Result).          (gives Result = -0.523599)
Fail:
      asin(1, 0.0).
Error:
      asin(A, 6.0).                  (Error 4).
      asin(1, 3).                    (Error 5).
      asin(2, Result).               (Error 20).
      asin(4 + 2, -0.279415).        (Error 24).
      asin(1, r).                    (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(atan / 2, [
	summary:"Evaluates the trigonometric function atan(Number) and unifies the resulting
value with Result.

",
	amode:(atan(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to atan(Number, Result) is
   equivalent to
<PRE>
    Result is atan(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to atan/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable, float or breal."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      atan(0.0, 0.0).
      atan(1.0, Result).       (gives Result = 0.785398)
      atan(-8, Result).        (gives Result = -1.44644)
Fail:
      atan(1, 0.0).
Error:
      atan(A, 6.0).                   (Error 4).
      atan(1.55741, 1).               (Error 5).
      atan(1 + 0.55741, 1.0).         (Error 24).
      atan(5, r).                     (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(atan / 3, [
	summary:"Computes the arc tangent function of two variables and unifies the resulting value with Result.",
	amode:(atan(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to atan(Y, X, Result) is
   equivalent to
<PRE>
    Result is atan(Y, X)
</PRE>
    which should be preferred for portability.
<P>
    It is similar to calculating the arc tangent of Y/X, except that the
    signs of both arguments are used to determine the quadrant of the result.
    The result lies in the interval -pi..pi. The operation is valid even if
    X is zero, in which case the result is pi/2 or -pi/2.  One application
    is the conversion of cartesian to polar coordinates, where this function
    computes the angle component (in radians).
<P>
   In coroutining mode, if X or Y is uninstantiated, the call to atan/3 is
   delayed until both variables are instantiated.

<P>
"),
	args:["Y" : "A number.", "X":"A number.", "Result" : "A variable, float or breal."],
	exceptions:[4 : "X or Y is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      atan( 0.0, -1.0, Result).	(gives Result =  3.141592)
      atan( 1.0, -1.0, Result).	(gives Result =  2.356194)
      atan( 1.0,  0.0, Result).	(gives Result =  1.570796)
      atan( 1.0,  1.0, Result).	(gives Result =  0.785398)
      atan( 0.0,  0.0, Result).	(gives Result =  0.0)
      atan(-1.0,  1.0, Result).	(gives Result = -0.785398)
      atan(-1.0,  0.0, Result).	(gives Result = -1.570796)
      atan(-1.0, -1.0, Result).	(gives Result = -2.356194)
      atan(-0.0, -1.0, Result).	(gives Result = -3.141592)

      atan( 7.0,  7.0, Result).	(gives Result =  0.785398)

Error:
      atan(A, 0.0, 6.0).              (Error 4).
      atan(1.55741, 0.0, 1).          (Error 5).
      atan(1 + 0.55741, 1.0, R).      (Error 24).
",
	see_also:[(is) / 2]]).

:- comment((\) / 2, [
	summary:"Evaluates the bitwise complement of Number and unifies the resulting value
with Result.

",
	amode:(\(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to \\(Number, Result) is equivalent
   to
<PRE>
    Result is \\Number
</PRE>
    which should be preferred for portability.
<P>
   This operation behaves as if operating on an unlimited length two's
   complement representation.
<P>
   In coroutining mode, if Number is uninstantiated, the call to \\/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not an integer.", 5 : "Number is a number but not an integer.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      \\(1, -2).
      \\(5, Result).            (gives Result = -6)
      \\(-6, Result).           (gives Result = 5)
Fail:
      \\(1, 0).
Error:
      \\(A, 6).                   (Error 4).
      \\(0.0, 0.0).               (Error 5).
      \\(4 + 2, -7).              (Error 24).
      \\(1, r).                   (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(cos / 2, [
	summary:"Evaluates the trigonometric function cos(Number) and unifies the resulting
value with Result.

",
	amode:(cos(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to cos(Number, Result) is
   equivalent to
<PRE>
    Result is cos(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to cos/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable, float or breal."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      cos(0, 1.0).
      cos(1.2, Result).        (gives Result = 0.362358)
      cos(-33, Result).        (gives Result = -0.0132767)
Fail:
      cos(1, 0.0).
Error:
      cos(A, 6.0).                   (Error 4).
      cos(0, 1).                     (Error 5).
      cos(4 + 2, 0.96017).           (Error 24).
      cos(5, r).                     (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((/) / 3, [
	summary:"Evaluates the quotient Number1 / Number2 and unifies the resulting value
with Result.

",
	amode:(/(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to /(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 / Number2
</PRE>
    which should be preferred for portability.
<P>
   The result type of the division depends on the value of the global flag
   prefer_rationals.  When it is off, the result is a float,
   when it is on, the result is a rational.  In coroutining mode, if
   Number1 or Number2 are uninstantiated, the call to //3 is delayed until
   these variables are instantiated.

<P>
"),
	args:["Number1" : "A number.", "Number2" : "A number.", "Result" : "A variable or float (resp. rational)."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not a float (resp. rational).", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable.", 20 : "Illegal arithmetic operation:  division by 0"],
	eg:"
Success:
    /(10, 2, 5.0).
    /(10, -2.0, -5.0).
    /(9, 12, 3_4).      (with set_flag(prefer_rationals, on))
Fail:
    /(1, 2, 1.0).
Error:
    /(A, 2, 6.0).            (Error 4).
    /(5, 2, r).              (Error 5).
    /(6, 2, 3).              (Error 5).
    /(2, 0, Result).         (Error 20).
    /(4 + 2, 2, 12).         (Error 24).



",
	see_also:[(is) / 2, get_flag / 2, set_flag / 2]]).

:- comment((=:=) / 2, [
	summary:"Succeed if the value of Expr1 is equal to the value of Expr2.

",
	template:"+Expr1 =:= +Expr2",
	amode:((+ =:= +) is semidet),
	desc:html("   Both arguments are evaluated and their types adjusted.  Then the
   resulting numbers are compared.  The predicate succeeds if the values of
   Expr1 and Expr2 are equal (beware of rounding errors when comparing
   floats).  If the system is in coroutining mode and the arguments are not
   ground, this predicate delays until the expressions are fully
   instantiated.
<P>
   The predicate also delays when the comparison involves bounded reals,
   and the compared values overlap such that the result is undecidable.
<P>
"),
	args:["Expr1" : "An arithmetic expression", "Expr2" : "An arithmetic expression"],
	fail_if:"fails if the value of Expr1 is not equal to the value of Expr2",
	exceptions:[4 : "Expr1 or Expr2 is a variable (non-coroutining mode only).", 5 : "Expr1 or Expr2 is not an arithmetic expression."],
	eg:"
   Success:
   5 - 2 =:= 6 / 2.
   1 =:= sin(pi/2).        % 1 converted to 1.0
   Fail:
   2 + 3 =:= 2 * 3.
   Error:
   _ =:= 0.                   (Error 4)
   \"s\" =:= 0.                 (Error 5)



",
	see_also:[_:(=:=)/2, (is) / 2, (<) / 2, (=\=) / 2, (>=) / 2, (=<) / 2, (>) / 2]]).

:- comment(exp / 2, [
	summary:"Evaluates the exponential function exp(Number) (\"e to the power of Number\")
and unifies the resulting value with Result.

",
	amode:(exp(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to exp(Number, Result) is
   equivalent to
<PRE>
    Result is exp(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to exp/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable, float or breal."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      exp(0.0, Result).       (gives Result = 1.0)
      exp(-6, Result).        (gives Result = 0.00247875)
Fail:
      exp(1, 0.0).
Error:
      exp(A, 6.0).                   (Error 4).
      exp(0, 1).                     (Error 5).
      exp(4 + 2, 403.429).           (Error 24).
      exp(1, r).                     (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(fix / 2, [
	summary:"Unifies the integer part of Number with Result (Truncation towards zero).

",
	amode:(fix(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to fix(Number, Result) is
   equivalent to
<PRE>
    Result is fix(Number)
</PRE>
    which should be preferred for portability.
<P>
    This function is deprecated. For clearer code, please use
<PRE>
    Result is integer(truncate(Number)).
</PRE>
<P>
   In coroutining mode, if Number is uninstantiated, the call to fix/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).",
	    5 : "Number is of type breal.",
	    5 : "Result is a number but not an integer.",
	    24 : "Number is not of a numeric type.",
	    24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      fix(1.5, 1).
      fix(-6.4, -6).
Fail:
      fix(1, 0).
Error:
      fix(A, 6.0).                 (Error 4).
      fix(0.0, 0.0).               (Error 5).
      fix(4 + 2.3, 6).             (Error 24).
      fix(1, r).                   (Error 24).



",
	see_also:[(is) / 2, integer/2, truncate/2, floor/2, ceiling/2, round/2]]).

:- comment(integer / 2, [
	summary:"Convert an integral number of any type to an integer",
	amode:(integer(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to integer(Number, Result) is
   equivalent to
<PRE>
    Result is integer(Number)
</PRE>
    which should be preferred for portability.
<P>
    This is a pure type conversion operation. If Number has an integral value
    of any type, Result is that same value, but represented as an integer.
    If Number does not have an integral value, an exception is raised.
    This function should therefore normally be applied to the result of
    one of the rounding operations floor, ceiling, round or truncate.
<P>
   In coroutining mode, if Number is uninstantiated, the call to integer/2 is
   delayed until this variable is instantiated.
<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).",
	    5 : "Number is of type breal.",
	    5 : "Result is a number but not an integer.",
	    20 : "Number is not integral.",
	    24 : "Number is not of a numeric type.",
	    24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      X is integer(5.0).               (gives X = 5)

      integer(5, 5).
      integer(5.0, 5).
      integer(5_1, 5).
      integer(5.0__5.0, 5).

Error:
      integer(1.1, X).                 (Error 20)
      integer(5_4, X).                 (Error 20)
      integer(0.99__1.01, X).          (Error 20)
      integer(A, 6.0).                 (Error 4).
      integer(0.0, 0.0).               (Error 5).
      integer(4 + 2.3, 6).             (Error 24).
      integer(1, r).                   (Error 24).
",
        see_also:[(is) / 2, floor/2, ceiling/2, round/2, truncate/2]]).

:- comment(float / 2, [
	summary:"Converts Number to float and unifies the resulting value with
Result.

",
	amode:(float(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to float(Number, Result) is
   equivalent to
<PRE>
    Result is float(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to float/2
   is delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or float."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      float(1, 1.0).
      float(-6, Result).         (gives Result = -6.0)
Fail:
      float(1, 0.0).
Error:
      float(A, 6.0).                   (Error 4).
      float(0, 0).                     (Error 5).
      float(4 + 2, 6.0).               (Error 24).
      float(1, r).                     (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((>) / 2, [
	summary:"Succeed if the value of Expr1 is greater than the value of Expr2.

",
	template:"+Expr1 > +Expr2",
	amode:((+ > +) is semidet),
	desc:html("   Both arguments are evaluated and their types adjusted.  Then the
   resulting numbers are compared.  The predicate succeeds if the value of
   Expr1 is greater than the value of Expr2.  If the system is in
   coroutining mode and the arguments are not ground, this predicate delays
   until the expressions are fully instantiated.
<P>
   The predicate also delays when the comparison involves bounded reals,
   and the compared values overlap such that the result is undecidable.

<P>
"),
	args:["Expr1" : "An arithmetic expression", "Expr2" : "An arithmetic expression"],
	fail_if:"fails if the value of Expr1 is less or equal to the value of Expr2",
	exceptions:[4 : "Expr1 or Expr2 is a variable (non-coroutining mode only).", 5 : "Expr1 or Expr2 is not an arithmetic expression."],
	eg:"
   Success:
   5 - 1 > 6 / 2.
   1 > sin(pi/4).            % 1 converted to 1.0
   Fail:
   2 + 3 > 2 * 3.
   Error:
   _ > 0.                   (Error 4)
   \"s\" > 0.                 (Error 5)



",
	see_also:[_:(>)/2, (is) / 2, (=:=) / 2, (=\=) / 2, (>=) / 2, (<) / 2, (=<) / 2]]).

:- comment((>=) / 2, [
	summary:"Succeed if the value of Expr1 is greater than or equal to the value of
Expr2.

",
	template:"+Expr1 >= +Expr2",
	amode:((+ >= +) is semidet),
	desc:html("   Both arguments are evaluated and their types adjusted.  Then the
   resulting numbers are compared.  The predicate succeeds if the value of
   Expr1 is greater than or equal to the value of Expr2.  If the system is
   in coroutining mode and the arguments are not ground, this predicate
   delays until the expressions are fully instantiated.
<P>
   The predicate also delays when the comparison involves bounded reals,
   and the compared values overlap such that the result is undecidable.

<P>
"),
	args:["Expr1" : "An arithmetic expression", "Expr2" : "An arithmetic expression"],
	fail_if:"fails if the value of Expr1 is less than the value of Expr2",
	exceptions:[4 : "Expr1 or Expr2 is a variable (non-coroutining mode only).", 5 : "Expr1 or Expr2 is not an arithmetic expression."],
	eg:"
   Success:
   5 - 1 >= 6 / 2.
   1 >= sin(pi/2).       % 1 converted to 1.0
   Fail:
   2 + 3 >= 2 * 3.
   Error:
   _ >= 10.              (Error 4)
   \"s\" >= 10.            (Error 5)



",
	see_also:[_:(>=)/2, (is) / 2, (=:=) / 2, (=\=) / 2, (<) / 2, (>) / 2, (=<) / 2]]).

:- comment((//) / 3, [
	summary:"Evaluates the integer quotient Number1 // Number2 and unifies the resulting
value with Result.

",
	amode:(//(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to //(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 // Number2
</PRE>
    which should be preferred for portability.
<P>
    This division operates on integer arguments, and delivers an integer
    result rounded towards zero (truncated).  The corresponding remainder
    is computed by the rem operation, such that the following equivalence
    always holds:
<PRE>
    X =:= (X rem Y) + (X // Y) * Y.
</PRE>
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to (//)/3 is delayed until these variables are instantiated.
<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Number1 or Number2 is a number but not an integer.", 5 : "Result is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable.", 20 : "Illegal arithmetic operation:  division by 0"],
	eg:"
Success:
      X is 10 // 3.		( gives X = 3)

      //( 10,  3,  3).
      //(-10,  3, -3).
      //( 10, -3, -3).
      //(-10, -3,  3).

Fail:
      //(1, 2, 3).
Error:
      //(A, 2, 6).              (Error 4).
      //(5, 2, r).              (Error 5).
      //(6, 2.0, 3.0).          (Error 5).
      //(2, 0, Result).        (Error 20).
      //(4 + 2, 2, 12).        (Error 24).
",
	see_also:[(is) / 2, (div)/3, (rem)/3]]).

:- comment((div) / 3, [
	summary:"Evaluates the integer quotient Number1 div Number2 and unifies the resulting
value with Result.

",
	amode:(div(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to div(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 div Number2
</PRE>
    which should be preferred for portability.
<P>
    This division operates on integer arguments, and delivers an
    integer result rounded down towards negative infinity (floored). 
    The corresponding remainder is computed by the mod operation, such
    that the following equivalence always holds:
<PRE>
    X =:= (X mod Y) + (X div Y) * Y.
</PRE>
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to (div)/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Number1 or Number2 is a number but not an integer.", 5 : "Result is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable.", 20 : "Illegal arithmetic operation:  division by 0"],
	eg:"
Success:
      X is 10 div 3.		( gives X = 3)

      div( 10,  3,  3).
      div(-10,  3, -4).
      div( 10, -3, -4).
      div(-10, -3,  3).
Fail:
      div(1, 2, 3).
Error:
      div(A, 2, 6).              (Error 4).
      div(5, 2, r).              (Error 5).
      div(6, 2.0, 3.0).          (Error 5).
      div(2, 0, Result).        (Error 20).
      div(4 + 2, 2, 12).        (Error 24).
",
	see_also:[(is) / 2, (//)/3, (mod)/3]]).

:- comment((<) / 2, [
	summary:"Succeed if the value of Expr1 is less than the value of Expr2.

",
	template:"+Expr1 < +Expr2",
	amode:((+ < +) is semidet),
	desc:html("   Both arguments are evaluated and their types adjusted.  Then the
   resulting numbers are compared.  The predicate succeeds if the value of
   Expr1 is less than the value of Expr2.  If the system is in coroutining
   mode and the arguments are not ground, this predicate delays until the
   expressions are fully instantiated.
<P>
   The predicate also delays when the comparison involves bounded reals,
   and the compared values overlap such that the result is undecidable.

<P>
"),
	args:["Expr1" : "An arithmetic expression", "Expr2" : "An arithmetic expression"],
	fail_if:"Fails if the value of Expr1 is greater than or equal to the value of Expr2",
	exceptions:[4 : "Expr1 or Expr2 is a variable (non-coroutining mode only).", 5 : "Expr1 or Expr2 is not an arithmetic expression."],
	eg:"
   Success:
   5 - 3 < 6 / 2.
   0 < sin(pi/4).        % 0 converted to 0.0
   Fail:
   2 + 4 < 2 * 3.
   Error:
   _ < 10.              (Error 4)
   \"s\" < 10.            (Error 5)



",
	see_also:[_:(<)/2, (is) / 2, (=:=) / 2, (=\=) / 2, (>=) / 2, (=<) / 2, (>) / 2]]).

:- comment(frandom / 1, [
	summary:"Generates a random floating-point number F in the range <0, 1>.

",
	amode:(frandom(-) is det),
	desc:html("   frandom/1 unifies F with a random floating-point number between 0 and 1.
   The code is taken from random2.c by John Burton, available from the net.
   Part of original comment:

<P>
<PRE>
 *
 * PMMMLCG - Prime Modulus M Multiplicative Linear Congruential Generator   *
 *  Modified version of the Random number generator proposed by             *
 *  Park &amp; Miller in \"Random Number Generators: Good Ones Are Hard to Find\" *
 *  CACM October 1988, Vol 31, No. 10                                       *
 *   - Modifications proposed by Park to provide better statistical         *
 *     properties (i.e. more \"random\" - less correlation between sets of    *
 *     generated numbers                                                    *
 *   - generator is of the form                                             *
 *         x = ( x * A) % M                                                 *
 *   - Choice of A &amp; M can radically modify the properties of the generator *
 *     the current values were chosen after followup work to the original   *
 *     paper mentioned above.                                               *
 *   - The generator has a period of 0x3fffffff with numbers generated in   *
 *     the range of 0 &lt; x &lt; M                                               *
 *   - The generator can run on any machine with a 32-bit integer, without  *
 *     overflow.                                                            *
</PRE>
"),
	args:["F" : "Floating-point number or variable."],
	exceptions:[5 : "F is instantiated, but not to a floating-point number."],
	eg:"
Success:
      [eclipse]: frandom(F1), frandom(F2).
      F1 = 0.900086582
      F2 = 0.0795856342
      yes.

      [eclipse]: seed(1), frandom(F).
      F = 2.2477936e-05
      yes.
      [eclipse]: seed(1), frandom(F).
      F = 2.2477936e-05
      yes.

Fail:
      frandom(123.45).

Error:
      frandom(1234).          (Error 5).



",
	see_also:[seed / 1, random / 1]]).

:- comment((=<) / 2, [
	summary:"Succeed if the value of Expr1 is less than or equal to the value of Expr2.

",
	template:"+Expr1 =< +Expr2",
	amode:((+ =< +) is semidet),
	desc:html("   Both arguments are evaluated and their types adjusted.  Then the
   resulting numbers are compared.  The predicate succeeds if the value of
   Expr1 is less than or equal to the value of Expr2.  If the system is in
   coroutining mode and the arguments are not ground, this predicate delays
   until the expressions are fully instantiated.
<P>
   The predicate also delays when the comparison involves bounded reals,
   and the compared values overlap such that the result is undecidable.

<P>
"),
	args:["Expr1" : "An arithmetic expression", "Expr2" : "An arithmetic expression"],
	fail_if:"fails if the value of Expr1 is greater than the value of Expr2",
	exceptions:[4 : "Expr1 or Expr2 is a variable (non-coroutining mode only).", 5 : "Expr1 or Expr2 is not an arithmetic expression."],
	eg:"
   Success:
   5 - 3 =< 6 / 2.
   1 =< sin(pi/2).      % 1 converted to 1.0
   Fail:
   2 + 5 =< 2 * 3.
   Error:
   _ =< 10.              (Error 4)
   \"s\" =< 10.            (Error 5)



",
	see_also:[_:(=<)/2, (is) / 2, (=:=) / 2, (=\=) / 2, (>=) / 2, (<) / 2, (>) / 2]]).

:- comment(ln / 2, [
	summary:"Evaluates the natural logarithm ln(Number) and unifies the resulting value
with Result.

",
	amode:(ln(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to ln(Number, Result) is equivalent
   to
<PRE>
    Result is ln(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to ln/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable float or breal."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable.", 20 : "Illegal arithmetic operation:  Number is 0 or less."],
	eg:"
Success:
      ln(2.0, Result).          (gives Result = 0.693147)
      ln(1, Result).            (gives Result = 0.0)
Fail:
      ln(1, 1.0).
Error:
      ln(A, 6.0).                   (Error 4).
      ln(1, 0).                     (Error 5).
      ln(-2, Result).               (Error 20).
      ln(0, Result).                (Error 20).
      ln(4 + 2, 1.79176).           (Error 24).
      ln(1, r).                     (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(max / 3, [
	summary:"Unifies the maximum of Number1 and Number2 with Maximum.

",
	amode:(max(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to max(Number1, Number2, Maximum)
   is equivalent to
<PRE>
	Maximum is max(Number1, Number2)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to max/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "A number.", "Number2" : "A number.", "Maximum" : "A variable or number."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is of a different type than the evaluation result.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      max(5, 2, 5).
      max(2_3, 3_4, 3_4).
      max(5.0 , 2.0, 5.0).
      max(5, 2.0, 5.0).         (The types are adjusted)
      max(5, 2_0, 5_0).         (The types are adjusted)
Fail:
      max(1, 2, 3).
Error:
      max(A, 2, 6).             (Error 4).
      max(1, 2, 2.0).           (Error 5).
      max(5, 2.0, 5).           (Error 5).
      max(4 - 2, 3, 3).         (Error 24).
      max(5, 2, r).             (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(min / 3, [
	summary:"Unifies the minimum of Number1 and Number2 with Minimum.

",
	amode:(min(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to min(Number1, Number2, Minimum)
   is equivalent to
<PRE>
	Minimum is min(Number1, Number2)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to min/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "A number.", "Number2" : "A number.", "Minimum" : "A variable or a number."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is of a different type than the evaluation result.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      min(5, 2, 2).
      min(2_3, 3_4, 2_3).
      min(5.0 , 2.0, 2.0).
      min(5.0, 2, 2.0).         (The types are adjusted)
      min(5_0, 2, 2_0).         (The types are adjusted)
Fail:
      min(1, 2, 3).
Error:
      min(A, 2, 6).             (Error 4).
      min(1, 2, 2.0).           (Error 5).
      min(5, 2.0, 5).           (Error 5).
      min(4 - 2, 3, 3).         (Error 24).
      min(5, 2, r).             (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((-) / 3, [
	summary:"Evaluates the difference Number1 - Number2 and unifies the resulting value
with Result.

",
	amode:(-(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to -(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 - Number2
</PRE>
    which should be preferred for portability.
<P>
   The result is of type breal if any of the arguments is a breal,
   else float if any of the arguments is a float, else rational if any
   of the arguments is a rational.  Only when both arguments are
   integers is the result an integer.

<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to -/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "A number.", "Number2" : "A number.", "Result" : "A variable or a number."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is of a different type than the evaluation result.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      -(5, 2, 3).            (gives Result = 3)
      -(5, -2.0, Result).    (gives Result = 7.0)
Fail:
      -(1, 2, 3).
Error:
      -(A, 2, 6).             (Error 4).
      -(1, 2, 3.0).           (Error 5).
      -(4 + 1, 2, 3).         (Error 24).
      -(5, 2, r).             (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((rem) / 3, [
	summary:"Evaluates the remainder Number1 rem Number2 and unifies the resulting value
with Result.

",
	amode:(rem(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to rem(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 rem Number2
</PRE>
    which should be preferred for portability.
<P>
    The modulus operation computes the remainder corresponding to the
    truncating division //.  The following relation always holds:
<PRE>
    X =:= (X rem Y) + (X // Y) * Y.
</PRE>
    The result Result is either zero, or has the same sign as Number1.  The
    absolute value of Result does not depend on the signs of the arguments.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to rem/3 is delayed until these variables are instantiated.
<P>
   See also the mod operation, whose result only differs when the arguments
   have opposite signs.
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).",
		5 : "Result is a number but not an integer.",
		5 : "Number1 or Number2 is a number but not an integer.",
		20 : "Illegal arithmetic operation: Number2 is zero", 
		24 : "Number1 or Number2 is not of a numeric type.",
		24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      X is 10 rem 3.		(gives X = 1)

      rem( 10,  3,  1).
      rem(-10,  3, -1).
      rem( 10, -3, -1).
      rem(-10, -3,  1).

      rem( 11,  3,  2).
Fail:
      rem(1, 2, 3).
Error:
      rem(A, 2, 6).              (Error 4).
      rem(6, 2.0, 3.0).          (Error 5).
      rem(2, 0, Result).         (Error 20).
      rem(4 + 2, 2, 12).         (Error 24).
      rem(5, 2, r).              (Error 24).
",
	see_also:[(is) / 2, (//)/3, (mod)/3]]).

:- comment((mod) / 3, [
	summary:"Evaluates the modulus Number1 mod Number2 and unifies the resulting value
with Result.

",
	amode:(mod(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to mod(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 mod Number2
</PRE>
    which should be preferred for portability.
<P>
    The modulus operation computes the remainder corresponding to the
    flooring division div.  The following relation always holds:
<PRE>
    X =:= (X mod Y) + (X div Y) * Y.
</PRE>
    The result Result is either zero, or has the same sign as Number2.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to mod/3 is delayed until these variables are instantiated.
<P>
   CAUTION: The behaviour of mod was changed for standard compliance!
   In ECLiPSe versions up to 5.8, mod computed the remainder corresponding
   to the truncating division //, and thus gave different results for
   arguments with opposite signs.  Moreover, the operator precedence was
   changed from op(300,xfx,mod) to op(400,yfx,mod), which means that
   a*b mod c is now parsed as (a*b)mod c rather than a*(b mod c).
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).",
	    5 : "Result is a number but not an integer.",
	    5 : "Number1 or Number2 is a number but not an integer.",
	    20 : "Illegal arithmetic operation: Number2 is zero",
	    24 : "Number1 or Number2 is not of a numeric type.",
	    24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      X is 10 mod 3.		(gives X = 1)

      mod( 10,  3,  1).
      mod(-10,  3,  2).
      mod( 10, -3, -2).
      mod(-10, -3,  1).

      mod( 11,  3,  2).
Fail:
      mod(1, 2, 3).
Error:
      mod(A, 2, 6).              (Error 4).
      mod(6, 2.0, 3.0).          (Error 5).
      mod(2, 0, Result).         (Error 20).
      mod(4 + 2, 2, 12).         (Error 24).
      mod(5, 2, r).              (Error 24).
",
	see_also:[(is) / 2, (div)/3, (rem)/3]]).

:- comment((*) / 3, [
	summary:"Evaluates the product Number1 * Number2 and unifies the resulting value
with Result.

",
	amode:(*(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to *(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 * Number2
</PRE>
    which should be preferred for portability.
<P>
   The result is of type breal if any of the arguments is a breal,
   else float if any of the arguments is a float, else rational if any
   of the arguments is a rational.  Only when both arguments are
   integers is the result an integer.

<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to */3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "A number.", "Number2" : "A number.", "Result" : "A variable or a number."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is of a different type than the evaluation result.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      *(5, 2, 10).
      *(5, -2.0, -10.0).
Fail:
      *(1, 2, 3).
      *(5, 2, 10.0).
      *(5, 2.0, 10).
Error:
      *(A, 2, 6).             (Error 4).
      *(1, 2, 3.0).           (Error 5).
      *(4 + 2, 2, 12).        (Error 24).
      *(5, 2, r).             (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(gcd / 3, [
	summary:"Unifies Results with the Greatest Common Divisor of Number1 and Number2",
	amode:(gcd(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to gcd(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is gcd(Number1, Number2)
</PRE>
    which should be preferred for portability.
<P>
   The Greatest Common Divisor operation is only defined on integer arguments.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number1 or Number2 is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      gcd(9, 15, 3).
      gcd(-9, 15, 3).
      gcd(2358352782,97895234896224,X).  ( gives X = 6 )

Error:
      gcd(A, 2, 6).             (Error 4).
      gcd(1, 2, 3.0).           (Error 5).
      gcd(1.0, 2, 3.0).         (Error 5).
      gcd(4 + 2, 2, 12).        (Error 24).
",
	see_also:[lcm/3, (is) / 2]]).

:- comment(lcm / 3, [
	summary:"Unifies Results with the Least Common Multiple of Number1 and Number2",
	amode:(lcm(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to lcm(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is lcm(Number1, Number2)
</PRE>
    which should be preferred for portability.
<P>
   The Least Common Multiple operation is only defined on integer arguments.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number1 or Number2 is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      lcm(9, 15, 45).
      lcm(-9, 15, 45).
      lcm(2358352782,97895234896224,X).  ( gives X = 38478583260342225282528 )

Error:
      lcm(A, 2, 6).             (Error 4).
      lcm(1, 2, 3.0).           (Error 5).
      lcm(1.0, 2, 3.0).         (Error 5).
      lcm(4 + 2, 2, 12).        (Error 24).
",
	see_also:[gcd/3, (is) / 2]]).

:- comment((=\=) / 2, [
	summary:"Succeed if the value of Expr1 is not equal to the value of Expr2.

",
	template:"+Expr1 =\\= +Expr2",
	amode:((+ =\= +) is semidet),
	desc:html("   Both arguments are evaluated and their types adjusted.  Then the
   resulting numbers are compared.  The predicate succeeds if the values of
   Expr1 and Expr2 are not equal (beware of rounding errors when comparing
   floats).  If the system is in coroutining mode and the arguments are not
   ground, this predicate delays until the expressions are fully
   instantiated.
<P>
   The predicate also delays when the comparison involves bounded reals,
   and the compared values overlap such that the result is undecidable.

<P>
"),
	args:["Expr1" : "An arithmetic expression", "Expr2" : "An arithmetic expression"],
	fail_if:"fails if the value of Expr1 is equal to the value of Expr2",
	exceptions:[4 : "Expr1 or Expr2 is a variable (non-coroutining mode only).", 5 : "Expr1 or Expr2 is not an arithmetic expression."],
	eg:"
Success:
      5 - 1 =\\= 6 / 2.
      1 =\\= sin(pi/4).      % 1 converted to 1.0

Fail:
      2 + 4 =\\= 2 * 3.

Error:
      _ =\\= 10.              (Error 4)
      \"s\" =\\= 10.            (Error 5)



",
	see_also:[_:(=\=)/2, (is) / 2, (=:=) / 2, (>=) / 2, (<) / 2, (>) / 2, (=<) / 2]]).

:- comment((\/) / 3, [
	summary:"Evaluates the bitwise disjunction Number1 \\/ Number2 and unifies the
resulting value with Result.

",
	amode:(\/(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to \\/(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 \\/ Number2
</PRE>
   which should be preferred for portability.
<P>
   This operation behaves as if operating on an unlimited length two's
   complement representation.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to \\//3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number1 or Number2 is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      \\/(11, 7, 15).
      \\/(11, -7, Result).     (gives Result = -5)
Fail:
      \\/(1, 2, 4).
Error:
      \\/(A, 2, 6).              (Error 4).
      \\/(6, 2.0, 6.0).          (Error 5).
      \\/(4 + 2, 2, 6).          (Error 24).
      \\/(5, 2, r).              (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((+) / 3, [
	summary:"Evaluates the sum Number1 + Number2 and unifies the resulting value with
Result.

",
	amode:(+(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to +(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 + Number2
</PRE>
    which should be preferred for portability.
<P>
   The result is of type breal if any of the arguments is a breal,
   else float if any of the arguments is a float, else rational if any
   of the arguments is a rational.  Only when both arguments are
   integers is the result an integer.

<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to +/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "A number.", "Number2" : "A number.", "Result" : "A variable or a number."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is of a different type than the evaluation result.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      +(5, 2, 7).
      +(5, -2.0, 3.0).
Fail:
      +(1, 2, 7).
Error:
      +(A, 2, 6).             (Error 4).
      +(1, 2, 3.0).           (Error 5).
      +(7 - 4, 2, 3).         (Error 24).
      +(5, 2, r).             (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((^) / 3, [
	summary:"Evaluates the expression Number1 \"to the power of\" Number2 and unifies the
resulting value with Result.

",
	amode:(^(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to ^(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 ^ Number2
</PRE>
    which should be preferred for portability.
<P>
   The result is of type float if any of the arguments is a float. 
   When an integer is raised to the power of a negative integer, the
   result type depends on the value of the global flag prefer_rationals.
   If it is on, it is a rational, otherwise a float.  When the exponent
   is not an integer, the result is of type float.

<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to ^/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "A number.", "Number2" : "A number.", "Result" : "A variable or a number."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is of a different type than the evaluation result.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable.", 20 : "Illegal arithmetic operation:  Number1 is negative and    Number2 is no integral number.", 20 : "Illegal arithmetic operation:  Number1 and Number2 are both    zero."],
	eg:"
Success:
      ^(5, 3, 125).
      ^(-5, 3, -125).
      ^(5, -2, 0.04).
      ^(5, 2.2, 34.493244).
      ^(5.0, 2, 25.0).
Fail:
      ^(1, 2, 3).
Error:
      ^(A, 2, 6).             (Error 4).
      ^(1, 2, 3.0).           (Error 5).
      ^(-5, 0.5, X).          (Error 20).
      ^(2 + 3, 2, 25).        (Error 24).
      ^(5, 2, r).             (Error 24).



",
	see_also:[(is) / 2, get_flag / 2, set_flag / 2]]).

:- comment(round / 2, [
	summary:"Rounds Number to the nearest integral value of the same type",
	amode:(round(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to round(Number, Result) is
   equivalent to
<PRE>
    Result is round(Number)
</PRE>
    which should be preferred for portability.
<P>
   This operation works on all numeric types. The result value is the
   integral value that is closest to Number (rounding to nearest). If
   Number is exactly in the middle between two integers, the result
   is the even one.
<P>
   The result type is the same as the argument type.  To convert the
   type to integer, use integer/2.
<P>
   In coroutining mode, if Number is uninstantiated, the call to round/2
   is delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Number and Result are numbers of different type.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      round(1.49, 1.0).
      round(1.5, 2.0).          (odd integer part)
      round(2.5, 2.0).
      round(2.51, 3.0).         (even integer part)
      round(3.5, 4.0).
      round(-6.4, Result).      (gives Result = -6.0)
      round(3, 3).
Fail:
      round(1, 0.0).
Error:
      round(A, 6.0).                   (Error 4).
      round(0.5, 0).                   (Error 5).
      round(4 + 2.3, 6.0).             (Error 24).
      round(1, r).                     (Error 24).



",
	see_also:[(is) / 2, floor/2, ceiling/2, truncate/2, integer/2]]).

:- comment((<<) / 3, [
	summary:"Shifts Number1 left by Number2 bits and unifies the
resulting value with Result.

",
	amode:(<<(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to &lt;&lt;(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 &lt;&lt; Number2
</PRE>
    which should be preferred for portability.
<P>
   The shift behaves as if operating on an unlimited length two's complement
   representation.  Shifting by a negative amount is the same as shifting by
   the same positive amount in the other direction.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to &lt;&lt;/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number1 or Number2 is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      <<(1, 3, 8).
Fail:
      <<(1, 2, 3).
Error:
      <<(A, 2, 6).              (Error 4).
      <<(6, 2.0, 24.0).         (Error 5).
      <<(4 + 2, 2, 24).         (Error 24).
      <<(5, 2, r).              (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((>>) / 3, [
	summary:"Shifts Number1 right arithmetically by Number2 bits and unifies the
resulting value with Result.

",
	amode:(>>(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to &gt;&gt;(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is Number1 &gt;&gt; Number2
</PRE>
    which should be preferred for portability.
<P>
   The shift behaves as an arithmetic (signed) shift operating on an unlimited
   length two's complement representation.  Shifting by a negative amount is
   the same as shifting by the same positive amount in the other direction.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to &gt;&gt;/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number1 or Number2 is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      >>(8, 3, 1).
      >>(17, 3, X).          (gives X = 2)
Fail:
      >>(1, 2, 3).
Error:
      >>(A, 2, 6).              (Error 4).
      >>(16, 2.0, 4.0).         (Error 5).
      >>(4 + 12, 2, 4).         (Error 24).
      >>(5, 2, r).              (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(sin / 2, [
	summary:"Evaluates the trigonometric function sin(Number) and unifies the resulting
value with Result.

",
	amode:(sin(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to sin(Number, Result) is
   equivalent to
<PRE>
    Result is sin(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to sin/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable, float or breal."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      sin(1.5708, 1.0).
      sin(-1.5708, Result).     (gives Result = -1.0)
      sin(0, Result).           (gives Result = 0.0)
Fail:
      sin(1, 0.0).
Error:
      sin(A, 6.0).                   (Error 4).
      sin(6, 3).                     (Error 5).
      sin(4 + 2, -0.279415).         (Error 24).
      sin(5, r).                     (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(sqrt / 2, [
	summary:"Evaluates the square root sqrt(Number) and unifies the resulting value with
Result.

",
	amode:(sqrt(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to sqrt(Number, Result) is
   equivalent to
<PRE>
    Result is sqrt(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to sqrt/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable, float or breal."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable.", 20 : "Illegal arithmetic operation:  Number is negative."],
	eg:"
Success:
      sqrt(1.0, 1.0).
      sqrt(1.0, Result).      (gives Result = 1.0)
      sqrt(49, Result).       (gives Result = 7.0)
Fail:
      sqrt(1, 0.0).
Error:
      sqrt(A, 6.0).                   (Error 4).
      sqrt(1, 1).                     (Error 5).
      sqrt(-2, Result).               (Error 20).
      sqrt(4 + 2, 2.44949).           (Error 24).
      sqrt(1, r).                     (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(tan / 2, [
	summary:"Evaluates the trigonometric function tan(Number) and unifies the resulting
value with Result.

",
	amode:(tan(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to tan(Number, Result) is
   equivalent to
<PRE>
    Result is tan(Number)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number is uninstantiated, the call to tan/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable, float or breal."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result is a number but not a float or breal.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable.", 20 : "Illegal arithmetic operation:  Number is (2k +1) * pi/2 for    every integer k."],
	eg:"
Success:
      tan(0, 0.0).
      tan(12.3, Result).      (gives Result = -0.272854)
      tan(-1, Result).        (gives Result = -1.55741)
Fail:
      tan(1, 0.0).
Error:
      tan(A, 6.0).                      (Error 4).
      tan(0, 0).                        (Error 5).
      X is pi/2, tan(X, Result).        (Error 20).
      tan(10.3 + 2, -0.272854).         (Error 24).
      tan(5, r).                        (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((-) / 2, [
	summary:"Unifies the negative of Number with Result.

",
	amode:(-(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to -(Number, Result) is equivalent
   to
<PRE>
    Result is -Number
</PRE>
    which should be preferred for portability.
<P>
   Number and Result have to be of the same type.

<P>
   In coroutining mode, if Number is uninstantiated, the call to -/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or a number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result and Number are numbers of different types.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      -(1, -1).
      -(5, Result).        (gives Result = -5)
      -(-6.2, Result).     (gives Result = 6.2)
Fail:
      -(1, 0).
Error:
      -(A, 6).                   (Error 4).
      -(1, -1.0).                (Error 5).
      -(1.0, -1).                (Error 5).
      -(4 + 2, -6).              (Error 24).
      -(1, r).                   (Error 24).



",
	see_also:[(is) / 2]]).

:- comment((+) / 2, [
	summary:"Checks if Number is a number and unifies it with Result.

",
	amode:(+(+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to +(Number, Result) is equivalent
   to
<PRE>
    Result is +Number
</PRE>
    which should be preferred for portability.
<P>
   Number and Result have to be of the same type.

<P>
   In coroutining mode, if Number is uninstantiated, the call to +/2 is
   delayed until this variable is instantiated.

<P>
"),
	args:["Number" : "A number.", "Result" : "A variable or a number."],
	exceptions:[4 : "Number is not instantiated (non-coroutining mode only).", 5 : "Result and Number are numbers of different types.", 24 : "Number is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      +(1, 1).
      +(5, Result).        (gives Result = 5)
      +(-6.2, Result).     (gives Result = -6.2)
Fail:
      +(1, 0).
Error:
      +(A, 6).                   (Error 4).
      +(1.0, 1).                 (Error 5).
      +(1, 1.0).                 (Error 5).
      +(4 + 2, 6).               (Error 24).
      +(1, r).                   (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(xor / 3, [
	summary:"Evaluates the bitwise exclusive disjunction Number1 xor Number2 and unifies
the resulting value with Result.

",
	amode:(xor(+,+,-) is det),
	desc:html("   This predicate is used by the ECLiPSe compiler to expand evaluable
   arithmetic expressions.  So the call to xor(Number1, Number2, Result) is
   equivalent to
<PRE>
    Result is xor(Number1, Number2)
</PRE>
    which should be preferred for portability.
<P>
   In coroutining mode, if Number1 or Number2 are uninstantiated, the call
   to xor/3 is delayed until these variables are instantiated.

<P>
"),
	args:["Number1" : "Integer.", "Number2" : "Integer.", "Result" : "A variable or integer."],
	exceptions:[4 : "Number1 or Number2 is not instantiated (non-coroutining mode    only).", 5 : "Result is a number but not an integer.", 5 : "Number1 or Number2 is a number but not an integer.", 24 : "Number1 or Number2 is not of a numeric type.", 24 : "Result is neither a number nor a variable."],
	eg:"
Success:
      xor(11, 7, 12).
      xor(11, -7, Result).     (gives Result = -14)
Fail:
      xor(1, 2, 4).
Error:
      xor(A, 2, 6).              (Error 4).
      xor(6, 2.0, 4.0).          (Error 5).
      xor(4 + 2, 2, 4).          (Error 24).
      xor(5, 2, r).              (Error 24).



",
	see_also:[(is) / 2]]).

:- comment(random / 1, [
	summary:"Generates a random integer N.

",
	amode:(random(-) is det),
	desc:html("random/1 unifies N with a random integer between 0 and 2^31-1
   (returned by the C library function random(), whose initialization
   has been made using the pid of the running ECLiPSe ).

<P>
   If it is required that the sequence produced by successive calls of
   random/1 be reproducible, seed(Seed) can be called to initialise the
   calls with the integer Seed.

<P>
"),
	args:["N" : "Integer or Variable."],
	exceptions:[5 : "N is instantiated, but not to an integer."],
	eg:"
Success:
      [eclipse]: random(N1), random(N2).
      N1 = 464880439
      N2 = 285401533
      yes.

      [eclipse]: seed(1), random(N).
      N = 2078917053
      yes.
      [eclipse]: seed(1), random(N).
      N = 2078917053
      yes.

Fail:
      random(12345).

Error:
      random(12.34).          (Error 5).



",
	see_also:[frandom / 1, seed / 1]]).

:- comment(seed / 1, [
	summary:"Sets the initial seed Seed for generating random numbers with random/1 or
frandom/1.

",
	amode:(seed(+) is det),
	desc:html("   Used to initialise the seed which is used for the generation of random
   numbers by random/1 or frandom/1.  Setting the same seed value with
   seed/1 enables the generation of a repeatable random sequence with
   random/1 ie.  pseudo-random number generation.
<P>
   The seed value should be an integer in the range 1 .. 2^31-1.
<P>
"),
	args:["Seed" : "Integer."],
	exceptions:[4 : "Seed is not instantiated.", 5 : "Seed is instantiated, but not to an integer."],
	eg:"
Success:
      [eclipse]: repeat, random(S).
      S = 464880439   More? (;)
      S = 285401533   More? (;)
      yes.
      [eclipse]: seed(1), repeat, random(S).
      S = 2078917053   More? (;)
      S = 143302914   More? (;)
      yes.
      [eclipse]: seed(1), repeat, random(S).
      S = 2078917053   More? (;)
      S = 143302914   More? (;)
      yes.



",
	see_also:[random / 1]]).


:- comment(breal_min / 2, [
    summary:"Extracts the lower floating point bound of Number",
    amode:(breal_min(+,-) is det),
    desc:html("\
    This predicate is used by the ECLiPSe compiler to expand evaluable
    arithmetic expressions.  So a call to breal_min(Number, Result) is
    equivalent to
<PRE>
    Result is breal_min(Number).
</PRE>
    A bounded real is a real number represented by a lower and upper
    bound in floating point format. This predicate extracts the lower
    bound and unifies it with Result. If Number is not a bounded real,
    the result returned is equivalent to converting it to a bounded real
    first.
<P>
"),
    args:["Number" : "A number.",
	"Result" : "A variable or float."],
    exceptions:[4 : "Number is not instantiated",
	5 : "Number is a not a number.",
	5 : "Result is neither a variable nor a float."],
    eg:"
Success:
      ?- breal_min(0.99__1.01, X).
      X = 0.99

      ?- breal_min(1, X).
      X = 1.0

      ?- breal_min(1.0, X).
      X = 1.0

      ?- breal_min(1_10, X).
      X = 0.099999999999999992

Error:
      ?- breal_min(\"a\", Z).
      type error in breal_min(\"a\", Z)

      ?- breal_min(2 + 4, Z).
      type error in breal_min(2 + 4, Z)
",
	see_also:[breal_max/2, breal/1, breal/2, breal_bounds/3,
		breal_from_bounds/3, (is) / 2]]).


:- comment(breal_max / 2, [
    summary:"Extracts the upper floating point bound of Number",
    amode:(breal_max(+,-) is det),
    desc:html("\
    This predicate is used by the ECLiPSe compiler to expand evaluable
    arithmetic expressions.  So a call to breal_max(Number, Result) is
    equivalent to
<PRE>
    Result is breal_max(Number).
</PRE>
    A bounded real is a real number represented by a lower and upper
    bound in floating point format. This predicate extracts the upper
    bound and unifies it with Result. If Number is not a bounded real,
    the result returned is equivalent to converting it to a bounded real
    first.
<P>
"),
    args:["Number" : "A number.",
	"Result" : "A variable or float."],
    exceptions:[4 : "Number is not instantiated",
	5 : "Number is a not a number.",
	5 : "Result is neither a variable nor a float."],
    eg:"
Success:
      ?- breal_max(0.99__1.01, X).
      X = 1.01

      ?- breal_max(1, X).
      X = 1.0

      ?- breal_max(1.0, X).
      X = 1.0

      ?- breal_max(1_10, X).
      X = 0.10000000000000002

Error:
      ?- breal_max(\"a\", Z).
      type error in breal_max(\"a\", Z)

      ?- breal_max(2 + 4, Z).
      type error in breal_max(2 + 4, Z)
",
	see_also:[breal_min/2, breal/1, breal/2, breal_bounds/3,
		breal_from_bounds/3, (is) / 2]]).


:- comment(breal_bounds / 3, [
    summary:"Extracts lower and upper floating point bounds of Number",
    amode:(breal_bounds(+,-,-) is det),
    desc:html("\
    A bounded real is a real number represented by a lower and upper
    bound in floating point format. This predicate extracts both bounds
    and unifies them with Min and Max respectively. If Number is not a
    bounded real, the result returned is equivalent to converting it to
    a bounded real first.
"),
    args:["Number" : "A number.",
	"Min" : "A variable or float.",
	"Max" : "A variable or float."],
    exceptions:[4 : "Number is not instantiated",
	5 : "Number is a not a number.",
	5 : "Min is neither a variable nor a float.",
	5 : "Max is neither a variable nor a float."],
    eg:"
Success:
    ?- breal_bounds(0.99__1.01, Min, Max).
    Min = 0.99
    Max = 1.01

    ?- breal(1.0, One), breal_bounds(One, Min, Max).
    One = 1.0__1.0
    Min = 1.0
    Max = 1.0

    ?- breal(1, One), breal_bounds(One, Min, Max).
    One = 1.0__1.0
    Min = 1.0
    Max = 1.0

    ?- breal_bounds(1, Min, Max).
    Min = 1.0
    Max = 1.0

    ?- breal_bounds(1.0, Min, Max).
    Min = 1.0
    Max = 1.0

    ?- breal_bounds(1_10, Min, Max).
    Min = 0.099999999999999992
    Max = 0.10000000000000002

Error:
    ?- breal_bounds(\"a\", Min, Max).
    type error in breal_bounds(\"a\", Min, Max)

    ?- breal_bounds(2 + 4, Min, Max).
    type error in breal_bounds(2 + 4, Min, Max)
",
    see_also:[breal/1, breal/2, breal_min/2, breal_max/2,
	    breal_from_bounds/3, (is) / 2]]).


:- comment(breal / 2, [
    summary:"Converts Number into a breal number and unifies it with Result.",
    amode:(breal(+,-) is det),
    desc:html("\
    This predicate is used by the ECLiPSe compiler to expand evaluable
    arithmetic expressions.  So the call to breal(Number, Result) is
    equivalent to
<PRE>
    Result is breal(Number)
</PRE>
    which should be preferred.
"),
    args:["Number" : "A number.",
	"Result" : "A variable or bounded real number."],
    exceptions:[4 : "Number is not instantiated (non-coroutining mode only).",
    5 : "Result is a number but not of type breal.",
    24 : "Number is not of a numeric type.",
    24 : "Result is neither a number nor a variable."],
    eg:"
Success:
    ?- breal(25, X).
    X = 25.0__25.0

    ?- breal(1.5, X).
    X = 1.5__1.5

    ?- breal(3_4, X).
    X = 0.74999999999999989__0.75000000000000011

    ?- breal(1.0__1.01, X).
    X = 1.0__1.01

Fail:
    ?- breal(1.0, 1.0__1.0).
    No (0.00s cpu)

Error:
    ?- breal(A, X).
    instantiation fault in breal(A, X)

    ?- breal(3, 3).
    type error in breal(3, 3)

    ?- breal(1, r).
    number expected in breal(1, r)

    ?- breal(4 + 2, X).
    number expected in breal(4 + 2, X)
",
	see_also:[integer/2,float/2,rational/2,(is)/2, breal_min/2, breal_max/2,
		breal_bounds/3, breal_from_bounds/3, breal/1]]).


:- comment(breal_from_bounds / 3, [
    summary:"Constructs a bounded real from the given floating point bounds",
    amode:(breal_from_bounds(+,+,-) is det),
    desc:html("\
    This predicate is used by the ECLiPSe compiler to expand evaluable
    arithmetic expressions.  So a call to breal_from_bounds(Lo, Hi, Result)
    is equivalent to
<PRE>
    Result is breal_from_bounds(Lo, Hi).
</PRE>
    This predicate constructs a new bounded real number with the specified
    bounds. In effect, the bounds are first cast to bounded reals, and then
    the new bounded real is constructed from the lower bound of Lo and the
    upper bound of Hi.
<P>
"),
    args:["Lo" : "A number.",
	"Hi" : "A number.",
	"Result" : "A variable."],
    exceptions:[4 : "Lo or Hi are not instantiated.",
	5 : "Result is not a variable.",
	20 : "The lower bound of Lo is greater than the upper bound of Hi.",
	24 : "Lo or Hi are not numbers."],
    eg:"
Success:
      ?- breal_from_bounds(0.99, 1.01, X).
      X = 0.99__1.01

      ?- breal_from_bounds(1_3, 2_3, X).
      X = 0.33333333333333326__0.66666666666666674

Error:
      ?- breal_from_bounds(1, H, X).
      instantiation fault in breal_from_bounds(1, H, X)

      ?- breal_from_bounds(\"a\", 2.0, X).
      number expected in breal_from_bounds(\"a\", 2.0, X)

      ?- breal_from_bounds(2 + 4, 3 + 5, Z).
      number expected in breal_from_bounds(2 + 4, 3 + 5, Z)

      ?- breal_from_bounds(1.0, 2.0, 1.0__2.0).
      type error in breal_from_bounds(1.0, 2.0, 1.0__2.0)

      ?- breal_from_bounds(1.1, 0.9, X).
      arithmetic exception in breal_from_bounds(1.1, 0.9, X)
",
	see_also:[breal_min/2, breal_max/2, breal/1, breal/2, breal_bounds/3, (is) / 2]]).


