XQuery 1.0 and XPath 2.0 Functions and Operators

1.5.1 xdt:anyAtomicType

The abstract datatype xdt:anyAtomicType is a child of xs:anySimpleType and is the base type for all the primitive atomic types described in [XML Schema Part 2: Datatypes]. This datatype cannot be used in [XML Schema Part 1: Structures] type declarations, nor can it be used as a base for user-defined atomic types. It can be used, as discussed in the Section 3.12 Expressions on SequenceTypes^XQ, to define a required type (for example in a function signature) to indicate that any of the primitive atomic types or xdt:untypedAtomic is acceptable. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

1.5.2 xdt:untypedAtomic

The abstract datatype xdt:untypedAtomic is a child of xdt:anyAtomicType and serves as a special type annotation to indicate atomic values that have not been validated by a XML Schema or a DTD or have received an instance type annotation of xs:anySimpleType in the PSVI. This datatype cannot be used in [XML Schema Part 1: Structures] type declarations, nor can it be used as a base for user-defined atomic types. It can be used, as discussed in the Section 3.12 Expressions on SequenceTypes^XQ, to define a required type (for example in a function signature) to indicate that only an untyped atomic value is acceptable. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

1.5.3 xdt:untypedAny

The abstract datatype xdt:untypedAny is a child of xs:anyType and serves as a special type annotation to indicate types that have not been validated by a XML Schema or a DTD. This type cannot be used in [XML Schema Part 1: Structures] type declarations, nor can it be used as a base for user-defined types. It can be used, as discussed in the Section 3.12 Expressions on SequenceTypes^XQ, to define a required type (for example in a function signature) to indicate that only an untyped value is acceptable. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

1.6.1 Examples

• A dateTime with lexical representation 1999-05-31T05:00:00 has a value represented by the tuple (1999-05-31T05:00:00Z, ())

• A dateTime with lexical representation 1999-05-31T13:20:00-05:00 has a value represented by the tuple (1999-05-31T18:20:00Z, -PT5H)

6.2.1 op:numeric-add

Summary: Backs up the "+" operator and returns the arithmetic sum of its operands: ($arg1 + $arg2).

6.2.2 op:numeric-subtract

Summary: Backs up the "-" operator and returns the arithmetic difference of its operands: ($arg1 - $arg2).

6.2.3 op:numeric-multiply

Summary: Backs up the "*" operator and returns the arithmetic product of its operands: ($arg1 * $arg2).

6.2.4 op:numeric-divide

Summary: Backs up the "div" operator and returns the arithmetic quotient of its operands: ($arg1 div $arg2).

As a special case, if the types of both $arg1 and $arg2 are xs:integer, then the return type is xs:decimal.

For xs:decimal and xs:integer operands, if the divisor is zero, then an error is raised [division by zero]. For xs:float and xs:double operands, floating point division is performed as specified in [IEEE 754-1985] and INF or -INF is returned if the divisor is zero.

6.2.5 op:numeric-integer-divide

Summary: Backs up the "idiv" operator and returns the arithmetic quotient of its operands: ($arg1 idiv $arg2). If the numerator is not evenly divided by the divisor, then the quotient is the xs:integer value obtained, ignoring any remainder that results from the division (that is, no rounding is performed).

If the divisor is zero, then an error is raised [division by zero].

6.2.6 op:numeric-mod

Summary: Backs up the "mod" operator. Informally, this function returns the remainder resulting from dividing $arg1, the dividend, by $arg2, the divisor. 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.

If $arg2 is zero, then an error is raised [division by zero].

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/b)*b+(a mod b) = a. Division is truncating division, analogous to integer division, not [IEEE 754-1985] rounding division.

6.2.7 op:numeric-unary-plus

Summary: Backs up the unary "+" operator and returns its operand with the sign unchanged: (+ $arg). Semantically, this operation performs no operation.

6.2.8 op:numeric-unary-minus

Summary: Backs up the unary "-" operator and returns its operand with the sign reversed: (- $arg). If $arg is positive, its negative is returned; if it is negative, its positive is returned.

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 and +INF return -INF. -INF returns INF.

6.3.1 op:numeric-equal

Summary: Returns true if and only if the value of $arg1 is equal to the value of $arg2. For xs:float and xs:double values, positive zero and negative zero compare equal. NaN does not equal itself.

This function backs up the "eq" and "ne" operators on numeric values.

6.3.2 op:numeric-less-than

Summary: Returns true if and only if $arg1 is less than $arg2. For xs:float and xs:double values, positive infinity is greater than all other non-NaN values; negative infinity is less than all other non-NaN values. If $arg1 or $arg2 is NaN, the function returns false.

This function backs up the "lt" and "ge" operators on numeric values.

6.3.3 op:numeric-greater-than

Summary: Returns true if and only if $arg1 is greater than $arg2. For xs:float and xs:double values, positive infinity is greater than all other non-NaN values; negative infinity is less than all other non-NaN values. If $arg1 or $arg2 is NaN, the function returns false.

This function backs up the "gt" and "le" operators on numeric values.

6.4.1 fn:abs

Summary: Returns the absolute value of $arg. If $arg is negative returns -$arg otherwise returns $arg. If type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the return is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the type of the return is the parent numeric type.

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

For detailed type semantics, see Section 6.2.1 The fn:abs, fn:ceiling, fn:floor, fn:round, and fn:round-half-to-even functions^FS

6.4.2 fn:ceiling

Summary: Returns the smallest (closest to negative infinity) number with no fractional part that is not less than the value of $arg. If type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the return is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the type of the return is the parent numeric type.

For xs:float and xs:double arguments, if the argument is positive zero (+0), then positive zero (+0) is returned. If the argument is negative zero (-0), then negative zero (-0) is returned. If the argument is less than zero (0), but greater than or equal to -0.5, then negative zero (-0) is returned.

For detailed type semantics, see Section 6.2.1 The fn:abs, fn:ceiling, fn:floor, fn:round, and fn:round-half-to-even functions^FS

6.4.3 fn:floor

Summary: Returns the largest (closest to positive infinity) number with no fractional part that is not greater than the value of $arg. If type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the return is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the type of the return is the parent numeric type.

For float and double arguments, if the argument is positive zero (+0), then positive zero (+0) is returned. If the argument is negative zero (-0), then negative zero (-0) is returned.

For detailed type semantics, see Section 6.2.1 The fn:abs, fn:ceiling, fn:floor, fn:round, and fn:round-half-to-even functions^FS

6.4.4 fn:round

Summary: Returns the number with no fractional part that is closest to the argument. If there are two such numbers, then the one that is closest to positive infinity is returned. More formally, fn:round(x) produces the same result as fn:floor(x+0.5). If type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the return is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the type of the return is the parent numeric type.

For xs:float and xs:double arguments, if the argument is positive zero (+0), then positive zero (+0) is returned. If the argument is negative zero (-0), then negative zero (-0) is returned. If the argument is less than zero (0), but greater than or equal to -0.5, then negative zero (-0) is returned.

For detailed type semantics, see Section 6.2.1 The fn:abs, fn:ceiling, fn:floor, fn:round, and fn:round-half-to-even functions^FS

6.4.5 fn:round-half-to-even

Summary: The value returned is the nearest (that is, numerically closest) numeric to $arg 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 $arg is exactly .500...), returns the one whose least significant digit is even. If type of $arg is one of the four numeric types xs:float, xs:double, xs:decimal or xs:integer the type of the return is the same as the type of $arg. If the type of $arg is a type derived from one of the numeric types, the type of the return is the parent numeric type.

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

For arguments of type xs:float and xs:double, if the argument is positive zero (+0), then positive zero (+0) is returned. If the argument is negative zero (-0), then negative zero (-0) is returned.

If $arg is of type xs:float or xs:double, rounding occurs on the value of the mantissa computed with exponent = 0.

For detailed type semantics, see Section 6.2.1 The fn:abs, fn:ceiling, fn:floor, fn:round, and fn:round-half-to-even functions^FS

7.2.1 fn:codepoints-to-string

Creates an xs:string from a sequence of code points. Returns the zero-length string if $arg is the empty sequence. If any of the code points in $arg is not a legal XML character, an error is raised [codepoint not valid].

7.2.2 fn:string-to-codepoints

Returns the sequence of code points that constitute an xs:string. If $arg is a zero-length string or the empty sequence, the empty sequence is returned.

7.3.1 Collations

When values whose type is xs:string or a type derived from xs:string are compared (or, equivalently, sorted), the comparisons are inherently performed according to some collation (even if that collation is defined entirely on code point values). 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 that two different code points are, in fact, equal for comparison purposes (e.g., "v" and "w" are considered equivalent in Swedish). Strings can be compared codepoint-by-codepoint or in a linguistically appropriate manner, as defined by the collation.

Some collations, especially those based on the [Unicode Collation Algorithm] can be "tailored" for various purposes. This document does not discuss such tailoring, nor does it provide a mechanism to perform tailoring. Instead, it assumes that the collation argument to the various functions below is a tailored and named collation. A specific collation with a distinguished name, http://www.w3.org/2003/11/xpath-functions/collation/codepoint, provides the ability to compare strings based on code point values. Every implementation of XQuery/XPath 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 specification assumes that collations are named and that the collation name may be provided as an argument to string functions. Functions that allow specification of a collation do so with an argument whose type is xs:string but whose lexical form must conform to an xs:anyURI. If the collation is specified using a relative URI, it is assumed to be relative to the value of the base-uri property in the static context. This specification also defines the manner in which a default collation is determined if the collation argument is not specified in invocations of functions that use a collation but allow it to be omitted.

Functions such as fn:compare and fn:max that compare xs:string values use a single collation URI to identify all aspects of the collation rules. This means that any parameters such as the strength of the collation must be specified as part of the collation URI. For example, suppose there is a collation "http://www.example.com/collations/French" that refers to a French collation that compares on the basis of base characters. Collations that use the same basic rules, but with higher strengths, for example, base characters and accents, or base characters, accents and case, would need to be given different names, say "http://www.example.com/collations/French1" and "http://www.example.com/collations/French2". Note that some specifications use the term collation to refer to an algorithm that can be parameterized, but in this specification, each possible parameterization is considered to be a distinct collation.

The XQuery/XPath static context includes a provision for a default collation that can be used for string comparisons (including ordering operations). However, the static context is not required to have a default collation specified. See the description of the static context in Section 2.1.1 Static Context^XQ. If the static context does not have a default collation specified, a system defined default can be invoked. If this is not provided, the Unicode code point collation is used as the default collation.

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

1. If the function 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 function and the function is fn:contains, fn:starts-with, fn:ends-with, fn:substring-before or fn:substring-after the Unicode code point collation (http://www.w3.org/2003/11/xpath-functions/collation/codepoint) is used.

3. If no collation is explicitly specified for the function and the function is not one of the above functions 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].

4. Otherwise, the Unicode code point collation (http://www.w3.org/2003/11/xpath-functions/collation/codepoint) is used.

7.3.2 fn:compare

Summary: Returns -1, 0, or 1, depending on whether the value of the $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, according to the rules of the collation that is used.

The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations.

If the value of $comparand2 begins with a string that is equal to the value of $comparand1 (according to the collation that is used) and has additional code points following that beginning string, then the result is -1. If the value of $comparand1 begins with a string that is equal to the value of $comparand2 (according to the collation that is used) and has additional code points following that beginning string, then the result is 1.

If either argument is the empty sequence, the result is the empty sequence.

This function, invoked with the second signature, backs up the "eq", "ne", "gt", "lt", "le" and "ge" operators on string values.

7.4.1 fn:concat

Summary: Accepts two or more xs:strings as arguments. Returns the xs:string that is the concatenation of the values of its arguments. If any of the arguments is the empty sequence, the argument is treated as the zero-length string.

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

7.4.2 fn:string-join

Summary: Returns a xs:string created by concatenating the members of the $arg1 sequence using $arg2 as a separator. If the value of $arg2 is the zero-length string, then the members of $arg1 are concatenated without a separator.

If the value of $arg1 is the empty sequence, the zero-length string is returned.

7.4.3 fn:substring

Summary: 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)

In the above computation, the rules for op:numeric-less-than() and op:numeric-greater-than() apply.

If the value of $sourceString is the empty sequence, the zero-length string is returned.

If $startingLoc is zero or negative, the substring includes characters from the beginning of the $sourceString.

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

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

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

7.4.4 fn:string-length

Summary: Returns an xs:integer equal to the length in characters of the value of $arg.

If the value of $arg is the empty sequence, the xs:integer 0 is returned.

If no argument is supplied, $arg defaults to the string value (calculated using fn:string()) of the context item (.).

7.4.5 fn:normalize-space

Summary: Returns the value of $arg with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of one or more than one whitespace character with a single space, #x20.

The whitespace characters are defined in [XML 1.0 Recommendation (Second Edition)] as TAB (#x9), LINE FEED (#xA), CARRIAGE RETURN (#xD) and SPACE (#x20). If the value of $arg is the empty sequence, returns the zero-length string. If no argument is supplied, $arg defaults to the string value (calculated using fn:string()) of the context item (.).

7.4.6 fn:normalize-unicode

Summary: Returns the value of $arg 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 value of $arg is the empty sequence, returns the zero-length string.

See [Character Model for the World Wide Web 1.0] for a description of the normalization forms.

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 $arg 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 $arg 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 $arg 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 $arg in Unicode Normalization Form KD (NFKD).

• If the effective value of $normalizationForm is "fully-normalized", then the value returned by the function is the value of $arg is the fully normalized form.

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

Conforming implementations ·must· support normalization form "NFC" and ·may· support normalization forms "NFD", "NFKC", "NFKD", "fully-normalized". They ·may· also support other normalization forms with ·implementation-defined· semantics. If the effective value of the $normalizationForm is other than one of the values supported by the implementation, then an error is raised [unsupported normalization form].

7.4.7 fn:upper-case

Summary: Returns the value of $srcval after translating every character to its upper-case correspondent. Every character that does not have an upper-case correspondent is included in the returned value in its original form. The precise mapping is determined using [Unicode Case Mappings].

If the value of $arg is the empty sequence, the zero-length string is returned.

7.4.8 fn:lower-case

Summary, returns the value of $srcval after translating every character to its lower-case correspondent. Every character that does not have an lower-case correspondent is included in the returned value in its original form. The precise mapping is determined using [Unicode Case Mappings].

If the value of $arg is the empty sequence, the zero-length string is returned.

7.4.9 fn:translate

Summary: Returns the value of $arg modified so that every character in the value of $arg 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.

If the value of $arg is the empty sequence, the zero-length string is returned.

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

Every character in the value of $arg 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 $mapString is the zero-length string $arg is returned.

If a character occurs more than once in $mapString, then the first occurrence determines the replacement character. If $transString is longer than $mapString, the excess characters are ignored.

7.4.10 fn:escape-uri

Summary: This function applies the URI escaping rules defined in section 2 of [RFC 2396] as amended by [RFC 2732], with one exception, 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 %HH, where HH... 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 $uri-part is the empty sequence, returns the zero-length string.

If $escape-reserved is true, all characters are escaped other than the lower case letters a-z, the upper case letters A-Z, the digits 0-9, the PERCENT SIGN "%" and the NUMBER SIGN "#" characters and the characters referred to in [RFC 2396] as "marks": specifically, HYPHEN-MINUS ("-"), LOW LINE ("_"), FULL STOP ".", EXCLAMATION MARK "!", TILDE "~", ASTERISK "*", APOSTROPHE "'", LEFT PARENTHESIS "(", and RIGHT PARENTHESIS ")".

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 NUMBER SIGN '#' character, (See [Uniform Resource Identifiers (URI): Generic Syntax]) are not escaped. These characters are SEMICOLON ";", SOLIDUS "/", QUESTION MARK "?", COLON ":", COMMERCIAL AT "@", AMPERSAND "&", EQUALS SIGN "=", PLUS SIGN "+", DOLLAR SIGN "$", COMMA "," NUMBER SIGN "#", LEFT SQUARE BRACKET "[" and RIGHT SQUARE BRACKET "]".

[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 generate hexadecimal values using 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.5.1 fn:contains

Summary: Returns an xs:boolean indicating whether or not the value of $arg1 contains (at the beginning, at the end, or anywhere within) a sequence of collation units that match the collation units of $arg2 according to the collation that is used.

The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations. If the specified collation is unsuitable for this function an error ·may· be raised [collation unsuitable for this function].

If the value of $arg1 or $arg2 is the empty sequence, it is interpreted as the zero-length string.

If the value of $arg2 is the zero-length string, then the function returns true.

If the value of $arg1 is the zero-length string, the function returns false.

7.5.2 fn:starts-with

Summary: Returns an xs:boolean indicating whether or not the value of $arg1 starts with a sequence of collation units that matches the collation units of $arg2 according to the collation that is used.

If the value of $arg1 or $arg2 is the empty sequence, it is interpreted as the zero-length string.

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

The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations. If the specified collation is unsuitable for this function an error ·may· be raised [collation unsuitable for this function].

7.5.3 fn:ends-with

Summary: Returns an xs:boolean indicating whether or not the value of $arg1 ends with a sequence of collation units that match the collation units of $arg2 according to the specified collation.

If the value of $arg1 or $arg2 is the empty sequence, it is interpreted as the zero-length string.

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

The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations. If the specified collation is unsuitable for this function an error ·may· be raised [collation unsuitable for this function].

7.5.4 fn:substring-before

Summary: Returns the substring of the value of $arg1 that precedes in the value of $arg1 the first occurrence of a string that is equal to the value of $arg2 according to the collation that is used.

If the value of $arg1 or $arg2 is the empty sequence, it is interpreted as the zero-length string.

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

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

The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations If the specified collation is unsuitable for this function an error ·may· be raised [collation unsuitable for this function].

7.5.5 fn:substring-after

Summary: Returns the substring of the value of $arg1 that follows in the value of $arg1 the first occurrence of a string that is equal to the value of $arg2 according to the collation that is used.

If the value of $arg1 or $arg2 is the empty sequence, it is interpreted as the zero-length string.

If the value of $arg2 is the zero-length string, then the function returns the value of $arg1.

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

The collation used by the invocation of this function is determined according to the rules in 7.3.1 Collations If the specified collation is unsuitable for this function an error ·may· be raised [collation unsuitable for this function].

7.6.1 Regular Expression Syntax

The regular expression syntax used by these functions is defined in terms of the regular expression syntax specified in XML Schema (see [XML Schema Part 2: Datatypes]), which in turn is based on the established conventions of languages such as Perl. However, because XML Schema uses regular expressions only for validity checking, it omits some facilities that are widely-used with languages such as Perl. This section, therefore, describes extensions to the XML Schema regular expressions syntax that reinstate these capabilities.

7.6.2 fn:matches

Summary: The function returns true if $input matches the regular expression supplied as $pattern as influenced by the value of $flags, if present; otherwise, it returns false.

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. Flags are defined in 7.6.1.1 Flags.

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

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 regular expression] if the value of $pattern is invalid according to the rules described in section 7.6.1 Regular Expression Syntax.

An error is raised [invalid regular expression flags] if the value of $flags is invalid according to the rules described in section 7.6.1 Regular Expression Syntax.

<poem author="Wilhelm Busch"> 
Kaum hat dies der Hahn gesehen,
Fängt er auch schon an zu krähen:
«Kikeriki! Kikikerikih!!»
Tak, tak, tak! - da kommen sie.
</poem>

7.6.3 fn:replace

Summary: The function returns the xs:string that is obtained by replacing each non-overlapping substring of $input that matches the given $pattern with an occurrence of the $replacement string.

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. Flags are defined in 7.6.1.1 Flags.

The $flags argument is interpreted in the same manner as for the fn:matches() function.

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

If two overlapping substrings of $input both match the $pattern, then only the first one (that is, the one whose first character comes first in the $input string) is replaced.

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. $0 refers to the substring captured by the regular expression as a whole. A literal "$" symbol must be written as "\$". A literal "\" symbol must be written as "\\". For each match of the pattern, these variables are assigned the value of the content of the relevant captured sub-expression, and the modified replacement string is then substituted for the characters in $input that matched the pattern.

If a variable $n is present in the replacement string, but there is no nth captured substring (which may happen because there were fewer than n parenthesized sub-expressions, or because the nth parenthesized sub-expression was not matched) then the variable is replaced by a zero-length string.

If two alternatives within the pattern both match at the same position in the $input, then the match that is chosen is the one matched by the first alternative. For example:

fn:replace("abcd", "(ab)|(a)", "[1=$1][2=$2]") returns "[1=ab][2=]cd" 

An error is raised [invalid regular expression] if the value of $pattern is invalid according to the rules described in section 7.6.1 Regular Expression Syntax.

An error is raised [invalid regular expression flags] if the value of $flags is invalid according to the rules described in section 7.6.1 Regular Expression Syntax.

An error is raised [regular expression matches zero-length string] if the pattern matches a zero-length string, that is, if the expression fn:matches("", $pattern, $flags) returns true. It is not an error, however, if a captured substring is zero-length.

An error is raised [invalid replacement string] if the value of $replacement contains a "$" character that is not immediately followed by a digit 1-9 and not immediately preceded by a "\".

An error is raised [invalid replacement string] if the value of $replacement contains a "\" character that is not part of a "\\" pair, unless it is immediately followed by a "$" character.

7.6.4 fn:tokenize

Summary: 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 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. Flags are defined in 7.6.1.1 Flags.

The $flags argument is interpreted in the same way as for the fn:matches() function.

If $input is the empty sequence, the result is the zero-length string.

If the supplied $pattern matches a zero-length string, that is, if fn:matches("", $pattern, $flags) returns true, then an error is raised: [regular expression matches zero-length string].

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.

If two alternatives within the supplied $pattern both match at the same position in the $input string, then the match that is chosen is the first. For example:

fn:tokenize("abracadabra", "(ab)|(a)") returns ("", "r", "c", "d", "r", "")

An error is raised [invalid regular expression] if the value of $pattern is invalid according to the rules described in section 7.6.1 Regular Expression Syntax.

An error is raised [invalid regular expression flags] if the value of $flags is invalid according to the rules described in section 7.6.1 Regular Expression Syntax.

8.1.1 fn:true

Summary: Returns the xs:boolean value true. Equivalent to xs:boolean("1").

8.1.2 fn:false

Summary: Returns the xs:boolean value false. Equivalent to xs:boolean("0").

8.2.1 op:boolean-equal

Summary: Returns true if both arguments are true or if both arguments are false. Returns false if one of the arguments is true and the other argument is false.

This function backs up the "eq" operator on xs:boolean values.

8.2.2 op:boolean-less-than

Summary: Returns true if $arg1 is false and $arg2 is true. Otherwise, returns false.

This function backs up the "lt" and "ge" operators on xs:boolean values.

8.2.3 op:boolean-greater-than

Summary: Returns true if $arg1 is true and $arg2 is false. Otherwise, returns false.

This function backs up the "gt" and "le" operators on xs:boolean values.

8.3.1 fn:not

Summary: $arg is first reduced to an effective boolean value by applying the fn:boolean() function. Returns true if the effective boolean value is false, and false if the effective boolean value is true.

9.1.1 Limits and Precision

For a number of the above datatypes [XML Schema Part 2: Datatypes] extends the basic [ISO 8601] lexical representations, such as YYYY-MM-DDThh:mm:ss.s for dateTime, by allowing a preceding minus sign, more than four digits to represent the year field — no maximum is specified — and an unlimited number of digits for fractional seconds.

For this specification, all minimally conforming processors must support year values with a minimum of 4 digits (i.e., YYYY) and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, conforming processors may set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations.

A processor that limits the number of digits in date and time datatype representations may encounter overflow and underflow conditions when it tries to execute the functions in 9.7 Adding and Subtracting Durations From dateTime, date and time. In these situations, the processor ·must· return zero in case of underflow and ·must· raise an error [overflow in date/time arithmetic] in case of overflow.

The value spaces of the two totally ordered subtypes of xs:duration described in 9.2 Two Totally Ordered Subtypes of Duration are xs:integer months for xdt:yearMonthDuration and xs:decimal seconds for xdt:dayTimeDuration. If a processor limits the number of digits allowed in the representation of xs:integer and xs:decimal then overflow and underflow situations can arise when it tries to execute the functions in 9.5 Arithmetic Functions on xdt:yearMonthDuration and xdt:dayTimeDuration. In these situations the processor ·must· return zero in case of underflow and ·must· raise an error [overflow in duration arithmetic] in case of overflow.

9.2.1 xdt:yearMonthDuration

[Definition] xdt:yearMonthDuration is derived from xs:duration by restricting its lexical representation to contain only the year and month components. The value space of xdt:yearMonthDuration is the set of xs:integer month values. The year and month components of xdt:yearMonthDuration correspond to the Gregorian year and month components defined in section 5.5.3.2 of [ISO 8601], respectively.

xdt:yearMonthDuration is derived from xs:duration as follows.

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

9.2.2 xdt:dayTimeDuration

[Definition] xdt:dayTimeDuration is derived from xs:duration by restricting its lexical representation to contain only the days, hours, minutes and seconds components. The value space of xdt:dayTimeDuration is the set of fractional second values. The components of xdt:dayTimeDuration correspond to the day, hour, minute and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. xdt:dayTimeDuration is derived from xs:duration as follows. To make the long pattern easier to read, it has been formatted on six lines using additional new line and space characters in the pattern string. These additional characters should not be interpreted as part of the pattern.

<xs:simpleType name='dayTimeDuration'>
    <xs:restriction base='xs:duration'>
         <xs: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))"/>
    </xs:restriction>
</xs:simpleType>

9.3.1 op:yearMonthDuration-equal

Summary: Returns true if and only if $arg1 is equal to $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xdt:yearMonthDuration values.

9.3.2 op:yearMonthDuration-less-than

Summary: Returns true if and only if $arg1 is less than $arg2. Returns false otherwise.

This function backs up the "lt" and "ge" operators on xdt:yearMonthDuration values.

9.3.3 op:yearMonthDuration-greater-than

Summary: Returns true if and only if $arg1 is greater than $arg2. Returns false otherwise.

This function backs up the "gt" and "le" operators on xdt:yearMonthDuration values.

9.3.4 op:dayTimeDuration-equal

Summary: Returns true if and only if the value of $arg1 is equal to the value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xdt:dayTimeDuration values.

9.3.5 op:dayTimeDuration-less-than

Summary: Returns true if and only if $arg1 is less than $arg2. Returns false otherwise.

This function backs up the "lt" and "ge" operators on xdt:dayTimeDuration values.

9.3.6 op:dayTimeDuration-greater-than

Summary: Returns true if and only if $arg1 is greater than $arg2. Returns false otherwise.

This function backs up the "gt" and "le" operators on xdt:dayTimeDuration values.

9.3.7 op:dateTime-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:dateTime values.

9.3.8 op:dateTime-less-than

Summary: Returns true if and only if the normalized value of $arg1 is less than the normalized value of $arg2. Returns false otherwise.

This function backs up the "lt" and "ge" operators ond xs:dateTime values.

9.3.9 op:dateTime-greater-than

Summary: Returns true if and only if the normalized value of $arg1 is greater than the normalized value of $arg2. Returns false otherwise.

This function backs up the "gt" and "le" operators on xs:dateTime values.

9.3.10 op:date-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:date values.

9.3.11 op:date-less-than

Summary: Returns true if and only if the normalized value of $arg1 is less than the normalized value of $arg2. Returns false otherwise.

This function backs up the "lt" and "ge" operators on xs:date values.

9.3.12 op:date-greater-than

Summary: Returns true if and only if the normalized value of $arg1 is greater than the normalized value of $arg2. Returns false otherwise.

This function backs up the "gt" and "le" operators on xs:date values.

9.3.13 op:time-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:time values.

9.3.14 op:time-less-than

Summary: Returns true if and only if the normalized value of $arg1 is less than the normalized value of $arg2. Returns false otherwise.

This function backs up the "lt" and "ge" operators on xs:time values.

9.3.15 op:time-greater-than

Summary: Returns true if and only if the normalized value of $arg1 is greater than the normalized value of $arg2. Returns false otherwise.

This function backs up the "gt" and "le" operators on xs:time values.

9.3.16 op:gYearMonth-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:gYearMonth values.

9.3.17 op:gYear-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:gYear values.

9.3.18 op:gMonthDay-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:gMonthDay values.

9.3.19 op:gMonth-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:gMonth values.

9.3.20 op:gDay-equal

Summary: Returns true if and only if the normalized value of $arg1 is equal to the normalized value of $arg2. Returns false otherwise.

This function backs up the "eq" and "ne" operators on xs:gDay values.

9.4.1 fn:get-years-from-yearMonthDuration

Summary: Returns an xs:integer representing the years component in the canonical lexical representation of the value of $arg. The result may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.2 fn:get-months-from-yearMonthDuration

Summary: Returns an xs:integer representing the months component in the canonical lexical representation of the value of $arg. The result may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.3 fn:get-days-from-dayTimeDuration

Summary: Returns an xs:integer representing the days component in the canonical lexical representation of the value of $arg. The result may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.4 fn:get-hours-from-dayTimeDuration

Summary: Returns an xs:integer representing the hours component in the canonical lexical representation of the value of $arg. The result may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.5 fn:get-minutes-from-dayTimeDuration

Summary: Returns an xs:integer representing the minutes component in the canonical lexical representation of the value of $arg. The result may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.6 fn:get-seconds-from-dayTimeDuration

Summary: Returns an xs:decimal representing the seconds component in the canonical lexical representation of the value of $arg. The result may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.7 fn:get-year-from-dateTime

Summary: Returns an xs:integer representing the year component in the localized value of $arg. The result may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.8 fn:get-month-from-dateTime

Summary: Returns an xs:integer between 1 and 12, both inclusive, representing the month component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.9 fn:get-day-from-dateTime

Summary: Returns an xs:integer between 1 and 31, both inclusive, representing the day component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.10 fn:get-hours-from-dateTime

Summary: Returns an xs:integer between 0 and 23, both inclusive, representing the hours component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.11 fn:get-minutes-from-dateTime

Summary: Returns an xs:integer value between 0 and 59, both inclusive, representing the minute component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.12 fn:get-seconds-from-dateTime

Summary: Returns an xs:decimal value between 0 and 60.999..., both inclusive representing the seconds and fractional seconds in the localized value of $arg. Note that the value can be greater than 60 seconds to accomodate occasional leap seconds used to keep human time synchronized with the rotation of the planet.

If $arg is the empty sequence, returns the empty sequence.

9.4.13 fn:get-timezone-from-dateTime

Summary: Returns the timezone component of $arg. The result is an xdt:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive.

.If $arg is the empty sequence, returns the empty sequence.

9.4.14 fn:get-year-from-date

Summary: Returns an xs:integer representing the year in the localized value of $arg. The value may be negative.

If $arg is the empty sequence, returns the empty sequence.

9.4.15 fn:get-month-from-date

Summary: Returns an xs:integer between 1 and 12, both inclusive, representing the month component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.16 fn:get-day-from-date

Summary: Returns an xs:integer between 1 and 31, both inclusive, representing the day component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.17 fn:get-timezone-from-date

Summary: Returns the timezone component in the value of $arg. The result is an xdt:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive.

If $arg is the empty sequence, returns the empty sequence.

9.4.18 fn:get-hours-from-time

Summary: Returns an xs:integer between 0 and 23, both inclusive, representing the value of the hours component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.19 fn:get-minutes-from-time

Summary: Returns an xs:integer value between 0 to 59, both inclusive, representing the value of the minutes component in the localized value of $arg.

If $arg is the empty sequence, returns the empty sequence.

9.4.20 fn:get-seconds-from-time

Summary: Returns an xs:decimal value between 0 and 60.999..., both inclusive, representing the seconds and fractional seconds in the localized value of $arg. Note that the value can be greater than 60 seconds to accomodate occassional leap seconds used to keep human time synchronized with the rotation of the planet.

If $arg is the empty sequence, returns the empty sequence.

9.4.21 fn:get-timezone-from-time

Summary: Returns an xdt:dayTimeDuration representing the timezone component of $arg. The result is a xdt:dayTimeDuration that indicates deviation from UTC; its value may range from +14:00 to -14:00 hours, both inclusive.

If $arg is the empty sequence, returns the empty sequence.

9.5.1 op:add-yearMonthDurations

Summary: Returns the result of adding the value of $arg1 to the value of $arg2. Backs up the "+" operator on xdt:yearMonthDuration values.

9.5.2 op:subtract-yearMonthDurations

Summary: Returns the result of subtracting the value of $arg2 from the value of $arg2. Backs up the "-" operator on xdt:yearMonthDuration values.

9.5.3 op:multiply-yearMonthDuration

Summary: Returns the result of multiplying the value of $arg1 by $arg2. The result is rounded to the nearest month. For a value v, 0 <= v < 0.5 rounds to 0; 0.5 <= v < 1.0 rounds to 1.

If $arg2 is positive or negative zero, the result is a zero-length duration. If $arg2 is positive or negative infinity, the result overflows and is handled as discussed in 9.1.1 Limits and Precision. If $arg2 is NaN an error is raised [NaN supplied as float/double value]

Backs up the "*" operator on xdt:yearMonthDuration values.

9.5.4 op:divide-yearMonthDuration

Summary: Returns the result of dividing the value of $arg1 by $arg2. The result is rounded to the nearest month. For a value v, 0 <= v < 0.5 rounds to 0; 0.5 <= v < 1.0 rounds to 1.

If $arg2 is positive or negative infinity, the result is a zero-length duration. If $arg2 is positive or negative zero, the result overflows and is handled as discussed in 9.1.1 Limits and Precision. If $arg2 is NaN an error is raised [NaN supplied as float/double value]

Backs up the "div" operator on xdt:yearMonthDuration values.

9.5.5 op:add-dayTimeDurations

Summary: Returns the result of adding the value of $arg1 to the value of $arg2. Backs up the "+" operator on xdt:dayTimeDuration values.

9.5.6 op:subtract-dayTimeDurations

Summary: Returns the result of subtracting the value of $arg2 from the value of $arg2. Backs up the "-" operator on xdt:dayTimeDuration values.

9.5.7 op:multiply-dayTimeDuration

Summary: Returns the result of multiplying the value of $arg1 by $arg2.

If $arg2 is positive or negative zero, the result is a zero-length duration. If $arg2 is positive or negative infinity, the result overflows and is handled as discussed in 9.1.1 Limits and Precision. If $arg2 is NaN an error is raised [NaN supplied as float/double value]

Backs up the "*" operator on xdt:dayTimeDuration values.

9.5.8 op:divide-dayTimeDuration

Summary: Returns the result of dividing the value of $arg1 by $arg2.

If $arg2 is positive or negative infinity, the result is a zero-length duration. If $arg2 is positive or negative zero, the result overflows and is handled as discussed in 9.1.1 Limits and Precision. If $arg2 is NaN an error is raised [NaN supplied as float/double value]

Backs up the "div" operator on xdt:dayTimeDuration values.

9.6.1 fn:adjust-dateTime-to-timezone

Summary: Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all. If $timezone is the empty sequence, returns an xs:dateTime without a timezone. Otherwise, returns an xs:dateTime with a timezone.

If $timezone is not specified, then $timezone is the value of the implicit timezone in the evaluation context.

If $arg is the empty sequence, then the result is the empty sequence.

A dynamic error is raised (invalid timezone value) if $timezone is less than -PT14H00M or greater than PT14H00M.

If $arg does not have a timezone component and $timezone is the empty sequence, then the result is $arg.

If $arg does not have a timezone component and $timezone is not the empty sequence, then the result is $arg with $timezone as the timezone component.

If $arg has a timezone component and $timezone is the empty sequence, then the result is the localized value of $arg without its timezone component.

If $arg has a timezone component and $timezone is not the empty sequence, then the result is an xs:dateTime value with a timezone component of $timezone that is equal to $arg.

9.6.2 fn:adjust-date-to-timezone

Summary: Adjusts an xs:date value to a specific timezone, or to no timezone at all. If $timezone is the empty sequence, returns an xs:date without a timezone. Otherwise, returns an xs:date with a timezone. For purposes of timezone adjustment, an xs:date is treated as an xs:dateTime with time 00:00:00.

If $timezone is not specified, then $timezone is the value of the implicit timezone in the evaluation context.

If $arg is the empty sequence, then the result is the empty sequence.

A dynamic error is raised (invalid timezone value) if $timezone is less than -PT14H00M or greater than PT14H00M.

If $arg does not have a timezone component and $timezone is the empty sequence, then the result is the value of $arg.

If $arg does not have a timezone component and $timezone is not the empty sequence, then the result is $arg with $timezone as the timezone component.

If $arg has a timezone component and $timezone is the empty sequence, then the result is the localized value of $arg without its timezone component.

If $timezone is not the empty sequence, then the result is $arg with $timezone as its timezone component.

9.6.3 fn:adjust-time-to-timezone

Summary: Adjusts an xs:time value to a specific timezone, or to no timezone at all. If $timezone is the empty sequence, returns an xs:time without a timezone. Otherwise, returns an xs:time with a timezone.

If $timezone is not specified, then $timezone is the value of the implicit timezone in the evaluation context.

If $arg is the empty sequence, then the result is the empty sequence.

A dynamic error is raised (invalid timezone value) if $timezone is less than -PT14H00M or greater than PT14H00M.

If $arg does not have a timezone component and $timezone is the empty sequence, then the result is $arg.

If $arg does not have a timezone component and $timezone is not the empty sequence, then the result is $arg with $timezone as the timezone component.

If $arg has a timezone component and $timezone is the empty sequence, then the result is the localized value of $arg without its timezone component.

If $arg has a timezone component and $timezone is not the empty sequence, then:

• Let $srcdt be an xs:dateTime value, with an arbitrary date for the date component and time and timezone components that are the same as the time and timezone components of $arg.

• Let $r be the result of evaluating

  fn:adjust-dateTime-to-timezone($srcdt, $timezone)

• The result of this function will be a time value that has time and timezone components that are the same as the time and timezone components of $r.

9.7.1 fn:subtract-dateTimes-yielding-yearMonthDuration

Summary: Returns the xdt:yearMonthDuration that corresponds to the difference between the normalized value of $arg1 and the normalized value of $arg2. In general, the difference between two xs:dateTime values will be a duration that contains years and months as well as days, hours, etc. In fact, it can be looked at as an xdt:yearMonthDuration plus an xdt:dayTimeDuration. This function returns the result rounded to contain only years and months. The calculation is as follows: first the duration is calculated as the value of an xdt:dayTimeDuration in seconds. Then, starting from $arg2, the maximum number of months in the duration are calculated. If there is a remaining number of days, they are discarded.

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

If the normalized value of $arg1 precedes in time the normalized value of $arg2, the returned value is a negative duration.

9.7.2 fn:subtract-dateTimes-yielding-dayTimeDuration

Summary: Returns the xdt:dayTimeDuration that corresponds to the difference between the normalized value of $arg1 and the normalized value of $arg2.

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

If the normalized value of $arg1 precedes in time the normalized value of $arg2, then the returned value is a negative duration.

9.7.3 op:subtract-dates

Summary: Returns the xdt:dayTimeDuration that corresponds to the difference between the normalized value of $arg1 and the normalized value of $arg2.

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

If the normalized value of $arg1 precedes in time the normalized value of $arg2, then the returned value is a negative duration.

Backs up the subtract, "-", operator on xs:date values.

9.7.4 op:subtract-times

Summary: Returns the xdt:dayTimeDuration that corresponds to the difference between the normalized value of $arg1 and the normalized value of $arg2.

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

If the normalized value of $arg1 precedes in time the normalized value of $arg2, then the returned value is a negative duration.

Backs up the subtract, "-", operator on xs:time values.

9.7.5 op:add-yearMonthDuration-to-dateTime