This section specifies arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes Second Edition].
The operators described in this section are defined on the following atomic types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indentation.
xs:decimal | |
xs:integer | |
xs:float | |
xs:double |
They also apply to types derived by restriction from the above types.
The type xs:numeric
is defined as a union type whose member types are
(in order) xs:double
, xs:float
, and xs:decimal
. This type is implicitly imported
into the static context, so it can also be used in defining the signature of user-written functions. Apart from the fact that
it is implicitly imported, it behaves exactly like a user-defined type with the same definition. This means, for example:
If the expected type of a function parameter is given as xs:numeric
, the actual value supplied
can be an instance of any of these three types, or any type derived from these three by restriction (this includes the built-in
type xs:integer
, which is derived from xs:decimal
).
If the expected type of a function parameter is given as xs:numeric
, and the actual value supplied
is xs:untypedAtomic
(or a node whose atomized value is xs:untypedAtomic
), then it will
be cast to the union type xs:numeric
using the rules in 19.3.5 Casting to union types.
Because the lexical space of xs:double
subsumes the lexical space of the other member types, and
xs:double
is listed first, the effect is that if the untyped atomic value is in the lexical space of
xs:double
, it will be converted to an xs:double
, and if not, a dynamic error occurs.
When the return type of a function is given as xs:numeric
, the actual value returned will be
an instance of one of the three member types (and perhaps also of types derived from these by restriction). The rules
for the particular function will specify how the type of the result depends on the values supplied as arguments.
In many cases, for the functions in this specification, the result is defined to be the same type as the first
argument.
Note:
This specification uses [IEEE 754-2008] arithmetic for xs:float
and xs:double
values.
One consequence of this is that some operations result in the value NaN
(not-a number), which
has the unusual property that it is not equal to itself. Another consequence is that some operations return the value negative zero.
This differs from [XML Schema Part 2: Datatypes Second Edition] which defines
NaN
as being equal to itself and defines only a single zero in the value space.
The text accompanying several functions defines behavior for both positive and negative zero inputs and outputs
in the interest of alignment with [IEEE 754-2008]. A conformant implementation must
respect these semantics. In consequence, the expression -0.0e0
(which is actually a unary minus operator
applied to an xs:double
value) will always return negative zero: see 4.2.8 op:numeric-unary-minus.
As a concession to implementations that rely on implementations of XSD 1.0, however, when casting from string to double
the lexical form -0
may be converted to positive zero, though negative zero
is recommended.
XML Schema 1.1 introduces support for positive and negative zero as distinct values, and also uses the [IEEE 754-2008]
semantics for comparisons involving NaN
.
The following functions define the semantics of arithmetic operators defined in [XQuery 4.1: An XML Query Language] and [XML Path Language (XPath) 4.0] on these numeric types.
Operator | Meaning |
---|---|
op:numeric-add
|
Addition |
op:numeric-subtract
|
Subtraction |
op:numeric-multiply
|
Multiplication |
op:numeric-divide
|
Division |
op:numeric-integer-divide
|
Integer division |
op:numeric-mod
|
Modulus |
op:numeric-unary-plus
|
Unary plus |
op:numeric-unary-minus
|
Unary minus (negation) |
The parameters and return types for the above operators are in most cases declared to be of type
xs:numeric
, which permits the basic numeric
types: xs:integer
, xs:decimal
, xs:float
and xs:double
, and types derived from them.
In general the two-argument functions require that both arguments are of the same primitive type,
and they return a value of this same type.
The exceptions are op:numeric-divide
, which returns
an xs:decimal
if called with two xs:integer
operands,
and op:numeric-integer-divide
which always returns an xs:integer
.
If the two operands of an arithmetic expression are not of the same type, subtype substitution and numeric type promotion are used to obtain two operands of the same type. Section B.1 Type Promotion XP31 and Section B.2 Operator Mapping XP31 describe the semantics of these operations in detail.
The result type of operations depends on their argument datatypes and is defined in the following table:
Operator | Returns |
---|---|
op:operation(xs:integer, xs:integer)
|
xs:integer (except for op:numeric-divide(integer,
integer) , which returns xs:decimal ) |
op:operation(xs:decimal, xs:decimal)
|
xs:decimal
|
op:operation(xs:float, xs:float)
|
xs:float
|
op:operation(xs:double, xs:double)
|
xs:double
|
op:operation(xs:integer)
|
xs:integer
|
op:operation(xs:decimal)
|
xs:decimal
|
op:operation(xs:float)
|
xs:float
|
op:operation(xs:double)
|
xs:double
|
These rules define any operation on any pair of arithmetic types. Consider the following example:
op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)
For this operation, xs:int
must be converted to
xs:double
. This can be done, since by the rules above:
xs:int
can be substituted for xs:integer
,
xs:integer
can be substituted for xs:decimal
,
xs:decimal
can be promoted to xs:double
. As far as possible, the promotions should be done in a
single step. Specifically, when an xs:decimal
is promoted to an
xs:double
, it should not be converted to an xs:float
and then to xs:double
, as this risks loss of precision.
As another example, a user may define height
as a derived type of
xs:integer
with a minimum value of 20 and a maximum value of 100.
They may then derive fenceHeight
using an enumeration to restrict the
permitted set of values to, say, 36, 48 and 60.
op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)
fenceHeight
can be substituted for its base type
height
and height
can be substituted for its base type
xs:integer
.
The basic rules for addition, subtraction, and multiplication
of ordinary numbers are not set out in this specification; they are taken as given. In the case of xs:double
and xs:float
the rules are as defined in [IEEE 754-2008]. The rules for handling
division and modulus operations, as well as the rules for handling special values such as infinity and NaN
,
and exception conditions such as overflow and underflow, are described more explicitly since they are not necessarily obvious.
On overflow and underflow situations during arithmetic operations conforming implementations must behave as follows:
For xs:float
and xs:double
operations, overflow
behavior must be conformant with [IEEE 754-2008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an overflow trap.
Returning INF
or -INF
.
Returning the largest (positive or negative) non-infinite number.
For xs:float
and xs:double
operations,
underflow behavior must be conformant with [IEEE 754-2008]. This specification allows the following options:
Raising a dynamic error [err:FOAR0002] via an underflow trap.
Returning 0.0E0
or +/- 2**Emin
or a
denormalized value; where Emin
is the smallest
possible xs:float
or xs:double
exponent.
For xs:decimal
operations, overflow behavior must
raise a dynamic error [err:FOAR0002]. On
underflow, 0.0
must be returned.
For xs:integer
operations, implementations that support
limited-precision integer operations must select from
the following options:
They may choose to always raise a dynamic error [err:FOAR0002].
They may provide an ·implementation-defined· mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967].
The functions op:numeric-add
, op:numeric-subtract
,
op:numeric-multiply
, op:numeric-divide
,
op:numeric-integer-divide
and op:numeric-mod
are each
defined for pairs of numeric operands, each of which has the same
type:xs:integer
, xs:decimal
, xs:float
, or
xs:double
. The functions op:numeric-unary-plus
and
op:numeric-unary-minus
are defined for a single operand whose type
is one of those same numeric types.
For xs:float
and xs:double
arguments, if either
argument is NaN
, the result is NaN
.
For xs:decimal
values, let N be the number of digits
of precision supported by the implementation, and let M (M <= N
) be the minimum limit on the number of digits
required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication
operations, the returned result should be accurate to N digits of precision, and for division and modulus operations,
the returned result should be accurate to at least M digits of precision.
The actual precision is ·implementation-defined·. If the number
of digits in the mathematical result exceeds the number of digits that the implementation
retains for that operation, the result is truncated or rounded in an ·implementation-defined· manner.
Note:
This Recommendation does not specify whether xs:decimal
operations are fixed point or floating point.
In an implementation using floating point it is possible for very simple operations to require more digits of precision than
are available; for example adding 1e100
to 1e-100
requires 200 digits of precision for an
accurate representation of the result.
The [IEEE 754-2008] specification also describes handling of
two exception conditions called divideByZero
and invalidOperation
. The
IEEE divideByZero
exception is raised not only by a direct attempt to divide by zero, but also by
operations such as log(0)
. The IEEE invalidOperation
exception is raised by
attempts to call a function with an argument that is outside the function's domain (for example,
sqrt(-1)
or log(-1)
).
Although IEEE defines these as exceptions, it also defines "default non-stop exception handling" in
which the operation returns a defined result, typically positive or negative infinity, or NaN. With this
function library,
these IEEE exceptions do not cause a dynamic error
at the application level; rather they result in the relevant function or operator returning
the defined non-error result.
The underlying IEEE exception may be notified to the application
or to the user by some ·implementation-defined·
warning condition, but the observable effect on an application
using the functions and operators defined in this specification is simply to return
the defined result (typically -INF, +INF, or NaN) with no error.
The [IEEE 754-2008] specification distinguishes two NaN values,
a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM model:
the value spaces of xs:float
and xs:double
each include only a single
NaN
value. This does not prevent the implementation distinguishing them internally,
and triggering different ·implementation-defined·
warning conditions, but such distinctions do not affect the observable behavior of an application
using the functions and operators defined in this specification.
Returns the arithmetic sum of its operands: ($arg1 + $arg2
).
Defines the semantics of the "+" operator when applied to two numeric values
op:numeric-add ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:numeric |
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or -INF
,
INF
or -INF
is returned. If both operands are
INF
, INF
is returned. If both operands are
-INF
, -INF
is returned. If one of the operands is
INF
and the other is -INF
, NaN
is
returned.
Returns the arithmetic difference of its operands: ($arg1 - $arg2
).
Defines the semantics of the "-" operator when applied to two numeric values.
op:numeric-subtract ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:numeric |
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero or a finite number and the other is INF
or -INF
, an
infinity of the appropriate sign is returned. If both operands are INF
or
-INF
, NaN
is returned. If one of the operands is
INF
and the other is -INF
, an infinity of the appropriate
sign is returned.
Returns the arithmetic product of its operands: ($arg1 * $arg2
).
Defines the semantics of the "*" operator when applied to two numeric values.
op:numeric-multiply ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:numeric |
General rules: see 4.2 Arithmetic operators on numeric values.
For xs:float
or xs:double
values, if one of the operands is a
zero and the other is an infinity, NaN
is returned. If one of the operands
is a non-zero number and the other is an infinity, an infinity with the appropriate sign
is returned.
Returns the arithmetic quotient of its operands: ($arg1 div $arg2
).
Defines the semantics of the "div" operator when applied to two numeric values.
op:numeric-divide ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:numeric |
General rules: see 4.2 Arithmetic operators on numeric values.
As a special case, if the types of both $arg1
and $arg2
are
xs:integer
, then the return type is xs:decimal
.
A dynamic error is raised [err:FOAR0001] for xs:decimal
and xs:integer
operands, if the divisor is (positive or negative) zero.
For xs:float
and xs:double
operands, floating point division
is performed as specified in [IEEE 754-2008]. A positive number divided by
positive zero returns INF
. A negative number divided by positive zero
returns -INF
. Division by negative zero returns -INF
and
INF
, respectively. Positive or negative zero divided by positive or
negative zero returns NaN
. Also, INF
or -INF
divided by INF
or -INF
returns NaN
.
Performs an integer division.
Defines the semantics of the "idiv" operator when applied to two numeric values.
op:numeric-integer-divide ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:integer |
General rules: see 4.2 Arithmetic operators on numeric values.
If $arg2
is INF
or -INF
, and $arg1
is not INF
or -INF
, then the result is zero.
Otherwise, subject to limits of precision and overflow/underflow conditions, the result
is the largest (furthest from zero) xs:integer
value $N
such
that the following expression is true:
fn:abs($N * $arg2) le fn:abs($arg1) and fn:compare($N * $arg2, 0) eq fn:compare($arg1, 0).
Note:
The second term in this condition ensures that the result has the correct sign.
The implementation may adopt a different algorithm provided that it is equivalent to
this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example,
the implementation-defined precision of the result of xs:decimal
division.
A dynamic error is raised [err:FOAR0001] if the divisor is (positive or negative) zero.
A dynamic error is raised [err:FOAR0002] if either operand is
NaN
or if $arg1
is INF
or
-INF
.
Except in situations involving errors, loss of precision, or overflow/underflow, the
result of $a idiv $b
is the same as ($a div $b) cast as
xs:integer
.
The semantics of this function are different from integer division as defined in programming languages such as Java and C++.
The expression op:numeric-integer-divide(10,3)
returns 3
.
The expression op:numeric-integer-divide(3,-2)
returns -1
.
The expression op:numeric-integer-divide(-3,2)
returns -1
.
The expression op:numeric-integer-divide(-3,-2)
returns 1
.
The expression op:numeric-integer-divide(9.0,3)
returns 3
.
The expression op:numeric-integer-divide(-3.5,3)
returns -1
.
The expression op:numeric-integer-divide(3.0,4)
returns 0
.
The expression op:numeric-integer-divide(3.1E1,6)
returns 5
.
The expression op:numeric-integer-divide(3.1E1,7)
returns 4
.
Returns the remainder resulting from dividing $arg1
, the dividend, by
$arg2
, the divisor.
Defines the semantics of the "mod" operator when applied to two numeric values.
op:numeric-mod ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:numeric |
General rules: see 4.2 Arithmetic operators on numeric values.
The operation a mod b
for operands that are xs:integer
or
xs:decimal
, or types derived from them, produces a result such that
(a idiv b)*b+(a mod b)
is equal to a
and the magnitude of
the result is always less than the magnitude of b
. This identity holds even
in the special case that the dividend is the negative integer of largest possible
magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this
rule that the sign of the result is the sign of the dividend.
For xs:float
and xs:double
operands the following rules
apply:
If either operand is NaN
, the result is NaN
.
If the dividend is positive or negative infinity, or the divisor is positive or
negative zero (0), or both, the result is NaN
.
If the dividend is finite and the divisor is an infinity, the result equals the dividend.
If the dividend is positive or negative zero and the divisor is finite, the result is the same as the dividend.
In the remaining cases, where neither positive or negative infinity, nor positive
or negative zero, nor NaN
is involved, the result obeys (a idiv
b)*b+(a mod b)
= a
.
Division is truncating division, analogous to integer division, not [IEEE 754-2008] rounding division i.e. additional digits are truncated,
not rounded to the required precision.
A dynamic error is raised [err:FOAR0001] for xs:integer
and xs:decimal
operands, if $arg2
is zero.
The expression op:numeric-mod(10,3)
returns 1
.
The expression op:numeric-mod(6,-2)
returns 0
.
The expression op:numeric-mod(4.5,1.2)
returns 0.9
.
The expression op:numeric-mod(1.23E2, 0.6E1)
returns 3.0E0
.
Returns its operand with the sign unchanged: (+ $arg
).
Defines the semantics of the unary "+" operator applied to a numeric value.
op:numeric-unary-plus ( |
||
$arg |
as xs:numeric |
|
) as xs:numeric |
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is equal to $arg
, and is an instance of
xs:integer
, xs:decimal
, xs:double
, or
xs:float
depending on the type of $arg
.
Because function conversion rules are applied in the normal way, the unary
+
operator can be used to force conversion of an untyped node to a
number: the result of +@price
is the same as xs:double(@price)
if the type of @price
is xs:untypedAtomic
.
Returns its operand with the sign reversed: (- $arg
).
Defines the semantics of the unary "-" operator when applied to a numeric value.
op:numeric-unary-minus ( |
||
$arg |
as xs:numeric |
|
) as xs:numeric |
General rules: see 4.2 Arithmetic operators on numeric values.
The returned value is an instance of xs:integer
, xs:decimal
,
xs:double
, or xs:float
depending on the type of
$arg
.
For xs:integer
and xs:decimal
arguments, 0
and
0.0
return 0
and 0.0
, respectively. For
xs:float
and xs:double
arguments, NaN
returns
NaN
, 0.0E0
returns -0.0E0
and vice versa.
INF
returns -INF
. -INF
returns
INF
.
The six value comparison operators eq
, ne
, lt
,
le
, gt
, and ge
are defined in terms of two
underlying functions: op:numeric-equal
and op:numeric-less-than
.
These functions are defined to operate on values of the same type.
If the arguments are of different types, then one of them is converted to the type of the other using the following rules, in order:
If one operand is xs:float
then it is converted to xs:double
.
If one operand is xs:double
and the other is xs:decimal
, then:
If the xs:double
operand is -INF
, +INF
, or NaN
,
then the xs:decimal
value is cast to xs:double
and the values are compared
as doubles.
Otherwise, the xs:double
value is converted to a decimal number with no rounding
or loss of precision and the values are compared acccording to their mathematical values.
Note:
Every instance of xs:float
, xs:double
, and xs:decimal
,
other than the values -INF
, +INF
, and NaN
, can be represented
exactly as a decimal number provided enough digits are available both before and after the decimal
point. The effect of this rule is that the comparison operators are transitive.
In edge cases this rule may give a different result from earlier releases. For example
in XPath 3.1 (depending on the implementation-defined precision), the values
xs:decimal('1.0000000000100000000001')
and xs:double('1.00000000001')
might compare as equal; in this version of the specification, they are not equal.
This change removes the problems caused for fn:distinct-values
and
xsl:for-each-group
as a result of non-transitivity, and it aligns the semantics
of the eq
operator (used also in fn:distinct-values
, fn:index-of
,
and fn:deep-equal
) with the semantics of the op:same-key
comparison
used for maps.
This specification defines the following comparison operators on numeric values.
Each comparison operator returns a boolean
value. If either, or both, operands are NaN
, false
is
returned.
Function | Meaning |
---|---|
op:numeric-equal |
Returns true if and only if the value of $arg1 is equal to the value of
$arg2 . |
op:numeric-less-than |
Returns true if and only if $arg1 is numerically less than
$arg2 . |
Returns true if and only if the value of $arg1
is equal to the value of
$arg2
.
Defines the semantics of the "eq" operator when applied to two numeric values, and is also used in defining the semantics of "ne", "le" and "ge".
op:numeric-equal ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:boolean |
General rules: see 4.3 Comparison operators on numeric values.
The two arguments will always have been converted so they have the same primitive type
(both xs:float
, both xs:double
, or both xs:decimal
.
The values are compared using the equality rules defined in [XML Schema Part 2: Datatypes Second Edition].
Positive and negative zero compare equal.
If $arg1
or $arg2
is
NaN
, the function returns false
.
Returns true
if and only if $arg1
is numerically less than
$arg2
.
Defines the semantics of the
lt
operator when applied to two numeric values, and is also used in defining the
semantics of le
, gt
, and ge
.
op:numeric-less-than ( |
||
$arg1 |
as xs:numeric , |
|
$arg2 |
as xs:numeric |
|
) as xs:boolean |
General rules: see 4.3 Comparison operators on numeric values.
The two arguments will always have been converted so they have the same primitive type
(both xs:float
, both xs:double
, or both xs:decimal
.
The values are compared using the ordering rules defined in [XML Schema Part 2: Datatypes Second Edition]. If the
ordering relation of the two values is imcomparable
(which happens when one or both
of them is NaN
, then the result is false.
For xs:float
and xs:double
values, positive infinity is
greater than all other non-NaN
values; negative infinity is less than all
other non-NaN
values. Positive and negative zero compare equal.
If $arg1
or $arg2
is
NaN
, the function returns false
.
The following functions are defined on numeric types. Each function returns a value of the same type as the type of its argument.
If the argument is the empty sequence, the empty sequence is returned.
For xs:float
and xs:double
arguments, if the
argument is "NaN", "NaN" is returned.
Except for fn:abs
, for xs:float
and
xs:double
arguments, if the argument is positive or
negative infinity, positive or negative infinity is returned.
Function | Meaning |
---|---|
fn:abs |
Returns the absolute value of $value . |
fn:ceiling |
Rounds $value upwards to a whole number. |
fn:floor |
Rounds $value downwards to a whole number. |
fn:round |
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near. |
fn:round-half-to-even |
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near. |
fn:is-NaN |
Returns true if the argument is the xs:float or xs:double value NaN. |
Note:
fn:round
and fn:round-half-to-even
produce the same result in all cases
except when the argument is exactly midway between two values with the required precision.
Other ways of rounding midway values can be achieved as follows:
Towards negative infinity: -fn:round(-$x)
Away from zero: fn:round(fn:abs($x))*fn:compare($x,0)
Towards zero: fn:abs(fn:round(-$x))*-fn:compare($x,0)
Returns the absolute value of $value
.
fn:abs ( |
||
$value |
as xs:numeric? |
|
) as xs:numeric? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
If $value
is negative the function returns -$value
, otherwise it
returns $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:positiveInteger
then the value of
$value
may be returned unchanged.
For xs:float
and xs:double
arguments, if the argument is
positive zero or negative zero, then positive zero is returned. If the argument is
positive or negative infinity, positive infinity is returned.
The expression fn:abs(10.5)
returns 10.5
.
The expression fn:abs(-10.5)
returns 10.5
.
Rounds $value
upwards to a whole number.
fn:ceiling ( |
||
$value |
as xs:numeric? |
|
) as xs:numeric? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the smallest (closest to negative infinity) number with no
fractional part that is not less than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
For xs:float
and xs:double
arguments, 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 and greater than -1,
negative zero is returned.
The expression fn:ceiling(10.5)
returns 11
.
The expression fn:ceiling(-10.5)
returns -10
.
Rounds $value
downwards to a whole number.
fn:floor ( |
||
$value |
as xs:numeric? |
|
) as xs:numeric? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the largest (closest to positive infinity) number with no
fractional part that is not greater than $value
.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
then the result may
be an instance of xs:integer
.
For xs:float
and xs:double
arguments, if the argument is
positive zero, then positive zero is returned. If the argument is negative zero, then
negative zero is returned.
The expression fn:floor(10.5)
returns 10
.
The expression fn:floor(-10.5)
returns -11
.
Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.
fn:round ( |
||
$value |
as xs:numeric? |
|
) as xs:numeric? |
fn:round ( |
||
$value |
as xs:numeric? , |
|
$precision |
as xs:integer |
|
) as xs:numeric? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (for example, if the
fractional part in $value
is exactly .5), the function returns the one that
is closest to positive infinity.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
and $precision
is
less than one, then the result may
be an instance of xs:integer
.
The single-argument version of this function produces the same result as the
two-argument version with $precision=0
(that is, it rounds to a whole
number).
When $value
is of type xs:float
and xs:double
:
If $value
is NaN, positive or negative zero, or positive or negative
infinity, then the result is the same as the argument.
For other values, the argument is cast to xs:decimal
using an
implementation of xs:decimal
that imposes no limits on the number of
digits that can be represented. The function is applied to this
xs:decimal
value, and the resulting xs:decimal
is
cast back to xs:float
or xs:double
as appropriate to
form the function result. If the resulting xs:decimal
value is zero,
then positive or negative zero is returned according to the sign of
$value
.
This function is typically used with a non-zero $precision
in financial
applications where the argument is of type xs:decimal
. For arguments of
type xs:float
and xs:double
the results may be
counter-intuitive. For example, consider round(35.425e0, 2)
. The result is
not 35.43, as might be expected, but 35.42. This is because the xs:double
written as 35.425e0 has an exact value equal to 35.42499999999..., which is closer to
35.42 than to 35.43.
The expression fn:round(2.5)
returns 3.0
.
The expression fn:round(2.4999)
returns 2.0
.
The expression fn:round(-2.5)
returns -2.0
. (Not the possible alternative, -3
).
The expression fn:round(1.125, 2)
returns 1.13
.
The expression fn:round(8452, -2)
returns 8500
.
The expression fn:round(3.1415e0, 2)
returns 3.14e0
.
Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.
fn:round-half-to-even ( |
||
$value |
as xs:numeric? |
|
) as xs:numeric? |
fn:round-half-to-even ( |
||
$value |
as xs:numeric? , |
|
$precision |
as xs:integer |
|
) as xs:numeric? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
General rules: see 4.4 Functions on numeric values.
The function returns the nearest (that is, numerically closest) value to
$value
that is a multiple of ten to the power of minus
$precision
. If two such values are equally near (e.g. if the fractional
part in $value
is exactly .500...), the function returns the one whose least
significant digit is even.
For the four types xs:float
,
xs:double
, xs:decimal
and xs:integer
, it is
guaranteed that if the type of $value
is an instance of type T then
the result will also be an instance of T. The result may
also be an instance of a type derived from one of these four by restriction. For example, if
$value
is an instance of xs:decimal
and $precision
is less than one, then the result may
be an instance of xs:integer
.
The first signature of this function produces the same result as the second signature
with $precision=0
.
For arguments of type xs:float
and xs:double
:
If the argument is NaN
, positive or negative zero, or positive or
negative infinity, then the result is the same as the argument.
In all other cases, the argument is cast to xs:decimal
using an
implementation of xs:decimal
that imposes no limits on the number of digits that
can be represented. The function is applied to this xs:decimal
value,
and the resulting xs:decimal
is cast back to xs:float
or
xs:double
as appropriate to form the function result. If the
resulting xs:decimal
value is zero, then positive or negative zero is
returned according to the sign of the original argument.
This function is typically used in financial applications where the argument is of type
xs:decimal
. For arguments of type xs:float
and
xs:double
the results may be counter-intuitive. For example, consider
round-half-to-even(xs:float(150.015), 2)
. The result is not 150.02 as
might be expected, but 150.01. This is because the conversion of the
xs:float
value represented by the literal 150.015 to an
xs:decimal
produces the xs:decimal
value 150.014999389...,
which is closer to 150.01 than to 150.02.
The expression fn:round-half-to-even(0.5)
returns 0.0
.
The expression fn:round-half-to-even(1.5)
returns 2.0
.
The expression fn:round-half-to-even(2.5)
returns 2.0
.
The expression fn:round-half-to-even(3.567812e+3, 2)
returns 3567.81e0
.
The expression fn:round-half-to-even(4.7564e-3, 2)
returns 0.0e0
.
The expression fn:round-half-to-even(35612.25, -2)
returns 35600
.
Returns true if the argument is the xs:float
or xs:double
value NaN.
fn:is-NaN ( |
||
$value |
as xs:anyAtomicType |
|
) as xs:boolean |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The function returns true if the argument is the xs:float
or xs:double
value NaN;
otherwise it returns false.
The expression fn:is-NaN(23)
returns false()
.
The expression fn:is-NaN("NaN")
returns false()
.
The expression fn:is-NaN(fn:number("twenty-three"))
returns true()
.
The expression fn:is-NaN(math:sqrt(-1))
returns true()
.
New in 4.0. Accepted 2022-09-20.
It is possible to convert strings to values of type xs:integer
,
xs:float
, xs:decimal
, or xs:double
using the constructor functions described in 18 Constructor functions
or using cast
expressions as described in 19 Casting.
In addition the fn:number
function is available to convert strings
to values of type xs:double
. It differs from the xs:double
constructor function in that any value outside the lexical space of the xs:double
datatype is converted to the xs:double
value NaN
.
Function | Meaning |
---|---|
fn:number |
Returns the value indicated by $value or, if $value is not
specified, the context item after atomization, converted to an xs:double .
|
Returns the value indicated by $value
or, if $value
is not
specified, the context item after atomization, converted to an xs:double
.
fn:number () as xs:double |
fn:number ( |
||
$value |
as xs:anyAtomicType? |
:= . |
) as xs:double |
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
Calling the zero-argument version of the function is defined to give the same result as
calling the single-argument version with the context item (.
). That is,
fn:number()
is equivalent to fn:number(.)
, as defined by
the rules that follow.
If $value
is the empty sequence or if $value
cannot be converted
to an xs:double
, the xs:double
value NaN
is
returned.
Otherwise, $value
is converted to an xs:double
following the
rules of 19.1.2.2 Casting to xs:double. If the conversion to xs:double
fails, the xs:double
value NaN
is returned.
A dynamic error is raised [err:XPDY0002]XP
if $value
is omitted and the context item is absentDM40.
As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item is a sequence containing more than one atomic value.
XSD 1.1 allows the string +INF
as a representation of positive infinity;
XSD 1.0 does not. It is ·implementation-defined· whether XSD 1.1 is
supported.
Generally fn:number
returns NaN
rather than raising a dynamic
error if the argument cannot be converted to xs:double
. However, a type
error is raised in the usual way if the supplied argument cannot be atomized or if the
result of atomization does not match the required argument type.
The expression fn:number($item1/quantity)
returns 5.0e0
.
The expression fn:number($item2/description)
returns xs:double('NaN')
.
Assume that the context item is the xs:string
value "15
".
Then fn:number()
returns 1.5e1
.
Function | Meaning |
---|---|
fn:format-integer |
Formats an integer according to a given picture string, using the conventions of a given natural language if specified. |
Formats an integer according to a given picture string, using the conventions of a given natural language if specified.
fn:format-integer ( |
||
$value |
as xs:integer? , |
|
$picture |
as xs:string |
|
) as xs:string |
fn:format-integer ( |
||
$value |
as xs:integer? , |
|
$picture |
as xs:string , |
|
$lang |
as xs:string? |
|
) as xs:string |
The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default language.
The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is an empty sequence, the function returns a zero-length
string.
In all other cases, the $picture
argument describes the format in which
$value
is output.
The rules that follow describe how non-negative numbers are output. If the value of
$value
is negative, the rules below are applied to the absolute value of
$value
, and a minus sign is prepended to the result.
The value of $picture
consists of a primary format token, optionally
followed by a format modifier. The primary format token is always present and
must not be zero-length. If the string contains one or more
semicolons then everything that precedes the last semicolon is taken as the primary
format token and everything that follows is taken as the format modifier; if the string
contains no semicolon then the entire picture is taken as the primary format token, and
the format modifier is taken to be absent (which is equivalent to supplying a
zero-length string).
The primary format token is classified as one of the following:
A decimal-digit-pattern made up of optional-digit-signs, mandatory-digit-signs, and grouping-separator-signs.
The optional-digit-sign is the character "#".
A mandatory-digit-sign is a ·character· in Unicode category Nd. All
mandatory-digit-signs within the format token
must be from the same digit family, where a digit
family is a sequence of ten consecutive characters in Unicode category Nd,
having digit values 0 through 9. Within the format token, these digits are
interchangeable: a three-digit number may thus be indicated equivalently by
000
, 001
, or 999
.
a grouping-separator-sign is a non-alphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.
If the primary format token contains at least one Unicode digit then it is taken
as a decimal digit pattern, and in this case it must match the
regular expression ^((\p{Nd}|#|[^\p{N}\p{L}])+?)$
. If it contains a
digit but does not match this pattern, a dynamic error is raised [err:FODF1310].
Note:
If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.
There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs, and (if present) these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-sign must not appear at the start or end of the decimal-digit-pattern, nor adjacent to another grouping-separator-sign.
The corresponding output format is a decimal number, using this digit family, with
at least as many digits as there are mandatory-digit-signs in the
format token. Thus, a format token 1
generates the sequence 0 1
2 ... 10 11 12 ...
, and a format token 01
(or equivalently,
00
or 99
) generates the sequence 00 01 02 ...
09 10 11 12 ... 99 100 101
. A format token of ١
(Arabic-Indic digit one) generates the sequence ١
then ٢
then ٣
...
The grouping-separator-signs are handled as follows:
The position of grouping separators within the format token, counting backwards from the last digit, indicates the position of grouping separators to appear within the formatted number, and the character used as the grouping-separator-sign within the format token indicates the character to be used as the corresponding grouping separator in the formatted number.
More specifically, the position of a grouping separator is the number of optional-digit-signs and mandatory-digit-signs appearing between the grouping separator and the right-hand end of the primary format token.
Grouping separators are defined to be regular if the following conditions apply:
There is at least one grouping separator.
Every grouping separator is the same character (call it C).
There is a positive integer G (the grouping size) such that:
The position of every grouping separator is an integer multiple of G, and
Every positive integer multiple of G that is less than the number of optional-digit-signs and mandatory-digit-signs in the primary format token is the position of a grouping separator.
The grouping separator template is a (possibly infinite) set of (position, character) pairs.
If grouping separators are regular, then the grouping separator template contains one pair of the form (n×G, C)
for every positive integer n where G is the grouping size and C is the grouping character.
Otherwise (when grouping separators are not regular), the grouping separator template contains one pair of the form
(P, C)
for every grouping separator found in the primary formatting token, where C is the grouping
separator character and P is its position.
Note:
If there are no grouping separators, then the grouping separator template is an empty set.
The number is formatted as follows:
Let S1 be the result of formatting the supplied number in decimal notation as if by casting
it to xs:string
.
Let S2 be the result of padding S1 on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number of mandatory-digit-signs in the primary format token.
Let S3 be the result of replacing all decimal digits (0-9) in S2 with the corresponding digits from the selected digit family.
Let S4 be the result of inserting grouping separators into S3: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S3, insert character C into S3 at position P, counting from the right-hand end.
Let S5 be the result of converting S4 into ordinal form, if an ordinal modifier is present, as described below.
The result of the function is then S5.
The format token A
, which generates the sequence A B C ... Z AA
AB AC...
.
The format token a
, which generates the sequence a b c ... z aa
ab ac...
.
The format token i
, which generates the sequence i ii iii iv v
vi vii viii ix x ...
.
The format token I
, which generates the sequence I II III IV V
VI VII VIII IX X ...
.
The format token w
, which generates numbers written as lower-case
words, for example in English, one two three four ...
The format token W
, which generates numbers written as upper-case
words, for example in English, ONE TWO THREE FOUR ...
The format token Ww
, which generates numbers written as title-case
words, for example in English, One Two Three Four ...
Any other format token, which indicates a numbering sequence in which that token
represents the number 1 (one) (but see the note below).
It is ·implementation-defined· which
numbering sequences, additional to those listed above, are supported. If an
implementation does not support a numbering sequence represented by the given
token, it must use a format token of 1
.
Note:
In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example (see also the example below) is classical Greek where a dexia keraia (x0374, ʹ) and sometimes an aristeri keraia (x0375, ͵) is added.
For all format tokens other than a decimal-digit-pattern, there
may be ·implementation-defined· lower and upper bounds on the range of numbers that
can be formatted using this format token; indeed, for some numbering sequences there may
be intrinsic limits. For example, the format token ①
(circled
digit one, ①) has a range imposed by the Unicode character repertoire — zero to 20
in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering
sequences described above any upper bound imposed by the implementation must
not be less than 1000 (one thousand) and any lower bound must not be
greater than 1. Numbers that fall outside this range must be
formatted using the format token 1
.
The above expansions of numbering sequences for format tokens such as a
and
i
are indicative but not prescriptive. There are various conventions in
use for how alphabetic sequences continue when the alphabet is exhausted, and differing
conventions for how roman numerals are written (for example, IV
versus
IIII
as the representation of the number 4). Sometimes alphabetic
sequences are used that omit letters such as i
and o
. This
specification does not prescribe the detail of any sequence other than those sequences
consisting entirely of decimal digits.
Many numbering sequences are language-sensitive. This applies especially to the sequence
selected by the tokens w
, W
and Ww
. It also
applies to other sequences, for example different languages using the Cyrillic alphabet
use different sequences of characters, each starting with the letter #x410 (Cyrillic
capital letter A). In such cases, the $lang
argument specifies which
language's conventions are to be used. If the argument is specified, the value
should be either an empty sequence or a value that would be valid
for the xml:lang
attribute (see [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). Note that this
permits the identification of sublanguages based on country codes (from ISO 3166-1) as
well as identification of dialects and regions within a country.
The set of languages for which numbering is supported is ·implementation-defined·. If the $lang
argument is absent, or is
set to an empty sequence, or is invalid, or is not a language supported by the
implementation, then the number is formatted using the default language from the dynamic
context.
The format modifier must be a string that matches the regular
expression ^([co](\(.+\))?)?[at]?$
. That is, if it is present it must
consist of one or more of the following, in order:
either c
or o
, optionally followed by a sequence of
characters enclosed between parentheses, to indicate cardinal or ordinal numbering
respectively, the default being cardinal numbering
either a
or t
, to indicate alphabetic or traditional
numbering respectively, the default being ·implementation-defined·.
If the o
modifier is present, this indicates a request to output ordinal
numbers rather than cardinal numbers. For example, in English, when used with the format
token 1
, this outputs the sequence 1st 2nd 3rd 4th ...
, and
when used with the format token w
outputs the sequence first second
third fourth ...
.
The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string.
It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.
The use of the a
or t
modifier disambiguates between numbering
sequences that use letters. In many languages there are two commonly used numbering
sequences that use letters. One numbering sequence assigns numeric values to letters in
alphabetic sequence, and the other assigns numeric values to each letter in some other
manner traditional in that language. In English, these would correspond to the numbering
sequences specified by the format tokens a
and i
. In some
languages, the first member of each sequence is the same, and so the format token alone
would be ambiguous. In the absence of the a
or t
modifier, the
default is ·implementation-defined·.
A dynamic error is raised [err:FODF1310] if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.
Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.
The following notes apply when a decimal-digit-pattern is used:
If grouping-separator-signs
appear at regular intervals within the format token, then the sequence is extrapolated to
the left, so grouping separators will be used in the formatted number at every
multiple of N. For example, if the format token is 0'000
then the number one million will be formatted as 1'000'000
, while the
number fifteen will be formatted as 0'015
.
The only purpose of optional-digit-signs is to mark the position of
grouping-separator-signs. For example, if the format token is
#'##0
then the number one million will be formatted as
1'000'000
, while the number fifteen will be formatted as
15
. A grouping separator is included in the formatted number only
if there is a digit to its left, which will only be the case if either (a) the
number is large enough to require that digit, or (b) the number of
mandatory-digit-signs in the format token requires insignificant
leading zeros to be present.
Grouping separators are not designed for effects such as
formatting a US telephone number as (365)123-9876
. In general they are not
suitable for such purposes because (a) only single characters are allowed, and (b) they
cannot appear at the beginning or end of the number.
Numbers will never be truncated. Given the decimal-digit-pattern
01
, the number three hundred will be output as 300
,
despite the absence of any optional-digit-sign.
The following notes apply when ordinal numbering is selected using the o
modifier.
In some languages, the form of numbers (especially ordinal numbers) varies depending
on the grammatical context: they may have different genders and may decline with the
noun that they qualify. In such cases the string appearing in parentheses after the
letter c
or o
may be used to indicate the variation of the
cardinal or ordinal number required.
The way in which the variation is indicated will depend on the conventions of the language.
For inflected languages that vary the ending of the word, the approach recommended
in the previous version of this specification was to indicate the required ending,
preceded by a hyphen: for example in German, appropriate values might be
o(-e)
, o(-er)
, o(-es)
, o(-en)
.
Another approach, which might usefully be adopted by an implementation based on the
open-source ICU localization library [ICU], or any other library making use of the
Unicode Common Locale Data Repository [Unicode CLDR], is to allow the value in parentheses
to be the name of a registered numbering rule set for the language in question,
conventionally prefixed with a percent sign: for example,
o(%spellout-ordinal-masculine)
, or c(%spellout-cardinal-year)
.
The expression format-integer(123, '0000')
returns "0123"
.
format-integer(123, 'w')
might return "one hundred and
twenty-three"
Ordinal numbering in Italian: The specification "1;o(-º)"
with $lang
equal to
it
, if supported, should produce the sequence:
1º 2º 3º 4º ...
The specification "Ww;o"
with $lang
equal to
it
, if supported, should produce the sequence:
Primo Secondo Terzo Quarto Quinto ...
The expression format-integer(21, '1;o', 'en')
returns "21st"
.
format-integer(14, 'Ww;o(-e)', 'de')
might return
"Vierzehnte"
The expression format-integer(7, 'a')
returns "g"
.
The expression format-integer(57, 'I')
returns "LVII"
.
The expression format-integer(1234, '#;##0;')
returns "1;234"
.
This section defines a function for formatting decimal and floating point numbers.
Function | Meaning |
---|---|
fn:format-number |
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context. |
Note:
This function can be used to format any numeric quantity, including an integer. For integers, however,
the fn:format-integer
function offers additional possibilities. Note also that the picture
strings used by the two functions are not 100% compatible, though they share some options in common.
Decimal formats are defined in the static context, and the way they are defined is therefore outside the scope of this specification. XSLT and XQuery both provide custom syntax for creating a decimal format.
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are ·implementation-defined·.
Each decimal format provides a set of named properties, described in the following table:
Name | Type | Usage (non-normative) |
---|---|---|
decimal-separator |
A single ·character· | Defines the character used to represent the decimal point (typically ".") both in the picture string and in the formatted number. |
grouping-separator |
A single ·character· | Defines the character used to separate groups of digits (typically ",") both in the picture string and in the formatted number. |
exponent-separator |
A single ·character· | Defines the character used to separate the mantissa from the exponent in scientific notation (typically "e") both in the picture string and in the formatted number. |
infinity |
A ·string· | Defines the string used to represent the value positive or negative infinity in the formatted number (typically "Infinity") |
minus-sign |
A single ·character· | Defines the character used as a minus sign in the formatted number if there is no subpicture for formatting negative numbers (typically "-", x2D) |
NaN |
A ·string· | Defines the string used to represent the value NaN in the formatted number |
percent |
A single ·character· | Defines the character used as a percent sign (typically "%") both in the picture string and in the formatted number |
per-mille |
A single ·character· | Defines the character used as a per-mille sign (typically "‰", x2030) both in the picture string and in the formatted number |
zero-digit |
A single ·character·, which must be a character in Unicode category Nd with decimal digit value 0 (zero) | Defines the characters used in the picture string to represent a mandatory digit: for example, if the zero-digit is "0" then any of the digits "0" to "9" may be used (interchangeably) in the picture string to represent a mandatory digit, and in the formatted number the characters "0" to "9" will be used to represent the digits zero to nine. |
digit |
A single ·character· | Defines the character used in the picture string to represent an optional digit (typically "#") |
pattern-separator |
A single ·character· | Defines the character used in the picture string to separate the positive and negative subpictures (typically ";") |
Note:
A phrase such as "The minus-signXP31 character" is to be read as "the character assigned to the minus-signXP31 property in the relevant decimal format within the static context".
[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the character that is the value of the zero-digitXP31 property.
[Definition] The optional digit character is the character that is the value of the digitXP31 property.
For any named or unnamed decimal format, the properties representing characters used in a ·picture string· must have distinct values. These properties are decimal-separatorXP31 , grouping-separatorXP31, exponent-separatorXP31, percentXP31, per-milleXP31, digitXP31, and pattern-separatorXP31. Furthermore, none of these properties may be equal to any ·character· in the ·decimal digit family·.
Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.
fn:format-number ( |
||
$value |
as xs:numeric? , |
|
$picture |
as xs:string |
|
) as xs:string |
fn:format-number ( |
||
$value |
as xs:numeric? , |
|
$picture |
as xs:string , |
|
$decimal-format-name |
as union(xs:string, xs:QName)? |
|
) as xs:string |
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on decimal formats, and namespaces.
The effect of the two-argument form of the function is equivalent to calling the three-argument form with an empty sequence as the value of the third argument.
The function formats $value
as a string using the ·picture string· specified by the
$picture
argument and the decimal-format named by the
$decimal-format-name
argument, or the unnamed decimal-format, if there
is no $decimal-format-name
argument. The syntax of the picture string is
described in 4.7.3 Syntax of the picture string.
The $value
argument may be of any numeric data type
(xs:double
, xs:float
, xs:decimal
, or their
subtypes including xs:integer
). Note that if an xs:decimal
is
supplied, it is not automatically promoted to an xs:double
, as such
promotion can involve a loss of precision.
If the supplied value of the $value
argument is an empty sequence, the
function behaves as if the supplied value were the xs:double
value
NaN
.
The value of $decimal-format-name
, if present and non-empty,
must be either an xs:QName
,
or a string which after removal of leading and trailing
whitespace is in the form of an EQName
as defined in the XPath 4.0
grammar, that is one of the following:
A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).
A URIQualifiedName
using the syntax Q{uri}local
, where
the URI can be zero-length to indicate a name in no namespace.
The decimal format that is used is the decimal format in the static context whose name
matches $decimal-format-name
if supplied, or the unnamed decimal format in
the static context otherwise.
The evaluation of the fn:format-number
function takes place in two
phases, an analysis phase described in 4.7.4 Analyzing the picture string and a
formatting phase described in 4.7.5 Formatting the number.
The analysis phase takes as its inputs the ·picture string· and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.
The result of the function is the formatted string representation of the supplied number.
A dynamic error is raised [err:FODF1280]
if
the $decimal-format-name
argument is supplied as an xs:string
that is neither a valid lexical QName nor a
valid URIQualifiedName
, or if it uses a prefix that is not found in the
statically known namespaces, or if the static context does not contain a declaration of
a decimal-format with a matching expanded QName. If the processor is able to detect the
error statically (for example, when the argument is supplied as a string literal), then
the processor may optionally signal this as a static error.
A string is an ordered sequence of characters, and this specification uses terms such as "left" and "right", "preceding" and "following" in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.
The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is ".", the grouping separator is ",", the minus-sign is "-", and the percent-sign is "%".
The expression format-number(12345.6, '#,###.00')
returns "12,345.60"
.
The expression format-number(12345678.9, '9,999.99')
returns "12,345,678.90"
.
The expression format-number(123.9, '9999')
returns "0124"
.
The expression format-number(0.14, '01%')
returns "14%"
.
The expression format-number(-6, '000')
returns "-006"
.
The following example assumes the existence of a decimal format named 'ch' in which
the grouping separator is ʹ
and the decimal separator is
·
:
The expression format-number(1234.5678, '#ʹ##0·00',
'ch')
returns "1ʹ234·57"
.
The following examples assume that the exponent separator is in decimal format 'fortran' is 'E':
The expression format-number(1234.5678, '00.000E0', 'fortran')
returns "12.346E2"
.
The expression format-number(0.234, '0.0E0', 'fortran')
returns "2.3E-1"
.
The expression format-number(0.234, '#.00E0', 'fortran')
returns "0.23E0"
.
The expression format-number(0.234, '.00E0', 'fortran')
returns ".23E0"
.
Note:
This differs from the format-number
function previously defined in XSLT 2.0 in that
any digit can be used in the picture string to represent a mandatory digit: for example the picture
strings '000', '001', and '999' are equivalent. The digits will all be from the same decimal digit family,
specifically, the sequence of ten consecutive digits starting with the digit assigned to the zero-digit property.
This change is to align format-number
(which previously used '000') with format-dateTime
(which used '001').
[Definition] The formatting of a number is controlled by a picture string. The picture string is a sequence of ·characters·, in which the characters assigned to the properties decimal-separatorXP31 , exponent-separatorXP31, grouping-separatorXP31, and digitXP31, and pattern-separatorXP31 and the members of the ·decimal digit family·, are classified as active characters, and all other characters (including the values of the properties percentXP31 and per-milleXP31) are classified as passive characters.
A dynamic error is raised [err:FODF1310] if the ·picture string· does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".
A picture-string consists either of a sub-picture, or of two sub-pictures separated by the pattern-separatorXP31 character. A picture-string must not contain more than one instance of the pattern-separatorXP31 character. If the picture-string contains two sub-pictures, the first is used for positive and unsigned zero values and the second for negative values.
A sub-picture must not contain more than one instance of the decimal-separatorXP31 character.
A sub-picture must not contain more than one instance of the percentXP31 or per-milleXP31 characters, and it must not contain one of each.
The mantissa part of a sub-picture (defined below) must contain at least one character that is either an ·optional digit character· or a member of the ·decimal digit family·.
A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.
A sub-picture must not contain a grouping-separatorXP31 character that appears adjacent to a decimal-separatorXP31 character, or in the absence of a decimal-separatorXP31 character, at the end of the integer part.
A sub-picture must not contain two adjacent instances of the grouping-separatorXP31 character.
The integer part of a sub-picture (defined below) must not contain a member of the ·decimal digit family· that is followed by an instance of the ·optional digit character·. The fractional part of a sub-picture (defined below) must not contain an instance of the ·optional digit character· that is followed by a member of the ·decimal digit family·.
A character that matches the exponent-separatorXP31 property is treated as an exponent-separator-sign if it is both preceded and followed within the sub-picture by an active character. Otherwise, it is treated as a passive character. A sub-picture must not contain more than one character that is treated as an exponent-separator-sign.
A sub-picture that contains a percentXP31 or per-milleXP31 character must not contain a character treated as an exponent-separator-sign.
If a sub-picture contains a character treated as an exponent-separator-sign then this must be followed by one or more characters that are members of the ·decimal digit family·, and it must not be followed by any active character that is not a member of the ·decimal digit family·.
The mantissa part of the sub-picture is defined as the part that appears to the left of the exponent-separator-sign if there is one, or the entire sub-picture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponent-separator-sign; if there is no exponent-separator-sign then the exponent part is absent.
The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separatorXP31 character if there is one, or the entire mantissa part otherwise.
The fractional part of the sub-picture is defined as that part of the mantissa part that appears to the right of the decimal-separatorXP31 character if there is one, or the part that appears to the right of the rightmost active character otherwise. The fractional part may be zero-length.
This phase of the algorithm analyzes the ·picture string· and the properties from the selected decimal format in the static context, and it has the effect of setting the values of various variables, which are used in the subsequent formatting phase. These variables are listed below. Each is shown with its initial setting and its datatype.
Several variables are associated with each sub-picture. If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positive and unsigned zero numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture.
The variables are as follows:
The integer-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture. For each grouping-separatorXP31 character that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the integer part of the sub-picture and to the right of the grouping-separatorXP31 character.
The grouping is defined to be regular if the following conditions apply:
There is an least one grouping-separator in the integer part of the sub-picture.
There is a positive integer G (the grouping size) such that the position of every grouping-separator in the integer part of the sub-picture is a positive integer multiple of G.
Every position in the integer part of the sub-picture that is a positive integer multiple of G is occupied by a grouping-separator.
If the grouping is regular, then the integer-part-grouping-positions sequence contains all integer multiples of G as far as necessary to accommodate the largest possible number.
The minimum-integer-part-size is an integer indicating the minimum number of digits that will appear to the left of the decimal-separator character. It is initially set to the number of ·decimal digit family· characters found in the integer part of the sub-picture, but may be adjusted as described below.
Note:
There is no maximum integer part size. All significant digits in the integer part of the number will be displayed, even if this exceeds the number of ·optional digit character· and ·decimal digit family· characters in the subpicture.
The scaling factor is a non-negative integer used to determine the scaling of the mantissa in exponential notation. It is set to the number of ·decimal digit family· characters found in the integer part of the sub-picture.
The prefix is set to contain all passive characters in the sub-picture to the left of the leftmost active character. If the picture string contains only one sub-picture, the prefix for the negative sub-picture is set by concatenating the minus-signXP31 character and the prefix for the positive sub-picture (if any), in that order.
The fractional-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the fractional part of the sub-picture. For each grouping-separatorXP31 character that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the fractional part of the sub-picture and to the left of the grouping-separatorXP31 character.
Note:
There is no need to extrapolate grouping positions on the fractional side, because the number of digits in the output will never exceed the number of ·optional digit character· and ·decimal digit family· characters in the fractional part of the sub-picture.
The minimum-fractional-part-size is set to the number of ·decimal digit family· characters found in the fractional part of the sub-picture.
The maximum-fractional-part-size is set to the total number of ·optional digit character· and ·decimal digit family· characters found in the fractional part of the sub-picture.
If the effect of the above rules is that minimum-integer-part-size and maximum-fractional-part-size are both zero, then an adjustment is applied as follows:
If an exponent separator is present then:
minimum-fractional-part-size is changed to 1 (one).
maximum-fractional-part-size is changed to 1 (one).
Note:
This has the effect that with the picture #.e9
, the value 0.123
is formatted as 0.1e0
Otherwise:
minimum-integer-part-size is changed to 1 (one).
Note:
This has the effect that with the picture #
, the value 0.23
is formatted
as 0
If all the following conditions are true:
An exponent separator is present
The minimum-integer-part-size is zero
There is at least one ·optional digit character· in the integer part of the sub-picture
then the minimum-integer-part-size is changed to 1 (one).
Note:
This has the effect that with the picture .9e9
, the value 0.1
is formatted
as .1e0
, while with the picture #.9e9
, it is formatted as 0.1e0
If (after making the above adjustments) the minimum-integer-part-size and the minimum-fractional-part-size are both zero, then the minimum-fractional-part-size is set to 1 (one).
The minimum-exponent-size is set to the number of ·decimal digit family· characters found in the exponent part of the sub-picture if present, or zero otherwise.
Note:
The rules for the syntax of the picture string ensure that if an exponent separator is present, then the minimum-exponent-size will always be greater than zero.
The suffix is set to contain all passive characters to the right of the rightmost active character in the sub-picture.
Note:
If there is only one sub-picture, then all variables for positive numbers and negative numbers will be the same, except for prefix: the prefix for negative numbers will be preceded by the minus-signXP31 character.
This section describes the second phase of processing of the
fn:format-number
function. This phase takes as input a number to be formatted
(referred to as the input number), and the variables set up by
analyzing the decimal format in the static context and the
·picture string·, as described above.
The result of this phase is a string, which forms the return value of
the fn:format-number
function.
The algorithm for this second stage of processing is as follows:
If the input number is NaN (not a number), the result is the value of the pattern separatorXP31 property (with no prefix or suffix).
In the rules below, the positive sub-picture and its associated variables are used
if the input number is positive, and the negative sub-picture and its associated
variables are used if it is negative. For xs:double
and xs:float
,
negative zero is taken as negative, positive zero as positive. For xs:decimal
and xs:integer
, the positive sub-picture is used for zero.
The adjusted number is determined as follows:
If the sub-picture contains a percentXP31 character, the adjusted number is the input number multiplied by 100.
If the sub-picture contains a per-milleXP31 character, the adjusted number is the input number multiplied by 1000.
Otherwise, the adjusted number is the input number.
If the multiplication causes numeric overflow, no error occurs, and the adjusted number is positive or negative infinity as appropriate.
If the adjusted number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the value of the infinityXP31 property, and the appropriate suffix.
If the minimum exponent size is non-zero, and the adjusted number is non-zero, then the adjusted number is scaled to establish a mantissa and an integer exponent. The mantissa and exponent are chosen such that all the following conditions are true:
The primitive type of the mantissa is the same as the primitive type of the adjusted number (integer, decimal, float, or double).
The mantissa multiplied by ten to the power of the exponent is equal to the adjusted number.
The mantissa (unless it is zero) is less than 10N, and at least 10N-1, where N is the scaling factor.
If the minimum exponent size is zero, then the mantissa is the adjusted number and there is no exponent.
If the minimum exponent size is non-zero and the adjusted number is zero, then the mantissa is the adjusted number and the exponent is zero.
The mantissa is converted (if necessary) to
an xs:decimal
value,
using an implementation of xs:decimal
that imposes no limits on the
totalDigits
or fractionDigits
facets. If there are several
such values that
are numerically equal to the mantissa (bearing in mind that if the
mantissa is an xs:double
or xs:float
, the comparison will be done by
converting the decimal value back to an xs:double
or xs:float
), the one that
is chosen should be one with the smallest possible number of digits
not counting leading or trailing zeroes (whether significant or insignificant).
For example, 1.0 is preferred to
0.9999999999, and 100000000 is preferred to 100000001. This value is then
rounded so that it uses no more than maximum-fractional-part-size
digits in
its fractional part. The rounded number is defined to be the result of
converting the mantissa to an xs:decimal
value, as described above,
and then calling the function fn:round-half-to-even
with this converted number
as the first argument and the maximum-fractional-part-size
as the second
argument, again with no limits on the totalDigits
or fractionDigits
in the
result.
The absolute value of the rounded number is converted to a string in decimal notation, using the digits in the ·decimal digit family· to represent the ten decimal digits, and the decimal-separatorXP31 character to separate the integer part and the fractional part. This string must always contain a decimal-separatorXP31, and it must contain no leading zeroes and no trailing zeroes. The value zero will at this stage be represented by a decimal-separatorXP31 on its own.
If the number of digits to the left of the decimal-separatorXP31 character is less than minimum-integer-part-size, leading zero digitXP31 characters are added to pad out to that size.
If the number of digits to the right of the decimal-separatorXP31 character is less than minimum-fractional-part-size, trailing zero digitXP31 characters are added to pad out to that size.
For each integer N in the integer-part-grouping-positions list, a grouping-separatorXP31 character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimal-separatorXP31 character, if there is such a digit.
For each integer N in the fractional-part-grouping-positions list, a grouping-separatorXP31 character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimal-separatorXP31 character, if there is such a digit.
If there is no decimal-separatorXP31 character in the sub-picture, or if there are no digits to the right of the decimal-separator character in the string, then the decimal-separator character is removed from the string (it will be the rightmost character in the string).
If an exponent exists, then the string produced from the mantissa as described above is extended with the following, in order: (a) the exponent-separatorXP31 character; (b) if the exponent is negative, the minus-signXP31 character; (c) the value of the exponent represented as a decimal integer, extended if necessary with leading zeroes to make it up to the minimum exponent size, using digits taken from the ·decimal digit family·.
The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.
The functions in this section perform trigonometric and other mathematical calculations on xs:double
values. They
are provided primarily for use in applications performing geometrical computation, for example when generating
SVG graphics.
Functions are provided to support the six most commonly used trigonometric calculations: sine, cosine and tangent, and their inverses arc sine, arc cosine, and arc tangent. Other functions such as secant, cosecant, and cotangent are not provided because they are easily computed in terms of these six.
The functions in this section (with the exception of math:pi
)
are specified by reference to [IEEE 754-2008], where
they appear as Recommended operations in section 9. IEEE defines
these functions for a variety of floating point formats; this specification
defines them only for xs:double
values. The IEEE specification
applies with the following caveats:
IEEE states that the preferred quantum is language-defined. In this specification, it is ·implementation-defined·.
IEEE states that certain functions should raise the inexact exception if the result is inexact. In this specification, this exception if it occurs does not result in an error. Any diagnostic information is outside the scope of this specification.
IEEE defines various rounding algorithms for inexact results, and states that the choice of rounding direction, and the mechanisms for influencing this choice, are language-defined. In this specification, the rounding direction and any mechanisms for influencing it are ·implementation-defined·.
Certain operations (such as taking the square root of a negative number)
are defined in IEEE to signal the invalid operation exception and return a
quiet NaN. In this specification, such operations return NaN
and do not raise an error. The same policy applies to operations (such as taking
the logarithm of zero) that raise a divide-by-zero exception. Any diagnostic
information is outside the scope of this specification.
Operations whose mathematical result is greater than the largest finite xs:double
value are defined in IEEE to signal the overflow exception; operations whose mathematical
result is closer to zero than the smallest non-zero xs:double
value are similarly
defined in IEEE to signal the underflow exception. The treatment of these exceptions in
this specification is defined in 4.2 Arithmetic operators on numeric values.
Function | Meaning |
---|---|
math:pi |
Returns an approximation to the mathematical constant π. |
math:exp |
Returns the value of ex where x is the argument value. |
math:exp10 |
Returns the value of 10 x, where x is the supplied argument value. |
math:log |
Returns the natural logarithm of the argument. |
math:log10 |
Returns the base-ten logarithm of the argument. |
math:pow |
Returns the result of raising the first argument to the power of the second. |
math:sqrt |
Returns the non-negative square root of the argument. |
math:sin |
Returns the sine of the argument. The argument is an angle in radians. |
math:cos |
Returns the cosine of the argument. The argument is an angle in radians. |
math:tan |
Returns the tangent of the argument. The argument is an angle in radians. |
math:asin |
Returns the arc sine of the argument. |
math:acos |
Returns the arc cosine of the argument. |
math:atan |
Returns the arc tangent of the argument. |
math:atan2 |
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis. |
Returns an approximation to the mathematical constant π.
math:pi () as xs:double |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
This function returns the xs:double
value whose lexical representation is
3.141592653589793e0
The expression 2*math:pi()
returns 6.283185307179586e0
.
The expression 60 * (math:pi() div 180)
converts an angle of 60 degrees
to radians.
Returns the value of ex where x is the argument value.
math:exp ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical constant e raised to the power of
$value
, as defined in the [IEEE 754-2008] specification of
the exp
function applied to 64-bit binary floating point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
The expression math:exp(())
returns ()
.
The expression math:exp(0)
returns 1.0e0
.
The expression math:exp(1)
returns 2.7182818284590455e0
(approximately).
The expression math:exp(2)
returns 7.38905609893065e0
.
The expression math:exp(-1)
returns 0.36787944117144233e0
.
The expression math:exp(math:pi())
returns 23.140692632779267e0
.
The expression math:exp(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:exp(xs:double('INF'))
returns xs:double('INF')
.
The expression math:exp(xs:double('-INF'))
returns 0.0e0
.
Returns the value of 10
x, where x is the supplied argument value.
math:exp10 ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is ten raised to the power of $value
, as defined in the
[IEEE 754-2008] specification of the exp10
function applied
to 64-bit binary floating point values.
The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.
The expression math:exp10(())
returns ()
.
The expression math:exp10(0)
returns 1.0e0
.
The expression math:exp10(1)
returns 1.0e1
.
The expression math:exp10(0.5)
returns 3.1622776601683795e0
.
The expression math:exp10(-1)
returns 1.0e-1
.
The expression math:exp10(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:exp10(xs:double('INF'))
returns xs:double('INF')
.
The expression math:exp10(xs:double('-INF'))
returns 0.0e0
.
Returns the natural logarithm of the argument.
math:log ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the natural logarithm of $value
, as defined in the
[IEEE 754-2008] specification of the log
function applied
to 64-bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is
zero, the result is -INF
, and if it is negative, the result is NaN
.
The expression math:log(())
returns ()
.
The expression math:log(0)
returns xs:double('-INF')
.
The expression math:log(math:exp(1))
returns 1.0e0
.
The expression math:log(1.0e-3)
returns -6.907755278982137e0
.
The expression math:log(2)
returns 0.6931471805599453e0
.
The expression math:log(-1)
returns xs:double('NaN')
.
The expression math:log(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:log(xs:double('INF'))
returns xs:double('INF')
.
The expression math:log(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the base-ten logarithm of the argument.
math:log10 ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the base-10 logarithm of $value
, as defined in the
[IEEE 754-2008] specification of the log10
function applied
to 64-bit binary floating point values.
The treatment of divideByZero
and invalidOperation
exceptions
is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is
zero, the result is -INF
, and if it is negative, the result is NaN
.
The expression math:log10(())
returns ()
.
The expression math:log10(0)
returns xs:double('-INF')
.
The expression math:log10(1.0e3)
returns 3.0e0
.
The expression math:log10(1.0e-3)
returns -3.0e0
.
The expression math:log10(2)
returns 0.3010299956639812e0
.
The expression math:log10(-1)
returns xs:double('NaN')
.
The expression math:log10(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:log10(xs:double('INF'))
returns xs:double('INF')
.
The expression math:log10(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the result of raising the first argument to the power of the second.
math:pow ( |
||
$x |
as xs:double? , |
|
$y |
as xs:numeric |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $x
is the empty sequence, the function returns the empty sequence.
If $y
is an instance of xs:integer
, the result is
$x
raised to the power of $y
as defined in the [IEEE 754-2008] specification of the pown
function applied to a
64-bit binary floating point value and an integer.
Otherwise $y
is converted to an xs:double
by numeric
promotion, and the result is $x
raised to the power of
$y
as defined in the [IEEE 754-2008] specification of the
pow
function applied to two 64-bit binary floating point values.
The treatment of the divideByZero
and invalidOperation
exceptions is defined in 4.2 Arithmetic operators on numeric values. Some of the consequences are
illustrated in the examples below.
The expression math:pow((), 93.7)
returns ()
.
The expression math:pow(2, 3)
returns 8.0e0
.
The expression math:pow(-2, 3)
returns -8.0e0
.
The expression math:pow(2, -3)
returns 0.125e0
.
The expression math:pow(-2, -3)
returns -0.125e0
.
The expression math:pow(2, 0)
returns 1.0e0
.
The expression math:pow(0, 0)
returns 1.0e0
.
The expression math:pow(xs:double('INF'), 0)
returns 1.0e0
.
The expression math:pow(xs:double('NaN'), 0)
returns 1.0e0
.
The expression math:pow(-math:pi(), 0)
returns 1.0e0
.
The expression math:pow(0e0, 3)
returns 0.0e0
.
The expression math:pow(0e0, 4)
returns 0.0e0
.
The expression math:pow(-0e0, 3)
returns -0.0e0
.
The expression math:pow(0, 4)
returns 0.0e0
.
The expression math:pow(0e0, -3)
returns xs:double('INF')
.
The expression math:pow(0e0, -4)
returns xs:double('INF')
.
The expression math:pow(-0e0, -3)
returns xs:double('-INF')
.
The expression math:pow(0, -4)
returns xs:double('INF')
.
The expression math:pow(16, 0.5e0)
returns 4.0e0
.
The expression math:pow(16, 0.25e0)
returns 2.0e0
.
The expression math:pow(0e0, -3.0e0)
returns xs:double('INF')
.
The expression math:pow(-0e0, -3.0e0)
returns xs:double('-INF')
. (Odd-valued whole numbers are treated specially).
The expression math:pow(0e0, -3.1e0)
returns xs:double('INF')
.
The expression math:pow(-0e0, -3.1e0)
returns xs:double('INF')
.
The expression math:pow(0e0, 3.0e0)
returns 0.0e0
.
The expression math:pow(-0e0, 3.0e0)
returns -0.0e0
. (Odd-valued whole numbers are treated specially).
The expression math:pow(0e0, 3.1e0)
returns 0.0e0
.
The expression math:pow(-0e0, 3.1e0)
returns 0.0e0
.
The expression math:pow(-1, xs:double('INF'))
returns 1.0e0
.
The expression math:pow(-1, xs:double('-INF'))
returns 1.0e0
.
The expression math:pow(1, xs:double('INF'))
returns 1.0e0
.
The expression math:pow(1, xs:double('-INF'))
returns 1.0e0
.
The expression math:pow(1, xs:double('NaN'))
returns 1.0e0
.
The expression math:pow(-2.5e0, 2.0e0)
returns 6.25e0
.
The expression math:pow(-2.5e0, 2.00000001e0)
returns xs:double('NaN')
.
Returns the non-negative square root of the argument.
math:sqrt ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the mathematical non-negative square root of $value
as defined in the [IEEE 754-2008] specification of the
squareRoot
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
exception is defined in 4.2 Arithmetic operators on numeric values. The effect is that if the argument is less than zero, the result
is NaN
.
If $value
is positive or negative zero, positive infinity, or
NaN
, then the result is $value
. (Negative zero is the only
case where the result can have negative sign)
The expression math:sqrt(())
returns ()
.
The expression math:sqrt(0.0e0)
returns 0.0e0
.
The expression math:sqrt(-0.0e0)
returns -0.0e0
.
The expression math:sqrt(1.0e6)
returns 1.0e3
.
The expression math:sqrt(2.0e0)
returns 1.4142135623730951e0
.
The expression math:sqrt(-2.0e0)
returns xs:double('NaN')
.
The expression math:sqrt(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:sqrt(xs:double('INF'))
returns xs:double('INF')
.
The expression math:sqrt(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the sine of the argument. The argument is an angle in radians.
math:sin ( |
||
$radians |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the sine of $radians
(which is treated as an angle in
radians) as defined in the [IEEE 754-2008] specification of the
sin
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in 4.2 Arithmetic operators on numeric values.
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range -1.0e0 to +1.0e0
The expression math:sin(())
returns ()
.
The expression math:sin(0)
returns 0.0e0
.
The expression math:sin(-0.0e0)
returns -0.0e0
.
The expression math:sin(math:pi() div 2)
returns 1.0e0
(approximately).
The expression math:sin(-math:pi() div 2)
returns -1.0e0
(approximately).
The expression math:sin(math:pi())
returns 0.0e0
(approximately).
The expression math:sin(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:sin(xs:double('INF'))
returns xs:double('NaN')
.
The expression math:sin(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the cosine of the argument. The argument is an angle in radians.
math:cos ( |
||
$radians |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $radians
is the empty sequence, the function returns the empty
sequence.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is the cosine of $
θ (which is treated as an angle in
radians) as defined in the [IEEE 754-2008] specification of the
cos
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
exception is defined in 4.2 Arithmetic operators on numeric values.
If $radians
is positive or negative zero, the result is
$radians
.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
Otherwise the result is always in the range -1.0e0 to +1.0e0
The expression math:cos(())
returns ()
.
The expression math:cos(0)
returns 1.0e0
.
The expression math:cos(-0.0e0)
returns 1.0e0
.
The expression math:cos(math:pi() div 2)
returns 0.0e0
(approximately).
The expression math:cos(-math:pi() div 2)
returns 0.0e0
(approximately).
The expression math:cos(math:pi())
returns -1.0e0
(approximately).
The expression math:cos(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:cos(xs:double('INF'))
returns xs:double('NaN')
.
The expression math:cos(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the tangent of the argument. The argument is an angle in radians.
math:tan ( |
||
$radians |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $radians
is the empty sequence, the function returns the empty
sequence.
Otherwise the result is the tangent of $radians
(which is treated as an angle
in radians) as defined in the [IEEE 754-2008] specification of the
tan
function applied to 64-bit binary floating point values.
The treatment of the invalidOperation
and underflow
exceptions
is defined in 4.2 Arithmetic operators on numeric values.
If $radians
is positive or negative infinity, or NaN
,
then the result is NaN
.
The expression math:tan(())
returns ()
.
The expression math:tan(0)
returns 0.0e0
.
The expression math:tan(-0.0e0)
returns -0.0e0
.
The expression math:tan(math:pi() div 4)
returns 1.0e0
(approximately).
The expression math:tan(-math:pi() div 4)
returns -1.0e0
(approximately).
The expression 1 div math:tan(math:pi() div 2)
returns 0.0e0
(approximately). (Mathematically, tan(π/2) is positive infinity. But because math:pi() div 2
returns an approximation, the result of math:tan(math:pi() div 2)
will be a large
but finite number.)
The expression 1 div math:tan(-math:pi() div 2)
returns -0.0e0
(approximately). (Mathematically, tan(-π/2) is negative infinity. But because -math:pi() div 2
returns an approximation, the result of math:tan(-math:pi() div 2)
will be a large
but finite negative number.)
The expression math:tan(math:pi())
returns 0.0e0
(approximately).
The expression math:tan(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:tan(xs:double('INF'))
returns xs:double('NaN')
.
The expression math:tan(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the arc sine of the argument.
math:asin ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc sine of $value
as defined in the [IEEE 754-2008] specification of the
asin
function applied to 64-bit binary floating point values.
The result is in the range -π/2 to +π/2 radians.
The treatment of the invalidOperation
and underflow
exceptions
is defined in 4.2 Arithmetic operators on numeric values.
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range -π/2 <=
θ <= +
π/2
.
The expression math:asin(())
returns ()
.
The expression math:asin(0)
returns 0.0e0
.
The expression math:asin(-0.0e0)
returns -0.0e0
.
The expression math:asin(1.0e0)
returns 1.5707963267948966e0
(approximately).
The expression math:asin(-1.0e0)
returns -1.5707963267948966e0
(approximately).
The expression math:asin(2.0e0)
returns xs:double('NaN')
.
The expression math:asin(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:asin(xs:double('INF'))
returns xs:double('NaN')
.
The expression math:asin(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the arc cosine of the argument.
math:acos ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc cosine of $value
, as defined in the [IEEE 754-2008] specification of the
acos
function applied to 64-bit binary floating point values.
The result is in the range zero to +π radians.
The treatment of the invalidOperation
exception is defined in 4.2 Arithmetic operators on numeric values.
If $value
is NaN
, or if its absolute value is greater than one,
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range 0 <=
θ <=
+
π.
The expression math:acos(())
returns ()
.
The expression math:acos(0)
returns 1.5707963267948966e0
(approximately).
The expression math:acos(-0.0e0)
returns 1.5707963267948966e0
(approximately).
The expression math:acos(1.0e0)
returns 0.0e0
.
The expression math:acos(-1.0e0)
returns 3.141592653589793e0
(approximately).
The expression math:acos(2.0e0)
returns xs:double('NaN')
.
The expression math:acos(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:acos(xs:double('INF'))
returns xs:double('NaN')
.
The expression math:acos(xs:double('-INF'))
returns xs:double('NaN')
.
Returns the arc tangent of the argument.
math:atan ( |
||
$value |
as xs:double? |
|
) as xs:double? |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If $value
is the empty sequence, the function returns the empty sequence.
Otherwise the result is the arc tangent of $value
, as defined
in the [IEEE 754-2008] specification of the
atan
function applied to 64-bit binary floating point values.
The result is in the range -π/2
to +π/2 radians.
The treatment of the underflow
exception is defined in 4.2 Arithmetic operators on numeric values.
If $value
is positive or negative zero, the result is $value
.
If $value
is NaN
then the result is NaN
.
In other cases the result is an xs:double
value representing an angle
θ in radians in the range -π/2 <=
θ <= +
π/2
.
The expression math:atan(())
returns ()
.
The expression math:atan(0)
returns 0.0e0
.
The expression math:atan(-0.0e0)
returns -0.0e0
.
The expression math:atan(1.0e0)
returns 0.7853981633974483e0
(approximately).
The expression math:atan(-1.0e0)
returns -0.7853981633974483e0
(approximately).
The expression math:atan(xs:double('NaN'))
returns xs:double('NaN')
.
The expression math:atan(xs:double('INF'))
returns 1.5707963267948966e0
(approximately).
The expression math:atan(xs:double('-INF'))
returns -1.5707963267948966e0
(approximately).
Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis.
math:atan2 ( |
||
$y |
as xs:double , |
|
$x |
as xs:double |
|
) as xs:double |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The result is the value of atan2(y, x)
as defined in the [IEEE 754-2008] specification of the atan2
function applied to
64-bit binary floating point values. The result is in the range -π
to +π radians.
The treatment of the underflow
exception is defined in 4.2 Arithmetic operators on numeric values. The following rules apply when the values are finite and non-zero,
(subject to rules for overflow, underflow and approximation).
If either argument is NaN
then the result is NaN
.
If $x
is positive, then the value of atan2($y,
$x)
is atan($y div $x)
.
If $x
is negative, then:
If $y
is positive, then the value of atan2($y, $x)
is
atan($y div $x) +
π.
If $y
is negative, then the value of atan2($y, $x)
is
atan($y div $x) -
π.
Some results for special values of the arguments are shown in the examples below.
The expression math:atan2(+0.0e0, 0.0e0)
returns 0.0e0
.
The expression math:atan2(-0.0e0, 0.0e0)
returns -0.0e0
.
The expression math:atan2(+0.0e0, -0.0e0)
returns 3.141592653589793e0
.
The expression math:atan2(-0.0e0, -0.0e0)
returns -3.141592653589793e0
.
The expression math:atan2(-1, 0.0e0)
returns -1.5707963267948966e0
.
The expression math:atan2(+1, 0.0e0)
returns 1.5707963267948966e0
.
The expression math:atan2(-0.0e0, -1)
returns -3.141592653589793e0
.
The expression math:atan2(+0.0e0, -1)
returns 3.141592653589793e0
.
The expression math:atan2(-0.0e0, +1)
returns -0.0e0
.
The expression math:atan2(+0.0e0, +1)
returns +0.0e0
.
Function | Meaning |
---|---|
fn:random-number-generator |
Returns a random number generator, which can be used to generate sequences of random numbers. |
Returns a random number generator, which can be used to generate sequences of random numbers.
fn:random-number-generator () as item-type(rng) |
fn:random-number-generator ( |
||
$seed |
as xs:anyAtomicType? |
|
) as item-type(rng) |
This function is ·deterministic·, ·context-independent·, ·focus-independent·, and ·higher-order·.
The function returns a random number generator. A random number generator is represented as a value of type
rng
, defined as follows:
record( number as xs:double, next as (function() as record(number, next, permute, *)), permute as (function(item()*) as item()*), * )
That is, the result of the function is a map containing three entries. The keys of each entry are strings:
The entry with key "number"
holds a random number; it is an xs:double
greater than or equal
to zero (0.0e0), and less than one (1.0e0).
The entry with key "next"
is a zero-arity function that can be called to return another random number
generator.
The properties of this function are as follows:
name: absent
parameter names: ()
signature: () => map(xs:string, item())
non-local variable bindings: none
implementation: implementation-dependent
The entry with key "permute"
is a function with arity 1 (one), which takes an arbitrary sequence
as its argument, and returns a random permutation of that sequence.
The properties of this function are as follows:
name: absent
parameter names: ("arg")
signature: (item()*) => item()*
non-local variable bindings: none
implementation: implementation-dependent
Calling the fn:random-number-generator
function with no arguments is equivalent to calling the single-argument
form of the function with an implementation-dependent seed.
Calling the fn:random-number-generator
function with an empty sequence as $seed
is equivalent to calling the single-argument form of the function with an implementation-dependent seed.
If a $seed
is supplied, it may be an atomic value of any type.
Both forms of the function are ·deterministic·: calling the function twice with the same arguments, within a single ·execution scope·, produces the same results.
The value of the number
entry should be such that the distribution of numbers is uniform: for example, the probability of the
number being in the range 0.1e0 to 0.2e0 is the same as the probability of its being in the range 0.8e0 to 0.9e0.
The function returned in the permute
entry should be such that all permutations
of the supplied sequence are equally likely to be chosen.
The map returned by the fn:random-number-generator
function may contain additional entries beyond
those specified here, but it must match the type
item-type(rng)
defined above. The meaning of any additional entries
is ·implementation-defined·. To avoid conflict with any future version of this specification, the keys of any
such entries should start with an underscore character.
It is not meaningful to ask whether the functions returned in the next
and permute
functions resulting from two separate calls with the same seed are "the same function", but the functions must be equivalent in the sense
that calling them produces the same sequence of random numbers.
The repeatability of the results of function calls in different execution scopes is outside the scope of this
specification. It is recommended that when the same seed is provided explicitly, the same random number sequence
should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed
that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by using
fn:current-dateTime()
as a seed.)
The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.
The following example returns a random permutation of the integers in the range 1 to 100:
fn:random-number-generator()?permute(1 to 100)
The following example returns a 10% sample of the items in an input sequence $seq
, chosen at random:
fn:random-number-generator()?permute($seq)[position() = 1 to (count($seq) idiv 10)]
The following code defines a function that can be called to produce a random sequence of xs:double
values in the range zero to one, of specified length:
declare %public function r:random-sequence($length as xs:integer) as xs:double* { r:random-sequence($length, fn:random-number-generator()) }; declare %private function r:random-sequence($length as xs:integer, $G as record(number as xs:double, next as function(*), *)) { if ($length eq 0) then () else ($G?number, r:random-sequence($length - 1, $G?next())) }; r:random-sequence(200);