XQuery 1.0 and XPath 2.0 Functions and Operators

1.1 Terminology

The terminology used to describe the functions and operators on [XML Schema Part 2: Datatypes] is defined in the body of this specification. The terms defined in the following list are used in building those definitions:

[Definition] for compatibility

A feature of this specification included to ensure that implementations that use this feature remain compatible with [XPath 1.0]

[Definition] may

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

[Definition] must

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

[Definition] implementation defined

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

[Definition] implementation dependent

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

1.2 Datatypes

The diagram below shows the built-in [XML Schema Part 2: Datatypes]. Solid lines connect a base datatype above to a derived datatype below. Dashed lines connect a datatype created as a list of an item type above.

Diagram courtesy Asir Vedamuthu, webMethods

1.3 Syntax

The purpose of this document is to catalog the functions and operators required for XPath 2.0, XML Query 1.0, and XSLT 2.0. The exact syntax used to invoke these functions and operators is specified in [XPath 2.0], [XQuery 1.0: An XML Query Language], and [XSLT 2.0].

In general, the above specifications do not support function overloading. Consequently, there are no overloaded functions in this document except for legacy [XPath 1.0] functions such as string() which takes a single argument of a variety of types and concat() which takes a variable number of string arguments. This does not apply to operators such as "+" which may be overloaded. Functions with optional arguments are allowed. If optional arguments are omitted, omissions are assumed to begin from the right.

1.4 Notations

This document defines, among other things, constructor functions and other functions that apply to one or more data types. Each function is defined by specifying its signature, a description of each of its arguments, and its semantics. For many functions, examples are included to illustrate their use.

Each function's signature is presented in a form like this:

In this notation, function-name is the name of the function whose signature is being specified. If the function takes no parameters, then the name is followed by an empty set of parentheses: (); otherwise, the name is followed by a parenthesized list of parameter declarations, each declaration specifying the static type of the parameter and a non-normative name used to reference the parameter when the function's semantics are specified. If there are two or more parameter declarations, they are separated by a comma. The return-type specifies the static type of the value returned by the function.

The function name is a QName as defined in [XML 1.0 Recommendation (Second Edition)] and must adhere to its syntactic conventions. Following [XPath 1.0], function names are composed of English words separated by hyphens,"-". If a function name contains a [XML Schema Part 2: Datatypes] datatype name, this may have intercapitalized spelling and is used in the function name as such. For example, xf:get-timezone-from-dateTime.

As is customary, the parameter type name indicates that the function accepts arguments of that type, or types derived from it, in that position.

Some functions accept the empty sequence as an argument and some may return the empty sequence. This is indicated in the function signature by following the parameter type name with a question mark:

[Issue 133: Syntax for indicating that function accepts empty sequence is incorrect]

1.5 Namespace Prefix

The functions and operators discussed in this document are contained in two namespaces (see [Namespaces in XML]) and referenced using a QName. The namespace prefix used in this document—merely for illustrative purposes—is xf: for the user functions and op: for the operator functions. The namespace prefix for these functions can vary, as long as the prefix is bound to the currect URI.

The actual namespaces (that is, the URIs of the namespaces) are:

• http://www.w3.org/2002/08/xquery-operators for operators

• http://www.w3.org/2002/08/xquery-functions for functions.

The functions defined with an xf: prefix are callable by the user. Functions defined with the op: prefix are described here to underpin the definitions of the operators in [XPath 2.0], [XQuery 1.0: An XML Query Language], and [XSLT 2.0]. These functions are not available directly to users, and there is no requirement that implementations should actually provide these functions. For example, multiplication is generally associated with the * operator, but it is described as a function in this document. For example:

2.1 xf:node-kind

This function returns a string value representing the node's kind: either "document", "element", "attribute", "text", "namespace", "processing-instruction", or "comment".

2.2 xf:node-name

This function returns an expanded QName for node kinds that can have names. For other node kinds, it returns the empty sequence. Expanded QName is defined in [XQuery 1.0 and XPath 2.0 Data Model], and consists of a namespace URI and a local name.

2.3 xf:string

Returns the value of $srcval represented as a string. If no argument is supplied, $srcval defaults to the context item (.).

If $srcval is the empty sequence, the zero-length string is returned.

If $srcval is a node, the function returns the string value of the node, as obtained using the string-value accessor defined in the [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval is an atomic value, then the function returns the same string as is returned by the expression cast as xs:string ($srcval), except in the cases listed below:

• Editorial note
  The "special rule" for xf:string, in which decimal values without a fractional component are converted to xs:string without a trailing decimal point, has been eliminated. This has not yet been considered by the Working Groups, but is felt to be appropriate for inclusion in this edition of this document.

• If the type of $srcval is xs:anyURI, the URI is converted to a string without any escaping of special characters.

NOTE: The reason for the special rule for xs:anyURI is that, although XML Schema strongly discourages the use of spaces within URI values, the escaping of spaces can cause problems with legacy applications (for example, this applies to spaces within fragment identifiers in many HTML browsers), and should therefore be under user control.

NOTE: The string representation of double values is not backwards-compatible with the representation of number values in [XPath 1.0]. Ordinary double values are now represented using scientific notation; the representations of positive and negative infinity are now 'INF' and '-INF' rather than 'Infinity' and '-Infinity'. (It should be observed that '+INF' is not supported as a lexical form of infinity in [XML Schema Part 2: Datatypes] and is thus not supported by this specification; if that lexical form is added in a future version of [XML Schema Part 2: Datatypes], then it will be supported by a future version of this specification that aligns with that future version of [XML Schema Part 2: Datatypes].) However, most expressions that would have produced a number in [XPath 1.0] will produce a decimal (or integer) in [XPath 2.0], so unless there is a loss of precision caused by numeric approximation, the result of the expression will in most simple cases be the same after conversion to a string.

[Issue 160: Align the string() function with 'cast as string'.]

2.4 xf:data

If $srcval is a text node, an element node, or an attribute node, xf:data returns the typed value of $srcval, as defined by the accessor function dm:typed-value defined for that kind of node in [XQuery 1.0 and XPath 2.0 Data Model].

Specifically:

If $srcval is a text node, then its typed value is equal to its string value, as an instance of xs:anySimpleType.

If $srcval is an attribute node with type annotation xs:anySimpleType, then its typed value is equal to its string value, as an instance of xs:anySimpleType. The typed value of any other attribute node is derived from its string value and type annotation in a way that is consistent with schema validation, as described in [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval is an element node with type annotation xs:anySimpleType, then its typed value is equal to its string value, as an instance of xs:anySimpleType. The typed value of an element nodes with a type annotation other than xs:anySimpleType is derived from its string value and type annotation in a way that is consistent with schema validation, as described in [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval is not a text node, an attribute node, or an element node, then xf:data causes a static type error.

2.5 xf:base-uri

For document and element nodes this function returns the value of the base-uri property. For other kinds of node it returns the empty sequence.

2.6 xf:unique-ID

This function accepts an element node and returns the identifier (ID) which may have been assigned by the user. It corresponds to the normalized value property of the attribute information item in the attributes property that has a type ID, if one exists. If no ID attribute exists the empty sequence is returned.

3.1 Examples

• xf:error()

• xf:error("Invalid argument")

• xf:error(<a>Really <emph>dumb</emph> decision!</a>)

5.1 Numeric Types

The operators described in this section are defined on the following numeric types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indent.

They also apply to user-defined types derived by restriction from these types.

5.2 Operators on Numeric Values

The following functions are defined to back up operators defined in [XQuery 1.0: An XML Query Language] and [XPath 2.0] on these numeric types.

The arguments and return types for the arithmetic operators are the basic numeric types: integer, decimal, float, and double, and types derived from them. For simplicity, each operator is defined to operate on operands of the same datatype and to return the same datatype. (The one exception is op:numeric-divide, which returns a double if called with two integer operands.) If the two operands are not of the same datatype, one operand is promoted to be the type of the other operand.

The type promotion scheme includes only two rules:

1. A derived type may be promoted to its base type. In particular, integer may be promoted to decimal.

2. decimal may be promoted to float, and float may be promoted to double.

The result type of operations depends on their argument datatypes and is defined in the following table:

These rules define any operation on any pair of arithmetic types. Consider the following example:

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

For this operation, int must be converted to double. This can be done, since by the rules above: int can be promoted to integer, integer can be promoted to decimal, decimal can be promoted to float, and float can be promoted to double. As far as possible, the promotions should be done in a single step. Specifically, when a decimal is promoted to a double, it must not be converted to a float and then to double as this will lose precision.

As another example, a user may define height as a derived type of integer with a minimum value of 20 and a maximum value of 100. He may then derive oddHeight using a pattern to restrict the value to odd integers.

op:operation(oddHeight, integer) => op:operation(integer, integer)

oddHeight is first promoted to its base type height. height is promoted to its base type integer.

[Issue 177: Must overflow and underflow always be reported?]

Overflow and underflow behavior is ·implementation-defined·. See [ISO 10967]. That is, implementations may determine that, when overflow or underflow is detected in any of the above operations, an error is raised ("overflow or underflow error"). However, implementations are not required to catch or report such errors.

Finally, consider some examples involving special IEEE 754 numerics.

1. If either argument is "NaN", the result is "NaN".

2. If neither argument is "NaN", but either argument is "INF", the result is "INF".

3. If neither argument is "NaN" or "INF", but either argument is "-INF", the result is "-INF".

Note: In the case of multiplication and division, "INF" may become "-INF", and vice versa, as appropriate.

The functions op:numeric-add, op:numeric-subtract, op:numeric-multiply, op:numeric-divide, op:numeric-integer-divide, and op:numeric-mod are each defined for pairs of numeric operands, each of which has the same type: integer, decimal, float, or double. The functions op:numeric-unary-plus and op:numeric-unary-minus are defined for a single operand whose type is one of those same numeric types.

5.3 Comparisons of Numeric Values

We define the following comparison operators on numeric values. Comparisons take two arguments of the same type. If the arguments are of different types, one argument is promoted to the type of the other. Each comparison operator returns a boolean value. If either, or both, operands are "NaN", false is returned.

5.4 Functions on Numeric Values

The following functions are defined on these numeric types. Each function returns an integer except:

• If the argument is the empty sequence, the empty sequence is returned.

• If the argument is "NaN", "NaN" is returned.

• If the argument is positive or negative infinity, positive or negative infinity is returned.

[Issue 79: How many digits of precision (etc.) are returned from certain functions?]

[Issue 142: Should floor ceiling and round return the same type as their argument? ]

[Issue 179: What is the appropriate return type for xf:floor, xf:celing, and xf:round?]

6.1 String Types

The operators described in this section are defined on the following string types. Each type whose name is indented is derived from the type whose name appears nearest above with one less level of indent.

They also apply to user-defined types derived by restriction from these types.

6.2 Equality and Comparison of Strings

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

Collations can indicate that some characters that are rendered differently are, in fact equal for collation purpose (e.g., "uve" and "uwe" are considered equivalent in some European languages). Strings can be compared character-by-character or in a logical manner, as defined by the collation.

Some collations, especially those based on the [Unicode Collation Algorithm] can be "tailored" for various purposes. This document does not discuss such tailoring. Instead, it assumes that the collation argument to the various functions below is a tailored and named collation. A specific collation with a distinguished name, http://www.w3.org/2002/08/query-operators/collation/codepoint, provides the ability to compare strings based on code point values. Every implementation of XQuery must support the collation based on code point values.

NOTE: This document uses the term "code point" as a synonym for "Unicode scalar value". [The Unicode Standard] sometimes spells this term "codepoint". Code points range from #x0000 to #x10FFFF inclusive.

While the [Character Model for the World Wide Web 1.0] recommends that all strings be subjected to early Unicode normalization, it is not possible to guarantee that all strings in all XML documents are, in fact, normalized, or that they are normalized in the same manner. In order to maximize interoperable results of operations on XML documents in general, there may be collations that operate on unnormalized strings, other collations that raise runtime errors when unnormalized strings are encountered, and still other collations that implicitly normalize strings for the purposes of collating them. For alignment with the [Character Model for the World Wide Web 1.0], applications may choose collations that treat unnormalized strings as though they were normalized (that is, that implicitly normalize the strings). Note that collations based on the Unicode collation algorithm produce equivalent results regardless of a string's normalization.

This document assumes that collations are named and that the collation name may be provided as an argument to string comparison functions. Functions that allow specification of a collation do so with an argument whose type is anyURI. This document also defines the manner in which a default collation is determined when the collation argument is not specified in invocations of the functions that allow it to be omitted.

The XQuery/XPath static context includes provision for a default collation that can be used for string comparisons (including ordering operations). However, the static context is not required to have a default collation specified; an implementation might choose to provide a default collation only under certain circumstances, or not at all. The static context default collation, if provided, is determined by ·implementation-defined· means. Such means might include determination from the host operating system environment, determination during XQuery/XPath installation, determination when the XQuery/XPath implementation was created, determination from the locale of some user environment, or even ·implementation-defined· language through which the user can specify that collation.

The decision of what collation to use for a given comparison or ordering operation is determined by the following algorithm:

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

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

   • Otherwise, an error is raised ("Unsupported collation").

2. If no collation is explicitly specified for the operation and the XQuery/XPath static context specifies a collation CollationB, then:

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

   • Otherwise, an error is raised ("Unsupported collation").

   NOTE: There might be several ways in which a collation might be specified in the XQuery/XPath static context. For example, XQuery might provide syntax that specifies a default collation as part of the query prolog.

3. Otherwise, the Unicode codepoint collation (http://www.w3.org/2002/08/query-operators/collation/codepoint) is used.

XML allows elements to specify the xml:lang attribute to indicate the language associated with the content of such an element. This specification does not use xml:lang to identify the default collation, in part because collations should be determined by the user of the data, not (normally) the data itself, and because using xml:lang does not produce desired effects when the two strings to be compared have different xml:lang values or when a string is multilingual.

NOTE: Some data management environments allow collations to be associated with the definition of string items (that is, with the metadata that describes items whose type is string). While such association may be appropriate for use in environments in which data is held in a repository tightly bound to its descriptive metadata, it is not appropriate in the XML environment in which different documents being processed by a single query may be described by differing schemas.

[Issue 44: Collations: URIs and URI references or short names?]

[Issue 170: Some functions require collations with special capabilities. ]

[Issue 73: Is a "between" function needed?]

6.3 Functions on String Values

The following functions are defined on these string types. Several of these function use a collation. See 6.2 Equality and Comparison of Strings for a discussion of collations.

[Issue 23: "Returns a copy" is not appropriate wording