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. In most cases, the dynamic type returned by the function is the same as its static type. The few exceptions to this rule are documented in specific functions.

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, fn: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. This is called subtype substitution. Details of the semantics of passing parameters to functions are discussed in Appendix B of [XQuery 1.0: An XML Query Language].

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:

1.5 Namespace Prefix

The functions and operators discussed in this document are contained in three namespaces (see [Namespaces in XML]) and referenced using a QName. Constructor functions for the built-in datatypes defined in [XML Schema Part 2: Datatypes] discussed in 4 Constructor Functions are in the XML Schema namespace and named in this document using the xs: prefix. The namespace prefix used in this document is fn: 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 correct URI.

The URIs of the namespaces are:

• http://www.w3.org/2001/XMLSchema-datatypes for constructors

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

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

The functions defined with an fn: 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 fn: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 fn: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 fn: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:

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

2.4 fn:data

If $srcval is a text node, an element node, or an attribute node, fn: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 XML Schema validation, as described in [XQuery 1.0 and XPath 2.0 Data Model].

If $srcval is an element node with type annotation xs:anyType, then its typed value is equal to its string value, as an instance of xs:anySimpleType. The typed value of an element node with a type annotation other than xs:anyType is derived from its string value and type annotation in a way that is consistent with XML Schema validation, as described in [XQuery 1.0 and XPath 2.0 Data Model]. If $srcval is an element node whose type annotation denotes a type with complex content (i.e., a type that permits subelements), fn:data raises an error (Node has complex content).

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

2.5 fn: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.

This version of the function returns the base-uri from the static context.

2.6 fn: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

• fn:error()

• fn:error("Invalid argument")

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

4.1 Constructor Functions for XML Schema Built-in Types

Every built-in type that is defined in [XML Schema Part 2: Datatypes], except xs:QName, as well as each of the two derived types fn:yearMonthDuration and fn:dayTimeDuration defined in this specification, has an associated constructor function. The form of that function for a type TYP is:

For example, the signature of the constructor function corresponding to the unsignedInt type defined in [XML Schema Part 2: Datatypes] is:

Invoking the constructor function xs:unsignedInt(12) returns the unsignedInt value 12. Another invocation of that constructor function that returns the same unsignedInt value is xs:unsignedInt("12").

If the argument to a constructor function is a string literal, the literal must be a valid lexical form for its type, as specified in [XML Schema Part 2: Datatypes] and the semantics of the function are identical to XML Schema validation. Whitespace normalization is applied before validation as indicated by the value of the whitespace facet for the datatype.

If the argument to a constructor function is a literal, the result of the function may be evaluated statically; if an error is found during such evaluation, it may be reported as a static error.

The semantics of the constructor function xs:TYP(item) are identical to the semantics of "cast as xs:TYP (item)". See 16 Casting Functions

The following constructor functions for the built-in types are supported:

• xs:string($srcval as item) as string
• xs:boolean($srcval as item) as boolean
• xs:decimal($srcval as item) as decimal
• xs:float($srcval as item) as float
• xs:double($srcval as item) as double
• xs:duration($srcval as item) as duration
• xs:dateTime($srcval as item) as dateTime
• xs:time($srcval as item) as time
• xs:date($srcval as item) as date
• xs:gYearMonth($srcval as item) as gYearMonth
• xs:gYear($srcval as item) as gYear
• xs:gMonthDay($srcval as item) as gMonthDay
• xs:gDay($srcval as item) as gDay
• xs:gMonth($srcval as item) as gMonth
• xs:hexBinary($srcval as item) as hexBinary
• xs:base64Binary($srcval as item) as base64Binary
• xs:anyURI($srcval as item) as anyURI
• xs:NOTATION($srcval as item) as NOTATION

• xs:normalizedString($srcval as item) as normalizedString
• xs:token($srcval as item) as token
• xs:language($srcval as item) as language
• xs:NMTOKEN($srcval as item) as NMTOKEN
• xs:NMTOKENS($srcval as item) as NMTOKENS
• xs:Name($srcval as item) as Name
• xs:NCName($srcval as item) as NCName
• xs:ID($srcval as item) as ID
• xs:IDREF($srcval as item) as IDREF
• xs:IDREFS($srcval as item) as IDREFS
• xs:ENTITY($srcval as item) as ENTITY
• xs:ENTITIES($srcval as item) as ENTITIES
• xs:integer($srcval as item) as integer
• xs:nonPositiveInteger($srcval as item) as nonPositiveInteger
• xs:negativeInteger($srcval as item) as negativeInteger
• xs:long($srcval as item) as long
• xs:int($srcval as item) as int
• xs:short($srcval as item) as short
• xs:byte($srcval as item) as byte
• xs:nonNegativeInteger($srcval as item) as nonNegativeInteger
• xs:unsignedLong($srcval as item) as unsignedLong
• xs:unsignedInt($srcval as item) as unsignedInt
• xs:unsignedShort($srcval as item) as unsignedShort
• xs:unsignedByte($srcval as item) as unsignedByte
• xs:positiveInteger($srcval as item) as positiveInteger

• fn:yearMonthDuration($srcval as item) as yearMonthDuration
• fn:dayTimeDuration($srcval as item) as dayTimeDuration

4.2 Constructor Functions for User-Defined Types

For every type defined in the static query context (See [XQuery 1.0: An XML Query Language] that is derived by restriction from a primitive type, there is a construction function (whose name is the same as the type name), whose effect is to create a value of that type from the supplied argument. The rules are defined in the same way as for built-in derived types 4.1 Constructor Functions for XML Schema Built-in Types.

Consider a situation where the static context contains a type called hatSize defined in a schema that is bound to the prefix my. In such a case the constructor function:

is available to users.

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 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 type, subtype substitution and type promotion may be used to obtain two operands of the same type. Appendix B of [XQuery 1.0: An XML Query Language] describes the semantics of these operations in detail.

1. Subtype substitution: A derived type may substitute for its base type. In particular, integer may be used where decimal is expected.

2. Type promotion: 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 substitutued for 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 can be substituted for its base type height and height can be substitutued for 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 that in some cases such as subtraction, 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 Comparison 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 fn:floor, fn:celing, and fn: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.

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. The use of the word 'character' in this document is in the sense of production [2] of [XML 1.0 Recommendation (Second Edition)].

6.2 Functions to Assemble and Disassemble Strings

6.3 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/11/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.

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 fn: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/11/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.

NOTE: all collations support the capability of deciding whether two strings are considered equal, and if not, which of the strings should be regarded as preceding the other. For functions such as fn:compare(), this is all that is required. For other functions, such as fn:contains() and fn:starts-with(), the collation needs to support an additional property: it must decompose the string into a sequence of units, each unit consisting of one or more characters, such that two strings can be compared by pairwise comparison of these units. The functions fn:contains(), fn:starts-with(), and fn:ends-with() first use the collation to decompose the string provided in the first argument into such a sequence of units, then examine this sequence to determine if there is a subsequence that matches the units obtained by decomposing the string supplied in the second argument. Substrings might not be matched if they start or end in the middle of a unit. For example, if a collation treats "Jaeger" and "Jäger" [ed note, second character is "a with umlaut"] as equal, then it is probably treating "ae" as one unit, which means that under this collation, the expression contains("Jaeger", "eg") is likely to return false.

It is possible to define collations that do not have this property, for example a collation that attempts to sort "ISO 8859" before "ISO 10646", or "January" before "February". Such collations may fail, or give unexpected results, when used with functions such as fn:contains().

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

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

6.4 Functions on String Values

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

[Issue 21: What is the precise type returned by each function?]

Note also that when the above operators and functions are applied to datatypes derived from string, they are guaranteeed to return legal strings, but they may not return legal value for the particular subtype to which they were applied.