XPath and XQuery Functions and Operators 4.0

1.6.1 Item Types

The first diagram and its corresponding table illustrate the relationship of various item types.

Item types are used to characterize the various types of item that can appear in a sequence (nodes, atomic values, and functions), and they are therefore used in declaring the types of variables or the argument types and result types of functions.

Item types in the data model form a directed graph, rather than a hierarchy or lattice: in the relationship defined by the derived-from(A, B) function, some types are derived from more than one other type. Examples include functions (function(xs:string) as xs:int is substitutable for function(xs:NCName) as xs:int and also for function(xs:string) as xs:decimal), and union types (A is substitutable for union(A, B) and also for union(A, C). In XDM, item types include node types, function types, and built-in atomic types. The diagram, which shows only hierarchic relationships, is therefore a simplification of the full model.

In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

1.6.2 Schema Type Hierarchy

The next diagram and table illustrate the schema type subsystem, in which all types are derived from the distinguished type xs:anyType.

Schema types include built-in types defined in the XML Schema specification, and user-defined types defined using mechanisms described in the XML Schema specification. Schema types define the permitted contents of nodes. The main categories are complex types, which define the permitted content of elements, and simple types, which can be used to constrain the values of both elements and attributes.

In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

1.6.3 Atomic Type Hierarchy

The final diagram and table show all of the atomic types, including the primitive simple types and the built-in types derived from the primitive simple types. This includes all the built-in datatypes defined in [XML Schema Part 2: Datatypes Second Edition].

Atomic types are both item types and schema types, so the root type xs:anyAtomicType may be found in both the previous diagrams.

In the table, each type whose name is indented is derived from the type whose name appears nearest above it with one less level of indentation.

1.7.1 Strings, characters, and codepoints

This document uses the terms string, character, and codepoint with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 3.1], and which are paraphrased here for ease of reference:

[Definition] A character is an instance of the Char^XML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].

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

[Definition] A codepoint is an 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.7.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 value in the value space of the xs:QName datatype as defined in the XDM data model (see [XQuery and XPath Data Model (XDM) 3.1]): that is, a triple containing namespace prefix (optional), namespace URI (optional), and local name. Two expanded QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same. The prefix plays no part in the comparison, but is used only if the expanded QName needs to be converted back to a string.

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.7.3 Conformance terminology

In this specification:

• The auxiliary verb must, when rendered in small capitals, indicates a precondition for conformance.

  • When the sentence relates to an implementation of a function (for example "All implementations must recognize URIs of the form ...") then an implementation is not conformant unless it behaves as stated.

  • When the sentence relates to the result of a function (for example "The result must have the same type as $arg") then the implementation is not conformant unless it delivers a result as stated.

  • When the sentence relates to the arguments to a function (for example "The value of $arg must be a valid regular expression") then the implementation is not conformant unless it enforces the condition by raising a dynamic error whenever the condition is not satisfied.

• The auxiliary verb may, when rendered in small capitals, indicates optional or discretionary behavior. The statement "An implementation may do X" implies that it is implementation-dependent whether or not it does X.

• The auxiliary verb should, when rendered in small capitals, indicates desirable or recommended behavior. The statement "An implementation should do X" implies that it is desirable to do X, but implementations may choose to do otherwise if this is judged appropriate.

[Definition] Where behavior is described as implementation-defined, variations between processors are permitted, but a conformant implementation must document the choices it has made.

[Definition] Where behavior is described as implementation-dependent, variations between processors are permitted, and conformant implementations are not required to document the choices they have made.

1.7.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] An execution scope is a sequence of calls to the function library during which certain aspects of the state are required to remain invariant. For example, two calls to fn:current-dateTime within the same execution scope will return the same result. The execution scope is defined by the host language that invokes the function library. In XSLT, for example, any two function calls executed during the same transformation are in the same execution scope (except that static expressions, such as those used in use-when attributes, are in a separate execution scope).

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:

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

2. Both items are nodes, and represent the same node.

3. Both items are maps, both maps have the same number of entries, and for every entry E1 in the first map there is an entry E2 in the second map such that the keys of E1 and E2 are ·the same key·, and the corresponding values V1 and V2 are ·identical·.

4. Both items are arrays, both arrays have the same number of members, and the members are pairwise ·identical·.

5. Both items are function items, neither item is a map or array, and all the following conditions apply:

   1. Either both functions have the same name, or both names are absent^DM31.

   2. Both functions have the same arity.

   3. Both functions have the same function signature. Two function signatures are defined to be the same if the declared result types are identical and the declared argument types are pairwise identical. Two types S and T are defined to be identical if and only if subtype(S, T) and subtype(T, S) both hold, where the subtype relation is defined in Section 2.5.6.1 The judgement subtype(A, B) ^XP31.

      Note:

      Under this definition, a union type with memberTypes="xs:double xs:decimal" is identical to a union type with memberTypes="xs:decimal xs:double". However, two functions whose signatures differ in this way will probably be deemed non-identical under rule (e) below, because they are likely to have different effect when invoked with an argument of type xs:untypedAtomic.

   4. Both functions have the same nonlocal variable bindings (sometimes called the function's closure).

   5. The processor is able to determine that the implementations of the two functions are equivalent, in the sense that for all possible combinations of arguments, the two functions have the same effect.

   Note:

   There is no function or operator defined in the specification that tests whether two function items are identical. Where the specification requires two function items to be identical, for example in the results of repeated calls of a function whose result is a function, then the processor must ensure that it returns functions that are indistinguishable in their observable effect. Where the specification defines behavior conditional on two function items being identical, the determination of identity is to some degree implementation-dependent. There are cases where function items are definitely not identical (for example if they have different name or arity), but positive determination of identity is possible only using implementation-dependent techniques, for example when both items contain references to the same piece of code representing the function's implementation.

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.

A function that is context-dependent can be used as a named function reference, can be partially applied, and can be found using fn:function-lookup. The principle in such cases is that the static context used for the function evaluation is taken from the static context of the named function reference, partial function application, or the call on fn:function-lookup; and the dynamic context for the function evaluation is taken from the dynamic context of the evaluation of the named function reference, partial function application, or the call of fn:function-lookup. In effect, the static and dynamic part of the context thus act as part of the closure of the function item.

Context-dependent functions fall into a number of categories:

1. The functions fn:current-date, fn:current-dateTime, fn:current-time, fn:default-language, 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:element-with-id#1, fn:id#1, fn:idref#1, fn:lang#1, fn:last#0, fn:local-name#0, fn:name#0, fn:namespace-uri#0, fn:normalize-space#0, fn:number#0, fn:path#0, fn:position#0, fn:root#0, fn:string#0, and fn:string-length#0 depend on the focus^XP31. 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^XP31 (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.

The fn:function-lookup function is a special case because it is potentially dependent on everything in the static and dynamic context. This is because the static and dynamic context of the call to fn:function-lookup are used as the static and dynamic context of the function that fn:function-lookup returns.

[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 within a single ·execution scope· 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:

• [Definition] Some functions (such as fn:distinct-values, fn:unordered, map:keys, and map:for-each) produce results in an ·implementation-defined· or ·implementation-dependent· order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering.

• Some functions (such as fn:analyze-string, fn:parse-xml, fn:parse-xml-fragment, and fn:json-to-xml) construct a tree of nodes to represent their 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·.

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.

  If no value is supplied for the $code argument (that is, if the function is called with no arguments or if the first argument is an empty sequence), the effective value of the error code is fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000').

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

  If no value is supplied for the $description argument (that is, if the function is called with less than two arguments), then the effective value of the description is ·implementation-dependent·.

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

  If no value is supplied for the $error-object argument (that is, if the function is called with less than three arguments), then the effective value of the error object is ·implementation-dependent·.

Error Conditions

This function always raises a dynamic error. By default, it raises [err:FOER0000]

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.

Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.

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.

Signatures

fn:trace($value as item()*) as item()*

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 $value, unchanged.

In addition, the values of $value, converted to an xs:string, and $label (if supplied) 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·.

Notes

Sometimes there is a need to output trace information unrelated to a specific value. In such cases it can be useful to set $value to an empty string or an empty sequence, and to compute the value of the $label argument: fn:trace((), "Processing item " || $i).

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.

3.2.2 fn:stack-trace

Summary

Returns implementation-dependent information about the current state of execution.

Signature

fn:stack-trace() as xs:string

Rules

The result of the function is an implementation-dependent string containing diagnostic information about the current state of execution.

The function is non-deterministic: multiple calls will typically produce different results.

Notes

The function will typically be called to assist in diagnosing dynamic errors.

4.2.1 op:numeric-add

Summary

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

Operator Mapping

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

Signature

op:numeric-add($arg1 as xs:numeric, $arg2 as xs:numeric) as xs: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 when applied to two numeric values.

Signature

op:numeric-subtract($arg1 as xs:numeric, $arg2 as xs:numeric) as xs: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 when applied to two numeric values.

Signature

op:numeric-multiply($arg1 as xs:numeric, $arg2 as xs:numeric) as xs: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 when applied to two numeric values.

Signature

op:numeric-divide($arg1 as xs:numeric, $arg2 as xs:numeric) as xs: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

A dynamic 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 [IEEE 754-2008]. A positive number divided by positive zero returns INF. A negative number divided by positive zero returns -INF. Division by negative zero returns -INF and INF, respectively. Positive or negative zero divided by positive or negative zero returns NaN. Also, INF or -INF divided by INF or -INF returns NaN.

4.2.5 op:numeric-integer-divide

Summary

Performs an integer division.

Operator Mapping

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

Signature

op:numeric-integer-divide(	$arg1	as xs:numeric,
	$arg2	as xs: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 the following expression is true:

fn:abs($N * $arg2) le fn:abs($arg1) 
               and fn:compare($N * $arg2, 0) eq fn:compare($arg1, 0).

Note:

The second term in this condition ensures that the result has the correct sign.

The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division.

Error Conditions

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

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

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 when applied to two numeric values.

Signature

op:numeric-mod($arg1 as xs:numeric, $arg2 as xs:numeric) as xs: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 [IEEE 754-2008] rounding division i.e. additional digits are truncated, not rounded to the required precision.

Error Conditions

A dynamic 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 a numeric value.

Signature

op:numeric-unary-plus($arg as xs:numeric) as xs: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 + operator can be used to force conversion of an untyped node to a number: the result of +@price is the same as xs:double(@price) if the type of @price is xs:untypedAtomic.

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 when applied to a numeric value.

Signature

op:numeric-unary-minus($arg as xs:numeric) as xs: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 when applied to two numeric values, and is also used in defining the semantics of "ne", "le" and "ge".

Signature

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

Rules

General rules: see 4.3 Comparison operators on numeric values.

The two arguments will always have been converted so they have the same primitive type (both xs:float, both xs:double, or both xs:decimal. The values are compared using the equality rules defined in [XSD11].

Notes

Positive and negative zero compare equal. If $arg1 or $arg2 is NaN, the function returns false.

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 when applied to two numeric values, and is also used in defining the semantics of le, gt, and ge.

Signature

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

Rules

General rules: see 4.3 Comparison operators on numeric values.

The two arguments will always have been converted so they have the same primitive type (both xs:float, both xs:double, or both xs:decimal. The values are compared using the ordering rules defined in [XSD11]. If the ordering relation of the two values is imcomparable (which happens when one or both of them is NaN, then the result is false.

Notes

For xs:float and xs:double values, positive infinity is greater than all other non-NaN values; negative infinity is less than all other non-NaN values. Positive and negative zero compare equal. If $arg1 or $arg2 is NaN, the function returns false.

4.4.1 fn:abs

Summary

Returns the absolute value of $value.

Signature

fn:abs($value as xs:numeric?) as xs:numeric?

Properties

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

Rules

General rules: see 4.4 Functions on numeric values.

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

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:positiveInteger then the value of $value may be returned unchanged.

For xs:float and xs:double arguments, if the argument is positive zero or negative zero, then positive zero is returned. If the argument is positive or negative infinity, positive infinity is returned.

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 $value upwards to a whole number.

Signature

fn:ceiling($value as xs:numeric?) as xs: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 $value.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is less than zero and greater than -1, negative zero is returned.

Examples

The expression fn:ceiling(10.5) returns 11.

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

4.4.3 fn:floor

Summary

Rounds $value downwards to a whole number.

Signature

fn:floor($value as xs:numeric?) as xs: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 $value.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned.

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($value as xs:numeric?) as xs:numeric?

fn:round($value as xs:numeric?, $precision as xs:integer) as xs: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 $value that is a multiple of ten to the power of minus $precision. If two such values are equally near (for example, if the fractional part in $value is exactly .5), the function returns the one that is closest to positive infinity.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

The single-argument version of this function produces the same result as the two-argument version with $precision=0 (that is, it rounds to a whole number).

When $value is of type xs:float and xs:double:

1. If $value 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 $value.

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($value as xs:numeric?) as xs:numeric?

fn:round-half-to-even(	$value	as xs:numeric?,
	$precision	as xs:integer) as xs: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 $value that is a multiple of ten to the power of minus $precision. If two such values are equally near (e.g. if the fractional part in $value is exactly .500...), the function returns the one whose least significant digit is even.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $value is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $value is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

The first signature of this function produces the same result as the second signature with $precision=0.

For arguments of type xs:float and xs:double:

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.4.6 fn:is-NaN

Summary

Returns true if the argument is the xs:float or xs:double value NaN.

Signature

fn:is-NaN($value as xs:anyAtomicType) as xs:boolean

Properties

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

Rules

The function returns true if the argument is the xs:float or xs:double value NaN; otherwise it returns false.

Examples

The expression fn:is-NaN(23) returns false().

The expression fn:is-NaN("NaN") returns false().

The expression fn:is-NaN(fn:number("twenty-three")) returns true().

The expression fn:is-NaN(math:sqrt(-1)) returns true().

4.5.1 fn:number

Summary

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

Signatures

fn:number() as xs:double

fn:number($value 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(.), as defined by the rules that follow.

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

Otherwise, $value is converted to an xs:double following the rules of 19.1.2.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.

Error Conditions

A dynamic error is raised [err:XPDY0002]^XP if $value is omitted and the context item is absent^DM31.

As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item is a sequence containing more than one atomic value.

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.

Generally fn:number returns NaN rather than raising a dynamic error if the argument cannot be converted to xs:double. However, a type error is raised in the usual way if the supplied argument cannot be atomized or if the result of atomization does not match the required argument type.

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

Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on default language.

The three-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.

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 consists of a primary format token, optionally followed by a format modifier. The primary format token is always present and must not be zero-length. If the string contains one or more semicolons then everything that precedes the last semicolon is taken as the primary format token and everything that follows is taken as the format modifier; if the string contains no semicolon then the entire picture is taken as the primary format token, and the format modifier is taken to be absent (which is equivalent to supplying a zero-length string).

The primary format token is classified as one of the following:

1. A decimal-digit-pattern made up of optional-digit-signs, mandatory-digit-signs, and grouping-separator-signs.

   • The optional-digit-sign is the character "#".

   • A mandatory-digit-sign is a ·character· in Unicode category Nd. All mandatory-digit-signs within the format token must be from the same digit family, where a digit family is a sequence of ten consecutive characters in Unicode category Nd, having digit values 0 through 9. Within the format token, these digits are interchangeable: a three-digit number may thus be indicated equivalently by 000, 001, or 999.

   • a grouping-separator-sign is a non-alphanumeric character, that is a ·character· whose Unicode category is other than Nd, Nl, No, Lu, Ll, Lt, Lm or Lo.

   If the primary format token contains at least one Unicode digit then it is taken as a decimal digit pattern, and in this case it must match the regular expression ^((\p{Nd}|#|[^\p{N}\p{L}])+?)$. If it contains a digit but does not match this pattern, a dynamic error is raised [err:FODF1310].

   Note:

   If a semicolon is to be used as a grouping separator, then the primary format token as a whole must be followed by another semicolon, to ensure that the grouping separator is not mistaken as a separator between the primary format token and the format modifier.

   There must be at least one mandatory-digit-sign. There may be zero or more optional-digit-signs, and (if present) these must precede all mandatory-digit-signs. There may be zero or more grouping-separator-signs. A grouping-separator-sign must not appear at the start or end of the decimal-digit-pattern, nor adjacent to another grouping-separator-sign.

   The corresponding output format is a decimal number, using this digit family, with at least as many digits as there are mandatory-digit-signs in the format token. Thus, a format token 1 generates the sequence 0 1 2 ... 10 11 12 ..., and a format token 01 (or equivalently, 00 or 99) generates the sequence 00 01 02 ... 09 10 11 12 ... 99 100 101. A format token of ١ (Arabic-Indic digit one) generates the sequence ١ then ٢ then ٣ ...

   The grouping-separator-signs are handled as follows:

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

   2. More specifically, the position of a grouping separator is the number of optional-digit-signs and mandatory-digit-signs appearing between the grouping separator and the right-hand end of the primary format token.

   3. Grouping separators are defined to be regular if the following conditions apply:

      1. There is at least one grouping separator.

      2. Every grouping separator is the same character (call it C).

      3. There is a positive integer G (the grouping size) such that:

         1. The position of every grouping separator is an integer multiple of G, and

         2. Every positive integer multiple of G that is less than the number of optional-digit-signs and mandatory-digit-signs in the primary format token is the position of a grouping separator.

   4. The grouping separator template is a (possibly infinite) set of (position, character) pairs.

   5. If grouping separators are regular, then the grouping separator template contains one pair of the form (n×G, C) for every positive integer n where G is the grouping size and C is the grouping character.

   6. Otherwise (when grouping separators are not regular), the grouping separator template contains one pair of the form (P, C) for every grouping separator found in the primary formatting token, where C is the grouping separator character and P is its position.

   7. Note:

      If there are no grouping separators, then the grouping separator template is an empty set.

   The number is formatted as follows:

   1. Let S₁ be the result of formatting the supplied number in decimal notation as if by casting it to xs:string.

   2. Let S₂ be the result of padding S₁ on the left with as many leading zeroes as are needed to ensure that it contains at least as many digits as the number of mandatory-digit-signs in the primary format token.

   3. Let S₃ be the result of replacing all decimal digits (0-9) in S₂ with the corresponding digits from the selected digit family.

   4. Let S₄ be the result of inserting grouping separators into S₃: for every (position P, character C) pair in the grouping separator template where P is less than the number of digits in S₃, insert character C into S₃ at position P, counting from the right-hand end.

   5. Let S₅ be the result of converting S₄ into ordinal form, if an ordinal modifier is present, as described below.

   6. The result of the function is then S₅.

2. The format token A, which generates the sequence A B C ... Z AA AB AC....

3. The format token a, which generates the sequence a b c ... z aa ab ac....

4. The format token i, which generates the sequence i ii iii iv v vi vii viii ix x ....

5. The format token I, which generates the sequence I II III IV V VI VII VIII IX X ....

6. The format token w, which generates numbers written as lower-case words, for example in English, one two three four ...

7. The format token W, which generates numbers written as upper-case words, for example in English, ONE TWO THREE FOUR ...

8. The format token Ww, which generates numbers written as title-case words, for example in English, One Two Three Four ...

9. Any other format token, which indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is ·implementation-defined· which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1.

   Note:

   In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example (see also the example below) is classical Greek where a dexia keraia (x0374, ʹ) and sometimes an aristeri keraia (x0375, ͵) is added.

For all format tokens other than a decimal-digit-pattern, there may be ·implementation-defined· lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the format token ① (circled digit one, ①) has a range imposed by the Unicode character repertoire — zero to 20 in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1.

The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. There are various conventions in use for how alphabetic sequences continue when the alphabet is exhausted, and differing conventions for how roman numerals are written (for example, IV versus IIII as the representation of the number 4). Sometimes alphabetic sequences are used that omit letters such as i and o. This specification does not prescribe the detail of any sequence other than those sequences consisting entirely of decimal digits.

Many numbering sequences are language-sensitive. This applies especially to the sequence selected by the tokens w, W and Ww. It also applies to other sequences, for example different languages using the Cyrillic alphabet use different sequences of characters, each starting with the letter #x410 (Cyrillic capital letter A). In such cases, the $lang argument specifies which language's conventions are to be used. If the argument is specified, the value should be either an empty sequence or a value that would be valid for the xml:lang attribute (see [Extensible Markup Language (XML) 1.0 (Fifth Edition)]). Note that this permits the identification of sublanguages based on country codes (from ISO 3166-1) as well as identification of dialects and regions within a country.

The set of languages for which numbering is supported is ·implementation-defined·. If the $lang argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context.

The format modifier must be a string that matches the regular expression ^([co](\(.+\))?)?[at]?$. That is, if it is present it must consist of one or more of the following, in order:

• either c or o, optionally followed by a sequence of characters enclosed between parentheses, to indicate cardinal or ordinal numbering respectively, the default being cardinal numbering

• either a or t, to indicate alphabetic or traditional numbering respectively, the default being ·implementation-defined·.

If the o modifier is present, this indicates a request to output ordinal numbers rather than cardinal numbers. For example, in English, when used with the format token 1, this outputs the sequence 1st 2nd 3rd 4th ..., and when used with the format token w outputs the sequence first second third fourth ....

The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string.

It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.

The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is ·implementation-defined·.

Error Conditions

A dynamic error is raised [err:FODF1310] if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.

Notes

1. Note the careful distinction between conditions that are errors and conditions where fallback occurs. The principle is that an error in the syntax of the format picture will be reported by all processors, while a construct that is recognized by some implementations but not others will never result in an error, but will instead cause a fallback representation of the integer to be used.

2. The following notes apply when a decimal-digit-pattern is used:

   1. If grouping-separator-signs appear at regular intervals within the format token, then the sequence is extrapolated to the left, so grouping separators will be used in the formatted number at every multiple of N. For example, if the format token is 0'000 then the number one million will be formatted as 1'000'000, while the number fifteen will be formatted as 0'015.

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

   3. Grouping separators are not designed for effects such as formatting a US telephone number as (365)123-9876. In general they are not suitable for such purposes because (a) only single characters are allowed, and (b) they cannot appear at the beginning or end of the number.

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

3. The following notes apply when ordinal numbering is selected using the o modifier.

   In some languages, the form of numbers (especially ordinal numbers) varies depending on the grammatical context: they may have different genders and may decline with the noun that they qualify. In such cases the string appearing in parentheses after the letter c or o may be used to indicate the variation of the cardinal or ordinal number required.

   The way in which the variation is indicated will depend on the conventions of the language.

   For inflected languages that vary the ending of the word, the approach recommended in the previous version of this specification was to indicate the required ending, preceded by a hyphen: for example in German, appropriate values might be o(-e), o(-er), o(-es), o(-en).

   Another approach, which might usefully be adopted by an implementation based on the open-source ICU localization library [ICU], or any other library making use of the Unicode Common Locale Data Repository [Unicode CLDR], is to allow the value in parentheses to be the name of a registered numbering rule set for the language in question, conventionally prefixed with a percent sign: for example, o(%spellout-ordinal-masculine), or c(%spellout-cardinal-year).

Examples

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

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

Ordinal numbering in Italian: The specification "1;o(-º)" with $lang equal to it, if supported, should produce the sequence:

1º 2º 3º 4º ...

The specification "Ww;o" with $lang equal to it, if supported, should produce the sequence:

Primo Secondo Terzo Quarto Quinto ...

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

format-integer(14, 'Ww;o(-e)', 'de') might return "Vierzehnte"

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

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

The expression format-integer(1234, '#;##0;') returns "1;234".

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 properties, 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 character that is the value of the zero-digit^XP31 property.

[Definition] The optional digit character is the character that is the value of the digit^XP31 property.

For any named or unnamed decimal format, the properties representing characters used in a ·picture string· must have distinct values. These properties are decimal-separator^XP31 , grouping-separator^XP31, exponent-separator^XP31, percent^XP31, per-mille^XP31, digit^XP31, and pattern-separator^XP31. Furthermore, none of these properties 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 xs:numeric?, $picture as xs:string) as xs:string

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

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 unnamed decimal-format, if there is no $decimal-format-name argument. The syntax of the picture string is described in 4.7.3 Syntax of the picture string.

The $value argument may be of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes including xs:integer). Note that if an xs:decimal is supplied, it is not automatically promoted to an xs:double, as such promotion can involve a loss of precision.

If the supplied value of the $value argument is an empty sequence, the function behaves as if the supplied value were the xs:double value NaN.

The value of $decimal-format-name, if present and non-empty, must be either an xs:QName, or a string which after removal of leading and trailing whitespace is in the form of an EQName as defined in the XPath 4.0 grammar, that is one of the following:

• A lexical QName, which is expanded using the statically known namespaces. The default namespace is not used (no prefix means no namespace).

• A URIQualifiedName using the syntax Q{uri}local, where the URI can be zero-length to indicate a name in no namespace.

The decimal format that is used is the decimal format in the static context whose name matches $decimal-format-name if supplied, or the unnamed decimal format in the static context otherwise.

The evaluation of the fn:format-number function takes place in two phases, an analysis phase described in 4.7.4 Analyzing the picture string and a formatting phase described in 4.7.5 Formatting the number.

The analysis phase takes as its inputs the ·picture string· and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.

The result of the function is the formatted string representation of the supplied number.

Error Conditions

A dynamic error is raised [err:FODF1280] if the $decimal-format-name argument is supplied as an xs:string that is neither a valid lexical QName nor a valid URIQualifiedName, or if it uses a prefix that is not found in the statically known namespaces, or if the static context does not contain a declaration of a decimal-format with a matching expanded QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

Notes

A string is an ordered sequence of characters, and this specification uses terms such as "left" and "right", "preceding" and "following" in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.

Examples

The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is ".", the grouping separator is ",", the minus-sign is "-", and the percent-sign is "%".

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

The expression format-number(12345678.9, '9,999.99') returns "12,345,678.90".

The expression format-number(123.9, '9999') returns "0124".

The expression format-number(0.14, '01%') returns "14%".

The expression format-number(-6, '000') returns "-006".

The following example assumes the existence of a decimal format named 'ch' in which the grouping separator is ʹ and the decimal separator is ·:

The expression format-number(1234.5678, '#ʹ##0·00', 'ch') returns "1ʹ234·57".

The following examples assume that the exponent separator is in decimal format 'fortran' is 'E':

The expression format-number(1234.5678, '00.000E0', 'fortran') returns "12.346E2".

The expression format-number(0.234, '0.0E0', 'fortran') returns "2.3E-1".

The expression format-number(0.234, '#.00E0', 'fortran') returns "0.23E0".

The expression format-number(0.234, '.00E0', 'fortran') returns ".23E0".

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 properties decimal-separator^XP31 , exponent-separator^XP31, grouping-separator^XP31, and digit^XP31, and pattern-separator^XP31 and the members of the ·decimal digit family·, are classified as active characters, and all other characters (including the values of the properties percent^XP31 and per-mille^XP31) are classified as passive characters.

A dynamic error is raised [err:FODF1310] if the ·picture string· does not conform to the following rules. Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".

• A picture-string consists either of a sub-picture, or of two sub-pictures separated by the pattern-separator^XP31 character. A picture-string must not contain more than one instance of the pattern-separator^XP31 character. If the picture-string contains two sub-pictures, the first is used for positive and unsigned zero values and the second for negative values.

• A sub-picture must not contain more than one instance of the decimal-separator^XP31 character.

• A sub-picture must not contain more than one instance of the percent^XP31 or per-mille^XP31 characters, and it must not contain one of each.

• The mantissa part of a sub-picture (defined below) must contain at least one character that is either an ·optional digit character· or a member of the ·decimal digit family·.

• A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.

• A sub-picture must not contain a grouping-separator^XP31 character that appears adjacent to a decimal-separator^XP31 character, or in the absence of a decimal-separator^XP31 character, at the end of the integer part.

• A sub-picture must not contain two adjacent instances of the grouping-separator^XP31 character.

• The integer part of a sub-picture (defined below) must not contain a member of the ·decimal digit family· that is followed by an instance of the ·optional digit character·. The fractional part of a sub-picture (defined below) must not contain an instance of the ·optional digit character· that is followed by a member of the ·decimal digit family·.

• A character that matches the exponent-separator^XP31 property is treated as an exponent-separator-sign if it is both preceded and followed within the sub-picture by an active character. Otherwise, it is treated as a passive character. A sub-picture must not contain more than one character that is treated as an exponent-separator-sign.

• A sub-picture that contains a percent^XP31 or per-mille^XP31 character must not contain a character treated as an exponent-separator-sign.

• If a sub-picture contains a character treated as an exponent-separator-sign then this must be followed by one or more characters that are members of the ·decimal digit family·, and it must not be followed by any active character that is not a member of the ·decimal digit family·.

The mantissa part of the sub-picture is defined as the part that appears to the left of the exponent-separator-sign if there is one, or the entire sub-picture otherwise. The exponent part of the subpicture is defined as the part that appears to the right of the exponent-separator-sign; if there is no exponent-separator-sign then the exponent part is absent.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator^XP31 character if there is one, or the entire mantissa part otherwise.

The fractional part of the sub-picture is defined as that part of the mantissa part that appears to the right of the decimal-separator^XP31 character if there is one, or the part that appears to the right of the rightmost active character otherwise. The fractional part may be zero-length.

4.7.4 Analyzing the picture string

This phase of the algorithm analyzes the ·picture string· and the properties from the selected decimal format in the static context, and it has the effect of setting the values of various variables, which are used in the subsequent formatting phase. These variables are listed below. Each is shown with its initial setting and its datatype.

Several variables are associated with each sub-picture. If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positive and unsigned zero numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture.

The variables are as follows:

• The integer-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture. For each grouping-separator^XP31 character that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the integer part of the sub-picture and to the right of the grouping-separator^XP31 character.

  The grouping is defined to be regular if the following conditions apply:

  1. There is an least one grouping-separator in the integer part of the sub-picture.

  2. There is a positive integer G (the grouping size) such that the position of every grouping-separator in the integer part of the sub-picture is a positive integer multiple of G.

  3. Every position in the integer part of the sub-picture that is a positive integer multiple of G is occupied by a grouping-separator.

  If the grouping is regular, then the integer-part-grouping-positions sequence contains all integer multiples of G as far as necessary to accommodate the largest possible number.

• The minimum-integer-part-size is an integer indicating the minimum number of digits that will appear to the left of the decimal-separator character. It is initially set to the number of ·decimal digit family· characters found in the integer part of the sub-picture, but may be adjusted as described below.

  Note:

  There is no maximum integer part size. All significant digits in the integer part of the number will be displayed, even if this exceeds the number of ·optional digit character· and ·decimal digit family· characters in the subpicture.

• The scaling factor is a non-negative integer used to determine the scaling of the mantissa in exponential notation. It is set to the number of ·decimal digit family· characters found in the integer part of the sub-picture.

• The prefix is set to contain all passive characters in the sub-picture to the left of the leftmost active character. If the picture string contains only one sub-picture, the prefix for the negative sub-picture is set by concatenating the minus-sign^XP31 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^XP31 character that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of ·optional digit character· and ·decimal digit family· characters that appear within the fractional part of the sub-picture and to the left of the grouping-separator^XP31 character.

  Note:

  There is no need to extrapolate grouping positions on the fractional side, because the number of digits in the output will never exceed the number of ·optional digit character· and ·decimal digit family· characters in the fractional part of the sub-picture.

• The minimum-fractional-part-size is set to the number of ·decimal digit family· characters found in the fractional part of the sub-picture.

• The maximum-fractional-part-size is set to the total number of ·optional digit character· and ·decimal digit family· characters found in the fractional part of the sub-picture.

• If the effect of the above rules is that minimum-integer-part-size and maximum-fractional-part-size are both zero, then an adjustment is applied as follows:

  • If an exponent separator is present then:

    • minimum-fractional-part-size is changed to 1 (one).

    • maximum-fractional-part-size is changed to 1 (one).

    Note:

    This has the effect that with the picture #.e9, the value 0.123 is formatted as 0.1e0

  • Otherwise:

    • minimum-integer-part-size is changed to 1 (one).

    Note:

    This has the effect that with the picture #, the value 0.23 is formatted as 0

• If all the following conditions are true:

  • An exponent separator is present

  • The minimum-integer-part-size is zero

  • There is at least one ·optional digit character· in the integer part of the sub-picture

  then the minimum-integer-part-size is changed to 1 (one).

  Note:

  This has the effect that with the picture .9e9, the value 0.1 is formatted as .1e0, while with the picture #.9e9, it is formatted as 0.1e0

• If (after making the above adjustments) the minimum-integer-part-size and the minimum-fractional-part-size are both zero, then the minimum-fractional-part-size is set to 1 (one).

• The minimum-exponent-size is set to the number of ·decimal digit family· characters found in the exponent part of the sub-picture if present, or zero otherwise.

  Note:

  The rules for the syntax of the picture string ensure that if an exponent separator is present, then the minimum-exponent-size will always be greater than zero.

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

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 analyzing the decimal format in the static context and the ·picture string·, as described above. The result of this phase is a string, which forms the return value of the fn:format-number function.

The algorithm for this second stage of processing is as follows:

1. If the input number is NaN (not a number), the result is the value of the pattern separator^XP31 property (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 if it is negative. For xs:double and xs:float, negative zero is taken as negative, positive zero as positive. For xs:decimal and xs:integer, the positive sub-picture is used for zero.

3. The adjusted number is determined as follows:

   • If the sub-picture contains a percent^XP31 character, the adjusted number is the input number multiplied by 100.

   • If the sub-picture contains a per-mille^XP31 character, the adjusted number is the input number multiplied by 1000.

   • Otherwise, the adjusted number is the input number.

   If the multiplication causes numeric overflow, no error occurs, and the adjusted number is positive or negative infinity as appropriate.

4. If the adjusted number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the value of the infinity^XP31 property, and the appropriate suffix.

5. If the minimum exponent size is non-zero, and the adjusted number is non-zero, then the adjusted number is scaled to establish a mantissa and an integer exponent. The mantissa and exponent are chosen such that all the following conditions are true:

   • The primitive type of the mantissa is the same as the primitive type of the adjusted number (integer, decimal, float, or double).

   • The mantissa multiplied by ten to the power of the exponent is equal to the adjusted number.

   • The mantissa is less than 10^N, and at least 10^N-1, where N is the scaling factor.

   If the minimum exponent size is zero, then the mantissa is the adjusted number and there is no exponent.

   If the minimum exponent size is non-zero and the adjusted number is zero, then the mantissa is the adjusted number and the exponent is zero.

6. The mantissa is converted (if necessary) to an xs:decimal value, using an implementation of xs:decimal that imposes no limits on the totalDigits or fractionDigits facets. If there are several such values that are numerically equal to the mantissa (bearing in mind that if the mantissa is an xs:double or xs:float, the comparison will be done by converting the decimal value back to an xs:double or xs:float), the one that is chosen should be one with the smallest possible number of digits not counting leading or trailing zeroes (whether significant or insignificant). For example, 1.0 is preferred to 0.9999999999, and 100000000 is preferred to 100000001. This value is then rounded so that it uses no more than maximum-fractional-part-size digits in its fractional part. The rounded number is defined to be the result of converting the mantissa to an xs:decimal value, as described above, and then calling the function fn:round-half-to-even with this converted number as the first argument and the maximum-fractional-part-size as the second argument, again with no limits on the totalDigits or fractionDigits in the result.

7. The absolute value of the rounded number is converted to a string in decimal notation, using the digits in the ·decimal digit family· to represent the ten decimal digits, and the decimal-separator^XP31 character to separate the integer part and the fractional part. This string must always contain a decimal-separator^XP31, and it must contain no leading zeroes and no trailing zeroes. The value zero will at this stage be represented by a decimal-separator^XP31 on its own.

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

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

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

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

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

13. If an exponent exists, then the string produced from the mantissa as described above is extended with the following, in order: (a) the exponent-separator^XP31 character; (b) if the exponent is negative, the minus-sign^XP31 character; (c) the value of the exponent represented as a decimal integer, extended if necessary with leading zeroes to make it up to the minimum exponent size, using digits taken from the ·decimal digit family·.

14. 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 where x is the argument value.

Signature

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

Properties

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

Rules

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

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

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

The expression math:exp(2) returns 7.38905609893065e0.

The expression math:exp(-1) returns 0.36787944117144233e0.

The expression math:exp(math:pi()) returns 23.140692632779267e0.

The expression math:exp(xs:double('NaN')) returns xs:double('NaN').

The expression math:exp(xs:double('INF')) returns xs:double('INF').

The expression math:exp(xs:double('-INF')) returns 0.0e0.

4.8.3 math:exp10

Summary

Returns the value of 10^x, where x is the supplied argument value.

Signature

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

Properties

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

Rules

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

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

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($value as xs:double?) as xs:double?

Properties

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

Rules

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

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

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 zero, the result is -INF, and if it is negative, 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($value as xs:double?) as xs:double?

Properties

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

Rules

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

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

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 zero, the result is -INF, and if it is negative, 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 xs: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 $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($value as xs:double?) as xs:double?

Properties

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

Rules

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

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

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

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. The argument is an angle in radians.

Signature

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

Properties

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

Rules

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

Otherwise the result is the sine of $radians (which is treated as an angle in radians) as defined in the [IEEE 754-2008] specification of the sin function applied to 64-bit binary floating point values.

Notes

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

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

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

Otherwise the result is always in the range -1.0e0 to +1.0e0

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

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

The expression math:sin(math:pi()) returns 0.0e0 (approximately).

The expression math:sin(xs:double('NaN')) returns xs:double('NaN').

The expression math:sin(xs:double('INF')) returns xs:double('NaN').

The expression math:sin(xs:double('-INF')) returns xs:double('NaN').

4.8.9 math:cos

Summary

Returns the cosine of the argument. The argument is an angle in radians.

Signature

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

Properties

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

Rules

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

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

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

Notes

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

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

If $radiansis 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 (approximately).

The expression math:cos(xs:double('NaN')) returns xs:double('NaN').

The expression math:cos(xs:double('INF')) returns xs:double('NaN').

The expression math:cos(xs:double('-INF')) returns xs:double('NaN').

4.8.10 math:tan

Summary

Returns the tangent of the argument. The argument is an angle in radians.

Signature

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

Properties

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

Rules

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

Otherwise the result is the tangent of $radians (which is treated as an angle in radians) as defined in the [IEEE 754-2008] specification of the tan function applied to 64-bit binary floating point values.

Notes

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

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

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 1 div math:tan(math:pi() div 2) returns 0.0e0 (approximately). (Mathematically, tan(π/2) is positive infinity. But because math:pi() div 2 returns an approximation, the result of math:tan(math:pi() div 2) will be a large but finite number.)

The expression 1 div math:tan(-math:pi() div 2) returns -0.0e0 (approximately). (Mathematically, tan(-π/2) is negative infinity. But because -math:pi() div 2 returns an approximation, the result of math:tan(-math:pi() div 2) will be a large but finite negative number.)

The expression math:tan(math:pi()) returns 0.0e0 (approximately).

The expression math:tan(xs:double('NaN')) returns xs:double('NaN').

The expression math:tan(xs:double('INF')) returns xs:double('NaN').

The expression math:tan(xs:double('-INF')) returns xs:double('NaN').

4.8.11 math:asin

Summary

Returns the arc sine of the argument.

Signature

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

Properties

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

Rules

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

Otherwise the result is the arc sine of $value as defined in the [IEEE 754-2008] specification of the asin function applied to 64-bit binary floating point values. The result is in the range -π/2 to +π/2 radians.

Notes

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

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

If $value is NaN, or if its absolute value is greater than one, then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range -π/2 <= θ <= +π/2.

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.

Signature

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

Properties

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

Rules

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

Otherwise the result is the arc cosine of $value, as defined in the [IEEE 754-2008] specification of the acos function applied to 64-bit binary floating point values. The result is in the range zero to +π radians.

Notes

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

If $value is NaN, or if its absolute value is greater than one, then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range 0 <= θ <= +π.

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.

Signature

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

Properties

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

Rules

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

Otherwise the result is the arc tangent of $value, as defined in the [IEEE 754-2008] specification of the atan function applied to 64-bit binary floating point values. The result is in the range -π/2 to +π/2 radians.

Notes

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

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

If $value is NaN then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range -π/2 <= θ <= +π/2.

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.

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. The result is in the range -π to +π radians.

Notes

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

If either argument 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 3.141592653589793e0.

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

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

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

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

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

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

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

4.9.1 fn:random-number-generator

Summary

Returns a random number generator, which can be used to generate sequences of random numbers.

Signatures

fn:random-number-generator() as item-type(rng)

fn:random-number-generator($seed as xs:anyAtomicType?) as item-type(rng)

Properties

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

Rules

The function returns a random number generator. A random number generator is represented as a value of type rng, defined as follows:

record(
       number   as xs:double,
       next     as (function() as record(number, next, permute, *)),
       permute  as (function(item()*) as item()*),
       *
   )

That is, the result of the function is a map containing three entries. The keys of each entry are strings:

1. The entry with key "number" holds a random number; it is an xs:double greater than or equal to zero (0.0e0), and less than one (1.0e0).

2. The entry with key "next" is a zero-arity function that can be called to return another random number generator.

   The properties of this function are as follows:

   • name: absent

   • parameter names: ()

   • signature: () => map(xs:string, item())

   • non-local variable bindings: none

   • implementation: implementation-dependent

3. The entry with key "permute" is a function with arity 1 (one), which takes an arbitrary sequence as its argument, and returns a random permutation of that sequence.

   The properties of this function are as follows:

   • name: absent

   • parameter names: ("arg")

   • signature: (item()*) => item()*

   • non-local variable bindings: none

   • implementation: implementation-dependent

Calling the fn:random-number-generator function with no arguments is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

Calling the fn:random-number-generator function with an empty sequence as $seed is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

If a $seed is supplied, it may be an atomic value of any type.

Both forms of the function are ·deterministic·: calling the function twice with the same arguments, within a single ·execution scope·, produces the same results.

The value of the number entry should be such that all eligible xs:double values are equally likely to be chosen.

The function returned in the permute entry should be such that all permutations of the supplied sequence are equally likely to be chosen.

The map returned by the fn:random-number-generator function may contain additional entries beyond those specified here, but it must match the type item-type(rng) defined above. The meaning of any additional entries is ·implementation-defined·. To avoid conflict with any future version of this specification, the keys of any such entries should start with an underscore character.

Notes

It is not meaningful to ask whether the functions returned in the next and permute functions resulting from two separate calls with the same seed are "the same function", but the functions must be equivalent in the sense that calling them produces the same sequence of random numbers.

The repeatability of the results of function calls in different execution scopes is outside the scope of this specification. It is recommended that when the same seed is provided explicitly, the same random number sequence should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by using fn:current-dateTime() as a seed.)

The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.

Examples

The following example returns a random permutation of the integers in the range 1 to 100: fn:random-number-generator()?permute(1 to 100)

The following example returns a 10% sample of the items in an input sequence $seq, chosen at random: fn:random-number-generator()?permute($seq)[position() = 1 to (count($seq) idiv 10)]

The following code defines a function that can be called to produce a random sequence of xs:double values in the range zero to one, of specified length:

declare %public function r:random-sequence($length as xs:integer) as xs:double* {
  r:random-sequence($length, fn:random-number-generator())
};

declare %private function r:random-sequence($length as xs:integer, 
                                            $G as record(number as xs:double, next as function(*), *)) {
  if ($length eq 0)
  then ()
  else ($G?number, r:random-sequence($length - 1, $G?next()))
};

r:random-sequence(200);
            

5.2.1 fn:codepoints-to-string

Summary

Returns an xs:string whose characters have supplied ·codepoints·.

Signature

fn:codepoints-to-string($values 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 $values. This will be the zero-length string if $values is the empty sequence.

Error Conditions

A dynamic error is raised [err:FOCH0001] if any of the codepoints in $values 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($value 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 ·codepoint· of the corresponding ·character· in $value.

If $value 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· 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 (see [UTS #10]) 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.

Collations may or may not perform Unicode normalization on strings before comparing them.

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 reference, it is resolved relative to the value of the static base URI property from the static 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 [UTS #35].

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 ^XP31. 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:tail($A) and fn:tail($B)

5.3.3 The Unicode Collation Algorithm

This specification defines a family of collation URIs representing tailorings of the Unicode Collation Algorithm (UCA) as defined in [UTS #10]. The parameters used for tailoring the UCA are based on the parameters defined in the Locale Data Markup Language (LDML), defined in [UTS #35].

This family of URIs use the scheme and path http://www.w3.org/2013/collation/UCA followed by an optional query part. The query part, if present, consists of a question mark followed by a sequence of zero or more semicolon-separated parameters. Each parameter is a keyword-value pair, the keyword and value being separated by an equals sign.

All implementations must recognize URIs in this family in the collation argument of functions that take a collation argument.

If the fallback parameter is present with the value no, then the implementation must either use a collation that conforms with the rules in the Unicode specifications for the requested tailoring, or fail with a static or dynamic error indicating that it does not provide the collation (the error code should be the same as if the collation URI were not recognized). If the fallback parameter is omitted or takes the value yes, and if the collation URI is well-formed according to the rules in this section, then the implementation must accept the collation URI, and should use the available collation that most closely reflects the user's intentions. For example, if the collation URI requested is http://www.w3.org/2013/collation/UCA?lang=se;fallback=yes and the implementation does not include a fully conformant version of the UCA tailored for Swedish, then it may choose to use a Swedish collation that is known to differ from the UCA definition, or one whose conformance has not been established. It might even, as a last resort, fall back to using codepoint collation.

If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not defined in this specification then the meaning is ·implementation-defined·. If the implementation recognizes the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize the keyword or value then if the fallback parameter is present with the value no it should reject the collation as unsupported, otherwise it should ignore the unrecognized parameter.

The following query parameters are defined. If any parameter is absent, the default is ·implementation-defined· except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in [UTS #35].

5.3.4 The HTML ASCII Case-Insensitive Collation

The collation URI http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive must be recognized by every implementation. It is used to refer to the HTML ASCII case-insensitive collation as defined in [HTML5: A vocabulary and associated APIs for HTML and XHTML] (section 2.5, Case sensitivity and string comparison). It is used, for example, when matching HTML class attribute values.

HTML5 defines the semantics of equality matching using this collation; it does not define rules for ordering. If the collation is used for ordering, the results are ·implementation-defined·. The collation supports collation units and can therefore be used with functions such as fn:contains; each Unicode codepoint is a single collation unit.

5.3.5 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, a dynamic 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, a dynamic error is raised [err:FOCH0002].

If the value of the collation argument is a relative URI reference, it is resolved against the base-URI from the static context. If it is a relative URI reference and cannot be resolved, perhaps because the base-URI property in the static context is absent, a dynamic error is raised [err:FOCH0002].

5.3.6 fn:compare

Summary

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

Signatures

fn:compare($value1 as xs:string?, $value2 as xs:string?) as xs:integer?

fn:compare(	$value1	as xs:string?,
	$value2	as xs:string?,
	$collation	as xs:string) as xs:integer?

Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.

Rules

Returns -1, 0, or 1, depending on whether $value1 is respectively less than, equal to, or greater than $value2, 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.5 Choosing a collation.

If either $value1 or $value2 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://www.w3.org/2013/collation/UCA?lang=de;strength=primary') returns 0. (The specified collation equates "ss" and the (German) character "ß" ("sharp-s").)

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.7 fn:codepoint-equal

Summary

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

Signature

fn:codepoint-equal($value1 as xs:string?, $value2 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 $value1 is equal to $value2, 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.3.8 fn:collation-key

Summary

Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.

Signatures

fn:collation-key($value as xs:string) as xs:base64Binary

fn:collation-key(	$value	as xs:string,
	$collation	as xs:string) as xs:base64Binary

Properties

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

Rules

Calling the one-argument version of this function is equivalent to calling the two-argument version supplying the default collation as the second argument.

The function returns an ·implementation-dependent· value with the property that, for any two strings $K1 and $K2:

• collation-key($K1, $C) eq collation-key($K2, $C) if and only if compare($K1, $K2, $C) eq 0

• collation-key($K1, $C) lt collation-key($K2, $C) if and only if compare($K1, $K2, $C) lt 0

The collation used by this function is determined according to the rules in 5.3.5 Choosing a collation. Collation keys are defined as xs:base64Binary values to ensure unambiguous and context-free comparison semantics.

An implementation is free to generate a collation key in any convenient way provided that it always generates the same collation key for two strings that are equal under the collation, and different collation keys for strings that are not equal. This holds only within a single ·execution scope·; an implementation is under no obligation to generate the same collation keys during a subsequent unrelated query or transformation.

It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an ·implementation-defined· property of the collation.

Error Conditions

An error is raised [err:FOCH0004] if the specified collation does not support the generation of collation keys.

Notes

The function is provided primarily for use with maps. If a map is required where codepoint equality is inappropriate for comparing keys, then a common technique is to normalize the key so that equality matching becomes feasible. There are many ways keys can be normalized, for example by use of functions such as fn:upper-case, fn:lower-case, fn:normalize-space, or fn:normalize-unicode, but this function provides a way of normalizing them according to the rules of a specified collation. For example, if the collation ignores accents, then the function will generate the same collation key for two input strings that differ only in their use of accents.

The result of the function is defined to be an xs:base64Binary value. Binary values are chosen because they have unambiguous and context-free comparison semantics, because the value space is unbounded, and because the ordering rules are such that between any two values in the ordered value space, an arbitrary number of further values can be interpolated. The choice between xs:base64Binary and xs:hexBinary is arbitrary; the only operation that behaves differently between the two binary data types is conversion to/from a string, and this operation is not one that is normally required for effective use of collation keys.

For collations based on the Unicode Collation Algorithm, an algorithm for computing collation keys is provided in [UTS #10]. Implementations are not required to use this algorithm.

The fact that collation keys are ordered can be exploited in XQuery, whose order by clause does not allow the collation to be selected dynamically. This restriction can be circumvented by rewriting the clause order by $e/@key collation "URI" as order by fn:collation-key($e/@key, $collation), where $collation allows the collation to be chosen dynamically.

Note that xs:base64Binary becomes an ordered type in XPath 3.1, making binary collation keys possible.

Examples

let $C := 'http://www.w3.org/2013/collation/UCA?strength=primary'

The expression map:merge((map{collation-key("A", $C):1}, map{collation-key("a", $C):2}), map{"duplicates":"use-last"})(collation-key("A", $C)) returns 2. (Given that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence.)

The expression let $M := map{collation-key("A", $C):1, collation-key("B", $C):2} return $M(collation-key("a", $C)) returns 1. (The strings "A" and "a" have the same collation key under this collation.)

As the above examples illustrate, it is important that when the collation-key function is used to add entries to a map, then it must also be used when retrieving entries from the map. This process can be made less error-prone by encapsulating the map within a function: function($k) {$M(collation-key($k, $collation)}.

5.3.9 fn:contains-token

Summary

Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.

Signatures

fn:contains-token($value as xs:string*, $token as xs:string) as xs:boolean

fn:contains-token(	$value	as xs:string*,
	$token	as xs:string,
	$collation	as xs:string) as xs:boolean

Properties

The two-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations.

The three-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on collations, and static base URI.

Rules

If $value is the empty sequence, the function returns false.

Leading and trailing whitespace is trimmed from $token. If the trimmed value of $token is a zero-length string, the function returns false.

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

The function returns true if and only if there is string in $value which, after tokenizing at whitespace boundaries, contains a token that is equal to the trimmed value of $token under the rules of the selected collation.

That is, the function returns the value of the expression:

some $t in $input!fn:tokenize(.) satisfies 
                 compare($t, fn:replace($token, '^\s*|\s*$', ''), $collation) eq 0)

Notes

Interior whitespace within $token will cause the function to return false, unless such whitespace is ignored by the selected collation.

This function can be used for processing space-separated attribute values (for example, the XHTML and DITA class attribute), where one often needs to test for the presence of a single token in a space-separated list. The function is designed to work both when the attribute has been validated against an XSD list type, and when it appears as a single untyped string. It differs from the HTML 5 definition in that HTML 5 recognizes form feed (x0C) as a separator. To reproduce the HTML token matching behavior, the HTML ASCII case-insensitive collation should be used: see 5.3.4 The HTML ASCII Case-Insensitive Collation.

Examples

The expression fn:contains-token("red green blue ", "red") returns true().

The expression fn:contains-token(("red", "green", "blue"), " red ") returns true().

The expression fn:contains-token("red, green, blue", "red") returns false().

The expression fn:contains-token("red green blue", "RED", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive") returns true().

5.4.1 fn:characters

Summary

Splits the supplied string into a sequence of single-character strings.

Signature

fn:characters($value as xs:string?) as xs:string*

Properties

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

Rules

The function returns a sequence of strings, each string having length 1, containing the corresponding ·character· in $value.

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

Examples

The expression fn:characters("Thérèse") returns ("T", "h", "é", "r", "è", "s", "e").

The expression fn:characters("") returns ().

The expression fn:characters(()) returns ().

The expression fn:characters("Banana") => fn:index-of("a") returns (2, 4, 6).

The expression fn:characters("stretch") => fn:string-join("-") returns "s-t-r-e-t-c-h".

The expression "Banana" => fn:characters() => fn:reverse() => fn:string-join() returns "ananaB".

5.4.2 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(	$value1	as xs:anyAtomicType?,
	$value2	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".