Builtin predicates - Arithmetic and string operations

Predicates and functions in this group are used to perform arithmetic and string operations. String operations are further subdivided into operations on UTF-8 character strings, and operations on strings of raw bytes.

Predicates: is/2, (=:=)/2, (=!=)/2, (<)/2, (<=)/2, (>)/2, (>=)/2, atom_name/2, fperror/1, isnan/1, isinf/1, randomize/0, randomize/1

Mathematical operators: (+)/2, (-)/1, (-)/2, (*)/2, (/)/2, (%)/2, (**)/2, mod/2, rem/2

Mathematical functions: abs/1, ceil/1, exp/1, float_fractional_part/1, float_integer_part/1, floor/1, log/1, pow/2, round/1, sign/1, sqrt/1, truncate/1

Mathematical constants: e/0, inf/0, nan/0, pi/0

Trigonometric functions: acos/1, asin/1, atan/1, atan2/2, cos/1, sin/1, tan/1

Bitwise operators: (/\)/2, (\/)/2, (^)/2, (~)/2, (<<)/2, (>>)/2, (>>>)/2

Type conversion functions: float/1, integer/1, string/1, string/2

UTF-8 string functions: char/2, char_to_string/1, left/2, length/1, mid/2, mid/3, right/2

Byte string functions: byte/2, byte_to_string/1, left_bytes/2, length_bytes/1, mid_bytes/2, mid_bytes/3, right_bytes/2

Random number generation: random/0

is/2 - unifies the result of an arithmetic expression with a variable.

Usage
Var is Expr
Description
Expr is evaluated as an arithmetic expression and the result is unified with Var. Expressions are evaluated as follows:
Errors
Examples
 X is Y + 1
 S is sin(Angle * pi / 180)
Compatibility
Evaluation and error reporting are mostly compatible with Standard Prolog. Floating-point exceptions such as overflow and divide-by-zero are not reported as thrown errors; use fperror/1 instead.
See Also
(=:=)/2, (::=)/2, fperror/1
(=:=)/2 - arithmetic equality.

Usage
Expr1 =:= Expr2
Description
Expr1 and Expr2 are evaluated as described in the documentation for is/2. If the two values are identical, then Expr1 =:= Expr2 succeeds. Otherwise, Expr1 =:= Expr2 fails.
If one of Expr1 or Expr2 evaluates to an integer and the other evaluates to a floating-point value, then both will be converted into floating-point values prior to comparison. Strings are compared for identity.
Errors
Same as for is/2.
Examples
 2 + 4 =:= 6
 1.5 =:= 3.0 / 2
 "foo" + "bar" =:= "foobar"
Compatibility
Compatible with Standard Prolog for integer and floating-point comparisons. String comparisons are a Plang extension.
See Also
is/2, (=!=)/2, (<)/2, (<=)/2, (>)/2, (>=)/2
(=!=)/2, (=\=)/2 - arithmetic inequality.

Usage
Expr1 =!= Expr2
Expr1 =\= Expr2
Description
Expr1 and Expr2 are evaluated as described in the documentation for is/2. If the two values are not identical, then Expr1 =!= Expr2 succeeds. Otherwise, Expr1 =!= Expr2 fails.
If one of Expr1 or Expr2 evaluates to an integer and the other evaluates to a floating-point value, then both will be converted into floating-point values prior to comparison. Strings are compared for non-identity.
Errors
Same as for is/2.
Examples
 2 + 2 =!= 5
 1.5 =!= 3.0 * 2
 "foo" + "ba" =!= "foobar"
Compatibility
The (=\=)/2 predicate is compatible with Standard Prolog. The new name (=!=)/2 is the recommended spelling. String comparisons are a Plang extension.
See Also
is/2, (=:=)/2, (<)/2, (<=)/2, (>)/2, (>=)/2
(<)/2 - arithmetic less than comparison.

Usage
Expr1 < Expr2
Description
Expr1 and Expr2 are evaluated as described in the documentation for is/2. If the value of Expr1 is less than the value of Expr2, then Expr1 < Expr2 succeeds. Otherwise, Expr1 < Expr2 fails.
If one of Expr1 or Expr2 evaluates to an integer and the other evaluates to a floating-point value, then both will be converted into floating-point values prior to comparison. Strings, which may contain embedded NUL's, are compared using the C function memcmp().
Errors
Same as for is/2.
Examples
 2 + 2 < 5
 1.5 < 3.0 * 2
 "foo" + "ba" < "foobar"
Compatibility
Compatible with Standard Prolog for integer and floating-point comparisons. String comparisons are a Plang extension.
See Also
is/2, (=:=)/2, (=!=)/2, (<=)/2, (>)/2, (>=)/2
(<=)/2, (=<)/2 - arithmetic less than or equal comparison.

Usage
Expr1 <= Expr2
Expr1 =< Expr2
Description
Expr1 and Expr2 are evaluated as described in the documentation for is/2. If the value of Expr1 is less than or equal to the value of Expr2, then Expr1 <= Expr2 succeeds. Otherwise, Expr1 <= Expr2 fails.
If one of Expr1 or Expr2 evaluates to an integer and the other evaluates to a floating-point value, then both will be converted into floating-point values prior to comparison. Strings, which may contain embedded NUL's, are compared using the C function memcmp().
Errors
Same as for is/2.
Examples
 2 + 2 <= 4
 1.5 <= 3.0 * 2
 1.5 <= 3.0 * 0.5
 "foo" + "ba" <= "foobar"
Compatibility
The (=<)/2 predicate is compatible with Standard Prolog. The new name (<=)/2 is the recommended spelling. String comparisons are a Plang extension.
See Also
is/2, (=:=)/2, (=!=)/2, (<)/2, (>)/2, (>=)/2
(>)/2 - arithmetic greater than comparison.

Usage
Expr1 > Expr2
Description
Expr1 and Expr2 are evaluated as described in the documentation for is/2. If the value of Expr1 is greater than the value of Expr2, then Expr1 > Expr2 succeeds. Otherwise, Expr1 > Expr2 fails.
If one of Expr1 or Expr2 evaluates to an integer and the other evaluates to a floating-point value, then both will be converted into floating-point values prior to comparison. Strings, which may contain embedded NUL's, are compared using the C function memcmp().
Errors
Same as for is/2.
Examples
 2 + 2 > 3
 3.0 * 2 > 1.5
 "foobar" > "foo" + "ba"
Compatibility
Compatible with Standard Prolog for integer and floating-point comparisons. String comparisons are a Plang extension.
See Also
is/2, (=:=)/2, (=!=)/2, (<)/2, (<=)/2, (>=)/2
(>=)/2 - arithmetic greater than or equal comparison.

Usage
Expr1 >= Expr2
Description
Expr1 and Expr2 are evaluated as described in the documentation for is/2. If the value of Expr1 is greater than or equal to the value of Expr2, then Expr1 >= Expr2 succeeds. Otherwise, Expr1 >= Expr2 fails.
If one of Expr1 or Expr2 evaluates to an integer and the other evaluates to a floating-point value, then both will be converted into floating-point values prior to comparison. Strings, which may contain embedded NUL's, are compared using the C function memcmp().
Errors
Same as for is/2.
Examples
 2 + 2 >= 4
 3.0 * 0.5 >= 1.5
 "foobar" >= "foo" + "ba"
Compatibility
Compatible with Standard Prolog for integer and floating-point comparisons. String comparisons are a Plang extension.
See Also
is/2, (=:=)/2, (=!=)/2, (<)/2, (<=)/2, (>)/2
atom_name/2 - converts between atoms and strings.

Usage
atom_name(Atom, String)
Description
If Atom is an atom, then unifies String with the name of Atom.
If Atom is a variable and String is a string, then unifies Atom with the atom whose name is String.
Errors
Examples
 atom_name(foobar, S)         sets S to "foobar"
 atom_name('hi there!', S)    sets S to "hi there!"
 atom_name(A, "foobar")       sets A to foobar
 atom_name(A, "")             sets A to ''
 atom_name(foobar, "barfoo")  fails
 atom_name(A, S)              instantiation_error
 atom_name(1.5, S)            type_error(atom, 1.5)
 atom_name(A, foobar)         type_error(string, foobar)
See Also
char/2
fperror/1 - floating-point exception handling.

Usage
fperror(Type)
Description
If Type is the atom clear, then clear all of the floating-point exception flags in the system and succeed. Otherwise, test for a specific floating-point exception and succeed if it is present. If Type is not recognized, or the exception has not been raised, then fperror(Type) fails.
  • inexact - result could not be represented exactly.
  • overflow - overflow occurred.
  • undefined - result was undefined (not-a-number).
  • underflow - underflow occurred.
  • zero_divisor - division by zero.
Note: fperror/1 relies upon the presence of the C99 floating-point exception functions feclearexcept() and fetestexcept(). If these functions are not present, then fperror/1 will succeed for clear and fail for all other arguments. The isnan/1 and isinf/1 predicates may be used to detect certain error conditions.
Errors
Examples
 fperror(clear);
 X is Y / Z;
 if (fperror(zero_divisor))
     stderr::writeln("division by zero occurred");
See Also
is/2, isnan/1, isinf/1
isnan/1 - test an arithmetic value for not-a-number.

Usage
isnan(Expr)
Description
Expr is as described in the documentation for is/2. If the value of Expr is the IEEE not-a-number indicator, then isnan(Expr) succeeds. Otherwise, isnan(Expr) fails.
Errors
Same as for is/2.
Examples
 isnan(nan)               succeeds
 isnan(float("nan"))      succeeds
 isnan(3)                 fails
 isnan(inf)               fails
 isnan("nan")             type_error(number, "nan")
See Also
is/2, isinf/1, nan/0, fperror/1
isinf/1 - test an arithmetic value for infinity.

Usage
isinf(Expr)
Description
Expr is as described in the documentation for is/2. If the value of Expr is an IEEE infinity indicator, then isinf(Expr) succeeds. Otherwise, isinf(Expr) fails.
Errors
Same as for is/2.
Examples
 isinf(inf)               succeeds
 isinf(-inf)              succeeds
 isinf(float("inf"))      succeeds
 isinf(float("-inf"))     succeeds
 isinf(3)                 fails
 isinf(nan)               fails
 isinf("inf")             type_error(number, "inf")
 isinf(X); X < 0          checks for negative infinity
 isinf(X); X > 0          checks for positive infinity
See Also
is/2, isnan/1, inf/0, fperror/1
randomize/0, randomize/1 - seed the random number generator.

Usage
randomize
randomize(Value)
Description
The randomize/0 predicate seeds the random number generator with indeterminate information from the operating system environment (e.g. current time of day). This version should be used if different results are desired each time the application is run.
The randomize/1 predicate seeds the random number generator based on the specified integer or floating-point Value. This version should be used to generate a repeatable sequence of random numbers each time the application is run.
Errors
Examples
 randomize
 randomize(42)
See Also
random/0
(+)/2 - addition of two arithmetic terms.

Usage
Var is Expr1 + Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value Expr1 + Expr2. If both are numbers (integers or floating-point), then the result is the floating-point value Expr1 + Expr2. If both are strings, then the result is the concatenation of Expr1 and Expr2.
Errors
Examples
 X is 2 + 2               sets X to the integer value 4
 X is 1.5 + 3             sets X to the floating-point value 4.5
 X is "foo" + "bar"       sets X to the string "foobar"
 X is 1 + "foo"           type_error(number, "foo")
 X is "foo" + 1           type_error(string, 1)
 X is "foo" + string(1)   sets X to the string "foo1"
Compatibility
The (+)/2 function is compatible with Standard Prolog for integer and floating-point arguments. String concatenation is a Plang extension.
See Also
(-)/1, (-)/2, (*)/2, (/)/2, (%)/2
(-)/1 - negation of an arithmetic term.

Usage
Var is - Expr
Description
Evaluates Expr. If the result is an integer, then the result is the integer value - Expr. If the result is a floating-point number, then the result is the floating-point value - Expr.
Note: integer and floating-point constants that start with "-" will be recognized as negative numbers by the parser if there is no space between the "-" and the digits. If there is a space, then a term with (-)/1 as its functor will be created. Thus, -2 == - 2 will fail, but -2 =:= - 2 will succeed.
Errors
Examples
 X is - 2                 sets X to the integer value -2
 X is - 1.5               sets X to the floating-point value -1.5
 X is - "foo"             type_error(number, "foo")
 X is --2                 sets X to the integer value 2
Compatibility
Standard Prolog
See Also
(+)/2, (-)/2, (*)/2, (/)/2, (%)/2, abs/1
(-)/2 - subtraction of two arithmetic terms.

Usage
Var is Expr1 - Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value Expr1 - Expr2. If both are numbers (integers or floating-point), then the result is the floating-point value Expr1 - Expr2.
Errors
Examples
 X is 2 - 2               sets X to the integer value 0
 X is 1.5 - 3             sets X to the floating-point value -1.5
 X is 1 - "foo"           type_error(number, "foo")
 X is "foo" - 1           type_error(number, "foo")
Compatibility
Standard Prolog
See Also
(+)/2, (-)/1, (*)/2, (/)/2, (%)/2
(*)/2 - multiplication of two arithmetic terms.

Usage
Var is Expr1 * Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value Expr1 * Expr2. If both are numbers (integers or floating-point), then the result is the floating-point value Expr1 * Expr2.
Errors
Examples
 X is 2 * 2               sets X to the integer value 4
 X is 1.5 * 3             sets X to the floating-point value 4.5
 X is 1 * "foo"           type_error(number, "foo")
 X is "foo" * 1           type_error(number, "foo")
Compatibility
Standard Prolog
See Also
(+)/2, (-)/1, (-)/2, (/)/2, (%)/2
(/)/2 - division of two arithmetic terms.

Usage
Var is Expr1 / Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value Expr1 / Expr2. If both are numbers (integers or floating-point), then the result is the floating-point value Expr1 / Expr2.
Errors
Examples
 X is 2 / 2               sets X to the integer value 1
 X is 1.5 / 3             sets X to the floating-point value 0.5
 X is 1 / "foo"           type_error(number, "foo")
 X is "foo" / 1           type_error(number, "foo")
 X is 42 / 0              evaluation_error(zero_divisor)
 X is 42 / 0.0            sets X to positive infinity
 X is 0.0 / 0.0           sets X to not-a-number
Compatibility
The (/)/2 function is part of Standard Prolog, but it has a slightly different interpretation when mixing integer and floating-point values. In Standard Prolog, (/)/2 always produces a floating-point result, even if both arguments are integers. Standard Prolog has a separate (//)/2 function for integer division. The Standard Prolog forms can be translated into Plang using explicit type conversions: 
 X is Y / Z               X is float(Y) / float(Z)
 X is Y // Z              X is integer(Y) / integer(Z)
See Also
(+)/2, (-)/1, (-)/2, (*)/2, (%)/2
(%)/2, mod/2 - modulus of dividing two arithmetic terms.

Usage
Var is Expr1 % Expr2
Var is Expr1 mod Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value Expr1 % Expr2. If both are numbers (integers or floating-point), then the result is the floating-point value fmod(Expr1, Expr2).
The floating-point modulus uses the C function fmod(). For the IEEE remainder, use remainder/2.
Errors
Examples
 X is 2 % 2               sets X to the integer value 0
 X is 3 % 2               sets X to the integer value 1
 X is 1.5 % 3             sets X to the floating-point value 1.5
 X is 1 % "foo"           type_error(number, "foo")
 X is "foo" % 1           type_error(number, "foo")
 X is 42 % 0              evaluation_error(zero_divisor)
 X is 42 % 0.0            sets X to not-a-number
Compatibility
The mod/2 function is from Standard Prolog. The new name (%)/2 is the recommended spelling. In Standard Prolog, mod/2 only works on integer values. Plang extends the definition to floating-point.
See Also
(+)/2, (-)/1, (-)/2, (*)/2, (/)/2, remainder/2
rem/2 - IEEE remainder of dividing two arithmetic terms.

Usage
Var is Expr1 rem Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value Expr1 % Expr2. If both are numbers (integers or floating-point), then the result is the floating-point value remainder(Expr1, Expr2).
The floating-point remainder uses the C function remainder(). For the C function fmod(), use (%)/2.
Errors
Examples
 X is 2 rem 2             sets X to the integer value 0
 X is 3 rem 2             sets X to the integer value 1
 X is 1.5 rem 3           sets X to the floating-point value 1.5
 X is 1 rem "foo"         type_error(number, "foo")
 X is "foo" rem 1         type_error(number, "foo")
 X is 42 rem 0            evaluation_error(zero_divisor)
 X is 42 rem 0.0          sets X to not-a-number
Compatibility
The rem/2 function is from Standard Prolog. The new name remainder/2 is the recommended spelling. In Standard Prolog, rem/2 only works on integer values. Plang extends the definition to floating-point.
See Also
(+)/2, (-)/1, (-)/2, (*)/2, (/)/2, (%)/2
(/\)/2 - bitwise-and of two integer values.

Usage
Var is Expr1 /\ Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value of performing a bitwise-and of Expr1 and Expr2.
Errors
Examples
 X is 22 /\\ 5            X is set to 4
 X is 22.0 /\\ 5          type_error(integer, 22.0)
 X is 22 /\\ 5.0          type_error(integer, 5.0)
Compatibility
Standard Prolog
See Also
(\/)/2, (^)/2, (~)/1, (<<)/2, (>>)/2, (>>>)/2
(\/)/2 - bitwise-or of two integer values.

Usage
Var is Expr1 \/ Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value of performing a bitwise-or of Expr1 and Expr2.
Errors
Examples
 X is 22 \\/ 5            X is set to 23
 X is 22.0 \\/ 5          type_error(integer, 22.0)
 X is 22 \\/ 5.0          type_error(integer, 5.0)
Compatibility
Standard Prolog
See Also
(/\)/2, (^)/2, (~)/1, (<<)/2, (>>)/2, (>>>)/2
(^)/2 - bitwise-xor of two integer values.

Usage
Var is Expr1 ^ Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value of performing a bitwise-xor of Expr1 and Expr2.
Errors
Examples
 X is 22 ^ 5              X is set to 19
 X is 22.0 ^ 5            type_error(integer, 22.0)
 X is 22 ^ 5.0            type_error(integer, 5.0)
Compatibility
Standard Prolog
See Also
(/\)/2, (\/)/2, (~)/1, (<<)/2, (>>)/2, (>>>)/2
(~)/1, (\)/1 - bitwise-not of an integer value.

Usage
Var is ~ Expr
Var is \ Expr
Description
Evaluates Expr. If it is an integers, then the result is the integer value of performing a bitwise-not on Expr.
Errors
Examples
 X is ~22                 X is set to -23
 X is ~22.0               type_error(integer, 22.0)
Compatibility
The (\)/1 function is from Standard Prolog. The new name (~)/1 is the recommended spelling.
See Also
(/\)/2, (\/)/2, (^)/2, (<<)/2, (>>)/2, (>>>)/2
(<<)/2 - bitwise shift left of two integer values.

Usage
Var is Expr1 << Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value of performing a left shift of Expr1 by the value in the bottom 5 bits of Expr2. The top bits of Expr2 are ignored.
Errors
Examples
 X is 22 << 5             X is set to 704
 X is 22.0 << 5           type_error(integer, 22.0)
 X is 22 << 5.0           type_error(integer, 5.0)
Compatibility
Standard Prolog
See Also
(/\)/2, (\/)/2, (^)/2, (~)/1, (>>)/2, (>>>)/2
(>>)/2 - bitwise signed shift right of two integer values.

Usage
Var is Expr1 >> Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value of performing a signed left shift of Expr1 by the value in the bottom 5 bits of Expr2. The top bits of Expr2 are ignored.
Errors
Examples
 X is 22 >> 5             X is set to 0
 X is -22 >> 5            X is set to -1
 X is 22.0 >> 5           type_error(integer, 22.0)
 X is 22 >> 5.0           type_error(integer, 5.0)
Compatibility
Standard Prolog leaves it unspecified whether (>>)/2 is signed or unsigned. In Plang, (>>)/2 is defined as signed, with (>>>)/2 provided for the unsigned case.
See Also
(/\)/2, (\/)/2, (^)/2, (~)/1, (<<)/2, (>>>)/2
(>>>)/2 - bitwise unsigned shift right of two integer values.

Usage
Var is Expr1 >>> Expr2
Description
Evaluates Expr1 and Expr2. If both are integers, then the result is the integer value of performing an unsigned left shift of Expr1 by the value in the bottom 5 bits of Expr2. The top bits of Expr2 are ignored.
Errors
Examples
 X is 22 >>> 5            X is set to 0
 X is -22 >>> 5           X is set to 134217727 (0x07ffffff)
 X is 22.0 >>> 5          type_error(integer, 22.0)
 X is 22 >>> 5.0          type_error(integer, 5.0)
See Also
(/\)/2, (\/)/2, (^)/2, (~)/1, (<<)/2, (>>)/2
abs/1 - absolute value of an arithmetic term.

Usage
Var is abs(Expr)
Description
Evaluates Expr and produces its absolute value as the result.
Errors
Examples
 X is abs(3)              X is set to 3
 X is abs(-35.125)        X is set to 35.125
 X is abs(-inf)           X is set to inf
 X is abs(nan)            X is set to nan
 X is abs("-35")          type_error(number, "-35")
 X is abs(-2147483648)    evaluation_error(int_overflow)
Compatibility
Standard Prolog
See Also
(-)/1, sign/1
acos/1 - arc cosine of an arithmetic term.

Usage
Var is acos(Expr)
Description
Evaluates Expr and produces its arc cosine as the result.
Errors
Examples
 X is acos(1)             sets X to 0.0
 X is acos(0.0)           sets X to pi / 2
 X is acos(inf)           sets X to nan
 X is acos(nan)           sets X to nan
 X is acos("1.0")         type_error(number, "1.0")
See Also
asin/1, atan/1, atan2/2, cos/1, sin/1, tan/1, pi/0
asin/1 - arc sine of an arithmetic term.

Usage
Var is asin(Expr)
Description
Evaluates Expr and produces its arc sine as the result.
Errors
Examples
 X is asin(0)             sets X to 0.0
 X is asin(1.0)           sets X to pi / 2
 X is asin(inf)           sets X to nan
 X is asin(nan)           sets X to nan
 X is asin("1.0")         type_error(number, "1.0")
See Also
acos/1, atan/1, atan2/2, cos/1, sin/1, tan/1, pi/0
atan/1 - arc tangent of an arithmetic term.

Usage
Var is atan(Expr)
Description
Evaluates Expr and produces its arc tangent as the result.
Errors
Examples
 X is atan(1.0)           sets X to pi / 4
 X is atan(0)             sets X to 0.0
 X is atan(inf)           sets X to pi / 2
 X is atan(nan)           sets X to nan
 X is atan("1.0")         type_error(number, "1.0")
Compatibility
Standard Prolog
See Also
acos/1, asin/1, atan2/2, cos/1, sin/1, tan/1, pi/0
atan2/2 - arc tangent of two arithmetic terms.

Usage
Var is atan2(Expr1, Expr2)
Description
Evaluates Expr1 and Expr2 and produces the arc tangent of Expr1 / Expr2.
Errors
Examples
 X is atan2(1.0, 1.0)     sets X to pi / 4
 X is atan2(0, 1)         sets X to 0.0
 X is atan2(0, -1)        sets X to pi
 X is atan2(inf, 2)       sets X to pi / 2
 X is atan2(nan, 1)       sets X to nan
 X is atan2(1, nan)       sets X to nan
 X is atan2("2.0", 1.0)   type_error(number, "2.0")
 X is atan2(2.0, "1.0")   type_error(number, "1.0")
See Also
acos/1, asin/1, atan/1, cos/1, sin/1, tan/1, pi/0
ceil/1, ceiling/1 - smallest integer not smaller than an arithmetic term.

Usage
Var is ceil(Expr)
Var is ceiling(Expr)
Description
Evaluates Expr and rounds the smallest integer that is not smaller than Expr.
Errors
Examples
 X is ceil(3)             X is set to 3
 X is ceil(35.125)        X is set to 36.0
 X is ceil(-35.125)       X is set to -35.0
 X is ceil(0.0)           X is set to 0.0
 X is ceil(-inf)          X is set to -inf
 X is ceil(nan)           X is set to nan
 X is ceil("-35")         type_error(number, "-35")
Compatibility
The ceiling/1 function is compatible with Standard Prolog. The new name ceil/1 is the recommended spelling.
See Also
floor/1, round/1, float_integer_part/1
byte/2 - integer value of a specific byte in a string.

Usage
Var is byte(Expr, Index)
Description
Evaluates Expr and Index and returns the integer value of the byte at position Index within the string Expr.
Errors
Examples
 X is byte("foobar", 3)       X is set to 98 (character code of 'b')
 X is byte(1.5, 2)            type_error(string, 1.5)
 X is byte("foobar", 3.0)     type_error(integer, 3.0)
 X is byte("foobar", -1)      domain_error(string_index, -1)
 X is byte("foobar", 6)       domain_error(string_index, 6)
See Also
atom_name/2, byte_to_string/1, char/2, length_bytes/1
byte_to_string/1 - convert an integer byte code into a single-byte string.

Usage
Var is byte_to_string(Expr)
Description
Evaluates Expr and returns the single-byte string that corresponds to the integer value of Expr.
Errors
Examples
 X is byte_to_string(98)      X is set to "b"
 X is byte_to_string(0xC1)    X is set to "\xC1"
 X is byte_to_string(1.5)     type_error(integer, 1.5)
 X is byte_to_string(-1)      type_error(byte, -1)
See Also
byte/2, char_to_string/1, length_bytes/1
char/2 - integer value of a specific character in a UTF-8 string.

Usage
Var is char(Expr, Index)
Description
Evaluates Expr and Index and returns the Unicode integer value of the UTF-8 character at position Index within the string Expr.
Errors
Examples
 X is char("foobar", 3)       X is set to 98 (character code of 'b')
 X is char("\u00AF", 0)       X is set to 0x00AF
 X is char(1.5, 2)            type_error(string, 1.5)
 X is char("foobar", 3.0)     type_error(integer, 3.0)
 X is char("foobar", -1)      domain_error(string_index, -1)
 X is char("foobar", 6)       domain_error(string_index, 6)
 X is char("\u00AF", 1)       domain_error(string_index, 1)
See Also
atom_name/2, byte/2, char_to_string/1, length/1
char_to_string/1 - convert a Unicode integer character code into a single-character UTF-8 string.

Usage
Var is char_to_string(Expr)
Description
Evaluates Expr and returns the single-character UTF-8 string that corresponds to the integer character code of Expr.
Errors
Examples
 X is char_to_string(98)      X is set to "b"
 X is char_to_string(0x00AF)  X is set to "\u00AF"
 X is char_to_string(1.5)     type_error(integer, 1.5)
 X is char_to_string(-1)      representation_error(character_code)
See Also
byte_to_string/1, char/2, length/1
cos/1 - cosine of an arithmetic term.

Usage
Var is cos(Expr)
Description
Evaluates Expr as a value in radians and produces its cosine as the result.
Errors
Examples
 X is cos(0)              sets X to 1.0
 X is cos(pi / 2)         sets X to 0.0
 X is cos(inf)            sets X to nan
 X is cos(nan)            sets X to nan
 X is cos("1.0")          type_error(number, "1.0")
Compatibility
Standard Prolog
See Also
acos/1, asin/1, atan/1, atan2/2, sin/1, tan/1, pi/0
exp/1 - base-e exponential of an arithmetic term.

Usage
Var is exp(Expr)
Description
Evaluates Expr and computes the base-e exponential of Expr.
Errors
Examples
 X is exp(1)              X is set to e
 X is exp(0)              X is set to 1.0
 X is exp(2.0)            X is set to e * e
 X is exp(-2.0)           X is set to 1 / (e * e)
 X is exp(inf)            X is set to inf
 X is exp(-inf)           X is set to 0.0
 X is exp(nan)            X is set to nan
 X is exp("2.0")          type_error(number, "2.0")
Compatibility
Standard Prolog
See Also
log/1, pow/2, sqrt/1, e/0
e/0 - mathematical constant for e.

Usage
Var is e
Description
This function evaluates to the floating-point mathematical constant for e, 2.7182818284590452354.
Examples
 E2 is e * 2
See Also
inf/0, nan/0, pi/0
float/1 - conversion to floating-point.

Usage
Var is float(Expr)
Description
Evaluates Expr and converts it into a floating-point value. Strings are converted using the C function strtod().
Errors
Same as for is/2.
Examples
 F is float(3)            F is set to 3.0
 F is float(3.5)          F is set to 3.5 (no change)
 F is float(2 + 6)        F is set to 8.0
 F is float("-3.5e02")    F is set to -350.0 (string conversion)
 F is float("foo")        type_error(number, "foo")
 F is float('3.5')        type_error(evaluable, '3.5')
See Also
is/2, integer/1, string/1
float_fractional_part/1 - fractional part of a floating-point arithmetic term.

Usage
Var is float_fractional_part(Expr)
Description
Evaluates Expr and returns the fractional part of the value.
Errors
Examples
 X is float_fractional_part(3)        X is set to 0
 X is float_fractional_part(35.125)   X is set to 0.125
 X is float_fractional_part(-35.125)  X is set to -0.125
 X is float_fractional_part(0.0)      X is set to 0.0
 X is float_fractional_part(-inf)     X is set to 0.0
 X is float_fractional_part(nan)      X is set to nan
 X is float_fractional_part("-35")    type_error(number, "-35")
Compatibility
Standard Prolog
See Also
float_integer_part/1, floor/1, round/1
float_integer_part/1 - integer part of a floating-point arithmetic term.

Usage
Var is float_integer_part(Expr)
Description
Evaluates Expr and returns the integer part of the value.
Errors
Examples
 X is float_integer_part(3)           X is set to 3
 X is float_integer_part(35.125)      X is set to 35.0
 X is float_integer_part(-35.125)     X is set to -35.0
 X is float_integer_part(0.0)         X is set to 0.0
 X is float_integer_part(-inf)        X is set to -inf
 X is float_integer_part(nan)         X is set to nan
 X is float_integer_part("-35")       type_error(number, "-35")
Compatibility
Standard Prolog
See Also
float_fractional_part/1, floor/1, round/1
floor/1 - largest integer not greater than an arithmetic term.

Usage
Var is floor(Expr)
Description
Evaluates Expr and returns the largest integer that is not larger than Expr.
Errors
Examples
 X is floor(3)            X is set to 3
 X is floor(35.125)       X is set to 35.0
 X is floor(-35.125)      X is set to -36.0
 X is floor(0.0)          X is set to 0.0
 X is floor(-inf)         X is set to -inf
 X is floor(nan)          X is set to nan
 X is floor("-35")        type_error(number, "-35")
Compatibility
Standard Prolog
See Also
ceil/1, round/1, float_integer_part/1
inf/0 - mathematical constant for positive infinity.

Usage
Var is inf
Description
This function evaluates to the floating-point mathematical constant for positive infinity.
Examples
 Inf is inf
 NegInf is -inf
See Also
e/0, nan/0, pi/0, isinf/1
integer/1, truncate/1 - conversion to integer.

Usage
Var is integer(Expr)
Var is truncate(Expr)
Description
Evaluates Expr and converts it into an integer value by truncating the fractional part. Strings are converted using the C function strtol().
Errors
Examples
 I is integer(3)              I is set to 3 (no change)
 I is integer(3.5)            I is set to 3
 I is integer(2.0 + 6.0)      I is set to 8
 I is integer("-35")          I is set to -35 (string conversion)
 I is integer("foo")          type_error(integer, "foo")
 I is integer('3')            type_error(evaluable, '3')
 I is integer(2147483648.0)   evaluation_error(int_overflow)
Compatibility
The truncate/1 function is compatible with Standard Prolog. The new name integer/1 is the recommended spelling.
See Also
is/2, float/1, round/1, string/1, float_integer_part/1
left/2 - extract the left portion of a string.

Usage
Var is left(Expr, Length)
Description
Evaluates Expr and Length. Returns the Length UTF-8 characters at the beginning of the string.
If Length is greater than the length of Expr, then the whole string is returned.
Errors
Examples
 X is left("foobar", 3)       X is set to "foo"
 X is left("foobar", 10)      X is set to "foobar"
 X is left("foobar", 0)       X is set to ""
 X is left(1.5, 1)            type_error(string, 1.5)
 X is left("foobar", 1.0)     type_error(integer, 1.0)
 X is left("foobar", -1)      domain_error(not_less_than_zero, -1)
See Also
left_bytes/2, mid/2, mid/3, right/2
left_bytes/2 - extract the left portion of a string.

Usage
Var is left_bytes(Expr, Length)
Description
Evaluates Expr and Length. Returns the Length bytes at the beginning of the string.
If Length is greater than the length of Expr, then the whole string is returned.
Errors
Examples
 X is left_bytes("foobar", 3)     X is set to "foo"
 X is left_bytes("foobar", 10)    X is set to "foobar"
 X is left_bytes("foobar", 0)     X is set to ""
 X is left_bytes(1.5, 1)          type_error(string, 1.5)
 X is left_bytes("foobar", 1.0)   type_error(integer, 1.0)
 X is left_bytes("foobar", -1)    domain_error(not_less_than_zero, -1)
See Also
left/2, mid_bytes/2, mid_bytes/3, right_bytes/2
length/1 - length of a string in UTF-8 characters.

Usage
Var is length(Expr)
Description
Evaluates Expr and returns the length of the string in UTF-8 characters.
Errors
Examples
 X is length("foobar")        X is set to 6
 X is length("foo" + "bar")   X is set to 6
 X is length("")              X is set to 0
 X is length("\u00AF")        X is set to 1
 X is length(1.5)             type_error(string, 1.5)
See Also
char/2, char_to_string/1, length_bytes/1
length_bytes/1 - length of a string in bytes.

Usage
Var is length(Expr)
Description
Evaluates Expr and returns the length of the string in bytes.
Errors
Examples
 X is length_bytes("foobar")          X is set to 6
 X is length_bytes("foo" + "bar")     X is set to 6
 X is length_bytes("")                X is set to 0
 X is length_bytes("\u00AF")          X is set to 2
 X is length_bytes(1.5)               type_error(string, 1.5)
See Also
byte/2, byte_to_string/1, length/1
log/1 - base-e logarithm of an arithmetic term.

Usage
Var is log(Expr)
Description
Evaluates Expr and computes the base-e logarithm of Expr.
Errors
Examples
 X is log(e)              X is set to 1
 X is log(1)              X is set to 0.0
 X is log(e * e)          X is set to 2.0
 X is log(1 / (e * e))    X is set to -2.0
 X is log(0.0)            X is set to -inf
 X is log(inf)            X is set to inf
 X is log(-inf)           X is set to nan
 X is log(nan)            X is set to nan
 X is log("2.0")          type_error(number, "2.0")
Compatibility
Standard Prolog
See Also
exp/1, pow/2, sqrt/1, e/0
mid/2, mid/3 - extract the middle portion of a string.

Usage
Var is mid(Expr, Start, Length)
Var is mid(Expr, Start)
Description
Evaluates Expr, Start, and Length. Returns the Length UTF-8 characters starting at index Start within Expr. The first character is at index 0.
If Length is omited, then the returned string starts at Start and extends to the end of Expr.
If Start is beyond the end of Expr, then the empty string is returned.
If (Start + Length) is greater than the length of Expr, then as many characters as are available are returned, starting at Start.
Errors
Examples
 X is mid("foobar", 1, 4)     X is set to "ooba"
 X is mid("foobar", 1, 0)     X is set to ""
 X is mid("foobar", 10, 3)    X is set to ""
 X is mid("foobar", 4, 3)     X is set to "ar"
 X is mid("foobar", 4)        X is set to "ar"
 X is mid(1.5, 1)             type_error(string, 1.5)
 X is mid("foobar", 1.0, 4)   type_error(integer, 1.0)
 X is mid("foobar", 1, 4.0)   type_error(integer, 4.0)
 X is mid("foobar", -1)       domain_error(not_less_than_zero, -1)
 X is mid("foobar", 1, -4)    domain_error(not_less_than_zero, -4)
See Also
left/2, right/2
mid_bytes/2, mid_bytes/3 - extract the middle portion of a string.

Usage
Var is mid_bytes(Expr, Start, Length)
Var is mid_bytes(Expr, Start)
Description
Evaluates Expr, Start, and Length. Returns the Length bytes starting at index Start within Expr. The first byte is at index 0.
If Length is omited, then the returned string starts at Start and extends to the end of Expr.
If Start is beyond the end of Expr, then the empty string is returned.
If (Start + Length) is greater than the length of Expr, then as many bytes as are available are returned, starting at Start.
Errors
Examples
 X is mid_bytes("foobar", 1, 4)   X is set to "ooba"
 X is mid_bytes("foobar", 1, 0)   X is set to ""
 X is mid_bytes("foobar", 10, 3)  X is set to ""
 X is mid_bytes("foobar", 4, 3)   X is set to "ar"
 X is mid_bytes("foobar", 4)      X is set to "ar"
 X is mid_bytes(1.5, 1)           type_error(string, 1.5)
 X is mid_bytes("foobar", 1.0, 4) type_error(integer, 1.0)
 X is mid_bytes("foobar", 1, 4.0) type_error(integer, 4.0)
 X is mid_bytes("foobar", -1)     domain_error(not_less_than_zero, -1)
 X is mid_bytes("foobar", 1, -4)  domain_error(not_less_than_zero, -4)
See Also
left_bytes/2, mid/2, mid/3, right_bytes/2
nan/0 - mathematical constant for the IEEE not-a-number indication.

Usage
Var is nan
Description
This function evaluates to the floating-point mathematical constant for the IEEE not-a-number indication.
Examples
 NaN is nan
See Also
e/0, inf/0, pi/0, isnan/1
pi/0 - mathematical constant for pi.

Usage
Var is pi
Description
This function evaluates to the floating-point mathematical constant for pi, 3.14159265358979323846.
Examples
 PIOver2 is pi / 2
See Also
e/0, inf/0, nan/0
pow/2, (**)/2 - raises one arithmetic term to the power of another.

Usage
Var is pow(Expr1, Expr2)
Var is Expr1 ** Expr2
Description
Evaluates Expr1 and Expr2 and computes the result of raising Expr1 to the power of Expr2.
Errors
Examples
 X is pow(2, 3)           X is set to 8
 X is pow(3.5, 0)         X is set to 1.0
 X is pow(9, 0.5)         X is set to 3.0
 X is pow(1.0, 43)        X is set to 1.0
 X is pow(1.0, nan)       X is set to 1.0
 X is pow(nan, 0)         X is set to 1.0
 X is pow(0.0, 20)        X is set to 0.0
 X is pow(-1, inf)        X is set to 1.0
 X is pow(-1, -inf)       X is set to 1.0
 X is pow(0.5, -inf)      X is set to inf
 X is pow(1.5, -inf)      X is set to 0.0
 X is pow(1.5, inf)       X is set to inf
 X is pow(-inf, -3)       X is set to 0.0
 X is pow(-inf, 3)        X is set to -inf
 X is pow(-inf, 4)        X is set to inf
 X is pow(inf, -2)        X is set to 0.0
 X is pow(inf, 2)         X is set to inf
 X is pow(0.0, -2)        X is set to inf
 X is pow(nan, nan)       X is set to nan
 X is pow("2.0", 2)       type_error(number, "2.0")
 X is pow(2, "2.0")       type_error(number, "2.0")
Compatibility
The (**)/2 function is compatible with Standard Prolog. The new name pow/2 is the recommended spelling.
See Also
exp/1, log/2, sqrt/1
random/0 - generate a random number between 0 and 1.

Usage
Var is random
Description
Generates a random number between 0 and 1, but not including 1.
Note: the random number generator uses a simple linear congruential algorithm. The generated values are not suitable for use in high security applications.
Examples
 X is random                  generates a float between 0.0 and 1.0
 X is integer(random * 20)    generates an integer between 0 and 19
See Also
randomize/1
right/2 - extract the right portion of a string.

Usage
Var is right(Expr, Length)
Description
Evaluates Expr and Length. Returns the Length characters at the end of the string.
If Length is greater than the length of Expr, then the whole string is returned.
Errors
Examples
 X is right("foobar", 3)      X is set to "bar"
 X is right("foobar", 10)     X is set to "foobar"
 X is right("foobar", 0)      X is set to ""
 X is right(1.5, 1)           type_error(string, 1.5)
 X is right("foobar", 1.0)    type_error(integer, 1.0)
 X is right("foobar", -1)     domain_error(not_less_than_zero, -1)
See Also
left/2, mid/2, mid/3, right_bytes/2
right_bytes/2 - extract the right portion of a string.

Usage
Var is right_bytes(Expr, Length)
Description
Evaluates Expr and Length. Returns the Length bytes at the end of the string.
If Length is greater than the length of Expr, then the whole string is returned.
Errors
Examples
 X is right_bytes("foobar", 3)    X is set to "bar"
 X is right_bytes("foobar", 10)   X is set to "foobar"
 X is right_bytes("foobar", 0)    X is set to ""
 X is right_bytes(1.5, 1)         type_error(string, 1.5)
 X is right_bytes("foobar", 1.0)  type_error(integer, 1.0)
 X is right_bytes("foobar", -1)   domain_error(not_less_than_zero, -1)
See Also
left_bytes/2, mid_bytes/2, mid_bytes/3, right/2
round/1 - rounds an arithmetic term to the nearest integer.

Usage
Var is round(Expr)
Description
Evaluates Expr and rounds the value to the nearest integer. If Expr is halfway between two integers (at 0.5), then round/1 will round away from zero.
Errors
Examples
 X is round(3)            X is set to 3
 X is round(35.125)       X is set to 35.0
 X is round(35.5)         X is set to 36.0
 X is round(35.625)       X is set to 36.0
 X is round(-35.125)      X is set to -35.0
 X is round(-35.5)        X is set to -36.0
 X is round(-35.625)      X is set to -36.0
 X is round(0.0)          X is set to 0.0
 X is round(-inf)         X is set to -inf
 X is round(nan)          X is set to nan
 X is round("-35")        type_error(number, "-35")
Compatibility
The round/1 function in Standard Prolog produces an integer result, which means it does not work on large floating-point values. Use integer(round(Expr)) to achieve the Standard Prolog behavior.
See Also
integer/1, ceil/1, floor/1
sign/1 - calculate the sign (-1, 0, or 1) of an arithmetic term.

Usage
Var is sign(Expr)
Description
Evaluates Expr and produces the integer values -1, 0, or 1 dependening upon whether Expr is negative, zero, or positive.
Errors
Examples
 X is sign(3)             X is set to 1
 X is sign(-35.125)       X is set to -1
 X is sign(0.0)           X is set to 0
 X is sign(-0.0)          X is set to 0
 X is sign(-inf)          X is set to -1
 X is sign(nan)           X is set to 0
 X is sign("-35")         type_error(number, "-35")
Compatibility
Standard Prolog
See Also
(-)/1, abs/1
sin/1 - sine of an arithmetic term.

Usage
Var is sin(Expr)
Description
Evaluates Expr as a value in radians and produces its sine as the result.
Errors
Examples
 X is sin(0)              sets X to 0.0
 X is sin(pi / 2)         sets X to 1.0
 X is sin(inf)            sets X to nan
 X is sin(nan)            sets X to nan
 X is sin("1.0")          type_error(number, "1.0")
Compatibility
Standard Prolog
See Also
acos/1, asin/1, atan/1, atan2/2, cos/1, tan/1, pi/0
sqrt/1 - square root of an arithmetic term.

Usage
Var is sqrt(Expr)
Description
Evaluates Expr and computes the square root of Expr.
Errors
Examples
 X is sqrt(1)             X is set to 1.0
 X is sqrt(0.0)           X is set to 0.0
 X is sqrt(2.0)           X is set to 1.41421...
 X is sqrt(256)           X is set to 16.0
 X is sqrt(inf)           X is set to inf
 X is sqrt(-2.0)          X is set to nan
 X is sqrt(-inf)          X is set to nan
 X is sqrt(nan)           X is set to nan
 X is sqrt("2.0")         type_error(number, "2.0")
Compatibility
Standard Prolog
See Also
exp/1, log/1, pow/2
string/1 - conversion to string.

Usage
Var is string(Expr)
Description
Evaluates Expr and converts it into a string value using the C function snprintf(). Floating point values use the format "<tt>%.10g</tt>", adding a trailing "<tt>.0</tt>" if necessary to make the value a valid Plang floating-point constant. Use string/2 to specify a different precision from 10.
Errors
Same as for is/2.
Examples
 S is string(3)           S is set to "3"
 S is string(3.5)         S is set to "3.5"
 S is string(2.0 + 6.0)   S is set to "8.0"
 S is string("foo")       S is set to "foo" (no change)
 S is string(2.0e35)      S is set to "2e+35"
 S is string('3')         type_error(evaluable, '3')
See Also
is/2, float/1, integer/1, string/2
string/2 - conversion to string with specified floating-point precision.

Usage
Var is string(Expr, Precision)
Description
Evaluates Expr and converts it into a string value using the C function snprintf(). Floating point values use the format "<tt>%.Pg</tt>" where P is the result of evaluating Precision. A trailing "<tt>.0</tt>" will be added if necessary to make the value a valid Plang floating-point constant.
Errors
Same as for is/2.
Examples
 S is string(3, 2)        S is set to "3"
 S is string(3.5, 2)      S is set to "3.5"
 S is string(3.125, 2)    S is set to "3.1"
 S is string("foo", 2)    S is set to "foo" (no change)
 S is string('3')         type_error(evaluable, '3')
See Also
is/2, float/1, integer/1, string/1
tan/1 - tangent of an arithmetic term.

Usage
Var is tan(Expr)
Description
Evaluates Expr as a value in radians and produces its tangent as the result.
Errors
Examples
 X is tan(0)              sets X to 0.0
 X is tan(1.0)            sets X to 1.557407...
 X is tan(inf)            sets X to nan
 X is tan(nan)            sets X to nan
 X is tan("1.0")          type_error(number, "1.0")
See Also
acos/1, asin/1, atan/1, atan2/2, cos/1, sin/1, pi/0
Generated on 26 May 2011 for plang by  doxygen 1.6.1