XPath and XQuery Functions and Operators 4.0

1.5.1 Function name

The function name is a QName as defined in [XML Schema Part 2: Datatypes Second Edition] and must adhere to its syntactic conventions. Following the precedent set by [XML Path Language (XPath) Version 1.0], function names are generally composed of English words separated by hyphens: specifically U+002D (HYPHEN-MINUS, -) . Abbreviations are used only where there is a strong precedent in other programming languages (as with math:sin and math:cos for sine and cosine). If a function name contains a [XML Schema Part 2: Datatypes Second Edition] datatype name, it may have intercapitalized spelling and is used in the function name as such. An example is fn:timezone-from-dateTime.

1.5.2 Function summary

The first section in the proforma is a short summary of what the function does. This is intended to be informative rather than normative.

1.5.3 Function signature

Each function is then defined by specifying its signature(s), which define the types of the parameters and of the result value.

Each function signature is presented in a form like this:

In this notation, function-name, in bold-face, is the local name of the function whose signature is being specified. The prefix fn indicates that the function is in the namespace http://www.w3.org/2005/xpath-functions: this is one of the conventional prefixes listed in 1.3 Namespaces and prefixes. If the function takes no parameters, then the name is followed by an empty parameter list: (); otherwise, the name is followed by a parenthesized list of parameter declarations. Each parameter declaration includes:

If there are two or more parameter declarations, they are separated by a comma.

The return-type, also in italics, specifies the static type of the value returned by the function. The dynamic type of the value returned by the function is the same as its static type or derived from the static type. All parameter types and return types are specified using the SequenceType notation defined in Section 2.5.4 SequenceType Syntax ^XP31.

1.5.4 Function rules

The next section in the proforma defines the semantics of the function as a set of rules. The order in which the rules appear is significant; they are to be applied in the order in which they are written. Error conditions, however, are generally listed in a separate section that follows the main rules, and take precedence over non-error rules except where otherwise stated. The principles outlined in Section 2.3.4 Errors and Optimization ^XP31 apply by default: to paraphrase, if the result of the function can be determined without evaluating all its arguments, then it is not necessary to evaluate the remaining arguments merely in order to determine whether any error conditions apply.

1.5.5 Formal Equivalents

Some functions supplement the prose rules with a more formal specification that describes the effect of the function in terms of an equivalent XPath or XQuery implementation. This is intended to take precedence over the prose rules in the event of any conflict; however, both sections are intended to be complete and not to rely on each other.

In writing the formal equivalents, a number of guidelines have been followed:

1. Where the equivalent code calls other functions, these should either be primitives defined in the data model specification (see [XQuery and XPath Data Model (XDM) 3.1]), or functions that themselves have a formal equivalent; and the dependencies should not be circular.

2. There should be minimal reliance on XPath or XQuery language features. Although no attempt has been made to precisely define a core set of language constructs, the specifications try to avoid relying on features other than function calls and a few basic operators including the comma operator, equality testing, and simple integer arithmetic.

3. There is no suggestion that the formal equivalent is a practical implementation; in many cases it might have very poor performance.

4. In some cases the formal equivalent does not attempt to replicate correct behavior in error cases; if so, this is always clearly stated.

5. The formal equivalent will always produce a conformant result for the function, but in some cases this will not be the only possible conformant result.

Editorial note
This worthy intent is not yet fully achieved; for example there are formal specifications that invoke fn:atomic-equal.

There is no attempt to write formal equivalents for functions that have complex logic (such as fn:format-number) or dependencies (such as fn:doc); the aim of the formal equivalents is to define as rigorously as possible a platform of basic functionality that can be used as a solid foundation for more complex features.

1.5.6 Notes

Where the proforma includes a section headed Notes, these are non-normative.

1.5.7 Examples

Where the proforma includes a section headed Examples, these are non-normative.

Many of the examples are given in structured form, showing example expressions and their expected results. These published examples are derived from executable test cases, so they follow a standard format. In general, the actual result of the expression is expected to be deep-equal to the presented result, under the rules of the fn:deep-equal function with default options. In some cases the result is qualified to indicate that the order of items in the result is implementation-dependent, or that numeric results are approximate.

For more complex functions, examples may be given using informal narrative prose.

1.8.1 Item Types

The first diagram illustrates 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 items, 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 the union type (A | B) and also for (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.

1.8.2 Schema Type Hierarchy

The next diagram illustrate the schema type subsystem, in which all types are derived from 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.

1.8.3 Atomic Type Hierarchy

The final diagram shows 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.

1.9.1 Atomic items

The following definitions are adopted from [XQuery and XPath Data Model (XDM) 4.0].

• [Definition] An atomic item is a pair (T, D) where T (the ·type annotation·) is an atomic type, and D (the ·datum·) is a point in the value space of T.

• [Definition] A primitive type is one of the 19 primitive atomic types defined in Section 3.2 Primitive datatypes^XS2 of [XML Schema Part 2: Datatypes Second Edition], or the type xs:untypedAtomic defined in [XQuery and XPath Data Model (XDM) 4.0].

• [Definition] The datum of an ·atomic item· is a point in the value space of its type, which is also a point in the value space of the primitive type from which that type is derived. There are 20 primitive atomic types (19 defined in XSD, plus xs:untypedAtomic), and these have non-overlapping value spaces, so each datum belongs to exactly one primitive atomic type.

• [Definition] The type annotation of an atomic item is the most specific atomic type that it is an instance of (it is also an instance of every type from which that type is derived).

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

This specification adopts the Unicode notation U+xxxx to refer to a codepoint by its hexadecimal value (always four to six hexadecimal digits). This is followed where appropriate by the official Unicode character name and its graphical representation: for example U+20AC (EURO SIGN, €) .

1.9.3 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) 4.0]): 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.9.4 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.9.5 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 $V1 and $V2 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 items, 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 E₁ in the first map there is an entry E₂ in the second map such that the keys of E₁ and E₂ are ·the same key·, and the corresponding values V₁ and V₂ 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 the two function items have the same function identity. The concept of function identity is explained in Section 2.9.4 Function Items^DM.

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

[Definition] A function definition^XP 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 of the caller as well as on the actual supplied arguments (if any). A function definition may be context-dependent for some arities in its arity range, and context-independent for others: for example fn:name#0 is context-dependent while fn:name#1 is context-independent.

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

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

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

A function definition that is context-dependent can be used as the target of 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. These constructs all deliver a function item^DM having a captured context based on the static and dynamic context of the construct that created the function item. This captured context forms part of the closure of the function item.

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 form the captured context of the function item that fn:function-lookup returns.

[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, fn:parse-html, 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 nondeterministic 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 nondeterministic 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.

[Definition] The function fn:concat is defined to be variadic: it accepts any number of arguments. No other function has this property.

2.1.1 fn:node-name

Summary

Returns the name of a node, as an xs:QName.

Signature

fn:node-name(
$node	as node()?	:= .
) as xs:QName?

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If $node is the empty sequence, the empty sequence is returned.

Otherwise, the function returns the result of the dm:node-name accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.10 node-name Accessor^DM).

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP.

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

For element and attribute nodes, the name of the node is returned as an xs:QName, retaining the prefix, namespace URI, and local part.

For processing instructions, the name of the node is returned as an xs:QName in which the prefix and namespace URI are absent^DM.

For a namespace node, the function returns an empty sequence if the node represents the default namespace; otherwise it returns an xs:QName in which prefix and namespace URI are absent^DM and the local part is the namespace prefix being bound.

For all other kinds of node, the function returns the empty sequence.

Examples

Variables
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc>

Expression	Result
node-name($e//*[@id = 'alpha'])	QName("", "p")
node-name($e//*[@id = 'gamma'])	QName("http://example.com/ns", "p")
node-name($e//*[@id = 'delta'])	QName("http://example.com/ns", "ex:p")
node-name($e//processing-instruction())	QName("", "pi")
node-name($e//*[@id = 'alpha']/text())	()
node-name($e//*[@id = 'alpha']/@id)	QName("", "id")
node-name($e//*[@id = 'alpha']/@xml:id)	xs:QName("xml:id")

2.1.2 fn:nilled

Summary

Returns true for an element that is nilled.

Signature

fn:nilled(
$node	as node()?	:= .
) as xs:boolean?

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

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

Otherwise the function returns the result of the dm:nilled accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.8 nilled Accessor^DM).

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

If $node is not an element node, the function returns the empty sequence.

If $node is an untyped element node, the function returns false.

In practice, the function returns true only for an element node that has the attribute xsi:nil="true" and that is successfully validated against a schema that defines the element to be nillable; the detailed rules, however, are defined in [XQuery and XPath Data Model (XDM) 3.1].

2.1.3 fn:string

Summary

Returns the value of $value represented as an xs:string.

Signature

fn:string(
$value	as item()?	:= .
) as xs:string

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

In the zero-argument version of the function, $value defaults to the context value. That is, calling fn:string() is equivalent to calling fn:string(.).

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

If $value is a node, the function returns the string value of the node, as obtained using the dm:string-value accessor defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 4.12 string-value Accessor^DM).

If $value is an atomic item, the function returns the result of the expression $value cast as xs:string (see 21 Casting).

In all other cases, a dynamic error occurs (see below).

Error Conditions

The following errors may be raised when $value is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP.

• If the context value is not a single item, type error [err:XPTY0004]^XP.

A type error is raised [err:FOTY0014] if $value is a function item (this includes maps and arrays).

Notes

Every node has a string value, even an element with element-only content (which has no typed value). Moreover, casting an atomic item to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.

Examples

Variables
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para>

Expression	Result
string(23)	"23"
string(false())	"false"
string("Paris")	"Paris"
string((1, 2, 3))	Raises error XPTY0004.
string([ [ 1, 2 ], [ 3, 4 ] ])	Raises error FOTY0014.
string(abs#1)	Raises error FOTY0014.
string($para)	"There lived a hobbit."

2.1.4 fn:data

Summary

Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.

Signature

fn:data(
$input	as item()*	:= .
) as xs:anyAtomicType*

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

The result of fn:data is the sequence of atomic items produced by applying the following rules to each item in $input:

• If the item is an atomic item, it is appended to the result sequence.

• If the item is a node, the typed value of the node is appended to the result sequence. The typed value is a sequence of zero or more atomic items: specifically, the result of the dm:typed-value accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 4.14 typed-value Accessor^DM).

• If the item is an array, the result of applying fn:data to each member of the array, in order, is appended to the result sequence.

Error Conditions

A type error is raised [err:FOTY0012] if an item in the sequence $input is a node that does not have a typed value.

A type error is raised [err:FOTY0013] if an item in the sequence $input is a function item other than an array.

A type error is raised [err:XPDY0002]^XP if $input is omitted and the context value is absent^DM.

Notes

The process of applying the fn:data function to a sequence is referred to as atomization. In many cases an explicit call on fn:data is not required, because atomization is invoked implicitly when a node or sequence of nodes is supplied in a context where an atomic item or sequence of atomic items is required.

The result of atomizing an empty sequence is an empty sequence.

The result of atomizing an empty array is an empty sequence.

Examples

Variables
let $para := <para>There lived a <term author="Tolkien">hobbit</term>.</para>

Expression	Result
data(123)	123
data((123, 456))	123, 456
data([ [ 1, 2 ], [ 3, 4 ] ])	1, 2, 3, 4
data($para)	xs:untypedAtomic("There lived a hobbit.")
data($para/term/@author)	xs:untypedAtomic("Tolkien")
data(abs#1)	Raises error FOTY0013.

2.1.5 fn:base-uri

Summary

Returns the base URI of a node.

Signature

fn:base-uri(
$node	as node()?	:= .
) as xs:anyURI?

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

The zero-argument version of the function returns the base URI of the context node: it is equivalent to calling fn:base-uri(.).

The single-argument version of the function behaves as follows:

1. If $node is the empty sequence, the function returns the empty sequence.

2. Otherwise, the function returns the value of the dm:base-uri accessor applied to the node $node. This accessor is defined, for each kind of node, in the XDM specification (See Section 4.2 base-uri Accessor^DM).

Note:

As explained in XDM, document, element and processing-instruction nodes have a base-uri property which may be empty. The base-uri property for all other node kinds is the empty sequence. The dm:base-uri accessor returns the base-uri property of a node if it exists and is non-empty; otherwise it returns the result of applying the dm:base-uri accessor to its parent, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a parentless node whose base-uri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always an empty sequence — it does not depend on the base URI of the parent element.

See also fn:static-base-uri.

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

2.1.6 fn:document-uri

Summary

Returns the URI of a resource where a document can be found, if available.

Signature

fn:document-uri(
$node	as node()?	:= .
) as xs:anyURI?

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

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

If $node is not a document node, the function returns the empty sequence.

Otherwise, the function returns the value of the document-uri accessor applied to $node, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 5.1.2 Accessors^DM).

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

In the 3.1 version of this specification, it was mandated that two distinct documents could not have the same document-uri property: more specifically, it was guaranteed that for any document node $D, either document-uri($D) would be absent, or doc(document-uri($D)) would return $D.

For various reasons, this constraint has proved impractical. Different parts of an application may read the same external resource in different ways, for example with or without validation or whitespace stripping, leading to different document nodes derived from the same external resource having the same document-uri property. In addition, the specification explicitly allows implementations, at user request, to relax the requirements for determinism of resource access functions, which makes it possible for multiple calls of functions such as fn:doc, fn:json-doc, or fn:collection to return different results for the same supplied URI.

Although the uniqueness of the document-uri property is no longer an absolute constraint, it is still desirable that implementations should where possible respect the principle that URIs are usable as identifiers for resources.

In the case of a document node $D returned by the fn:doc function, it will generally be the case that fn:document-uri($D) returns a URI $U such that a call on fn:doc($U) in the same dynamic context will return the same document node $D. The URI $U will not necessarily be the same URI that was originally passed to the fn:doc function, since several URIs may identify the same resource.

It is recommended that implementations of fn:collection should ensure that any documents included in the returned collection, if they have a non-empty fn:document-uri property, should be such that a call on fn:doc supplying this URI returns the same document node.

2.2.1 fn:name

Summary

Returns the name of a node, as an xs:string that is either the zero-length string, or has the lexical form of an xs:QName.

Signature

fn:name(
$node	as node()?	:= .
) as xs:string

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If the argument is supplied and is the empty sequence, the function returns the zero-length string.

If the node identified by $node has no name (that is, if it is a document node, a comment, a text node, or a namespace node having no name), the function returns the zero-length string.

Otherwise, the function returns the value of the expression fn:string(fn:node-name($node)).

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

Because the result depends on the choice of namespace prefixes in the source document, it is not good practice to use the result of this function for anything other than display purposes. For example, the test name(.) = 'my:profile' will fail if the source document uses an unexpected namespace prefix. Such a test (assuming it relates to an element node) is better written as boolean(self::my:profile).

Examples

Variables
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc>

Expression	Result
name($e//*[@id = 'alpha'])	"p"
name($e//*[@id = 'gamma'])	"p"
name($e//*[@id = 'delta'])	"ex:p"
name($e//processing-instruction())	"pi"
name($e//*[@id = 'alpha']/text())	""
name($e//*[@id = 'alpha']/@id)	"id"
name($e//*[@id = 'alpha']/@xml:id)	"xml:id"

2.2.2 fn:local-name

Summary

Returns the local part of the name of $node as an xs:string that is either the zero-length string, or has the lexical form of an xs:NCName.

Signature

fn:local-name(
$node	as node()?	:= .
) as xs:string

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If the argument is supplied and is the empty sequence, the function returns the zero-length string.

If the node identified by $node has no name (that is, if it is a document node, a comment, a text node, or a namespace node having no name), the function returns the zero-length string.

Otherwise, the function returns the local part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 4.10 node-name Accessor^DM. This will be an xs:string whose lexical form is an xs:NCName.

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Examples

Variables
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc>

Expression	Result
local-name($e//*[@id = 'alpha'])	"p"
local-name($e//*[@id = 'gamma'])	"p"
local-name($e//*[@id = 'delta'])	"p"
local-name($e//processing-instruction())	"pi"
local-name($e//*[@id = 'alpha']/text())	""
local-name($e//*[@id = 'alpha']/@id)	"id"
local-name($e//*[@id = 'alpha']/@xml:id)	"id"

2.2.3 fn:namespace-uri

Summary

Returns the namespace URI part of the name of $node, as an xs:anyURI value.

Signature

fn:namespace-uri(
$node	as node()?	:= .
) as xs:anyURI

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context node (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

If the node identified by $node is neither an element nor an attribute node, or if it is an element or attribute node whose expanded-QName (as determined by the dm:node-name accessor in the Section 4.10 node-name Accessor^DM) is in no namespace, then the function returns the zero-length xs:anyURI value.

Otherwise, the result will be the namespace URI part of the expanded-QName of the node identified by $node, as determined by the dm:node-name accessor defined in Section 4.10 node-name Accessor^DM), returned as an xs:anyURI value.

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Examples

Variables
let $e := <doc> <p id="alpha" xml:id="beta">One</p> <p id="gamma" xmlns="http://example.com/ns">Two</p> <ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p> <?pi 3.14159?> </doc>

Expression	Result
namespace-uri($e//*[@id = 'alpha'])	""
namespace-uri($e//*[@id = 'gamma'])	"http://example.com/ns"
namespace-uri($e//*[@id = 'delta'])	"http://example.com/ns"
namespace-uri($e//processing-instruction())	""
namespace-uri($e//*[@id = 'alpha']/text())	""
namespace-uri($e//*[@id = 'alpha']/@id)	""
namespace-uri($e//*[@id = 'alpha']/@xml:id)	"http://www.w3.org/XML/1998/namespace"

2.2.4 fn:lang

Summary

This function tests whether the language of $node, or the context value if the second argument is omitted, as specified by xml:lang attributes is the same as, or is a sublanguage of, the language specified by $language.

Signature

fn:lang(
$language	as xs:string?,
$node	as node()	:= .
) as xs:boolean

Properties

The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

The behavior of the function if the second argument is omitted is exactly the same as if the context value (.) had been passed as the second argument.

The language of the argument $node, or the context value if the second argument is omitted, is determined by the value of the xml:lang attribute on the node, or, if the node has no such attribute, by the value of the xml:lang attribute on the nearest ancestor of the node that has an xml:lang attribute. If there is no such ancestor, then the function returns false.

If $language is the empty sequence it is interpreted as the zero-length string.

The relevant xml:lang attribute is determined by the value of the XPath expression:

(ancestor-or-self::*/@xml:lang)[last()]

If this expression returns an empty sequence, the function returns false.

Otherwise, the function returns true if and only if, based on a caseless default match as specified in section 3.13 of [The Unicode Standard], either:

1. $language is equal to the string-value of the relevant xml:lang attribute, or

2. $language is equal to some substring of the string-value of the relevant xml:lang attribute that starts at the start of the string-value and ends immediately before a hyphen, - (HYPHEN-MINUS, #x002D).

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Examples

The expression fn:lang("en") would return true if the context node were any of the following four elements:

<para xml:lang="en"/> <div xml:lang="en"><para>And now, and forever!</para></div> <para xml:lang="EN"/> <para xml:lang="en-us"/>

The expression fn:lang("fr") would return false if the context node were <para xml:lang="EN"/>

2.2.5 fn:root

Summary

Returns the root of the tree to which $node belongs. This will usually, but not necessarily, be a document node.

Signature

fn:root(
$node	as node()?	:= .
) as node()?

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the function is called without an argument, the context value (.) is used as the default argument. The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

The function returns the value of the expression ($arg/ancestor-or-self::node())[1].

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Examples

These examples use some variables which could be defined in [XQuery 4.0: An XML Query Language] as:

let $i := <tool>wrench</tool> let $o := <order>{ $i }<quantity>5</quantity></order> let $odoc := document { $o } let $newi := $o/tool

Or they could be defined in [XSL Transformations (XSLT) Version 4.0] as:

<xsl:variable name="i" as="element()"> <tool>wrench</tool> </xsl:variable> <xsl:variable name="o" as="element()"> <order> <xsl:copy-of select="$i"/> <quantity>5</quantity> </order> </xsl:variable> <xsl:variable name="odoc"> <xsl:copy-of select="$o"/> </xsl:variable> <xsl:variable name="newi" select="$o/tool"/>

root($i) returns the element node $i

root($o/quantity) returns the element node $o

root($odoc//quantity) returns the document node $odoc

root($newi) returns the element node $o

The final three examples could be made type-safe by wrapping their operands with exactly-one().

2.2.6 fn:path

Summary

Returns a path expression that can be used to select the supplied node relative to the root of its containing document.

Signature

fn:path(
$node	as node()?	:= .,
$options	as map(*)	:= {}
) as xs:string?

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

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

Rules

The behavior of the function if the $nodeargument is omitted is exactly the same as if the context value (.) had been passed as the argument.

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

The $options argument, if present, defines additional parameters controlling how the output is formatted. The ·option parameter conventions· apply. The options available are as follows:

record(
namespaces?	as map((xs:NCName | enum('')), xs:anyURI)?,
indexes?	as xs:boolean
)

Key	Meaning
namespaces?	A map from namespace prefixes to namespace URIs, such as might be returned by the function fn:in-scope-namespaces. If a prefix is available for a given URI, it is used in preference to using Q{uri}local notation. Type: map((xs:NCName | enum('')), xs:anyURI)? Default: ()
indexes?	If true, the returned path includes the index positions of nodes. If false, only the node names are included. Type: xs:boolean Default: true

If $node is a document node, the function returns the string "/".

Otherwise, the function returns a string that consists of a sequence of steps, one for each ancestor-or-self of $node other than the root node.

If the root node is not a document node then this string is preceded by a string notionally representing a call to the fn:root function, expressed as follows:

• If the namespaces option is present and defines a mapping from a non empty prefix P to the namespace URI http://www.w3.org/2005/xpath-functions, then "P:root()"

• If the namespaces option is present and defines a mapping from the empty string to the namespace URI http://www.w3.org/2005/xpath-functions, then "root()"

• Otherwise, "Q{http://www.w3.org/2005/xpath-functions}root()".

Each step consists of the character "/" followed by a string whose form depends on the kind of node selected by that step, as follows:

1. For an element node, then by default Q{uri}local[position], where uri is the namespace URI of the node name or the empty string if the node is in no namespace, local is the local part of the node name, and position is an integer representing the one-based position of the selected node among its like-named siblings.

   The suffix [position] is omitted if the indexes option is present with the value false.

   If the namespaces option is present, and if it includes a mapping from a namespace prefix to the namespace URI of the element, or to the empty string if the element is in no namespace, then:

   • If there is more than one such prefix, then one of them is chosen arbitrarily.

   • If the namespace prefix is the zero-length string, then the Q{uri} part of the step is replaced by the empty string.

   • If the prefix is an NCName P, then the Q{uri} part of the step is replaced by P:.

2. For an attribute node:

   1. If the node is in no namespace, @local, where local is the local part of the node name.

   2. Otherwise, by default @Q{uri}local, where uri is the namespace URI of the node name, and local is the local part of the node name.

      If the namespaces option is present , and if it includes a mapping from a non-empty namespace prefix to the namespace URI of the attribute, then the Q{uri} part of the step is replaced with a namespace prefix in the same way as for element nodes, described above.

3. For a text node: text()[position] where position is an integer representing the position of the selected node among its text node siblings.

   The suffix [position] is omitted if the indexes option is present with the value false.

4. For a comment node: comment()[position] where position is an integer representing the position of the selected node among its comment node siblings.

   The suffix [position] is omitted if the indexes option is present with the value false.

5. For a processing-instruction node: processing-instruction(local)[position] where local is the name of the processing instruction node and position is an integer representing the position of the selected node among its like-named processing-instruction node siblings.

   The suffix [position] is omitted if the indexes option is present with the value false.

6. For a namespace node:

   1. If the namespace node has a name: namespace::prefix, where prefix is the local part of the name of the namespace node (which represents the namespace prefix).

   2. If the namespace node has no name (that is, if it represents the default namespace): namespace::*[Ulocal-name() = ""]

      Here Ulocal-name() represents a call on the function fn:local-name and is formatted using the same conventions as the call on fn:root described earlier.

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

Using the namespaces option to shorten the generated path is often convenient, but the resulting path may be unusable if the input tree contains multiple bindings for the same prefix.

A map returned by fn:in-scope-namespaces will never contain an entry that maps any prefix to the zero-length URI. Such an entry can, however, be added manually, and can be used to control how no-namespace names are represented in the output (including the option of giving them a non-empty prefix).

Examples

Variables
let $e := document { <p xmlns="http://example.com/one" xml:lang="de" author="Friedrich von Schiller"> Freude, schöner Götterfunken,<br/> Tochter aus Elysium,<br/> Wir betreten feuertrunken,<br/> Himmlische, dein Heiligtum. </p>}
let $emp := <employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee>

Expression:	path($e)
Result:	'/'
Expression:	path($e/*:p)
Result:	'/Q{http://example.com/one}p[1]'
Expression:	path($e/*:p, {'namespaces': in-scope-namespaces($e/*)})
Result:	'/p[1]'
Expression:	path($e/*:p, {'indexes': false()})
Result:	'/Q{http://example.com/one}p'
Expression:	path($e/*:p/@xml:lang)
Result:	'/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang'
Expression:	path($e//@xml:lang, {'namespaces': in-scope-namespaces($e/*)})
Result:	'/p[1]/@xml:lang'
Expression:	path($e/*:p/@author)
Result:	'/Q{http://example.com/one}p[1]/@author'
Expression:	path($e/*:p/*:br[2])
Result:	'/Q{http://example.com/one}p[1]/Q{http://example.com/one}br[2]'
Expression:	path($e/*:p/*:br[2], {'namespaces': { 'N': 'http://example.com/one' }, 'indexes': false() })
Result:	'/N:p/N:br'
Expression:	path( $e//text()[ starts-with(normalize-space(), 'Tochter') ] )
Result:	'/Q{http://example.com/one}p[1]/text()[2]'
Expression:	path($emp)
Result:	'Q{http://www.w3.org/2005/xpath-functions}root()'
Expression:	path($emp/@xml:id)
Result:	'Q{http://www.w3.org/2005/xpath-functions}root()/@Q{http://www.w3.org/XML/1998/namespace}id'
Expression:	path($emp/empnr)
Result:	'Q{http://www.w3.org/2005/xpath-functions}root()/Q{}empnr[1]'
Expression:	path($emp/empnr, { 'namespaces': { 'fn': 'http://www.w3.org/2005/xpath-functions', '': '' } })
Result:	'fn:root()/empnr[1]'

2.2.7 fn:has-children

Summary

Returns true if the supplied node has one or more child nodes (of any kind).

Signature

fn:has-children(
$node	as node()?	:= .
) as xs:boolean

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the argument is omitted, it defaults to the context value (.). The behavior of the function if the argument is omitted is exactly the same as if the context value had been passed as the argument.

Provided that the supplied argument $node matches the expected type node()?, the result of the function call fn:has-children($node) is defined to be the same as the result of the expression fn:exists($node/child::node()).

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

If $node is an empty sequence the result is false.

The motivation for this function is to support streamed evaluation. According to the streaming rules in [XSL Transformations (XSLT) Version 4.0], the following construct is not streamable:

<xsl:if test="exists(row)">
  <ulist>
    <xsl:for-each select="row">
      <item><xsl:value-of select="."/></item>
    </xsl:for-each>
  </ulist>
</xsl:if>

This is because it makes two downward selections to read the child row elements. The use of fn:has-children in the xsl:if conditional is intended to circumvent this restriction.

Although the function was introduced to support streaming use cases, it has general utility as a convenience function.

Examples

Variables
let $e := <doc> <p id="alpha">One</p> <p/> <p>Three</p> <?pi 3.14159?> </doc>

Expression	Result
has-children($e)	true()
has-children($e//p[1])	true()
has-children($e//p[2])	false()
has-children($e//p[3])	true()
has-children($e//processing-instruction())	false()
has-children($e//p[1]/text())	false()
has-children($e//p[1]/@id)	false()

2.2.8 fn:siblings

Summary

Returns the supplied node together with its siblings, in document order.

Signature

fn:siblings(
$node	as node()?	:= .
) as node()*

Properties

The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.

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

Rules

If the $node argument is omitted, it defaults to the context value (.).

If the value of $node is an empty sequence, the function returns an empty sequence.

If $node is a child of some parent node P, the function returns all the children of P (including $node), in document order.

Otherwise (specifically, if $node is parentless, or if it is an attribute or namespace node), the function returns $node.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression.

if ($node intersect $node/parent::node()/child::node())
then $node/parent::node()/child::node()
else $node

Error Conditions

The following errors may be raised when $node is omitted:

• If the context value is absent^DM, type error [err:XPDY0002]^XP

• If the context value is not a single node, type error [err:XPTY0004]^XP.

Notes

The result of siblings($n) (except in error cases) is the same as the result of $n/(preceding-sibling::node() | following-sibling-or-self::node()). It is also the same as $n/(preceding-sibling-or-self::node() | following-sibling::node())

As with names such as parent and child, the word sibling used here as a technical term is not a precise match to its use in describing human family relationships, but is chosen for convenience.

Examples

Variables
let $e := <doc x="X"><a>A</a>text<?pi 3.14159?></doc>

Expression	Result
siblings($e//a) ! string()	"A", "text", "3.14159"
siblings($e//processing-instruction('pi')) ! string()	"A", "text", "3.14159"
siblings($e//@x) ! string()	"X"

2.3.1 fn:distinct-ordered-nodes

Summary

Removes duplicate nodes and sorts the input into document order.

Signature

fn:distinct-ordered-nodes(
$nodes	as node()*
) as node()*

Properties

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

Rules

Any duplicate nodes in the input (based on node identity) are discarded. The remaining nodes are returned in document order^XP.

Notes

Document order is ·implementation-dependent· (but stable) for nodes in different documents. If some node in document A precedes some node in document B, then every node in A precedes every node in B.

Examples

Expression:	let $x := parse-xml('<doc><a/><b/><c/><d/><c/><e/></doc>') return distinct-ordered-nodes(($x//c, $x//b, $x//a, $x//b)) ! name()
Result:	"a", "b", "c", "c" (The two $x//b expressions select the same node; one of these is eliminated as a duplicate. The $x//c expression selects two nodes that have distinct identity, so both are retained.)

2.3.2 fn:innermost

Summary

Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated.

Signature

fn:innermost(
$nodes	as node()*
) as node()*

Properties

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

Rules

The effect of the function call fn:innermost($nodes) is defined to be equivalent to the result of the expression:

$nodes except $nodes/ancestor::node()

That is, the function takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.

Examples

If the source document contains nested sections represented by div elements, the expression innermost(//div) returns those div elements that do not contain further div elements.

2.3.3 fn:outermost

Summary

Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.

Signature

fn:outermost(
$nodes	as node()*
) as node()*

Properties

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

Rules

The effect of the function call fn:outermost($nodes) is defined to be equivalent to the result of the expression:

$nodes[not(ancestor::node() intersect $nodes)]/.

That is, the function takes as input a sequence of nodes, and returns every node within the sequence that does not have another node within the sequence as an ancestor; the nodes are returned in document order with duplicates eliminated.

Notes

The formulation $nodes except $nodes/descendant::node() might appear to be simpler, but does not correctly account for attribute nodes, as these are not descendants of their parent element.

The motivation for the function was based on XSLT streaming use cases. There are cases where the [XSL Transformations (XSLT) Version 4.0] streaming rules allow the construct outermost(//section) but do not allow //section; the function can therefore be useful in cases where it is known that sections will not be nested, as well as cases where the application actually wishes to process all sections except those that are nested within another.

Examples

If the source document contains nested sections represented by div elements, the expression outermost(//div) returns those div elements that are not contained within further div elements.

3.1.1 fn:error

Summary

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

Signature

fn:error(
$code	as xs:QName?	:= (),
$description	as xs:string?	:= (),
$value	as item()*	:= .
) as item()*

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, or if the value supplied 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, or if the value supplied is an empty sequence, then the effective value of the description is ·implementation-dependent·.

• The $value 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 $value argument or if the value supplied is an empty sequence, 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.

Since the function never returns a value, the declared return type of item()* is a convenient fiction. It is relevant insofar as a function item such as error#1 may (as a consequence of function coercion) be supplied in contexts where a function with a more specific return type is required.

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

Expression:	error()
Result:	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.)
Expression:	error( QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Salary is too high' )
Result:	Raises error myerr:toohighsal. (This returns http://www.example.com/HR#toohighsal and the xs:string "Salary is too high" (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

3.2.1 fn:trace

Summary

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

Signature

fn:trace(
$input	as item()*,
$label	as xs:string?	:= ()
) as item()*

Properties

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

Rules

The function returns $input, unchanged.

In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination.

Any serialization of the implementation's trace output must not raise an error. This can be achieved (for example) by using a serialization method that can handle arbitrary input, such as the adaptive output method (see Section 10 Adaptive Output Method ^SER31).

The format of the trace output and its order are ·implementation-dependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is reported before the error occurs.

Notes

If the trace information is unrelated to a specific value, fn:message can be used instead.

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 return $v. The processor may output "124.84" and "the value of $v is:" to an ·implementation-defined· destination.

The following two XPath expressions are identical, but only the second provides trace feedback to the user:

//book[xs:decimal(@price) gt 100] //book[xs:decimal(@price) gt 100] => trace('books more expensive than €100:')

3.2.2 fn:message

Summary

Outputs trace information and discards the result.

Signature

fn:message(
$input	as item()*,
$label	as xs:string?	:= ()
) as empty-sequence()

Properties

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

Rules

Similar to fn:trace, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination.

In contrast to fn:trace, the function returns an empty sequence.

Any serialization of the implementation’s log output must not raise an error. This can e.g. be achieved by using a serialization method that can handle arbitrary input, such as the Section 10 Adaptive Output Method ^SER31.

The format of the log output and its order are ·implementation-dependent·. Therefore, the order in which the output appears is not predictable. This also means that if dynamic errors occur (whether or not they are caught using try/catch), it may be unpredictable whether any output is logged before the error occurs.

Notes

The function can be used for debugging. It can also be helpful in productive environments, e.g. to store dynamic input and evaluations to log files.

Examples

The following two XPath expressions are identical, but only the second logs any feedback:

//book[xs:decimal(@price) lt 1000] //book[if (xs:decimal(@price) lt 1000) then true() else message(@price, @title || ' is unexpectedly expensive: ')]

op:operation(xs:int, xs:double) => op:operation(xs:double, xs:double)

op:operation(fenceHeight, xs:integer) => op:operation(xs:integer, xs:integer)

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-2019]. 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:

abs($N * $arg2) le abs($arg1) and
compare($N * $arg2, 0) eq 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

Expression	Result
op:numeric-integer-divide(10, 3)	3
op:numeric-integer-divide(3, -2)	-1
op:numeric-integer-divide(-3, 2)	-1
op:numeric-integer-divide(-3, -2)	1
op:numeric-integer-divide(9.0, 3)	3
op:numeric-integer-divide(-3.5, 3)	-1
op:numeric-integer-divide(3.0, 4)	0
op:numeric-integer-divide(3.1E1, 6)	5
op:numeric-integer-divide(3.1E1, 7)	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-2019] 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

Expression	Result
op:numeric-mod(10, 3)	1
op:numeric-mod(6, -2)	0
op:numeric-mod(4.5, 1.2)	0.9
op:numeric-mod(1.23E2, 0.6E1)	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 coercion 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.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

Expression	Result
abs(10.5)	10.5
abs(-10.5)	10.5
abs(-math:log(0))	xs:double('INF')

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. If the argument is positive or negative infinity, the value of the argument is returned.

Examples

Expression	Result
ceiling(10.5)	11
ceiling(-10.5)	-10
ceiling(math:log(0))	-xs:double('INF')

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. If the argument is positive or negative infinity, the value of the argument is returned.

Examples

Expression	Result
floor(10.5)	10
floor(-10.5)	-11
math:log(0) => floor()	-xs:double('INF')

4.4.4 fn:round

Summary

Rounds a value to a specified number of decimal places, with control over how the rounding takes place.

Signature

fn:round(
$value	as xs:numeric?,
$precision	as xs:integer?	:= 0,
$mode	as enum('floor', 'ceiling', 'toward-zero', 'away-from-zero', 'half-to-floor', 'half-to-ceiling', 'half-toward-zero', 'half-away-from-zero', 'half-to-even')?	:= 'half-to-ceiling'
) 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 a value that is close to $value and that is a multiple of ten to the power of minus $precision. The default value of $precision is zero, in which case the function returns a whole number (but not necessarily an xs:integer).

The detailed way in which rounding is performed depends on the value of $mode, as follows. Here L means the highest multiple of ten to the power of minus $precision that is less than or equal to $value, U means the lowest multiple of ten to the power of minus $precision that is greater than or equal to $value, N means the multiple of ten to the power of minus $precision that is numerically closest to $value, and midway means that $value is equal to the arithmetic mean of L and U.

Rounding Modes

Rounding Mode	Meaning
'floor'	Returns L.
'ceiling'	Returns U.
'toward-zero'	Returns L if $value is positive, otherwise U.
'away-from-zero'	Returns U if $value is positive, otherwise L
'half-to-floor'	Returns N, unless midway, in which case L.
'half-to-ceiling'	Returns N, unless midway, in which case U. This is the default.
'half-toward-zero'	Returns N, unless midway, in which case it returns L if $value is positive, otherwise U.
'half-away-from-zero'	Returns N, unless midway, in which case it returns U if $value is positive, otherwise L.
'half-to-even'	Returns N, unless midway, in which case it returns whichever of L and U has a last significant digit that 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.

If the second argument is omitted or is an empty sequence, the function produces the same result as when $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.

The call round($v, 0, "floor") is equivalent to floor($v).

The call round($v, 0, "ceiling") is equivalent to ceiling($v).

The call round($v, $p, "half-to-even") is equivalent to round-half-to-even($v, $p).

Examples

Expression	Result
round(2.5)	3.0
round(2.4999)	2.0
round(-2.5)	-2.0
round(1.125, 2)	1.13
round(8452, -2)	8500
round(3.1415e0, 2)	3.14e0
math:log(0) => round()	-xs:double('INF')
round(1.7, 0, "floor")	1
round(-1.7, 0, "floor")	-2
round(1.7, 0, "ceiling")	2
round(-1.7, 0, "ceiling")	-1
round(1.7, 0, "toward-zero")	1
round(-1.7, 0, "toward-zero")	-1
round(1.7, 0, "away-from-zero")	2
round(-1.7, 0, "away-from-zero")	-2
round(1.125, 2, "half-to-floor")	1.12
round(-1.125, 2, "half-to-floor")	-1.13
round(1.125, 2, "half-to-ceiling")	1.13
round(-1.125, 2, "half-to-ceiling")	-1.12
round(1.125, 2, "half-toward-zero")	1.12
round(-1.125, 2, "half-toward-zero")	-1.12
round(1.125, 2, "half-away-from-zero")	1.13
round(-1.125, 2, "half-away-from-zero")	-1.13
round(1.125, 2, "half-to-even")	1.12
round(-1.125, 2, "half-to-even")	-1.12

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.

Signature

fn:round-half-to-even(
$value	as xs:numeric?,
$precision	as xs:integer?	:= 0
) 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.

If the second argument is omitted or an empty sequence, the function produces the same result as the two-argument version 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.

From 4.0, the effect of this function can also be achieved by calling fn:round with the third argument set to "half-to-even".

Examples

Expression	Result
round-half-to-even(0.5)	0.0
round-half-to-even(1.5)	2.0
round-half-to-even(2.5)	2.0
round-half-to-even(3.567812e+3, 2)	3567.81e0
round-half-to-even(4.7564e-3, 2)	0.0e0
round-half-to-even(35612.25, -2)	35600
math:log(0) => round-half-to-even()	-xs:double('INF')

4.5.1 fn:number

Summary

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

Signature

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 value (.). 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 21.1.3.2 Casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.

Error Conditions

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

As a consequence of the rules given above, a type error is raised [err:XPTY0004]^XP if the context value cannot be atomized, or if the result of atomizing the context value is a sequence containing more than one atomic item.

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

Variables
let $e := <e price="12.1" discount="NONE"/>

Expression	Result
number(12)	1.2e1
number('12')	1.2e1
number('INF')	xs:double('INF')
number('NaN')	xs:double('NaN')
number('non-numeric')	xs:double('NaN')
number($e/@price)	1.21e1
number($e/@discount)	xs:double('NaN')
number($e/@misspelt)	xs:double('NaN')
("10", "11", "12") ! number()	1.0e1, 1.1e1, 1.2e1

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.

Signature

fn:format-integer(
$value	as xs:integer?,
$picture	as xs:string,
$language	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 the following, in order:

1. An optional radix, which is an integer in the range 2 to 36, written using ASCII digits (0-9) without any leading zero;

2. A circumflex (^), which is present if the radix is present, and absent otherwise.

   A circumflex is recognized as marking the presence of a radix only if (a) it is immediately preceded by an integer in the range 2 to 36, and (b) it is followed (somewhere within the primary format token) by an "X" or "x". In other cases, the circumflex is treated as a grouping separator. For example, the picture 9^000 outputs the number 2345 as "2^345", whereas 9^XXX outputs "3185". This rule is to ensure backwards compatibility.

3. A primary format token. This is always present and must not be zero-length.

4. An optional format modifier.

   If the string contains one or more semicolons then the last semicolon is taken as terminating the primary format token, and everything that follows is taken as the format modifier; if the string contains no semicolon then the format modifier is taken to be absent (which is equivalent to supplying a zero-length string).

If a radix is present, then the primary format token must follow the rules for a digit-pattern.

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

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

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

   • If the radix is absent, then 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.

     If the primary format token contains at least one Unicode digit, then the primary format token 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].

   • If the radix (call it R) is present (including the case where an explicit radix of 10 is used), then the character used as the mandatory-digit-sign is either "x" or "X". If any mandatory-digit-sign is upper-case "X", then all mandatory-digit-signs must be upper-case "X". The digit family used in the output comprises the first R characters of the alphabet 0123456789abcdefghijklmnopqrstuvwxyz, but using upper-case letters in place of lower-case if an upper-case "X" is used as the mandatory-digit-sign.

     In this case the primary format token must match the regular expression ^(([Xx#]|[^\p{N}\p{L}])+?)$

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

   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 digit-pattern, nor adjacent to another grouping-separator-sign.

   The corresponding output is a number in the specified radix, 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 ...

   • 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 U+0661 (ARABIC-INDIC DIGIT ONE, ١) generates the sequence ١ then ٢ then ٣ ...

   • A format token of 16^xx generates the sequence 00 01 02 03 ... 08 09 0a 0b 0c 0d 0e 0f 10 11 ...

   • A format token of 16^X generates the sequence 0 1 2 3 ... 8 9 A B C D E F 10 11 ...

   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 the appropriate radix: for radix 10 this will be the value obtained 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. (This has no effect when the selected digit family uses ASCII digits (0-9), which will always be the case if a radix is specified.)

   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, for example, in ancient Greek U+0374 (DEXIA KERAIA, ʹ) and sometimes U+0375 (ARISTERI KERAIA, ͵) . These should not be included in the format token.

For all format tokens other than a 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 U+2460 (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 U+0410 (CYRILLIC CAPITAL LETTER A, А) . In such cases, the $language argument specifies which language 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 $language argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using 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 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 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).

4. The following notes apply when the primary format token is neither a digit-pattern nor one of the seven other defined format tokens (A, a, i, I, w, W, Ww), but is an arbitrary token representing the number 1:

   Unexpected results may occur for traditional numbering. For example, in an implementation that supports traditional numbering system in Greek, the example format-integer(19, "α;t") might return δπιιιι or ιθ, depending upon whether the ancient acrophonic or late antique alphabetic system is supported.

   Unexpected results may also occur for alphabetic numbering. For example, in an implementation that supports alphabetic numbering system in Greek, someone writing format-integer(19, "α;a") might expect the nineteenth Greek letter, U+03C4 (GREEK SMALL LETTER TAU, τ) , but the implementation might return the eighteenth one, U+03C3 (GREEK SMALL LETTER SIGMA, σ) , because the latter is the nineteenth item in the sequence of lowercase Greek letters in Unicode (the sequence is interrupted because of the final form of the sigma, U+03C2 (GREEK SMALL LETTER FINAL SIGMA, ς) ). Because Greek never had a final capital sigma, Unicode has marked U+03A2, the eighteenth codepoint in the sequence of Greek capital letters, as reserved, to ensure that every Greek uppercase letter is always 32 codepoints less than its lowercase counterpart. Therefore, someone writing format-integer(18, "Α;a") might expect the eighteenth Greek capital letter, U+03A3 (GREEK CAPITAL LETTER SIGMA, Σ) , but an implementation might return U+03A2, the eighteenth position in the sequence of Greek capital letters, but unassigned to any character.

Examples

Expression:	format-integer(123, '0000')
Result:	"0123"
format-integer(123, 'w') might return "one hundred and twenty-three"
Ordinal numbering in Italian: The specification "1;o(-º)" with $language equal to it, if supported, should produce the sequence:
1º 2º 3º 4º ...
The specification "Ww;o" with $language equal to it, if supported, should produce the sequence:
Primo Secondo Terzo Quarto Quinto ...
Expression:	format-integer(21, '1;o', 'en')
Result:	"21st"
format-integer(14, 'Ww;o(-e)', 'de') might return "Vierzehnte"
Expression:	format-integer(7, 'a')
Result:	"g"
Expression:	format-integer(27, 'a')
Result:	"aa"
Expression:	format-integer(57, 'I')
Result:	"LVII"
Expression:	format-integer(1234, '#;##0;')
Result:	"1;234"
Expression:	format-integer(1234, '16^xxxx')
Result:	"04d2"
Expression:	format-integer(1234, '16^X')
Result:	"4D2"
Expression:	format-integer(12345678, '16^xxxx_xxxx')
Result:	"00bc_614e"
Expression:	format-integer(12345678, '16^#_xxxx')
Result:	"bc_614e"
Expression:	format-integer(255, '2^xxxx xxxx')
Result:	"1111 1111"
Expression:	format-integer(1023, '32^XXXX')
Result:	"00VV"
Expression:	format-integer(1023, '10^XXXX')
Result:	"1023"
Expression:	format-integer(1023, '10^00')
Result:	"10^23"