XQuery 1.0 and XPath 2.0 Functions and Operators

3 The Error Function

In this document, as well as in [XQuery 1.0: An XML Query Language], [XPath 2.0],and [XQuery 1.0 and XPath 2.0 Formal Semantics], the phrase "an error is raised" is used whenever the semantics being described encounter an error other than a static type error. The occurrence of that phrase implicitly causes the invocation of the fn:error function defined in this section. Whenever the raising of an error is accompanied by a specific error, the phrase "an error is raised (name-of-error)" is used, and the value name-of-error is passed as an argument to the fn:error function invocation.

The fn:error function accepts any item (e.g., an atomic value or an element) as an argument. An alternate version of the function takes no arguments. The fn:error function never returns a value.

[Issue 181: What are the semantics of fn:error?]

4 Constructor Functions

5 Functions and Operators on Numerics

This section discusses arithmetic operators on the numeric datatypes defined in [XML Schema Part 2: Datatypes]. It uses an approach that permits lightweight operations whenever possible.

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

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

6 Functions on Strings

This section discusses functions and operators on the [XML Schema Part 2: Datatypes] string datatype and the datatypes derived from string.

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.

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

6.4.1 fn:concat

Accepts zero or more strings as arguments. Returns the string that is the concatenation of the values of its arguments. The resulting string might not be normalized in any Unicode or W3C normalization. If called with no arguments, returns the zero-length string. If any of the arguments is the empty sequence, it is treated as the zero-length string.

The concat() function is specified to allow an arbitrary number of string arguments that are concatenated together. This capability is retained for compatibility with [XPath 1.0] and is the only function specified in this document that has that characteristic.

[Issue 144: Should the concat function accept sequences as arguments?]

6.4.3 fn:starts-with

Returns a boolean indicating whether or not the value of $operand1 starts with a string that is equal to the value of $operand2 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns true. If the value of $operand1 is the zero-length string and the value of $operand2 is not the zero-length string, then the function returns false.

If the value of $operand1 or $operand2 is the empty sequence, the empty sequence is returned.

The collation used by the invocation of this function is determined according to the rules in 6.3 Equality and Comparison of Strings.

6.4.4 fn:ends-with

Returns a boolean indicating whether or not the value of $operand1 ends with a string that is equal to the value of $operand2 according to the specified collation.

If the value of $operand2 is the zero-length string, then the function returns true. If the value of $operand1 is the zero-length string and the value of $operand2 is not the zero-length string, then the function returns false.

If the value of $operand1 or $operand2 is the empty sequence, the empty sequence is returned.

The collation used by the invocation of this function is determined according to the rules in 6.3 Equality and Comparison of Strings.

6.4.5 fn:contains

Returns a boolean indicating whether or not the value of $operand1 contains (at the beginning, at the end, or anywhere within) a string equal to the value of $operand2 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns true. If the value of $operand1 is the zero-length string and the value of $operand2 is not the zero-length string, then the function returns false.

If the value of $operand1 or $operand2 is the empty sequence, the empty sequence is returned.

The collation used by the invocation of this function is determined according to the rules in 6.3 Equality and Comparison of Strings.

6.4.6 fn:substring

Returns the portion of the value of $sourceString beginning at the position indicated by the value of $startingLoc and continuing for the number of characters indicated by the value of $length. More specifically, returns the characters in $sourceString whose position $p obeys:

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

If $length is not specified, the substring identifies characters to the end of $sourceString.

If $length is greater than the number of characters in the value of $sourceString following $startingLoc, the substring identifies characters to the end of $sourceString.

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

If the value of any of the three parameters is the empty sequence, the empty sequence is returned.

6.4.7 fn:string-length

Returns an integer equal to the length in characters of the value of $srcval. If the value of $srcval is the empty sequence, the empty sequence is returned.

6.4.8 fn:substring-before

Returns the substring of the value of $operand1 that precedes in the value of $operand1 the first occurrence of a string that is equal to the value of $operand2 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns the value of $operand1.

If the value of $operand1 does not contain a string that is equal to the value of $operand2, then the function returns the zero-length string.

If the value of $operand1 or $operand2 is the empty sequence, returns the empty sequence.

The collation used by the invocation of this function is determined according to the rules in 6.3 Equality and Comparison of Strings.

6.4.9 fn:substring-after

Returns the substring of the value of $operand1 that follows in the value of $operand1 the first occurrence of a string that is equal to the value of $operand2 according to the collation that is used.

If the value of $operand2 is the zero-length string, then the function returns the value of $operand1.

If the value of $operand1 does not contain a string that is equal to the value of $operand2, then the function returns the zero-length string.

If the value of $operand1 or $operand2 is the empty sequence, returns the empty sequence.

The collation used by the invocation of this function is determined according to the rules in 6.3 Equality and Comparison of Strings.

6.4.10 fn:normalize-space

Returns the value of the string argument with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of more than one whitespace character by a single space. If the value of $srcval is the empty sequence, returns the empty sequence.

6.4.11 fn:normalize-unicode

Returns the value of $srcval normalized according to the normalization criteria for a normalization form identified by the value of $normalizationForm. The effective value of the $normalizationForm is computed by removing leading and trailing blanks, if present, and converting to upper case:

If the $normalizationForm is absent, as in the first format above, it shall be assumed to be "NFC"

• If the effective value of $normalizationForm is "NFC", then the value returned by the function is the value of $srcval in Unicode Normalization Form C (NFC).

• If the effective value of $normalizationForm is "NFD", then the value returned by the function is the value of $srcval in Unicode Normalization Form D (NFD).

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

• If the effective value of $normalizationForm is "NFKD", then the value returned by the function is the value of $srcval in Unicode Normalization Form KD (NFKD).

• If the effective value of $normalizationForm is "W3C", then the value returned by the function is the value of $srcval is the fully normalized form. See [Character Model for the World Wide Web 1.0].

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

• Implementations may choose to support other normalization forms in addition to the normalization forms discussed above.

If the effective value of the $normalizationForm is other than one of the values supported by the implementation, then an error is raised ("Invalid normalization form").

If the value of $srcval is the empty sequence, returns the empty sequence.

6.4.12 fn:upper-case

Returns the value of $srcval after translating every lower-case letter to its upper-case correspondent. Every lower-case letter that does not have an upper-case correspondent, and every character that is not a lower-case letter, is included in the returned value in its original form.

A "lower-case letter" is a character whose Unicode General Category class includes "Ll". The corresponding upper-case letter is determined using [Unicode Case Mappings].

If the value of $srcval is the empty sequence, returns the empty sequence.

6.4.13 fn:lower-case

Returns the value of $srcval after translating every upper-case letter to its lower-case correspondent. Every upper-case letter that does not have a lower-case correspondent, and every character that is not an upper-case letter, is included in the output in its original form.

An "upper-case letter" is a character whose Unicode General Category class includes "Lu". The corresponding lower-case letter is determined using [Unicode Case Mappings].

If the value of $srcval is the empty sequence, returns the empty sequence.

6.4.14 fn:translate

Returns the value of $srcval modified so that every character in the value of $srcval that occurs at some position N in the value of $mapString has been replaced by the character that occurs at position N in the value of $transString.

Every character in the value of $srcval that does not appear in the value of $mapString is unchanged.

Every character in the value of $srcval that appears at some position M in the value of $mapString, where the value of $transString is less than M characters in length, is omitted from the returned value.

If the value of $srcval or $mapString or $transString is the empty sequence, returns the empty sequence.

6.4.15 fn:string-pad

Returns a string consisting of $padCount copies of $padString concatenated together. Returns the zero-length string if $padCount is zero (0).

If the value of $padCount is less than zero (0), then an error is raised ("Invalid string-pad count").

If the value of $padString or $padCount is the empty sequence, returns the empty sequence.

6.4.16 fn:matches

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string.

The function returns true if $input matches the regular expression supplied as $pattern; otherwise, it returns false.

If any of the arguments is an empty sequence, the result is an empty sequence.

Unless the metacharacters ^ and $ are used as anchors, the string is considered to match the pattern if any substring matches the pattern. But if anchors are used, the anchors must match the start/end of the string (in string mode), or the start/end of a line (in multiline mode).

An error is raised ("Invalid matches argument") if the value of $pattern or of $flags does not conform to the required syntax defined in section 6.4.16.1 Regular Expression Syntax.

6.4.17 fn:replace

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string.

The function returns the string that is obtained by replacing all non-overlapping substrings of $input that match the given $pattern with an occurrence of the $replacement string. The $flags argument is interpreted in the same way as for the fn:matches function.

If any of the arguments is an empty sequence, the result is an empty sequence.

Within the $replacement string, the variables $1 to $9 may be used to refer to the substring captured by each of the first nine parenthesized sub-expressions in the regular expression. A literal $ symbol must be written as \$.

An error is raised ("Invalid replace argument") if the value of $pattern or $flags is invalid according to the rules described in section 6.4.16.1 Regular Expression Syntax.

An error is raised ("Pattern matches zero-length string") if the pattern matches a zero-length string.

6.4.18 fn:tokenize

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string.

This function breaks the $input string into a sequence of strings, treating any substring that matches $pattern as a separator. The separators themselves are not returned. The $flags argument is interpreted in the same way as for the fn:matches function.

If any of the arguments is an empty sequence, the result is an empty sequence.

If a separator occurs at the start of the $input string, the result sequence will start with a zero-length string. Zero-length strings will also occur in the result sequence if a separator occurs at the end of the $input string, or if two adjacent substrings match the supplied $pattern.

6.4.19 fn:escape-uri

This function applies the URI escaping rules defined in section 2 of [RFC 2396] as amended by [RFC 2732] to the string supplied as $uri-part, which typically represents all or part of a URI. The effect of the function is to replace any special character in the string by an escape sequence of the form %xx%yy..., where xxyy... is the hexadecimal representation of the octets used to represent the character in UTF-8.

The set of characters that are escaped depends on the setting of the boolean argument $escape-reserved.

If $escape-reserved is true, all characters are escaped other than lower case letters a-z, upper case letters A-Z, digits 0-9, and the characters referred to in [RFC 2396] as "marks": specifically, "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")". The "%" character itself is escaped only if it is not followed by two hexadecimal digits (that is, 0-9, a-f, and A-F).

If $escape-reserved is false, the behavior differs in that characters referred to in [RFC 2396] and [RFC 2732] as reserved characters, together with the '#' character, are not escaped. These characters are ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | "," | "#", "[", "]".

[RFC 2396] does not define whether escaped URIs should use lower case or upper case for hexadecimal digits. To ensure that escaped URIs can be compared using string comparison functions, this function must always use the upper-case letters A-F.

Generally, $escape-reserved should be set to true when escaping a string that is to form a single part of a URI, and to false when escaping an entire URI or URI reference.

7 Functions and Operators on Booleans

This section discusses operators on the [XML Schema Part 2: Datatypes] boolean datatype.

8 Functions and Operators on Durations, Dates, and Times

This section discusses operations on the [XML Schema Part 2: Datatypes] duration, date and time types. In addition, it discusses operations on two subtypes of the duration datatype that are defined in 8.2 Two Totally Ordered Subtypes of Duration.

[Issue 136: Should we allow casting a date/time from one timezone to another?]

<simpleType name='yearMonthDuration'>
    <restriction base='duration'>
        <xsd:pattern value="[\-]?P[0-9]+(Y([0-9]+M)?|M)"/>
    </restriction>
</simpleType>

<simpleType name='dayTimeDuration'>
    <restriction base='duration'>
              <xsd:pattern value="[\-]?P([0-9]+D(T([0-9]+(H([0-9]+(M([0-9]+(\.[0-9]*)?S
                      |\.[0-9]+S)?|(\.[0-9]*)?S)|(\.[0-9]*)?S)?|M([0-9]+
                      (\.[0-9]*)?S|\.[0-9]+S)?|(\.[0-9]*)?S)|\.[0-9]+S))?
                      |T([0-9]+(H([0-9]+(M([0-9]+(\.[0-9]*)?S|\.[0-9]+S)?
                      |(\.[0-9]*)?S)|(\.[0-9]*)?S)?|M([0-9]+(\.[0-9]*)?S|\.[0-9]+S)?
                      |(\.[0-9]*)?S)|\.[0-9]+S))"/>
    </restriction>
</simpleType>

8.6.1 fn:add-timezone-to-dateTime

Returns a dateTime with a timezone.

If $srcval is a dateTime value without a timezone, then let $srcn be $srcval. Otherwise, let $srcn be the value of fn:remove-timezone-from-dateTime ($srcval). If $timezone is not specified, then $timezone will be the value of the implicit timezone for the query. The value of $srcn - $timezone is returned with a timezone of Z.

8.6.2 fn:remove-timezone-from-dateTime

Returns a dateTime without a timezone.

If $srcval has a timezone, then let $srcn be $srcval. Otherwise, let $srcn be the value of fn:add-timezone-to-dateTime ($srcval). If $timezone is not specified, then $timezone will be the value of the implicit timezone for the query. The value returned is $srcn + $timezone, expressed in timezone Z, with the timezone of Z removed.

8.6.3 fn:add-timezone-to-date

Returns a date with a timezone.

If $srcval is a date value without a timezone, then let $srcn be $srcval. Otherwise, let $srcn be the value of fn:remove-timezone-from-date($srcval). If $timezone is not specified, then $timezone will be the value of the implicit timezone for the query. The value of $srcn - $timezone is returned with a timezone of Z.

8.6.4 fn:add-timezone-to-time

Returns a time with a timezone.

If $srcval is a time value without a timezone, then let $srcn be $srcval. Otherwise, let $srcn be the value of fn:remove-timezone-from-time($srcval). If $timezone is not specified, then $timezone will be the value of the implicit timezone for the query. The value of $srcn - $timezone is returned with a timezone of Z.

8.6.5 fn:remove-timezone-from-time

Returns a time without a timezone.

If $srcval has a timezone, then let $srcn be $srcval. Otherwise, let $srcn be the value of fn:add-timezone-to-time ($srcval). If $timezone is not specified, then $timezone will be the value of the implicit timezone for the query. The value returned is $srcn + $timezone, expressed in timezone Z, with the timezone of Z removed.

8.7 Adding and Subtracting Durations From dateTime, date and time

These functions support adding or subtracting a duration value to or from a dateTime, a date or a time value. Appendix E of [XML Schema Part 2: Datatypes] describes an algorithm for performing such operations.

If any of the arguments to the functions below is a dateTime, date or time value that does not contain a timezone, then, for the purposes of the function, the argument is considered to a have an implicit timezone provided by the implementation.

9 Functions Related to QNames

9.2 Functions Related to QNames

This section discusses functions on QNames as defined in [XML Schema Part 2: Datatypes].

9.2.1 op:QName-equal

Returns true if the namespace names of $srcval1 and $srcval2 are equal and the local-name parts of $srcval1 and $srcval2 are identical on a codepoint-by-codepoint basis. Otherwise, returns false. Two namespace names are considered equal if they are either both absent or both present and identical on a codepoint-by-codepoint basis.

Backs up the "eq" and "ne" operators on values of type QName.

If either namespace name is a relative URI, it is undefined whether it will compare equal to any other namespace name.

9.2.2 fn:get-local-name-from-QName

Returns a string representing the local part of $srcval. If $srcval is the empty sequence, returns the empty sequence.

9.2.3 fn:get-namespace-from-QName

Returns the namespace URI for $srcval. If $srcval is in no namespace, the function returns the empty sequence.

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

10 Functions and Operators for anyURI

11 Functions and Operators on base64Binary and hexBinary

12 Functions and Operators on NOTATION

13 Functions and Operators on Nodes

This section discusses functions and operators on nodes. Nodes are formally defined in [XQuery 1.0 and XPath 2.0 Data Model].

13.1.1 fn:name

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

If the argument is omitted, it defaults to the context node. If there is no context node (that is, if the context item is not a node), the function returns the zero-length string.

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

If the target 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 value returned is a string whose lexical form is a QName.

If $srcval is a processing instruction or a namespace node, or if it is an element or attribute node whose expanded-QName (as determined by the name accessor in the data model) is in no namespace, then the function returns the local part of the expanded-QName.

If $srcval is an element or attribute whose expanded QName is in a namespace, then a prefix is determined using the same rules as those for determining the prefix property when the element or attribute node is mapped to an element or attribute information item in the InfoSet. These rules are given in [XQuery 1.0 and XPath 2.0 Data Model]. This prefix is then combined with the local part of the node's expanded QName to form a string which will take one of the forms "prefix:local-part" (if the prefix is a non-zero length string) or "local-part" (if the prefix is a zero-length string).

13.1.2 fn:local-name

Returns the local part of the name of $srcval as a string that will either be the zero-length string, or will have the lexical form of an NCName.

If the argument is omitted, it defaults to the context node. If there is no context node (that is, if the context item is not a node), the function returns the zero-length string.

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

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

Otherwise, the value returned will be the local part of the expanded-QName of the target node (as determined by the name accessor in the data model). This will be a string whose lexical form is an NCName.

13.1.3 fn:namespace-uri

Returns the namespace URI of the QName of $srcval as a string. If the argument is omitted, it defaults to the context node. If there is no context node (that is, if the context item is not a node), the function returns the zero-length string. If $srcval is the empty sequence, the zero-length string is returned.