This section discusses arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes]. It uses an approach that permits lightweight operations whenever possible.
3.2 Numeric Constructors
The following constructors are defined on the above numeric types. Each constructor takes a single string literal as argument. Leading and trailing whitespace, if present, is stripped from the literal
before the value is constructed.
[Issue 149: Either the constructor functions should allow dynamic
expressions or the syntax should be changed so that they do not appear to
be functions. ]
| Constructor | Meaning |
xf:decimal
| Produces a decimal value by parsing and interpreting a string. |
xf:integer
| Produces an integer value by parsing and interpreting a string. |
xf:long
| Produces a long value by parsing and interpreting a string. |
xf:int
| Produces an int value by parsing and interpreting a string. |
xf:short
| Produces a short value by parsing and interpreting a string. |
xf:byte
| Produces a byte value by parsing and interpreting a string. |
xf:float
| Produces a float value by parsing and interpreting a string. |
xf:double
| Produces a double value by parsing and interpreting a string. |
For float and double, the string argument can indicate the special values: NaN, INF, -INF, +0, and -0.
If the argument string passed to a constructor results in an error
(for example, if it conatains a letter other than "E" or "e" or a string other than the special values named above), the constructor returns the error value as defined in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.1 xf:decimal
xf:decimal(string $srcval) => decimal
Returns the decimal value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is not a valid lexical representation for the decimal type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the number of characters contained in the value of $srcval that are digits is greater than the maximum number of decimal digits supported by the implementation, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.1.1 Examples
xf:decimal('123.5') returns the decimal value corresponding to one hundred twenty three and one-half.
xf:decimal('12.5E2') returns the error value, since the use of the letter "E" is prohibited in the constructor for the decimal type.
xf:decimal(' 12.5 ') returns the decimal value corresponding to twelve and one-half.
3.2.2 xf:integer
xf:integer(string $srcval) => integer
Returns the integer value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is not a valid lexical representation for the integer type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the number of characters contained in the value of $srcval that are digits is greater than the maximum number of digits supported by the implementation, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.2.1 Examples
xf:integer('-123') returns the integer value corresponding to negative one hundred twenty three.
xf:integer('123.5') returns the error value, since the use of a decimal point is prohibited in the constructor for the integer type.
3.2.3 xf:long
xf:long(string $srcval) => integer
Returns the long value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is not a valid lexical representation for the long type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the value of the number corresponding to the characters contained in the value of $srcval is greater than 9,223,372,036,854,775,807 or less than -9,223,372,036,854,775,808, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.3.1 Examples
xf:long('-1235') returns the long value corresponding to negative one thousand two hundred thirty five.
xf:long('10000000000000000000') returns the error value, since ten quintillion is not a valid value for the long type.
3.2.4 xf:int
xf:int(string $srcval) => integer
Returns the int value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is not a valid lexical representation for the int type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the value of the number corresponding to the characters contained in the value of $srcval is greater than 2,147,483,647 or less than -2,147,483,648, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.4.1 Examples
xf:int('1235') returns the int value corresponding to one thousand two hundred thirty five.
xf:int('2147483648') returns the error value, since the value two billion, one hundred forty seven million, four hundred eighty three thousand, six hundred forty eight is not a valid value for the short type.
3.2.5 xf:short
xf:short(string $srcval) => integer
Returns the short value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is not a valid lexical representation for the short type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the value of the number corresponding to the characters contained in the value of $srcval is greater than 32,767 or less than -32,768, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.5.1 Examples
xf:short('1235') returns the short value corresponding to one thousand two hundred thirty five.
xf:short('32768') returns the error value, since the value thirty two thousand seven hundred sixty eight is not a valid value for the short type.
3.2.6 xf:byte
xf:byte(string $srcval) => integer
Returns the byte value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is not a valid lexical representation for the byte type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the value of the number corresponding to the characters contained in the value of $srcval is greater than 127 or less than -128, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.6.1 Examples
xf:byte('127') returns the byte value corresponding to one hundred twenty seven.
xf:byte('128') returns the error value, since the value one hundred twenty eight is not a valid value for the byte type.
3.2.7 xf:float
xf:float(string $srcval) => float
Returns the float value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is
"NaN", then the constructor returns the "not-a-number" value.
If the value of $srcval is
"INF" or
"+INF", then the constructor returns the "positive infinity" value. If the value of $srcval is
"-INF", then the constructor returns the "negative infinity" value.
If the value of $srcval is
"0" or
"+0", then the constructor returns the value positive zero. If the value of $srcval is
"-0", then the constructor returns the value negative zero.
If the value of $srcval is not a valid lexical representation for the float type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the value of the number corresponding to the characters contained in the value of $srcval is not a valid value for the float type, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.7.1 Examples
xf:float('510E2') returns the float value corresponding to fifty one thousand.
xf:float('15.25') returns the float value corresponding to fifteen and a quarter.
xf:float('51D1') returns the error value, since the use of the letter "D" is prohibited in the constructor for the float type.
3.2.8 xf:double
xf:double(string $srcval) => double
Returns the double value that is represented by the characters contained in the value of $srcval. For this constructor, $srcval must be a
string literal.
If the value of $srcval is
"NaN", then the constructor returns the "not-a-number" value.
If the value of $srcval is
"INF" or
"+INF", then the constructor returns the "positive infinity" value. If the value of $srcval is
"-INF", then the constructor returns the "negative infinity" value.
If the value of $srcval is
"0" or "+0",
then the constructor returns the value positive zero. If the value of $srcval is "-0", then the constructor returns the value negative zero.
If the value of $srcval is not a valid lexical representation for the double type as specified in [XML Schema Part 2: Datatypes], then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
If the value of the number corresponding to the characters contained in the value of $srcval is not a valid value for the float type, then the error value is returned as specified in [XQuery 1.0 and XPath 2.0 Data Model].
3.2.8.1 Examples
xf:double('510E2') returns the double value corresponding to fifty one thousand.
xf:double('15.25') returns the double value corresponding to fifteen and a quarter.
xf:double('51D1') returns the error value, since the use of the letter "D" is prohibited in the constructor for the double type.
3.3 Operators on Numeric Values
The arguments and return types for the arithmetic operators are the basic numeric types: decimal, float, and double and types derived from them. For simplicity, each operator is defined to operate on operands of the same datatype and to return the same datatype. If the two operands are not of the same datatype, one operand is promoted to be the type of the other operand.
The type promotion scheme includes only two rules:
A derived type may be promoted its base type.
decimal may be promoted to float, and float may be promoted to double.
The result type of operations depends on their argument datatypes and is
defined in the following table:
| Operator | Returns |
| op:operation(decimal, decimal) | decimal |
| op:operation(float, float) | float |
| op:operation(double, double) | double |
| op:operation(decimal) | decimal |
| op:operation(float) | float |
| op:operation(double) | double |
These rules define any operation on any pair of arithmetic types. Consider the following example:
op:operation(int, double) => op:operation(double, double)
For this operation, int must be converted to double. This can be done, since by the rules above: int can be promoted to integer, integer can be promoted to decimal, decimal can be promoted to float, and float can be promoted to double. As far as possible, the promotions should be done in a single step. Specifically, when a decimal is promoted to a double, it must not be converted to a float and then to double as this will lose precision.
As another example, a user may define height as a derived type of integer with a minimum value of 20 and a maximum value of 100. He may then derive oddHeight using a pattern to restrict the value to odd integers.
op:operation(oddHeight, 2) => op:operation(decimal, decimal)
oddHeight is first promoted to it's base type height. height is promoted to its base type integer and integer to it's base type decimal.
[Issue 72: Effects of overflow and underflow unspecified]
Finally, consider some examples involving special IEEE 754 numerics.
If either argument is "NaN", the result is "NaN".
If neither argument is "NaN", but either argument
is "INF", the result is "INF".
If neither argument is "NaN" or "INF", but either argument
is "-INF", the result is "-INF".
Note: In the case of multiplication
and division, "INF" may become "-INF", and vice versa, as
appropriate.
The functions op:numeric-add, op:numeric-subtract, op:numeric-multiply,
op:numeric-divide and op:numeric-mod are each defined for three pairs of numeric
operands of the same type: decimal, float and double. The functions
op:numeric-unary-plus and op:numeric-unary-minus are defined for a single
operand of the same three numeric types.
3.3.1 op:numeric-add
op:numeric-add(numeric $operand1, numeric $operand2) => numeric
Backs up the "+" operator and returns the arithmetic sum of its operands:
($operand1 + $operand2).
3.3.2 op:numeric-subtract
op:numeric-subtract(numeric $operand1, numeric $operand2) => numeric
Backs up the "-" operator and returns the arithmetic difference of its operands:
($operand1 - $operand2).
3.3.3 op:numeric-multiply
op:numeric-multiply(numeric $operand1, numeric $operand2) => numeric
Backs up the "*" operator and returns the arithmetic product of its operands:
($operand1 * $operand2).
3.3.4 op:numeric-divide
op:numeric-divide(numeric $operand1, numeric $operand2) => numeric
Backs up the "div" operator and returns the arithmetic quotient of its operands:
($operand1 div $operand2).
3.3.5 op:numeric-mod
op:numeric-mod(numeric $operand1, numeric $operand2) => numeric
Backs up the "mod" operator and returns the remainder after dividing the first operand by the second operand:
($operand1 mod $operand2).
The result is of the same type as the operands after type promotion. The following rules apply:
If either operand is NaN, the result is NaN.
If the dividend is an infinity, or the divisor is a zero, or both, the result is NaN.
If not NaN, the sign of the result equals the sign of the dividend.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is a zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither an infinity, nor a zero, nor NaN is involved, the float or double remainder r from a dividend n and a divisor d is defined by the mathematical relation r = n .(d * q)
where q is an integer that is negative only if n/d is negative and positive only if n/d is positive, and
whose magnitude is as large as possible without exceeding the magnitude of the true mathematical quotient of n and d. This is truncating division, analogous to integer division, not
[IEEE 754-1985] rounding division.
Evaluation of a floating-point mod never throws a run-time exception, even if the right-hand operand is zero. Overflow, underflow, or loss of precision cannot occur.
3.3.5.1 Examples
op:numeric-mod(10,3) returns 1.
op:numeric-mod(6,2) returns 0.
op:numeric-mod(4.5,1.2) returns 0.9.
op:numeric-mod(1.23E2, 0.6E1) returns 3.0E0.
3.3.6 op:numeric-unary-plus
op:numeric-unary-plus(numeric $operand) => numeric
Backs up the unary "+" operator and returns its operand with the sign unchanged: (+ $operand). Semantically, this operation
performs no operation.
3.3.7 op:numeric-unary-minus
op:numeric-unary-minus(numeric $operand) => numeric
Backs up the unary "-" operator and returns its operand with the sign reversed: (- $operand). If $operand
is positive, its negative is returned; if it it is negative, its positive
is returned.
3.5 Functions on Numeric Values
The following functions are defined on these numeric types. Each function
returns an integer except:
If the argument is the empty sequence, the empty
sequence is returned.
If the argument is "NaN", "NaN" is returned.
[Issue 79: How many digits of precision (etc.) are returned from certain functions?]
[Issue 142: Should floor ceiling and round return the same type as
their argument? ]
3.5.1 xf:floor
xf:floor(double? $srcval) => integer?
Returns the largest (closest to positive infinity) integer that is
not greater than the value of $srcval. If the argument is the empty sequence, returns the empty sequence.
3.5.2 xf:ceiling
xf:ceiling(double? $srcval) => integer?
Returns the smallest (closest to negative infinity) number that is not smaller than the value of $srcvaland that is an integer. If the argument is the empty sequnce, returns the empty sequence.
3.5.3 xf:round
xf:round(double? $srcval) => integer?
Returns the number that is closest to the argument and that is an
integer. More formally, round(x) produces the same result
as floor(x+0.5). These semantics are consistent with
Java's semantics. If there are two such numbers, then the one that is
closest to positive infinity is returned. If the argument is NaN, then
NaN is returned. If the argument is positive infinity, then positive
infinity is returned. If the argument is negative infinity, then
negative infinity is returned. If the argument is positive zero, then
positive zero is returned. If the argument is negative zero, then
negative zero is returned. If the argument is less than zero, but
greater than or equal to -0.5, then negative zero is returned.
If the argument is the empty sequnce, returns the empty sequence.
