XPath and XQuery Functions and Operators 3.0

1.6.1 Strings, characters, and codepoints

This document uses the terms string, character, and codepoint with the following meanings:

[Definition] A character is an instance of the Char^XML production of [REC-xml].

[Definition] A string is a sequence of zero or more ·characters·, or equivalently, a value in the value space of the xs:string data type.

[Definition] A codepoint is a non-negative integer assigned to a ·character· by the Unicode consortium, or reserved for future assignment to a character.

Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader's attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.

It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.

Unless explicitly stated, the xs:string values returned by the functions in this document are not normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].

1.6.2 Namespaces and URIs

This document uses the phrase "namespace URI" to identify the concept identified in [Namespaces in XML] as "namespace name", and the phrase "local name" to identify the concept identified in [Namespaces in XML] as "local part".

It also uses the term "expanded-QName" defined below.

[Definition] An expanded-QName is a pair of values consisting of a namespace URI and a local name. They belong to the value space of the [XML Schema Part 2: Datatypes Second Edition] datatype xs:QName. When this document refers to xs:QName we always mean the value space, i.e. a namespace URI, local name pair (and not the lexical space referring to constructs of the form prefix:local-name).

The term URI is used as follows:

[Definition] Within this specification, the term URI refers to Universal Resource Identifiers as defined in [RFC 3986] and extended in [RFC 3987] with a new name IRI. The term URI Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI datatype as defined in [XML Schema Part 2: Datatypes Second Edition].

1.6.3 Conformance terminology

[Definition] for compatibility

A feature of this specification included to ensure that implementations that use this feature remain compatible with [XML Path Language (XPath) Version 1.0]

[Definition] may

Conforming documents and processors are permitted to, but need not, behave as described.

[Definition] must

Conforming documents and processors are required to behave as described; otherwise, they are either non-conformant or else in error.

[Definition] implementation-defined

Possibly differing between implementations, but specified and documented by the implementor for each particular implementation.

[Definition] implementation-dependent

Possibly differing between implementations, but not specified by this or other W3C specification, and not required to be specified by the implementor for any particular implementation.

1.6.4 Properties of functions

This section is concerned with the question of whether two calls on a function, with the same arguments, may produce different results.

[Definition] Two function calls are said to be within the same execution scope if the host environment defines them as such. In XSLT, any two calls executed during the same transformation are in the same execution scope. In XQuery, any two calls executed during the evaluation of a top-level expression are in the same execution scope. In other contexts, the execution scope is specified by the host environment that invokes the function library.

The following definition explains more precisely what it means for two function calls to return the same result:

[Definition] Two values are defined to be identical if they contain the same number of items and the items are pairwise identical. Two items are identical if and only if one of the following conditions applies:

• Both items are atomic values, of precisely the same type, and the values are equal as defined using the eq operator, using the Unicode codepoint collation when comparing strings

• Both items are nodes, and represent the same node

• Both items are function items, and have the same name (or absence of a name), arity, function signature, and closure. (Note that there is no function or operator defined in the specification that tests whether two function items are identical.)

Some functions produce results that depend not only on their explicit arguments, but also on the static and dynamic context.

[Definition] A function may have the property of being context-dependent: the result of such a function depends on the values of properties in the static and dynamic evaluation context as well as on the actual supplied arguments (if any).

[Definition] A function that is not ·context-dependent· is called context-independent.

Functions that are context-dependent cannot be used as literal function items, nor can they be partially applied. For example, position#0 is not valid as a literal function item, and fn:starts-with(?, ?, "http://example.com/collation") is not a valid partial function application. In the latter case this is because, in theory, the same URI might refer to different collations depending on the static context in which the collation URI appears. It is possible to circumvent this problem by writing a user-defined function as a simple wrapper for a call on fn:starts-with, and writing a partial application of this user-defined function. In this way the static context for the call on fn:starts-with is made unambiguous.

Context-dependent functions fall into a number of categories:

1. The functions fn:current-date, fn:current-dateTime, fn:current-time, fn:implicit-timezone, fn:adjust-date-to-timezone, fn:adjust-dateTime-to-timezone, and fn:adjust-time-to-timezone depend on properties of the dynamic context that are fixed within the ·execution scope·. The same applies to a number of functions in the op: namespace that manipulate dates and times and that make use of the implicit timezone. These functions will return the same result if called repeatedly during a single ·execution scope·.

2. A number of functions including fn:base-uri#0, fn:data#0, fn:document-uri#0, fn:position, fn:last, fn:id#1, fn:idref#1, fn:element-with-id#1, fn:lang#1, fn:local-name#0, fn:name#0, fn:namespace-uri#0, fn:normalize-space#0, fn:number#0, fn:root#0, fn:string#0, fn:string-length#0, and fn:path#0 depend on the focus. These functions will in general return different results on different calls if the focus is different.

   [Definition] A function is focus-dependent if its result depends on the focus (that is, the context item, position, or size).

   [Definition] A function that is not ·focus-dependent· is called focus-independent

3. The function fn:default-collation and many string-handling operators and functions depend on the default collation and the in-scope collations, which are both properties of the static context. If a particular call of one of these functions is evaluated twice with the same arguments then it will return the same result each time (because the static context, by definition, does not change at run time). However, two distinct calls (that is, two calls on the function appearing in different places in the source code) may produce different results even if the explicit arguments are the same.

4. Functions such as fn:static-base-uri, fn:doc, and fn:collection depend on other aspects of the static context. As with functions that depend on collations, a single call will produce the same results on each call if the explicit arguments are the same, but two calls appearing in different places in the source code may produce different results.

[Definition] For a ·context-dependent· function, the parts of the context on which it depends are referred to as implicit arguments.

[Definition] A function that is guaranteed to produce ·identical· results from repeated calls if the explicit and implicit arguments are identical is referred to as deterministic.

[Definition] A function that is not ·deterministic· is referred to as nondeterministic.

All functions defined in this specification are ·deterministic· unless otherwise stated. Exceptions include the following:

• Some functions (such as fn:distinct-values and fn:unordered) produce results in an ·implementation-defined· or ·implementation-dependent· order. In such cases there is no guarantee that the order of results from different calls will be the same. These functions are said to be non-deterministic with respect to ordering.

• The function fn:analyze-string constructs an element node to represent its results. There is no guarantee that repeated calls with the same arguments will return the same identical node (in the sense of the is operator). However, if non-identical nodes are returned, their content will be the same in the sense of the fn:deep-equal function. Such a function is said to be non-deterministic with respect to node identity.

• Some functions (such as fn:doc and fn:collection) create new nodes by reading external documents. Such functions are guaranteed to be ·deterministic· with the exception that an implementation is allowed to make them non-deterministic as a user option.

Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results.

3.1.1 fn:error

Summary

Calling the fn:error function raises an application-defined error.

Signatures

fn:error() as none

fn:error($code as xs:QName) as none

fn:error($code as xs:QName?, $description as xs:string) as none

fn:error(	$code	as xs:QName?,
	$description	as xs:string,
	$error-object	as item()*) as none

Properties

This function is ·nondeterministic·, ·context-independent·, and ·focus-independent·.

Rules

This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.

The parameters to the fn:error function supply information that is associated with the error condition and that is made available to a caller that asks for information about the error. The error may be caught either by the host language (using a try/catch construct in XSLT or XQuery, for example), or by the calling application or external processing environment. The way in which error information is returned to the external processing environment is ·implementation dependent·

If fn:error is called with no arguments, then its behavior is the same as the function call:

 fn:error(fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')) 

If $code is the empty sequence then the effective value is the xs:QName constructed by:

 fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000')

There are three pieces of information that may be associated with an error:

• The $code is an error code that distinguishes this error from others. It is an xs:QName; the namespace URI conventionally identifies the component, subsystem, or authority responsible for defining the meaning of the error code, while the local part identifies the specific error condition. The namespace URI http://www.w3.org/2005/xqt-errors is used for errors defined in this specification; other namespace URIs may be used for errors defined by the application.

  If the external processing environment expects the error code to be returned as a URI or a string rather than as an xs:QName, then an error code with namespace URI NS and local part LP will be returned in the form NS#LP. The namespace URI part of the error code should therefore not include a fragment identifier.

• The $description is a natural-language description of the error condition.

• The $error-object is an arbitrary value used to convey additional information about the error, and may be used in any way the application chooses.

Error Conditions

This function always raises an error.

Notes

The value of the $description parameter may need to be localized.

The type "none" is a special type defined in [XQuery 1.0 and XPath 2.0 Formal Semantics] and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.

Examples

The expression fn:error() raises error FOER0000. (This returns the URI http://www.w3.org/2005/xqt-errors#FOER0000 (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.).

The expression fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Does not apply because salary is too high') raises error myerr:toohighsal. (This returns http://www.example.com/HR#toohighsal and the xs:string "Does not apply because salary is too high" (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.).

3.2.1 fn:trace

Summary

Provides an execution trace intended to be used in debugging queries.

Signature

fn:trace($value as item()*, $label as xs:string) as item()*

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the value of $value, unchanged.

In addition, the values of $value, converted to an xs:string, and $label may be directed to a trace data set. The destination of the trace output is ·implementation-defined·. The format of the trace output is ·implementation dependent·. The ordering of output from calls of the fn:trace function is ·implementation dependent·.

Examples

Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will put the strings "124.84" and "the value of $v is:" in the trace data set in implementation dependent order.

4.2.1 op:numeric-add

Summary

Returns the arithmetic sum of its operands: ($arg1 + $arg2).

Operator Mapping

Defines the semantics of the "+" operator applied to numeric values

Signature

op:numeric-add($arg1 as numeric, $arg2 as numeric) as numeric

Rules

General rules: see 4.2 Arithmetic operators on numeric values.

Notes

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.

4.2.2 op:numeric-subtract

Summary

Returns the arithmetic difference of its operands: ($arg1 - $arg2).

Operator Mapping

Defines the semantics of the "-" operator applied to numeric values.

Signature

op:numeric-subtract($arg1 as numeric, $arg2 as numeric) as numeric

Rules

General rules: see 4.2 Arithmetic operators on numeric values.

Notes

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.

4.2.3 op:numeric-multiply

Summary

Returns the arithmetic product of its operands: ($arg1 * $arg2).

Operator Mapping

Defines the semantics of the "*" operator applied to numeric values.

Signature

op:numeric-multiply($arg1 as numeric, $arg2 as numeric) as numeric

Rules

General rules: see 4.2 Arithmetic operators on numeric values.

Notes

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.

4.2.4 op:numeric-divide

Summary

Returns the arithmetic quotient of its operands: ($arg1 div $arg2).

Operator Mapping

Defines the semantics of the "div" operator applied to numeric values.

Signature

op:numeric-divide($arg1 as numeric, $arg2 as numeric) as numeric

Rules

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.

Error Conditions

An error is raised [err:FOAR0001] for xs:decimal and xs:integer operands, if the divisor is (positive or negative) zero.

Notes

For xs:float and xs:double operands, floating point division is performed as specified in [ieee754]. 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.

4.2.5 op:numeric-integer-divide

Summary

Performs an integer division.

Operator Mapping

Defines the semantics of the "idiv" operator applied to numeric values.

Signature

op:numeric-integer-divide($arg1 as numeric, $arg2 as numeric) as xs:integer

Rules

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 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.

Error Conditions

An error is raised [err:FOAR0001] if the divisor is (positive or negative) zero.

An error is raised [err:FOAR0002] if either operand is NaN or if $arg1 is INF or -INF.

Notes

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++.

Examples

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.

4.2.6 op:numeric-mod

Summary

Returns the remainder resulting from dividing $arg1, the dividend, by $arg2, the divisor.

Operator Mapping

Defines the semantics of the "mod" operator applied to numeric values.

Signature

op:numeric-mod($arg1 as numeric, $arg2 as numeric) as numeric

Rules

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 [ieee754] rounding division i.e. additional digits are truncated, not rounded to the required precision.

Error Conditions

An error is raised [err:FOAR0001] for xs:integer and xs:decimal operands, if $arg2 is zero.

Examples

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.

4.2.7 op:numeric-unary-plus

Summary

Returns its operand with the sign unchanged: (+ $arg).

Operator Mapping

Defines the semantics of the unary "+" operator applied to numeric values.

Signature

op:numeric-unary-plus($arg as numeric) as numeric

Rules

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.

Notes

Because function conversion rules are applied in the normal way, the unary + 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.

4.2.8 op:numeric-unary-minus

Summary

Returns its operand with the sign reversed: (- $arg).

Operator Mapping

Defines the semantics of the unary "-" operator applied to numeric values.

Signature

op:numeric-unary-minus($arg as numeric) as numeric

Rules

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.

4.3.1 op:numeric-equal

Summary

Returns true if and only if the value of $arg1 is equal to the value of $arg2.

Operator Mapping

Defines the semantics of the "eq" operator on numeric values, and is also used in defining the semantics of "ne", "le" and "ge".

Signature

op:numeric-equal($arg1 as numeric, $arg2 as numeric) as xs:boolean

Rules

General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.

For xs:float and xs:double values, positive zero and negative zero compare equal. INF equals INF, and -INF equals -INF. NaN does not equal itself.

4.3.2 op:numeric-less-than

Summary

Returns true if and only if $arg1 is numerically less than $arg2.

Operator Mapping

Defines the semantics of the "lt" operator on numeric values, and is also used in defining the semantics of "le".

Signature

op:numeric-less-than($arg1 as numeric, $arg2 as numeric) as xs:boolean

Rules

General rules: see 4.2 Arithmetic operators on numeric values and 4.3 Comparison operators on numeric values.

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. If $arg1 or $arg2 is NaN, the function returns false.

4.3.3 op:numeric-greater-than

Summary

Returns true if and only if $arg1 is numerically greater than $arg2.

Operator Mapping

Defines the semantics of the "gt" operator on numeric values, and is also used in defining the semantics of "ge".

Signature

op:numeric-greater-than($arg1 as numeric, $arg2 as numeric) as xs:boolean

Rules

The function call op:numeric-greater-than($A, $B) is defined to return the same result as op:numeric-less-than($B, $A)

4.4.1 fn:abs

Summary

Returns the absolute value of $arg.

Signature

fn:abs($arg as numeric?) as numeric?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

General rules: see 4.4 Functions on numeric values.

If $arg is negative the function returns -$arg, otherwise it returns $arg.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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.

Examples

The expression fn:abs(10.5) returns 10.5.

The expression fn:abs(-10.5) returns 10.5.

4.4.2 fn:ceiling

Summary

Rounds $arg upwards to a whole number.

Signature

fn:ceiling($arg as numeric?) as numeric?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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 the value of $arg.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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.

Examples

The expression fn:ceiling(10.5) returns 11.

The expression fn:ceiling(-10.5) returns -10.

4.4.3 fn:floor

Summary

Rounds $arg downwards to a whole number.

Signature

fn:floor($arg as numeric?) as numeric?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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 the value of $arg.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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.

Examples

The expression fn:floor(10.5) returns 10.

The expression fn:floor(-10.5) returns -11.

4.4.4 fn:round

Summary

Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.

Signatures

fn:round($arg as numeric?) as numeric?

fn:round($arg as numeric?, $precision as xs:integer) as numeric?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

General rules: see 4.4 Functions on numeric values.

The function returns the nearest (that is, numerically closest) value to $arg 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 $arg is exactly .5), the function returns the one that is closest to positive infinity.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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 $arg is of type xs:float and xs:double:

1. If $arg is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

2. 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 $arg.

Notes

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.

Examples

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.

4.4.5 fn:round-half-to-even

Summary

Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.

Signatures

fn:round-half-to-even($arg as numeric?) as numeric?

fn:round-half-to-even($arg as numeric?, $precision as xs:integer) as numeric?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

General rules: see 4.4 Functions on numeric values.

The function returns the nearest (that is, numerically closest) value to $arg 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 $arg is exactly .500...), the function returns the one whose least significant digit is even.

If the type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the result is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the result is an instance of the base numeric type.

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:

1. If the argument is NaN, positive or negative zero, or positive or negative infinity, then the result is the same as the argument.

2. 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.

Notes

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.

Examples

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.

4.5.1 fn:number

Summary

Returns the value indicated by $arg or, if $arg is not specified, the context item after atomization, converted to an xs:double.

Signatures

fn:number() as xs:double

fn:number($arg as xs:anyAtomicType?) as xs:double

Properties

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·.

Rules

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(.).

If $arg is the empty sequence or if $arg or the context item cannot be converted to an xs:double, the xs:double value NaN is returned.

Otherwise, $arg, or the context item after atomization, is converted to an xs:double following the rules of 18.1.2.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.

Error Conditions

An error is raised [err:XPDY0002]^XP if $arg is omitted and the context item is absent^DM30.

Notes

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.

Examples

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.

4.6.1 fn:format-integer

Summary

Formats an integer according to a given picture string, using the conventions of a given natural language if specified.

Signatures

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,
	$language	as xs:string?) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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 must match the regular expression:

^((\p{Nd}|#|[^\p{N}\p{L}])+?)(([co](\([^()]\))?)?[at]?)$

The substring that matches the first capturing group in this regular expression are referred to as the primary format token. The substring that matches the second capturing group (which may be empty) is referred to as the format modifier. A picture thus consists of a primary format token, followed by an optional format modifier.

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.

  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. If grouping-separator-signs appear at regular intervals within the format token, that is if the same grouping separator appears at positions forming a sequence N, 2N, 3N, ... for some integer value N (including the case where there is only one number in the list), 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.

  Note:

  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 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 the first kind above (one that consists of decimal digits), 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 of 1 to 20 imposed by the Unicode character repertoire. 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 $language argument specifies which language's conventions are to be used. If the argument is specified, the value should be a string that is castable to the type xs:language.

The set of languages for which numbering is supported is ·implementation-defined·. If the $language 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 a default language; the default language is ·implementation-defined·.

The format modifier, if present, is 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 ....

In some languages, ordinal numbers vary depending on the grammatical context, for example 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 o may be used to indicate the variation of the 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 preferred approach is to indicate the required ending, preceded by a hyphen: for example in German, appropriate values are o(-e), o(-er), o(-es), o(-en).

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.

Example: Ordinal Numbering in Italian

The specification "1o(-º)" with $language equal to it, if supported, should produce the sequence:

1º 2º 3º 4º ...

The specification "Wwo" with $language equal to it, if supported, should produce the sequence:

Primo Secondo Terzo Quarto Quinto ...

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·.

Examples

The expression format-integer(123, '0000') returns "0123".

format-integer(123, 'w') might return "one hundred and twenty-three"

The expression format-integer(21, '1o', 'en') returns "21st".

format-integer(14, 'Wwo(-e)', 'de') might return "Vierzehnte"

The expression format-integer(7, 'a') returns "g".

The expression format-integer(57, 'I') returns "LVII".

4.7.1 Defining a decimal format

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 variables, described in the following table:

[Definition] The decimal digit family of a decimal format is the sequence of ten digits with consecutive Unicode ·codepoints· starting with the mandatory-digit-sign.

It is a constraint that, for any named or unnamed decimal format, the variables representing characters used in a ·picture string· must have distinct values. These variables are decimal-separator-sign, grouping-separator-sign, percent-sign, per-mille-sign, optional-digit-sign, and pattern-separator-sign. Furthermore, none of these variables may be equal to any ·character· in the ·decimal digit family·.

4.7.2 fn:format-number

Summary

Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.

Signatures

fn:format-number($value as numeric?, $picture as xs:string) as xs:string

fn:format-number(	$value	as numeric?,
	$picture	as xs:string,
	$decimal-format-name	as xs:string?) as xs:string

Properties

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.

Rules

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 default 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 a lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means 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 default decimal format in the static context otherwise.

The evaluation of the format-number function takes place in two phases, an analysis phase described in 4.7.4 Analysing 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.

Error Conditions

An error is raised [err:FODF1280] if the name specified as the $decimal-format-name argument is not a valid lexical QName, or if its prefix 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.

Notes

Numbers will always be formatted with the most significant digit on the left.

Examples

The expression format-number(12345.6, '#.###,00') returns "12.345,00".

4.7.3 Syntax of the picture string

[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 variables decimal-separator-sign, grouping-sign, decimal-digit-family, optional-digit-sign and pattern-separator-sign are classified as active characters, and all other characters (including the percent-sign and per-mille-sign) are classified as passive characters.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator-sign if there is one, or the entire sub-picture otherwise. The fractional part of the sub-picture is defined as the part that appears to the right of the decimal-separator-sign if there is one; it is a zero-length string otherwise.

An 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 a pattern-separator-sign. A picture-string must not contain more than one pattern-separator-sign. If the picture-string contains two sub-pictures, the first is used for positive values and the second for negative values.

• A sub-picture must not contain more than one decimal-separator-sign.

• A sub-picture must not contain more than one percent-sign or per-mille-sign, and it must not contain one of each.

• A sub-picture must contain at least one character that is an optional-digit-sign 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-separator-sign adjacent to a decimal-separator-sign.

• The integer part of a sub-picture must not contain a member of the decimal-digit-family that is followed by an optional-digit-sign. The fractional part of a sub-picture must not contain an optional-digit-sign that is followed by a member of the decimal-digit-family.

4.7.4 Analysing the picture string

This phase of the algorithm analyses the ·picture string· and the variables 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 data type.

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 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-separator-sign 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-sign and decimal-digit-family characters that appear within the integer part of the sub-picture and to the right of the grouping-separator-sign. In addition, if these integer-part-grouping-positions are at regular intervals (that is, if they form a sequence N, 2N, 3N, ... for some integer value N, including the case where there is only one number in the list), then the sequence contains all integer multiples of N 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-sign. It is normally set to the number of decimal-digit-family characters found in the integer part of the sub-picture. But if the sub-picture contains no decimal-digit-family character and no decimal-separator-sign, it is set to one.

  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-sign and decimal-digit-family characters in the subpicture.

• 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-sign 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-separator-sign 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-sign and decimal-digit-family characters that appear within the fractional part of the sub-picture and to the left of the grouping-separator-sign.

• 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-sign and decimal-digit-family characters found in the fractional part of the sub-picture.

• The suffix is set to contain all passive characters to the right of the rightmost active character in the fractional part of the sub-picture.

4.7.5 Formatting the number

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 analysing 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:

1. If the input number is NaN (not a number), the result is the specified NaN-symbol (with no prefix or suffix).

2. 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 otherwise. Negative zero is taken as negative, positive zero as positive.

3. If the input number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the infinity-symbol, and the appropriate suffix.

4. If the sub-picture contains a percent-sign, the number is multiplied by 100. If the sub-picture contains a per-mille-sign, the number is multiplied by 1000. The resulting number is referred to below as the adjusted number.

5. The adjusted number 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 adjusted number (bearing in mind that if the adjusted number 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 adjusted number 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.

6. The absolute value of the rounded number is converted to a string in decimal notation, with no insignificant leading or trailing zeroes, using the digits in the decimal-digit-family to represent the ten decimal digits, and the decimal-separator-sign to separate the integer part and the fractional part. (The value zero will at this stage be represented by a decimal-separator-sign on its own.)

7. If the number of digits to the left of the decimal-separator-sign is less than minimum-integer-part-size, leading zero-digit-sign characters are added to pad out to that size.

8. If the number of digits to the right of the decimal-separator-sign is less than minimum-fractional-part-size, trailing zero-digit-sign characters are added to pad out to that size.

9. For each integer N in the integer-part-grouping-positions list, a grouping-separator-sign 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-separator-sign, if there is such a digit.

10. For each integer N in the fractional-part-grouping-positions list, a grouping-separator-sign 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-separator-sign, if there is such a digit.

11. If there is no decimal-separator-sign in the sub-picture, or if there are no digits to the right of the decimal-separator-sign character in the string, then the decimal-separator-sign character is removed from the string (it will be the rightmost character in the string).

12. 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.

4.8.1 math:pi

Summary

Returns an approximation to the mathematical constant π.

Signature

math:pi() as xs:double

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

This function returns the xs:double value whose lexical representation is 3.141592653589793e0

Examples

The expression 2*math:pi() returns 6.283185307179586e0.

The expression 60 * (math:pi() div 180) converts an angle of 60 degrees to radians.

4.8.2 math:exp

Summary

Returns the value of e^x.

Signature

math:exp($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is the mathematical constant e raised to the power of $arg, as defined in the [IEEE 754-2008] specification of the exp function applied to 64-bit binary floating point values.

Notes

The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.

Examples

The expression math:exp(()) returns ().

The expression math:exp(0) returns 1.0e0.

The expression math:exp(1) returns 2.7182818284590455e0.

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.

4.8.3 math:exp10

Summary

Returns the value of 10^x.

Signature

math:exp10($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is ten raised to the power of $arg, as defined in the [IEEE 754-2008] specification of the exp10 function applied to 64-bit binary floating point values.

Notes

The treatment of overflow and underflow is defined in 4.2 Arithmetic operators on numeric values.

Examples

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.

4.8.4 math:log

Summary

Returns the natural logarithm of the argument.

Signature

math:log($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is the natural logarithm of $arg, as defined in the [IEEE 754-2008] specification of the log function applied to 64-bit binary floating point values.

Notes

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 less than or equal to zero, the result is NaN.

Examples

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').

4.8.5 math:log10

Summary

Returns the base-ten logarithm of the argument.

Signature

math:log10($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is the base-10 logarithm of $arg, as defined in the [IEEE 754-2008] specification of the log10 function applied to 64-bit binary floating point values.

Notes

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 less than or equal to zero, the result is NaN.

Examples

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').

4.8.6 math:pow

Summary

Returns the result of raising the first argument to the power of the second.

Signature

math:pow($x as xs:double?, $y as numeric) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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 the value of $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.

Notes

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.

Examples

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').

4.8.7 math:sqrt

Summary

Returns the non-negative square root of the argument.

Signature

math:sqrt($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is the mathematical non-negative square root of $arg as defined in the [IEEE 754-2008] specification of the squareRoot function applied to 64-bit binary floating point values.

Notes

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 $arg is positive or negative zero, positive infinity, or NaN, then the result is $arg. (Negative zero is the only case where the result can have negative sign)

Examples

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').

4.8.8 math:sin

Summary

Returns the sine of the argument, expressed in radians.

Signature

math:sin($θ as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $θ is the empty sequence, the function returns the empty sequence.

Otherwise the result is the sine of $θ, 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.

Notes

The treatment of the invalidOperation and underflow exceptions is defined in 4.2 Arithmetic operators on numeric values.

If $θ is positive or negative zero, the result is $θ.

If $θ 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

Examples

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.

The expression math:sin(-math:pi() div 2) returns -1.0e0.

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').

4.8.9 math:cos

Summary

Returns the cosine of the argument, expressed in radians.

Signature

math:cos($θ as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $θ is the empty sequence, the function returns the empty sequence.

If $θ is positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is the cosine of $θ, 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.

Notes

The treatment of the invalidOperation exception is defined in 4.2 Arithmetic operators on numeric values.

If $θ is positive or negative zero, the result is $θ.

If $θ 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

Examples

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.

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').

4.8.10 math:tan

Summary

Returns the tangent of the argument, expressed in radians.

Signature

math:tan($θ as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $θ is the empty sequence, the function returns the empty sequence.

Otherwise the result is the tangent of $θ, 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.

Notes

The treatment of the invalidOperation and underflow exceptions is defined in 4.2 Arithmetic operators on numeric values.

If $θ is positive or negative infinity, or NaN, then the result is NaN.

Examples

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 math:tan(math:pi() div 2) returns 1.633123935319537E16 (approximately).

The expression math:tan(-math:pi() div 2) returns -1.633123935319537E16 (approximately).

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').

4.8.11 math:asin

Summary

Returns the arc sine of the argument, the result being in the range -π/2 to +π/2 radians.

Signature

math:asin($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is the arc sine of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the asin function applied to 64-bit binary floating point values.

Notes

The treatment of the invalidOperation and underflow exceptions is defined in 4.2 Arithmetic operators on numeric values.

If $arg is positive or negative zero, the result is $arg.

If $arg 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.

Examples

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').

4.8.12 math:acos

Summary

Returns the arc cosine of the argument, the result being in the range zero to +π radians.

Signature

math:acos($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is the arc cosine of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the acos function applied to 64-bit binary floating point values.

Notes

The treatment of the invalidOperation exception is defined in 4.2 Arithmetic operators on numeric values.

If $arg 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 <= $θ <= +π.

Examples

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').

4.8.13 math:atan

Summary

Returns the arc tangent of the argument, the result being in the range -π/2 to +π/2 radians.

Signature

math:atan($arg as xs:double?) as xs:double?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $arg is the empty sequence, the function returns the empty sequence.

Otherwise the result is the arc tangent of $θ, treated as an angle in radians, as defined in the [IEEE 754-2008] specification of the atan function applied to 64-bit binary floating point values.

Notes

The treatment of the underflow exception is defined in 4.2 Arithmetic operators on numeric values.

If $arg is positive or negative zero, the result is $arg.

If $arg 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.

Examples

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).

4.8.14 math:atan2

Summary

Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis, the result being in the range -π to +π.

Signature

math:atan2($y as xs:double, $x as xs:double) as xs:double

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

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.

Notes

The treatment of the underflow exception is defined in 4.2 Arithmetic operators on numeric values.

If $arg is NaN then the result is NaN.

If $y is positive and $x is positive and finite, then (subject to rules for overflow, underflow and approximation) the value of atan2($y, $x) is atan($y div $x).

If $y is positive and $x is negative and finite, then (subject to the same caveats) 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.

Examples

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 math:pi().

The expression math:atan2(-0.0e0, -0.0e0) returns -math:pi().

The expression math:atan2(-1, 0.0e0) returns -math:pi() div 2.

The expression math:atan2(+1, 0.0e0) returns +math:pi() div 2.

The expression math:atan2(-0.0e0, -1) returns -math:pi().

The expression math:atan2(+0.0e0, -1) returns +math:pi().

The expression math:atan2(-0.0e0, +1) returns -0.0e0.

The expression math:atan2(+0.0e0, +1) returns +0.0e0.

5.2.1 fn:codepoints-to-string

Summary

Creates an xs:string from a sequence of ·codepoints·.

Signature

fn:codepoints-to-string($arg as xs:integer*) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the string made up from the ·characters· whose Unicode ·codepoints· are supplied in $arg. This will be the zero-length string if $arg is the empty sequence.

Error Conditions

An error is raised [err:FOCH0001] if any of the codepoints in $arg is not a permitted XML character.

Examples

The expression fn:codepoints-to-string((66, 65, 67, 72)) returns "BACH".

The expression fn:codepoints-to-string((2309, 2358, 2378, 2325)) returns "अशॊक".

The expression fn:codepoints-to-string(()) returns "".

The expression fn:codepoints-to-string(0) raises error FOCH0001.

5.2.2 fn:string-to-codepoints

Summary

Returns the sequence of ·codepoints· that constitute an xs:string value.

Signature

fn:string-to-codepoints($arg as xs:string?) as xs:integer*

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a sequence of integers, each integer being the Unicode ·codepoints· of the corresponding ·character· in $arg.

If $arg is a zero-length string or the empty sequence, the function returns the empty sequence.

Examples

The expression fn:string-to-codepoints("Thérèse") returns (84, 104, 233, 114, 232, 115, 101).

5.3.1 Collations

A collation is a specification of the manner in which ·strings·s are compared and, by extension, ordered. When values whose type is xs:string or a type derived from xs:string are compared (or, equivalently, sorted), the comparisons are inherently performed according to some collation (even if that collation is defined entirely on codepoint values). The [Character Model for the World Wide Web 1.0: Fundamentals] observes that some applications may require different comparison and ordering behaviors than other applications. Similarly, some users having particular linguistic expectations may require different behaviors than other users. Consequently, the collation must be taken into account when comparing strings in any context. Several functions in this and the following section make use of a collation.

Collations can indicate that two different codepoints are, in fact, equal for comparison purposes (e.g., "v" and "w" are considered equivalent in some Swedish collations). Strings can be compared codepoint-by-codepoint or in a linguistically appropriate manner, as defined by the collation.

Some collations, especially those based on the [Unicode Collation Algorithm] can be "tailored" for various purposes. This document does not discuss such tailoring, nor does it provide a mechanism to perform tailoring. Instead, it assumes that the collation argument to the various functions below is a tailored and named collation.

The ·Unicode codepoint collation· is a collation available in every implementation, which sorts based on codepoint values. For further details see 5.3.2 The Unicode Codepoint Collation

In the ideal case, a collation should treat two strings as equal if the two strings are identical after Unicode normalization. Thus, the [Character Model for the World Wide Web 1.0: Normalization] recommends that all strings be subjected to early Unicode normalization and some collations will raise runtime errors if they encounter strings that are not properly normalized. However, it is not possible to guarantee that all strings in all XML documents are, in fact, normalized, or that they are normalized in the same manner. In order to maximize interoperability of operations on XML documents in general, there may be collations that operate on unnormalized strings and other collations that implicitly normalize strings before comparing them. Applications may choose the kind of collation best suited for their needs. Note that collations based on the Unicode collation algorithm implicitly normalize strings before comparison and produce equivalent results regardless of a string's normalization.

This specification assumes that collations are named and that the collation name may be provided as an argument to string functions. Functions that allow specification of a collation do so with an argument whose type is xs:string but whose lexical form must conform to an xs:anyURI. If the collation is specified using a relative URI, it is assumed to be relative to the value of the Dynamic Base URI property from the dynamic context. This specification also defines the manner in which a default collation is determined if the collation argument is not specified in calls of functions that use a collation but allow it to be omitted.

This specification does not define whether or not the collation URI is dereferenced. The collation URI may be an abstract identifier, or it may refer to an actual resource describing the collation. If it refers to a resource, this specification does not define the nature of that resource. One possible candidate is that the resource is a locale description expressed using the Locale Data Markup Language: see [Locale Data Markup Language].

Functions such as fn:compare and fn:max that compare xs:string values use a single collation URI to identify all aspects of the collation rules. This means that any parameters such as the strength of the collation must be specified as part of the collation URI. For example, suppose there is a collation " http://www.example.com/collations/French " that refers to a French collation that compares on the basis of base characters. Collations that use the same basic rules, but with higher strengths, for example, base characters and accents, or base characters, accents and case, would need to be given different names, say " http://www.example.com/collations/French1 " and " http://www.example.com/collations/French2 ". Note that some specifications use the term collation to refer to an algorithm that can be parameterized, but in this specification, each possible parameterization is considered to be a distinct collation.

The XQuery/XPath static context includes a provision for a default collation that can be used for string comparisons and ordering operations. See the description of the static context in Section 2.1.1 Static Context ^XP30. If the default collation is not specified by the user or the system, the default collation is the ·Unicode codepoint collation·.

5.3.2 The Unicode Codepoint Collation

[Definition] The collation URI http://www.w3.org/2005/xpath-functions/collation/codepoint identifies a collation which must be recognized by every implementation: it is referred to as the Unicode codepoint collation (not to be confused with the Unicode collation algorithm).

The Unicode codepoint collation does not perform any normalization on the supplied strings.

The collation is defined as follows. Each of the two strings is converted to a sequence of integers using the fn:string-to-codepoints function. These two sequences $A and $B are then compared as follows:

• If both sequences are empty, the strings are equal

• If one sequence is empty and the other is not, then the string corresponding to the empty sequence is less than the other string.

• If the first integer in $A is less than the first integer in $B, then the string corresponding to $A is less than the string corresponding to $B.

• If the first integer in $A is greater than the first integer in $B, then the string corresponding to $A is greater than the string corresponding to $B.

• Otherwise (the first pair of integers are equal), the result is obtained by applying the same rules recursively to fn:subsequence($A, 2) and fn:subsequence($B, 2)

5.3.3 Choosing a collation

Many functions have two signatures, where one signature includes a $collation argument and the other omits this argument.

The collation to use for these functions is determined by the following rules:

1. If the function specifies an explicit collation, CollationA (e.g., if the optional collation argument is specified in a call of the fn:compare function), then:

   • If CollationA is supported by the implementation, then CollationA is used.

   • Otherwise, an error is raised [err:FOCH0002].

2. If no collation is explicitly specified for the function and the default collation in the XQuery/XPath static context is CollationB, then:

   • If CollationB is supported by the implementation, then CollationB is used.

   • Otherwise, an error is raised [err:FOCH0002].

5.3.4 fn:compare

Summary

Returns -1, 0, or 1, depending on whether $comparand1 collates before, equal to, or after $comparand2 according to the rules of a selected collation.

Signatures

fn:compare($comparand1 as xs:string?, $comparand2 as xs:string?) as xs:integer?

fn:compare(	$comparand1	as xs:string?,
	$comparand2	as xs:string?,
	$collation	as xs:string) as xs:integer?

Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

Rules

Returns -1, 0, or 1, depending on whether the value of the $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, according to the rules of the collation that is used.

The collation used by this function is determined according to the rules in 5.3.3 Choosing a collation.

If either $comparand1 or $comparand2 is the empty sequence, the function returns the empty sequence.

This function, called with the first signature, defines the semantics of the "eq", "ne", "gt", "lt", "le" and "ge" operators on xs:string values.

Examples

The expression fn:compare('abc', 'abc') returns 0.

The expression fn:compare('Strasse', 'Straße') returns 0. (Assuming the default collation includes provisions that equate "ss" and the (German) character "ß" ("sharp-s"). Otherwise, the returned value depends on the semantics of the default collation.).

The expression fn:compare('Strasse', 'Straße', 'http://example.com/deutsch') returns 0. (Assuming the collation identified by the URI http://example.com/deutsch includes provisions that equate "ss" and the (German) character "ß" ("sharp-s"). Otherwise, the returned value depends on the semantics of that collation.).

The expression fn:compare('Strassen', 'Straße') returns 1. (Assuming the default collation includes provisions that treat differences between "ss" and the (German) character "ß" ("sharp-s") with less strength than the differences between the base characters, such as the final "n". ).

5.3.5 fn:codepoint-equal

Summary

Returns true if two strings are equal, considered codepoint-by-codepoint.

Signature

fn:codepoint-equal(	$comparand1	as xs:string?,
	$comparand2	as xs:string?) as xs:boolean?

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If either argument is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns true or false depending on whether the value of $comparand1 is equal to the value of $comparand2, according to the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

Notes

This function allows xs:anyURI values to be compared without having to specify the Unicode codepoint collation.

Examples

The expression fn:codepoint-equal("abcd", "abcd") returns true().

The expression fn:codepoint-equal("abcd", "abcd ") returns false().

The expression fn:codepoint-equal("", "") returns true().

The expression fn:codepoint-equal("", ()) returns ().

The expression fn:codepoint-equal((), ()) returns ().

5.4.1 fn:concat

Summary

Returns the concatenation of the string values of the arguments.

Operator Mapping

The two-argument form of this function defines the semantics of the "||" operator.

Signature

fn:concat(	$arg1	as xs:anyAtomicType?,
	$arg2	as xs:anyAtomicType?,
	...	) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

This function accepts two or more xs:anyAtomicType arguments and casts each one to xs:string. The function returns the xs:string that is the concatenation of the values of its arguments after conversion. If any argument is the empty sequence, that argument is treated as the zero-length string.

The fn:concat function is specified to allow two or more arguments, which are concatenated together. This is the only function specified in this document that allows a variable number of arguments. This capability is retained for compatibility with [XML Path Language (XPath) Version 1.0].

Notes

As mentioned in 5.1 String types Unicode normalization is not automatically applied to the result of fn:concat. If a normalized result is required, fn:normalize-unicode can be applied to the xs:string returned by fn:concat. The following XQuery:

let $v1 := "I plan to go to Mu"
let $v2 := "?nchen in September"
return concat($v1, $v2)

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:

"I plan to go to Mu?nchen in September"

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈". It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD. .

However, the following XQuery:

let $v1 := "I plan to go to Mu"
let $v2 := "?nchen in September"
return normalize-unicode(concat($v1, $v2))

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:

"I plan to go to München in September"

This returned result is normalized in NFC.

Examples

The expression fn:concat('un', 'grateful') returns "ungrateful".

The expression fn:concat('Thy ', (), 'old ', "groans", "", ' ring', ' yet', ' in', ' my', ' ancient',' ears.') returns "Thy old groans ring yet in my ancient ears.".

The expression fn:concat('Ciao!',()) returns "Ciao!".

The expression fn:concat('Ingratitude, ', 'thou ', 'marble-hearted', ' fiend!') returns "Ingratitude, thou marble-hearted fiend!".

The expression fn:concat(01, 02, 03, 04, true()) returns "1234true".

The expression 10 || '/' || 6 returns "10/6".

5.4.2 fn:string-join

Summary

Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.

Signatures

fn:string-join($arg1 as xs:string*) as xs:string

fn:string-join($arg1 as xs:string*, $arg2 as xs:string) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The effect of calling the single-argument version of this function is the same as calling the two-argument version with $arg2 set to a zero-length string.

The function returns an xs:string created by concatenating the items in the sequence $arg1, in order, using the value of $arg2 as a separator between adjacent items. If the value of $arg2 is the zero-length string, then the members of $arg1 are concatenated without a separator.

Notes

If the value of $arg1 is the empty sequence, the function returns the zero-length string.

Examples

The expression fn:string-join(('Now', 'is', 'the', 'time', '...'), ' ') returns "Now is the time ...".

The expression fn:string-join(('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '') returns "Blow, blow, thou winter wind!".

The expression fn:string-join((), 'separator') returns "".

Assume a document:

<doc>
  <chap>
    <section/>
  </chap>
</doc>

with the <section> element as the context node, the [XML Path Language (XPath) 2.0] expression:

fn:string-join(ancestor-or-self::*/name(), '/')

returns "doc/chap/section"

5.4.3 fn:substring

Summary

Returns the portion of the value of $sourceString beginning at the position indicated by the value of $start and continuing for the number of ·characters· indicated by the value of $length.

Signatures

fn:substring($sourceString as xs:string?, $start as xs:double) as xs:string

fn:substring(	$sourceString	as xs:string?,
	$start	as xs:double,
	$length	as xs:double) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the value of $sourceString is the empty sequence, the function returns the zero-length string.

Otherwise, the function returns a string comprising those ·characters· of $sourceString whose index position (counting from one) is greater than or equal to the value of $start (rounded to an integer), and (if $length is specified) less than the sum of $start and $length (both rounded to integers).

The characters returned do not extend beyond $sourceString. If $start is zero or negative, only those characters in positions greater than zero are returned.

More specifically, the three argument version of the function returns the characters in $sourceString whose position $p satisfies:

fn:round($start) <= $p < fn:round($start) + fn:round($length)

The two argument version of the function assumes that $length is infinite and thus returns the ·characters· in $sourceString whose position $p satisfies:

fn:round($start) <= $p

In the above computations, the rules for op:numeric-less-than and op:numeric-greater-than apply.

Notes

The first character of a string is located at position 1, not position 0.

Examples

The expression fn:substring("motor car", 6) returns " car". (Characters starting at position 6 to the end of $sourceString are selected.).

The expression fn:substring("metadata", 4, 3) returns "ada". (Characters at positions greater than or equal to 4 and less than 7 are selected.).

The expression fn:substring("12345", 1.5, 2.6) returns "234". (Characters at positions greater than or equal to 2 and less than 5 are selected.).

The expression fn:substring("12345", 0, 3) returns "12". (Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2.).

The expression fn:substring("12345", 5, -3) returns "". (Characters at positions greater than or equal to 5 and less than 2 are selected.).

The expression fn:substring("12345", -3, 5) returns "1". (Characters at positions greater than or equal to -3 and less than 2 are selected. Since the first position is 1, this is the character at position 1.).

The expression fn:substring("12345", 0 div 0E0, 3) returns "". (Since 0 div 0E0 returns NaN, and NaN compared to any other number returns false, no characters are selected.).

The expression fn:substring("12345", 1, 0 div 0E0) returns "". (As above.).

The expression fn:substring((), 1, 3) returns "".

The expression fn:substring("12345", -42, 1 div 0E0) returns "12345". (Characters at positions greater than or equal to -42 and less than INF are selected.).

The expression fn:substring("12345", -1 div 0E0, 1 div 0E0) returns "". (Since the value of -INF + INF is NaN, no characters are selected.).

5.4.4 fn:string-length

Summary

Returns the number of ·characters· in a string.

Signatures

fn:string-length() as xs:integer

fn:string-length($arg as xs:string?) as xs:integer

Properties

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·.

Rules

The function returns an xs:integer equal to the length in ·characters· of the value of $arg.

Calling the zero-argument version of the function is equivalent to calling fn:string-length(fn:string(.)).

If the value of $arg is the empty sequence, the function returns the xs:integer value zero (0).

Error Conditions

If $arg is not specified and the context item is absent^DM30, an error is raised: [err:XPDY0002]^XP.

Notes

Unlike some programming languages, a ·codepoint· greater than 65535 counts as one character, not two.

Examples

The expression fn:string-length("Harp not on that string, madam; that is past.") returns 45.

The expression fn:string-length(()) returns 0.

5.4.5 fn:normalize-space

Summary

Returns the value of $arg with leading and trailing whitespace removed, and sequences of internal whitespace reduced to a single space character.

Signatures

fn:normalize-space() as xs:string

fn:normalize-space($arg as xs:string?) as xs:string

Properties

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·.

Rules

If the value of $arg is the empty sequence, the function returns the zero-length string.

The function returns a string constructed by stripping leading and trailing whitespace from the value of $arg, and replacing sequences of one or more adjacent whitespace characters with a single space, #x20.

The whitespace characters are defined in the metasymbol S (Production 3) of [REC-xml].

If no argument is supplied, then $arg defaults to the string value (calculated using fn:string) of the context item (.).

Error Conditions

If no argument is supplied and the context item is absent^DM30 then an error is raised: [err:XPDY0002]^XP.

Notes

The definition of whitespace is unchanged in [Extensible Markup Language (XML) 1.1 Recommendation].

Examples

The expression fn:normalize-space(" The    wealthy curled darlings                                         of    our    nation. ") returns "The wealthy curled darlings of our nation.".

The expression fn:normalize-space(()) returns "".

5.4.6 fn:normalize-unicode

Summary

Returns the value of $arg after applying Unicode normalization.

Signatures

fn:normalize-unicode($arg as xs:string?) as xs:string

fn:normalize-unicode(	$arg	as xs:string?,
	$normalizationForm	as xs:string) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the value of $arg is the empty sequence, the function returns the zero-length string.

If the single-argument version of the function is used, the result is the same as calling the two-argument version with $normalizationForm set to the string "NFC".

Otherwise, the function returns the value of $arg normalized according to the rules of the normalization form identified by the value of $normalizationForm.

The effective value of $normalizationForm is the value of the expression fn:upper-case(fn:normalize-space($normalizationForm)).

• If the effective value of $normalizationForm is "NFC", then the function returns the value of $arg converted to Unicode Normalization Form C (NFC).

• If the effective value of $normalizationForm is "NFD", then the function returns the value of $arg converted to Unicode Normalization Form D (NFD).

• If the effective value of $normalizationForm is "NFKC", then the function returns the value of $arg in Unicode Normalization Form KC (NFKC).

• If the effective value of $normalizationForm is "NFKD", then the function returns the value of $arg converted to Unicode Normalization Form KD (NFKD).

• If the effective value of $normalizationForm is "FULLY-NORMALIZED", then the function returns the value of $arg converted to fully normalized form.

• If the effective value of $normalizationForm is the zero-length string, no normalization is performed and $arg is returned.

Normalization forms NFC, NFD, NFKC, and NFKD, and the algorithms to be used for converting a string to each of these forms, are defined in [Unicode Normaliation Forms].

The motivation for normalization form FULLY-NORMALIZED is explained in [Character Model for the World Wide Web 1.0: Normalization]. However, as that specification did not progress beyond working draft status, the normative specification is as follows:

• A string is fully-normalized if (a) it is in normalization form NFC as defined in [Unicode Normaliation Forms], and (b) it does not start with a composing character.

• A composing character is a character that is one or both of the following:

  • the second character in the canonical decomposition mapping of some character that is not listed in the Composition Exclusion Table defined in [Unicode Normaliation Forms];

  • of non-zero canonical combining class (as defined in [The Unicode Standard]).

• A string is converted to FULLY-NORMALIZED form as follows:

  • if the first character in the string is a composing character, prepend a single space (x20);

  • convert the resulting string to normalization form NFC.

Conforming implementations must support normalization form "NFC" and may support normalization forms "NFD", "NFKC", "NFKD", and "FULLY-NORMALIZED". They may also support other normalization forms with ·implementation-defined· semantics.

Error Conditions

An error is raised [err:FOCH0003] if the effective value of the $normalizationForm argument is not one of the values supported by the implementation.

5.4.7 fn:upper-case

Summary

Converts a string to upper case.

Signature

fn:upper-case($arg as xs:string?) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the value of $arg is the empty sequence, the zero-length string is returned.

Otherwise, the function returns the value of $arg after translating every ·character· to its upper-case correspondent as defined in the appropriate case mappings section in the Unicode standard [The Unicode Standard]. For versions of Unicode beginning with the 2.1.8 update, only locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and likely future versions) of Unicode, precise mappings are described in default case operations, which are full case mappings in the absence of tailoring for particular languages and environments. Every lower-case character that does not have an upper-case correspondent, as well as every upper-case character, is included in the returned value in its original form.

Notes

Case mappings may change the length of a string. In general, the fn:upper-case and fn:lower-case functions are not inverses of each other: fn:lower-case(fn:upper-case($arg)) is not guaranteed to return $arg, nor is fn:upper-case(fn:lower-case($arg)). The Latin small letter dotless i (as used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The Latin capital letter i with dot above is the most prominent upper-case letter which will not round trip; there are others, such as Latin capital letter Sharp S (#1E9E) which is introduced in Unicode 5.1.

These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.

Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of "è" is "È", while in metropolitan France it is more commonly "E"; only one of these is supported by the functions as defined.

Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.

Examples

The expression fn:upper-case("abCd0") returns "ABCD0".

5.4.8 fn:lower-case

Summary

Converts a string to lower case.

Signature

fn:lower-case($arg as xs:string?) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the value of $arg is the empty sequence, the zero-length string is returned.

Otherwise, the function returns the value of $arg after translating every ·character· to its lower-case correspondent as defined in the appropriate case mappings section in the Unicode standard [The Unicode Standard]. For versions of Unicode beginning with the 2.1.8 update, only locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and likely future versions) of Unicode, precise mappings are described in default case operations, which are full case mappings in the absence of tailoring for particular languages and environments. Every upper-case character that does not have a lower-case correspondent, as well as every lower-case character, is included in the returned value in its original form.

Notes

Case mappings may change the length of a string. In general, the fn:upper-case and fn:lower-case functions are not inverses of each other: fn:lower-case(fn:upper-case($arg)) is not guaranteed to return $arg, nor is fn:upper-case(fn:lower-case($arg)). The Latin small letter dotless i (as used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The Latin capital letter i with dot above is the most prominent upper-case letter which will not round trip; there are others, such as Latin capital letter Sharp S (#1E9E) which is introduced in Unicode 5.1.

These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.

Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of "è" is "È", while in metropolitan France it is more commonly "E"; only one of these is supported by the functions as defined.

Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.

Examples

The expression fn:lower-case("ABc!D") returns "abc!d".

5.4.9 fn:translate

Summary

Returns the value of $arg modified by replacing or removing individual characters.

Signature

fn:translate(	$arg	as xs:string?,
	$mapString	as xs:string,
	$transString	as xs:string) as xs:string

Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If the value of $arg is the empty sequence, the function returns the zero-length string.

Otherwise, the function returns a result string constructed by processing each ·character· in the value of $arg, in order, according to the following rules:

1. If the character does not appear in the value of $mapString then it is added to the result string unchanged.

2. If the character first appears in the value of $mapString at some position M, where the value of $transString is M or more characters in length, then the character at position M in $transString is added to the result string.

3. If the character first appears in the value of $mapString at some position M, where the value of $transString is less than M characters in length, then the character is omitted from the result string.

Notes

If $mapString is the zero-length string then the function returns $arg unchanged.

If a character occurs more than once in $mapString, then the first occurrence determines the action taken.

If $transString is longer than $mapString, the excess characters are ignored.

Examples

The expression fn:translate("bar","abc","ABC") returns "BAr".

The expression fn:translate("--aaa--","abc-","ABC") returns "AAA".

The expression fn:translate("abcdabc", "abc", "AB") returns "ABdAB".