- Reference manual
- Built-in Predicates
- Notation of Predicate Descriptions
- Character representation
- Loading Prolog source files
- Editor Interface
- List the program, predicates or clauses
- Verify Type of a Term
- Comparison and Unification of Terms
- Control Predicates
- Meta-Call Predicates
- Delimited continuations
- Exception handling
- Handling signals
- DCG Grammar rules
- Declaring predicate properties
- Examining the program
- Input and output
- Status of streams
- Primitive character I/O
- Term reading and writing
- Analysing and Constructing Terms
- Analysing and Constructing Atoms
- Localization (locale) support
- Character properties
- Character Conversion
- Misc arithmetic support predicates
- Built-in list operations
- Finding all Solutions to a Goal
- Formatted Write
- Global variables
- Terminal Control
- Operating System Interaction
- File System Interaction
- User Top-level Manipulation
- Creating a Protocol of the User Interaction
- Debugging and Tracing Programs
- Obtaining Runtime Statistics
- Execution profiling
- Memory Management
- Windows DDE interface
- Built-in Predicates
- Reference manual
Arithmetic can be divided into some special purpose integer predicates and a series of general predicates for integer, floating point and rational arithmetic as appropriate. The general arithmetic predicates all handle expressions. An expression is either a simple number or a function. The arguments of a function are expressions. The functions are described in section 22.214.171.124.
The predicates in this section provide more logical operations between integers. They are not covered by the ISO standard, although they are `part of the community' and found as either library or built-in in many other Prolog systems.
- between(+Low, +High, ?Value)
- Low and High are integers, High >=Low.
Value is an integer, Low =<Value
=<High. When Value is a variable it is
successively bound to all integers between Low and High.
If High is
infinite, but some other Prolog systems already use
inffor infinity; we accept both for the time being. between/3 is true iff Value >=Low, a feature that is particularly interesting for generating integers from a certain value.
- succ(?Int1, ?Int2)
- True if Int2 = Int1 + 1 and Int1
>= 0. At least one of the arguments must be instantiated to a
natural number. This predicate raises the domain error
not_less_than_zeroif called with a negative integer. E.g.
succ(X, 0)fails silently and
succ(X, -1)raises a domain error.107The behaviour to deal with natural numbers only was defined by Richard O'Keefe to support the common count-down-to-zero in a natural way. Up to 5.1.8, succ/2 also accepted negative integers.
- plus(?Int1, ?Int2, ?Int3)
- True if Int3 = Int1 + Int2. At least two of the three arguments must be instantiated to integers.
- divmod(+Dividend, +Divisor, -Quotient, -Remainder)
- This predicate is a shorthand for computing both the Quotient
Remainder of two integers in a single operation. This allows
for exploiting the fact that the low level implementation for computing
the quotient also produces the remainder. Timing confirms that this
predicate is almost twice as fast as performing the steps independently.
is defined as below.
divmod(Dividend, Divisor, Quotient, Remainder) :- Quotient is Dividend div Divisor, Remainder is Dividend mod Divisor.
Note that this predicate is only available if SWI-Prolog is compiled with unbounded integer support. This is the case for all packaged versions.
- nth_integer_root_and_remainder(+N, +I, -Root, -Remainder)
- True when Root ** N + Remainder = I. N and I
must be integers.108This predicate
was suggested by Markus Triska. The final name and argument order is by
Richard O'Keefe. The decision to include the remainder is by Jan
Wielemaker. Including the remainder makes this predicate about twice as
slow if Root is not exact.
N must be one or more. If I is negative and
N is odd, Root and Remainder
are negative, i.e., the following holds for I < 0:
% I < 0, % N mod 2 =\= 0, nth_integer_root_and_remainder( N, I, Root, Remainder), IPos is -I, nth_integer_root_and_remainder( N, IPos, RootPos, RemainderPos), Root =:= -RootPos, Remainder =:= -RemainderPos.
The general arithmetic predicates are optionally compiled (see set_prolog_flag/2 and the -O command line option). Compiled arithmetic reduces global stack requirements and improves performance. Unfortunately compiled arithmetic cannot be traced, which is why it is optional.
- [ISO]+Expr1 > +Expr2
- True if expression Expr1 evaluates to a larger number than Expr2.
- [ISO]+Expr1 < +Expr2
- True if expression Expr1 evaluates to a smaller number than Expr2.
- [ISO]+Expr1 =< +Expr2
- True if expression Expr1 evaluates to a smaller or equal number to Expr2.
- [ISO]+Expr1 >= +Expr2
- True if expression Expr1 evaluates to a larger or equal number to Expr2.
- [ISO]+Expr1 =\= +Expr2
- True if expression Expr1 evaluates to a number non-equal to Expr2.
- [ISO]+Expr1 =:= +Expr2
- True if expression Expr1 evaluates to a number equal to Expr2.
- [ISO]-Number is +Expr
- True when Number is the value to which Expr
evaluates. Typically, is/2
should be used with unbound left operand. If equality is to be tested, =:=/2
should be used. For example:
?- 1 is sin(pi/2).
Fails! sin(pi/2) evaluates to the float 1.0, which does not unify with the integer 1.
?- 1 =:= sin(pi/2).
Succeeds as expected.
SWI-Prolog defines the following numeric types:
If SWI-Prolog is built using the GNU multiple precision arithmetic library (GMP), integer arithmetic is unbounded, which means that the size of integers is limited by available memory only. Without GMP, SWI-Prolog integers are 64-bits, regardless of the native integer size of the platform. The type of integer support can be detected using the Prolog flags bounded, min_integer and max_integer. As the use of GMP is default, most of the following descriptions assume unbounded integer arithmetic.
Internally, SWI-Prolog has three integer representations. Small integers (defined by the Prolog flag max_tagged_integer) are encoded directly. Larger integers are represented as 64-bit values on the global stack. Integers that do not fit in 64 bits are represented as serialised GNU MPZ structures on the global stack.
- rational number
Rational numbers (Q) are quotients of two integers. Rational arithmetic is only provided if GMP is used (see above). Rational numbers are currently not supported by a Prolog type. They are represented by the compound term
rdiv(N,M). Rational numbers that are returned from is/2 are canonical, which means M is positive and N and M have no common divisors. Rational numbers are introduced in the computation using the rational/1, rationalize/1 or the rdiv/2 (rational division) function. Using the same functor for rational division and for representing rational numbers allows for passing rational numbers between computations as well as for using format/3 for printing.
In the long term, it is likely that rational numbers will become atomic as well as a subtype of number. User code that creates or inspects the
rdiv(M,N)terms will not be portable to future versions. Rationals are created using one of the functions mentioned above and inspected using rational/3.
Floating point numbers are represented using the C type
double. On most of today's platforms these are 64-bit IEEE floating point numbers.
Arithmetic functions that require integer arguments accept, in addition to integers, rational numbers with (canonical) denominator `1'. If the required argument is a float the argument is converted to float. Note that conversion of integers to floating point numbers may raise an overflow exception. In all other cases, arguments are converted to the same type using the order below.
integer -> rational number -> floating point number
The use of rational numbers with unbounded integers allows for exact integer or fixed point arithmetic under addition, subtraction, multiplication and division. To exploit rational arithmetic rdiv/2 should be used instead of `/' and floating point numbers must be converted to rational using rational/1. Omitting the rational/1 on floats will convert a rational operand to float and continue the arithmetic using floating point numbers. Here are some examples.
|A is 2 rdiv 6||A = 1 rdiv 3|
|A is 4 rdiv 3 + 1||A = 7 rdiv 3|
|A is 4 rdiv 3 + 1.5||A = 2.83333|
|A is 4 rdiv 3 + rational(1.5)||A = 17 rdiv 6|
Note that floats cannot represent all decimal numbers exactly. The function rational/1 creates an exact equivalent of the float, while rationalize/1 creates a rational number that is within the float rounding error from the original float. Please check the documentation of these functions for details and examples.
Rational numbers can be printed as decimal numbers with arbitrary precision using the format/3 floating point conversion:
?- A is 4 rdiv 3 + rational(1.5), format('~50f~n', [A]). 2.83333333333333333333333333333333333333333333333333 A = 17 rdiv 6
Arithmetic functions are terms which are evaluated by the arithmetic predicates described in section 4.27.2. There are four types of arguments to functions:
|Expr||Arbitrary expression, returning either a floating point value or an integer.|
|IntExpr||Arbitrary expression that must evaluate to an integer.|
|RatExpr||Arbitrary expression that must evaluate to a rational number.|
|FloatExpr||Arbitrary expression that must evaluate to a floating point.|
For systems using bounded integer arithmetic (default is unbounded, see section 126.96.36.199 for details), integer operations that would cause overflow automatically convert to floating point arithmetic.
SWI-Prolog provides many extensions to the set of floating point functions defined by the ISO standard. The current policy is to provide such functions on `as-needed' basis if the function is widely supported elsewhere and notably if it is part of the C99 mathematical library. In addition, we try to maintain compatibility with YAP.
- [ISO]- +Expr
- Result = -Expr
- [ISO]+ +Expr
- Result = Expr. Note that if
is followed by a number, the parser discards the
- [ISO]+Expr1 + +Expr2
- Result = Expr1 + Expr2
- [ISO]+Expr1 - +Expr2
- Result = Expr1 - Expr2
- [ISO]+Expr1 * +Expr2
- Result = Expr1 × Expr2
- [ISO]+Expr1 / +Expr2
- Result = Expr1/Expr2. If the
flag iso is
true, both arguments are converted to float and the return value is a float. Otherwise (default), if both arguments are integers the operation returns an integer if the division is exact. If at least one of the arguments is rational and the other argument is integer, the operation returns a rational number. In all other cases the return value is a float. See also ///2 and rdiv/2.
- [ISO]+IntExpr1 mod +IntExpr2
- Modulo, defined as Result = IntExpr1 - (IntExpr1
div IntExpr2) × IntExpr2, where
divis floored division.
- [ISO]+IntExpr1 rem +IntExpr2
- Remainder of integer division. Behaves as if defined by Result is IntExpr1 - (IntExpr1 // IntExpr2) × IntExpr2
- [ISO]+IntExpr1 // +IntExpr2
- Integer division, defined as Result is rnd_I(Expr1/Expr2)
. The function rnd_I is the default rounding used by the C
compiler and available through the Prolog flag
In the C99 standard, C-rounding is defined as
towards_zero.109Future versions might guarantee rounding towards zero.
- [ISO]div(+IntExpr1, +IntExpr2)
- Integer division, defined as Result is (IntExpr1 - IntExpr1 mod IntExpr2)
// IntExpr2. In other words, this is integer division that
rounds towards -infinity. This function guarantees behaviour that is
mod/2, i.e., the
following holds for every pair of integers
Y =\= 0.
Q is div(X, Y), M is mod(X, Y), X =:= Y*Q+M.
- +RatExpr rdiv +RatExpr
- Rational number division. This function is only available if SWI-Prolog has been compiled with rational number support. See section 188.8.131.52 for details.
- +IntExpr1 gcd +IntExpr2
- Result is the greatest common divisor of IntExpr1, IntExpr2.
- Evaluate Expr and return the absolute value of it.
- Evaluate to -1 if Expr < 0, 1 if Expr > 0 and 0 if Expr = 0. If Expr evaluates to a float, the return value is a float (e.g., -1.0, 0.0 or 1.0). In particular, note that sign(-0.0) evaluates to 0.0. See also copysign/2
- [ISO]copysign(+Expr1, +Expr2)
- Evaluate to X, where the absolute value of X equals the absolute value of Expr1 and the sign of X matches the sign of Expr2. This function is based on copysign() from C99, which works on double precision floats and deals with handling the sign of special floating point values such as -0.0. Our implementation follows C99 if both arguments are floats. Otherwise, copysign/2 evaluates to Expr1 if the sign of both expressions matches or -Expr1 if the signs do not match. Here, we use the extended notion of signs for floating point numbers, where the sign of -0.0 and other special floats is negative.
- [ISO]max(+Expr1, +Expr2)
- Evaluate to the larger of Expr1 and Expr2. Both arguments are compared after converting to the same type, but the return value is in the original type. For example, max(2.5, 3) compares the two values after converting to float, but returns the integer 3.
- [ISO]min(+Expr1, +Expr2)
- Evaluate to the smaller of Expr1 and Expr2. See max/2 for a description of type handling.
- A list of one element evaluates to the element. This implies
"a"evaluates to the character code of the letter `a' (97) using the traditional mapping of double quoted string to a list of character codes. Arithmetic evaluation also translates a string object (see section 5.2) of one character length into the character code for that character. This implies that expression
"a"also works of the Prolog flag double_quotes is set to
string. The recommended way to specify the character code of the letter `a' is
- Evaluate to a random integer i for which 0 =< i < IntExpr.
The system has two implementations. If it is compiled with support for
unbounded arithmetic (default) it uses the GMP library random functions.
In this case, each thread keeps its own random state. The default
algorithm is the Mersenne Twister algorithm. The seed is set
when the first random number in a thread is generated. If available, it
is set from
/dev/random.110On Windows the state is initialised from CryptGenRandom(). Otherwise it is set from the system clock. If unbounded arithmetic is not supported, random numbers are shared between threads and the seed is initialised from the clock when SWI-Prolog was started. The predicate set_random/1 can be used to control the random number generator.
Warning! Although properly seeded (if supported on the OS), the Mersenne Twister algorithm does not produce cryptographically secure random numbers. To generate cryptographically secure random numbers, use crypto_n_random_bytes/2 from library
library(crypto)provided by the
- Evaluate to a random float I for which 0.0 < i < 1.0. This function shares the random state with random/1. All remarks with the function random/1 also apply for random_float/0. Note that both sides of the domain are open. This avoids evaluation errors on, e.g., log/1 or //2 while no practical application can expect 0.0.111Richard O'Keefe said: ``If you are generating IEEE doubles with the claimed uniformity, then 0 has a 1 in 2^53 = 1 in 9,007,199,254,740,992 chance of turning up. No program that expects [0.0,1.0) is going to be surprised when 0.0 fails to turn up in a few millions of millions of trials, now is it? But a program that expects (0.0,1.0) could be devastated if 0.0 did turn up.''
- Evaluate Expr and round the result to the nearest integer.
According to ISO, round/1
is defined as
floor(Expr+1/2), i.e., rounding down. This is an unconventional choice and under which the relation
round(Expr) == -round(-Expr)does not hold. SWI-Prolog rounds outward, e.g.,
round(1.5) =:= 2and round
round(-1.5) =:= -2.
- Same as round/1 (backward compatibility).
- Translate the result to a floating point number. Normally, Prolog will use integers whenever possible. When used around the 2nd argument of is/2, the result will be returned as a floating point number. In other contexts, the operation has no effect.
- Convert the Expr to a rational number or integer. The
function returns the input on integers and rational numbers. For
floating point numbers, the returned rational number exactly
represents the float. As floats cannot exactly represent all decimal
numbers the results may be surprising. In the examples below, doubles
can represent 0.25 and the result is as expected, in contrast to the
rational(0.1). The function rationalize/1 remedies this. See section 184.108.40.206 for more information on rational number support.
?- A is rational(0.25). A is 1 rdiv 4 ?- A is rational(0.1). A = 3602879701896397 rdiv 36028797018963968
- Convert the Expr to a rational number or integer. The
function is similar to rational/1,
but the result is only accurate within the rounding error of floating
point numbers, generally producing a much smaller denominator.112The
as well as their semantics are inspired by Common Lisp.
?- A is rationalize(0.25). A = 1 rdiv 4 ?- A is rationalize(0.1). A = 1 rdiv 10
- Fractional part of a floating point number. Negative if Expr is negative, rational if Expr is rational and 0 if Expr is integer. The following relation is always true: X is float_fractional_part(X) + float_integer_part(X).
- Integer part of floating point number. Negative if Expr is negative, Expr if Expr is integer.
- Truncate Expr to an integer. If Expr >= 0
this is the same as
floor(Expr). For Expr < 0 this is the same as
ceil(Expr). That is, truncate/1 rounds towards zero.
- Evaluate Expr and return the largest integer smaller or equal to the result of the evaluation.
- Evaluate Expr and return the smallest integer larger or equal to the result of the evaluation.
- Same as ceiling/1 (backward compatibility).
- [ISO]+IntExpr1 >> +IntExpr2
- Bitwise shift IntExpr1 by IntExpr2 bits to the right. The operation performs arithmetic shift, which implies that the inserted most significant bits are copies of the original most significant bits.
- [ISO]+IntExpr1 << +IntExpr2
- Bitwise shift IntExpr1 by IntExpr2 bits to the left.
- [ISO]+IntExpr1 \/ +IntExpr2
- Bitwise `or' IntExpr1 and IntExpr2.
- [ISO]+IntExpr1 /\ +IntExpr2
- Bitwise `and' IntExpr1 and IntExpr2.
- [ISO]+IntExpr1 xor +IntExpr2
- Bitwise `exclusive or' IntExpr1 and IntExpr2.
- [ISO]\ +IntExpr
- Bitwise negation. The returned value is the one's complement of IntExpr.
- Result = sqrt(Expr)
- Result = sin(Expr). Expr is the angle in radians.
- Result = cos(Expr). Expr is the angle in radians.
- Result = tan(Expr). Expr is the angle in radians.
- Result = arcsin(Expr). Result is the angle in radians.
- Result = arccos(Expr). Result is the angle in radians.
- Result = arctan(Expr). Result is the angle in radians.
- [ISO]atan2(+YExpr, +XExpr)
- Result = arctan(YExpr/XExpr). Result
is the angle in radians. The return value is in the range [- pi ...
pi ]. Used to convert between rectangular and polar coordinate
Note that the ISO Prolog standard demands
atan2(0.0,0.0)to raise an evaluation error, whereas the C99 and POSIX standards demand this to evaluate to 0.0. SWI-Prolog follows C99 and POSIX.
- atan(+YExpr, +XExpr)
- Same as atan2/2 (backward compatibility).
- Result = sinh(Expr). The hyperbolic sine of X is defined as e ** X - e ** -X / 2.
- Result = cosh(Expr). The hyperbolic cosine of X is defined as e ** X + e ** -X / 2.
- Result = tanh(Expr). The hyperbolic tangent of X is defined as sinh( X ) / cosh( X ).
- Result = arcsinh(Expr) (inverse hyperbolic sine).
- Result = arccosh(Expr) (inverse hyperbolic cosine).
- Result = arctanh(Expr). (inverse hyperbolic tangent).
- Natural logarithm. Result = ln(Expr)
- Base-10 logarithm. Result = log10(Expr)
- Result = e **Expr
- [ISO]+Expr1 ** +Expr2
- Result = Expr1**Expr2. The
result is a float, unless SWI-Prolog is compiled with unbounded integer
support and the inputs are integers and produce an integer result. The
integer expressions 0 ** I, 1 ** I and -1 **
I are guaranteed to work for any integer I. Other
integer base values generate a
resourceerror if the result does not fit in memory.
The ISO standard demands a float result for all inputs and introduces ^/2 for integer exponentiation. The function float/1 can be used on one or both arguments to force a floating point result. Note that casting the input result in a floating point computation, while casting the output performs integer exponentiation followed by a conversion to float.
- [ISO]+Expr1 ^ +Expr2
- In SWI-Prolog, ^/2 is
equivalent to **/2. The
ISO version is similar, except that it produces a evaluation error if
Expr1 and Expr2 are integers and the result is not
an integer. The table below illustrates the behaviour of the
exponentiation functions in ISO and SWI.
Expr1 Expr2 Function SWI ISO Int Int **/2 Int or Float Float Int Float **/2 Float Float Rational Int **/2 Rational - Float Int **/2 Float Float Float Float **/2 Float Float Int Int ^/2 Int or Float Int or error Int Float ^/2 Float Float Rational Int ^/2 Rational - Float Int ^/2 Float Float Float Float ^/2 Float Float
- powm(+IntExprBase, +IntExprExp, +IntExprMod)
- Result = (IntExprBase**IntExprExp) modulo IntExprMod. Only available when compiled with unbounded integer support. This formula is required for Diffie-Hellman key-exchange, a technique where two parties can establish a secret key over a public network. IntExprBase and IntExprExp must be non-negative (>=0), IntExprMod must be positive (>0).113The underlying GMP mpz_powm() function allows negative values under some conditions. As the conditions are expensive to pre-compute, error handling from GMP is non-trivial and negative values are not needed for Diffie-Hellman key-exchange we do not support these.
- Return the natural logarithm of the absolute value of the Gamma function.114Some interfaces also provide the sign of the Gamma function. We canot do that in an arithmetic function. Future versions may provide a predicate lgamma/3 that returns both the value and the sign.
- WikipediA: ``In mathematics, the error function (also called the Gauss error function) is a special function (non-elementary) of sigmoid shape which occurs in probability, statistics and partial differential equations.''
- WikipediA: ``The complementary error function.''
- Evaluate to the mathematical constant pi (3.14159 ... ).
- Evaluate to the mathematical constant e (2.71828 ... ).
- Evaluate to the difference between the float 1.0 and the first larger floating point number.
- Evaluate to positive infinity. See section 220.127.116.11. This value can be negated using -/1.
- Evaluate to Not a Number. See section 18.104.22.168.
- Evaluate to a floating point number expressing the CPU time (in seconds) used by Prolog up till now. See also statistics/2 and time/1.
- Evaluate Expr. Although ISO standard dictates that `A=1+2, B is A' works and unifies B to 3, it is widely felt that source level variables in arithmetic expressions should have been limited to numbers. In this view the eval function can be used to evaluate arbitrary expressions.115The eval/1 function was first introduced by ECLiPSe and is under consideration for YAP.
The functions below are not covered by the standard. The
msb/1 function also
appears in hProlog and SICStus Prolog. The getbit/2
function also appears in ECLiPSe, which also provides
clrbit(Vector,Index). The others are SWI-Prolog
extensions that improve handling of ---unbounded--- integers as
- Return the largest integer N such that
(IntExpr >> N) /\ 1 =:= 1. This is the (zero-origin) index of the most significant 1 bit in the value of IntExpr, which must evaluate to a positive integer. Errors for 0, negative integers, and non-integers.
- Return the smallest integer N such that
(IntExpr >> N) /\ 1 =:= 1. This is the (zero-origin) index of the least significant 1 bit in the value of IntExpr, which must evaluate to a positive integer. Errors for 0, negative integers, and non-integers.
- Return the number of 1s in the binary representation of the non-negative integer IntExpr.
- getbit(+IntExprV, +IntExprI)
- Evaluates to the bit value (0 or 1) of the IntExprI-th bit of
IntExprV. Both arguments must evaluate to non-negative
integers. The result is equivalent to
(IntExprV >> IntExprI)/\1, but more efficient because materialization of the shifted value is avoided. Future versions will optimise
(IntExprV >> IntExprI)/\1to a call to getbit/2, providing both portability and performance.116This issue was fiercely debated at the ISO standard mailinglist. The name getbit was selected for compatibility with ECLiPSe, the only system providing this support. Richard O'Keefe disliked the name and argued that efficient handling of the above implementation is the best choice for this functionality.