XQuery 1.0 and XPath 2.0 Functions and Operators

5.2.1 op:numeric-add

Backs up the "+" operator and returns the arithmetic sum of its operands: ($operand1 + $operand2).

5.2.2 op:numeric-subtract

Backs up the "-" operator and returns the arithmetic difference of its operands: ($operand1 - $operand2).

5.2.3 op:numeric-multiply

Backs up the "*" operator and returns the arithmetic product of its operands: ($operand1 * $operand2).

5.2.4 op:numeric-divide

Backs up the "div" operator and returns the arithmetic quotient of its operands: ($operand1 div $operand2).

For xs:decimal and xs:integer operands, if the divisor is 0, then an error is raised ("Division by zero"). For xs:float and xs:double operands, performs floating point division as specified in [IEEE 754-1985].

5.2.5 op:numeric-integer-divide

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

If the divisor is 0, then an error is raised ("Division by zero").

5.2.6 op:numeric-mod

Backs up the "mod" operator and returns the remainder after dividing the first operand by the second operand: ($operand1 mod $operand2). The result is of the same type as the operands after type promotion. The following rules apply:

• For xs:decimal and xs:integer operands, if the divisor is 0, then an error is raised ("Division by zero").

• For xs:float and xs:double operands:

  • 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 not NaN, the sign of the result equals the sign of the dividend.

  • 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 float or double remainder r from a dividend n and a divisor d is defined by the mathematical relation r = n-(d * q) where q is an integer that is negative only if n/d is negative and positive only if n/d is positive, and whose magnitude is as large as possible without exceeding the magnitude of the true mathematical quotient of n and d. This is truncating division, analogous to integer division, not [IEEE 754-1985] rounding division.

5.2.7 op:numeric-unary-plus

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

5.2.8 op:numeric-unary-minus

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

5.3.1 op:numeric-equal

Returns true if and only if $operand1 is exactly equal to $operand2. For xs:float and xs:double values, 0 (zero), +0 (positive zero), and -0 (negative zero) all compare equal. NaN does not equal itself.

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

5.3.2 op:numeric-less-than

Returns true if and only if $operand1 is less than $operand2. 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. NaN is not comparable with (neither greater than nor less than) any other value including itself.

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

5.3.3 op:numeric-greater-than

Returns true if and only if $operand1 is greater than $operand2. 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. NaN is not comparable with (neither greater than nor less than) any other value including itself.

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

5.4.1 xf:floor

Returns the largest (closest to positive infinity) integer that is not greater than the value of $srcval. If the argument is the empty sequence, returns the empty sequence.

5.4.2 xf:ceiling

Returns the smallest (closest to negative infinity) integer that is not smaller than the value of $srcval. If the argument is the empty sequence, returns the empty sequence.

5.4.3 xf:round

Returns the number 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, xf:round(x) produces the same result as xf:floor(x+0.5). If the argument is NaN, then NaN is returned. If the argument is positive infinity, then positive infinity is returned. If the argument is negative infinity, then negative infinity is returned. 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. If the argument is the empty sequence, then the empty sequence is returned.

6.2.1 xf:compare

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 6.2 Equality and Comparison of Strings.

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 characters 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 characters following that beginning string, then the result is 1.

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

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

6.3.1 xf: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.3.2 xf: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.2 Equality and Comparison of Strings.

6.3.3 xf: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.2 Equality and Comparison of Strings.

6.3.4 xf: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.2 Equality and Comparison of Strings.

6.3.5 xf: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:

xf:round($startingLoc) <= $p < xf:round($startingLoc + $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 $startingLoc is negative or greater than the length of $sourceString, then an error is raised ("Invalid substring starting argument").

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

6.3.6 xf: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.3.7 xf: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.2 Equality and Comparison of Strings.

6.3.8 xf: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.2 Equality and Comparison of Strings.

6.3.9 xf: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.3.10 xf: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.3.11 xf: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.3.12 xf: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.3.13 xf: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.3.14 xf: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.3.15 xf: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.3.15.1 Regular Expression Syntax.

6.3.16 xf: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 xf: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.3.15.1 Regular Expression Syntax.

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

6.3.17 xf: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 xf: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.3.18 xf:escape-uri

This function applies the URI escaping rules defined in section 2 of [RFC 2396] 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] as reserved characters 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.1.1 xf:true

Returns the boolean value true.

7.1.2 xf:false

Returns the boolean value false.

7.2.1 op:boolean-equal

The arguments and return type are all boolean. The result is true if both arguments are true or if both arguments are false. The result is false if one of the arguments is true and the other argument is false.

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

7.2.2 op:boolean-less-than

Returns true if $srcval1 is false and $srcval2 is true. Otherwise, returns false.

This function backs up the "lt" operator on boolean values.

7.2.3 op:boolean-greater-than

Returns true if $srcval1 is true and $srcval2 is false. Otherwise, returns false.

This function backs up the "gt" operator on boolean values.

7.3.1 xf:not

$srcval is first reduced to an effective boolean value as defined in [XQuery 1.0: An XML Query Language].

Returns true if the effective boolean value is false, and false if the effective boolean value is true.

8.2.1 yearMonthDuration

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

yearMonthDuration is derived from duration as follows:

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

8.2.2 dayTimeDuration

[Definition:] dayTimeDuration is derived from duration by restricting its lexical representation to contain only the day, hour, minute, and second components. The value space of dayTimeDuration is the set of fractional second values. The components of dayTimeDuration correspond to the day, hour, minute and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. dayTimeDuration is derived from duration as follows:

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

8.3.1 op:duration-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.3.2 op:yearMonthDuration-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.3.3 op:yearMonthDuration-less-than

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

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

8.3.4 op:yearMonthDuration-greater-than

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

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

8.3.5 op:dayTimeDuration-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.3.6 op:dayTimeDuration-less-than

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

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

8.3.7 op:dayTimeDuration-greater-than

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

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

8.3.8 op:dateTime-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the dateTime data type is defined by section 3.2.7.3, "Order relation on dateTime", of [XML Schema Part 2: Datatypes].

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

8.3.9 op:dateTime-less-than

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the dateTime data type is defined by section 3.2.7.3, "Order relation on dateTime", of [XML Schema Part 2: Datatypes].

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

8.3.10 op:dateTime-greater-than

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the dateTime data type is defined by section 3.2.7.3, "Order relation on dateTime", of [XML Schema Part 2: Datatypes].

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

8.3.11 op:date-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the date data type is defined by section 3.2.7.3, "Order relation on dateTime", and section 3.2.9, "date", of [XML Schema Part 2: Datatypes].

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

8.3.12 op:date-less-than

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the date data type is defined by section 3.2.7.3, "Order relation on dateTime", and section 3.2.9, "date", of [XML Schema Part 2: Datatypes].

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

8.3.13 op:date-greater-than

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the date data type is defined by section 3.2.7.3, "Order relation on dateTime", and section 3.2.9, "date", of [XML Schema Part 2: Datatypes].

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

8.3.14 op:time-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the date data type is defined by section 3.2.7.3, "Order relation on dateTime", and section 3.2.8, "time", of [XML Schema Part 2: Datatypes].

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

8.3.15 op:time-less-than

Returns true if and only if $operand1 is less than $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the date data type is defined by section 3.2.7.3, "Order relation on dateTime", and section 3.2.8, "time", of [XML Schema Part 2: Datatypes].

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

8.3.16 op:time-greater-than

Returns true if and only if $operand1 is greater than $operand2. Returns false otherwise.

If either $operand1 or $operand2 is a value that does not contain a timezone, then for the purposes of this operation the Implicit Timezone is considered to be present in the value. The ordering of the date data type is defined by section 3.2.7.3, "Order relation on dateTime", and section 3.2.8, "time", of [XML Schema Part 2: Datatypes].

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

8.3.17 op:gYearMonth-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.3.18 op:gYear-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.3.19 op:gMonthDay-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.3.20 op:gMonth-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.3.21 op:gDay-equal

Returns true if and only if $operand1 is exactly equal to $operand2. Returns false otherwise.

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

8.4.1 xf:get-years-from-yearMonthDuration

Returns an integer representing the years component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.2 xf:get-months-from-yearMonthDuration

Returns an integer representing the months component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.3 xf:get-days-from-dayTimeDuration

Returns an integer representing the days component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.4 xf:get-hours-from-dayTimeDuration

Returns an integer representing the hours component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.5 xf:get-minutes-from-dayTimeDuration

Returns an integer representing the minutes component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.6 xf:get-seconds-from-dayTimeDuration

Returns a decimal number representing the seconds component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.7 xf:get-year-from-dateTime

Returns an integer representing the year component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.8 xf:get-month-from-dateTime

Returns an integer representing the month component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.9 xf:get-day-from-dateTime

Returns an integer representing the day component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.10 xf:get-hours-from-dateTime

Returns an integer representing the hours value identified in the value of $srcval. The hours value ranges from 0 to 23, inclusive. If $srcval is the empty sequence, returns the empty sequence.

8.4.11 xf:get-minutes-from-dateTime

Returns an integer value representing the minute identified in the value of $srcval. The minute value ranges from 0 to 59, inclusive. If $srcval is the empty sequence, returns the empty sequence.

8.4.12 xf:get-seconds-from-dateTime

Returns a decimal value representing the seconds and fractional seconds identified in the value of $srcval. The value ranges from 0 to 60.999..., inclusive. The number of digits of fractional seconds precision is determined by the relevant facet of the argument. 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 $srcval is the empty sequence, returns the empty sequence.

8.4.13 xf:get-timezone-from-dateTime

Returns a string representing the timezone component of $srcval. The result is a duration in "hh:mm" format with an optional leading minus (-) sign, indicating the deviation from GMT (UTC). If $srcval does not contain a timezone, the result is the empty sequence. If $srcval is the empty sequence, returns the empty sequence.

[Issue 110: No timezone: Empty sequence or zero-length string?]

[Issue 137: Should functions that return timezones return a duration?]

8.4.14 xf:get-year-from-date

Returns an integer representing the year in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.15 xf:get-month-from-date

Returns an integer representing the month component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.16 xf:get-day-from-date

Returns an integer representing the day component in the value of $srcval. If $srcval is the empty sequence, returns the empty sequence.

8.4.17 xf:get-timezone-from-date

Returns a string representing the timezone component of $srcval. The result is a duration in "hh:mm" format with an optional leading minus (-) sign, indicating the deviation from GMT (UTC). If $srcval does not contain a timezone, the result is the empty sequence. If $srcval is the empty sequence, returns the empty sequence.

8.4.18 xf:get-hours-from-time

Returns an integer representing the hours value identified in the value of $srcval. The hours value ranges from 0 to 23, inclusive. If $srcval is the empty sequence, returns the empty sequence.

8.4.19 xf:get-minutes-from-time

Returns an integer value representing the minute identified in the value of $srcval. The minute value ranges from 0 to 59, inclusive. If $srcval is the empty sequence, returns the empty sequence.

8.4.20 xf:get-seconds-from-time

Returns a decimal value representing the seconds and fractional seconds identified in the value of $srcval. The value ranges from 0 to 60.999..., inclusive. The number of digits of fractional seconds precision is determined by the relevant facet of the argument. 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 $srcval is the empty sequence, returns the empty sequence.

8.4.21 xf:get-timezone-from-time

Returns a string representing the timezone component of $srcval. The result is a duration in "hh:mm" format with an optional leading minus (-) sign, indicating the deviation from GMT (UTC). If $srcval does not contain a timezone, the result is the empty sequence. If $srcval is the empty sequence, returns the empty sequence.

8.5.1 op:add-yearMonthDurations

Returns the result of adding the value of $srcval1 to the value of $srcval2. Backs up the "+" operator on yearMonthDuration values.

8.5.2 op:subtract-yearMonthDurations

Returns the result of subtracting the value of $srcval2 from the value of $srcval2. Backs up the "-" operator on yearMonthDuration values.

8.5.3 op:multiply-yearMonthDuration

Returns the result of multiplying the value of $srcval1 by $srcval2. 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.

Backs up the "*" operator on yearMonthDuration values.

8.5.4 op:divide-yearMonthDuration

Returns the result of dividing the value of $srcval1 by $srcval2. 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.

Backs up the "div" operator on yearMonthDuration values.

8.5.5 op:add-dayTimeDurations

Returns the result of adding the value of $srcval1 to the value of $srcval2. Backs up the "+" operator on dayTimeDuration values.

8.5.6 op:subtract-dayTimeDurations

Returns the result of subtracting the value of $srcval2 from the value of $srcval2. Backs up the "-" operator on dayTimeDuration values.

8.5.7 op:multiply-dayTimeDuration

Returns the result of multiplying the value of $srcval1 by $srcval2. Backs up the "*" operator on dayTimeDuration values.

8.5.8 op:divide-dayTimeDuration

Returns the result of dividing the value of $srcval1 by $srcval2. The result is rounded to the nearest month. Backs up the "div" operator on dayTimeDuration values.

8.6.1 xf: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 xf: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 xf: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 xf: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 xf: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 xf: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 xf: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 xf: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 xf: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 xf: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.1 xf:get-yearMonthDuration-from-dateTimes

Returns the yearMonthDuration that corresponds to the difference between the value of $srcval1 and the value of $srcval2. If the value of $srcval1 follows in time the value of $srcval2, then the returned value is a negative duration. If one or both arguments do not have a timezone they are assigned an implicit ·implementation-defined· timezone. If either argument is the empty sequence, returns the empty sequence.

In general, the difference between two 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 a yearMonthDuration plus a 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 a dayTimeDuration in seconds. Then, starting from $srcval2, the maximum number of months in the duration are calculated. The remainder r is is rounded and added to the number of months. If 0 <= r < 15.5 days, r rounds to 0 months; if 15.5 days <= r, r rounds to 1 month.

8.7.2 xf:get-dayTimeDuration-from-dateTimes

Returns the dayTimeDuration that corresponds to the difference between the value of $srcval1 and the value of $srcval2. If the value of $srcval1 follows in time the value of $srcval2, then the returned value is a negative duration. If one or both arguments do not have a timezone they are assigned an implicit ·implementation-defined· timezone. If either argument is the empty sequence, returns the empty sequence.

This function returns the value of a dayTimeDuration in seconds. Note that the number of days in this value can be greater than 31.

8.7.3 op:subtract-dates

Returns the dayTimeDuration that corresponds to the difference between the value of $srcval1 and the value of $srcval2. If the value of $srcval1 follows in time the value of $srcval2, then the returned value is a negative duration. If one or both arguments do not have a timezone, they are assigned an implicit ·implementation-defined· timezone. If either argument is the empty sequence, returns the empty sequence.

This function returns the value of a dayTimeDuration in seconds. Note that the number of days in this value can be greater than 31.

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

8.7.4 op:subtract-times

Returns the dayTimeDuration that corresponds to the difference between the value of $srcval1 and the value of $srcval2. If the value of $srcval1 follows in time the value of $srcval2, then the returned value is a negative duration. If one or both arguments do not have a timezone, they are assigned an implicit ·implementation-defined· timezone. If either argument is the empty sequence, returns the empty sequence.

This function returns the value of a dayTimeDuration in seconds.

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

8.7.5 op:add-yearMonthDuration-to-dateTime

Returns the end of a time period by adding a yearMonthDuration ($srcval2) to the dateTime that starts the period ($srcval1). If the duration is negative, then the "end" of the period precedes the "start" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on dateTime and yearMonthDuration.

8.7.6 op:add-dayTimeDuration-to-dateTime

Returns the end of a time period by adding a dayTimeDuration ($srcval2) to the dateTime that starts the period ($srcval1). If the duration is negative, then the "end" of the period precedes the "start" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on dateTime and dayTimeDuration.

8.7.7 op:subtract-yearMonthDuration-from-dateTime

Returns the start of a time period by subtracting a yearMonthDuration ($srcval2) from the dateTime that ends the period ($srcval1). If the duration is negative, then the "start" of the period precedes the "end" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on dateTime and yearMonthDuration.

8.7.8 op:subtract-dayTimeDuration-from-dateTime

Returns the start of a time period by subtracting a dayTimeDuration ($srcval2) from the dateTime that ends the period ($srcval1). If the duration is negative, then the "start" of the period precedes the "end" of the period.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on dateTime and dayTimeDuration.

8.7.9 op:add-yearMonthDuration-to-date

Returns the date computed by adding the yearMonthDuration in $srcval2 to the date in $srcval1. If the duration is negative, then the result date precedes $srcval1.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on date and yearMonthDuration.

8.7.10 op:add-dayTimeDuration-to-date

Returns the date computed by adding the days component of the canonical representation of the dayTimeDuration in $srcval2 to the date in $srcval1.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on date and dayTimeDuration.

8.7.11 op:subtract-yearMonthDuration-from-date

Returns the date computed by subtracting the yearMonthDuration in $srcval2 from the date in $srcval. If the duration is negative, then the result date follows $srcval1.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on date and yearMonthDuration.

8.7.12 op:subtract-dayTimeDuration-from-date

Returns the date computed by subtracting the days component of the canonical representation of the dayTimeDuration in $srcval2 from the date in $srcval1. If the duration is negative, then the result date follows $srcval1

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on date and dayTimeDuration.

8.7.13 op:add-dayTimeDuration-to-time

First, the days component of $srcval2 is set to zero (0) and the value of the resulting duration is calculated. This value is added to $parameter1 and the result returned.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "+" operator on time and dayTimeDuration.

8.7.14 op:subtract-dayTimeDuration-from-time

First, the days component of $srcval2 is set to zero (0) and the value of the resulting duration is calculated. This value is subtracted from $srcval1 and the result returned.

The result has the same timezone as srcval1. If srcval1 has no timezone the result has no timezone.

This functions backs up the "-" operator on time and dayTimeDuration.

9.1.1 xf:expanded-QName

Returns a QName with the namespace URI given in $paramURI and the local name in $paramLocal.

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 xf: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 xf: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.1.1 xf:resolve-uri

This functions expects $base to be an absolute URI and $relative to be a relative URI. It resolves the relative URI $relative against the base URI $base and returns an absolute URI. Returns $relative if it is an absolute URI. If $base is a relative URI, then an error is raised ("Relative URI base argument to resolve-uri").

10.2.1 op:anyURI-equal

Returns true if $srcval1 and $srcval2 compare equal on a codepoint-by-codepoint basis. Else returns false. This function backs up the "eq" and "ne" operators on anyURI.

11.1.1 op:hex-binary-equal

Returns true if $value1 and value2 are of the same length and contain the same code-points. Otherwise, returns false.

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

11.1.2 op:base64-binary-equal

Returns true if $value1 and value2 are of the same length and contain the same code-points. Otherwise, returns false.

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

12.1.1 op:NOTATION-equal

Returns true if $srcval1 and $srcval2 compare equal on a codepoint-by-codepoint basis. Else returns false. This function backs up the "eq" and "ne" operators on NOTATION.

13.1.1 xf: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, or a text node), 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 by searching the namespace nodes for that element, or in the case of an attribute, the namespace nodes for the element that is the parent of the attribute. There will always be at least one such namespace node whose namespace URI matches the namespace URI of the node's expanded QName. The prefix is taken from one of these namespace nodes; if there are several, then the implementation may choose one of them arbitrarily (implementations have the option to record the original namespace prefix as part of the data associated with a node, but they are not required to do so). 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 xf: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 xf: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.

If the $srcval is neither an element nor an attribute node, or if it is an element or attribute node which has no QName or whose expanded QName (as determined by the name accessor in the data model) is in no namespace, then the function returns the zero-length string.

13.1.4 xf:number

Returns the value of the node indicated by $srcval or, if $srcval is not specified, the context node, converted to a double. If the string value of the node is not a valid lexical representation of a numeric simple type as defined in [XML Schema Part 2: Datatypes], then an error is raised ("Invalid lexical representation").

13.1.5 xf:lang

Returns true or false depending on whether the language of the context node, as defined using the xml:lang attribute, is the same as, or a sublanguage of, the language specified by $testlang.

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

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

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

Otherwise, the function returns true if and only if the string-value of the relevant xml:lang attribute is equal to $testlang ignoring case, or if the string-value of the relevant testlang attribute contains some hyphen (-) such that the part of the string-value preceding that hyphen is equal to $testlang, ignoring case.

13.1.6 op:node-equal

If the node identified by the value of $parameter1 is the same node as the node identified by the value of $parameter2 (that is, the two nodes have the same identity), then the function returns true; otherwise, the function returns false. This function backs up the "is" and "isnot" operators on nodes.

13.1.7 xf:deep-equal

This function tests whether the name and content of the node $parameter1 are the same as the name and content of the node $parameter2.

The following (recursive) tests are applied in order to determine whether two nodes are deep-equal.

If the two nodes are of different node-kinds, the result is false.

if (xf:node-kind($parameter1) ne xf:node-kind($parameter2)) 
then false
else

If the two nodes have names, and the names are different when compared as expanded-QNames, the result is false.

if (xf:node-name($parameter1) != xf:node-name($parameter2)) 
then false
else

If the two nodes are text nodes, comment nodes, processing instruction nodes, or namespace nodes, then the result is true if and only if the two nodes have equal string-values, when compared using the selected collation.

if (some $n in ("text", "comment", "processing-instruction", "namespace")
         satisfies $n eq xf:node-kind($parameter1)
    and xf:compare(xf:string($parameter1), xf:string($parameter2), $collation) ne 0)
then false
else

If either node has attributes, then the result is false if either node has an attribute that is not deep-equal to an attribute of the other node, using the selected collation.

if (some $a1 in $parameter1/@* satisfies
      not (some $a2 in $parameter2/@* 
           satisfies xf:deep-equal($a1, $a2, $collation))
    or some $a2 in $parameter2/@* satisfies
      not (some $a1 in $parameter1/@* 
           satisfies xf:deep-equal($a1, $a2, $collation)))
then false
else

If neither node has element children, then the result is true only if the other node also has simple content, and if the simple content of the two nodes (that is, the result of the xf:data function) is equal under the rules for the xf:sequence-deep-equal function, using the selected collation. (Note: attributes always have simple content.)

if (empty($parameter1/*) and empty($parameter2/*))
then xf:sequence-deep-equal( xf:data($parameter1),
                             xf:data($parameter2),
                             $collation )
else

Otherwise, the result is true if and only if the children of node $parameter1 are pairwise deep-equal to the children of node $parameter2, ignoring comment and processing instruction nodes in both cases.

xf:sequence-deep-equal( $parameter1/(* | text()),
                        $parameter2/(* | text()),
                        $collation )

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

13.1.8 op:node-before

If the node identified by the value of $parameter1 occurs in document order before the node identified by the value of $parameter2, this function returns true; otherwise, it returns false. The rules determining the order of nodes within a single document and in different documents can be found in [XQuery 1.0 and XPath 2.0 Data Model]. This function backs up the "<<" operator.

13.1.9 op:node-after

If the node identified by the value of $parameter1 occurs in document after the node identified by the value of $parameter2, this function returns true; otherwise, it returns false. The rules determining the order of nodes within a single document and in different documents can be found in [XQuery 1.0 and XPath 2.0 Data Model]. This function backs up the ">>" operator.

13.1.10 xf:copy

Returns a copy of the node that is the value of $srcval including all its attributes and descendants; the copy has a different identity than the node indicated by the value of $srcval.

[Issue 60: What are the precise semantics of the copy() function?]

   <family name='green'>
      <father>peter</father>
      <mother>mary<mother>
      <child>joseph</child>
   </family>

   <family name='green'>
      <father>peter</father>
      <mother>mary<mother>
      <child>joseph</child>
   </family>

13.1.11 xf:root

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

[Issue 162: Can we omit the node argument to root() and use the context item if it is omitted.]

13.2.1 xf:if-absent

If the first argument is the empty sequence, if-absent() returns the second argument; otherwise, it returns the content of the first argument.

13.2.2 xf:if-empty

If the first argument is the empty sequence or an element with empty content, if-empty() returns the second argument; otherwise, it returns the content of the first argument.

[Issue 155: The term 'empty content' should be changed or, at least, be carefully defined.]

[Issue 171: Do we need if-empty and if-absent functions?]

14.1.1 op:to

The effective values of $firstval and $lastval are computed as cast as integer(floor($firstval)) and cast as integer(floor($lastval)).

Converts both its operands to integers and returns the sequence containing every integer whose value is between the effective value of $firstval (inclusive) and the effective value of $lastval (inclusive), in monotonic order. If the effective value of the first operand is less than the effective value of the second, the sequence is in increasing order; otherwise, it is in decreasing order. If the effective value of the two operands is equal, a sequence containing a single integer equal to the effective value is returned.

This function backs up the "to" operator.

14.2.1 xf:boolean

Returns the effective boolean value of the argument as defined in [XQuery 1.0: An XML Query Language] (true if the effective boolean value is true, and false if the effective boolean value is false).

If fallback conversion is enabled, then the function is applied to the first item in the sequence. This is expected to be a value. If the first item in the sequence is a node, then its typed value is extracted. The value is converted to boolean as defined in 16.9 Casting to boolean .

14.2.2 op:concatenate

Returns a sequence consisting of the items in $seq1 followed by the items in $seq2. This function backs up the infix operator ",". If either sequence is the empty sequence, the other operand is returned.

14.2.3 xf:item-at

Returns the item in $seqParam that is located at the index that is the value of $posParam.

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

If the value of $posParam is greater than the number of items in the sequence, or is less than or equal to zero (0), then an error is raised ("Invalid position").

This function is used in the definition of the formal semantics of filter expressions, that is, expressions of the form expression-1[expression-2]

14.2.4 xf:index-of

If the value of $seqParam contains only simple values, then the function returns a sequence of unsigned integers indicating the indexes (positions) of items in the value of $seqParam that are equal to the simple value of $srchParam. If the data types of the simple values are strings, then equality is determined according to the collation that is used.

If the value of $seqParam contains nodes, then the function returns a sequence of unsigned integers indicating the indexes (positions) of nodes whose string values are equal to the string value of the node in the second argument. Equality of string values is determined according to the collation that is used.

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

The sequence must contain either simple values or nodes, not both. In addition, if the sequence contains simple values $srchParam must be a simple value and if the sequence contains nodes $srchParam must be a node. If the above conditions are violated, then an error is raised ("Mixed simple values and nodes").

If the value of $seqParam is the empty sequence, the empty sequence is returned.

The index is 1-based, not 0-based.

14.2.5 xf:empty

If the value of $srcval is the empty sequence, the function returns true; otherwise, the function returns false.

14.2.6 xf:exists

If the value of $srcval is not the empty sequence, the function returns true; otherwise, the function returns false.

14.2.7 xf:distinct-nodes

Returns the sequence that results from removing from $srcval all but one of a set of nodes that have the same identity as one another, based on node identity (that is, using node-equal()). The specific occurrence in a collection of identical nodes that is retained is implementation-dependent. If $srcval is the empty sequence, returns the empty sequence.

[Issue 154: Should we define a second order distinct function?]

14.2.8 xf:distinct-values

$srcval must contain either simple values or nodes, not both. If the sequence contains both simple values and nodes, then an error is raised ("Mixed simple values and nodes").

If $srcval contains only nodes, returns the sequence that results from removing from $srcval all but one of a set of nodes that are equal to one other, based on the nodes' values (that is, using deep-equal()). The specific node in a collection of nodes having equal values that is retained is implementation-dependent.

If $srcval contains only values, returns the sequence that results from removing from $srcval all but one of a set of values that are eq to one other. Values of the same type must have a total order: date/time values must either all contain a timezone or all not contain a timezone; duration values must all contain either only years and months or only days, hours, minutes and seconds. If this condition is not satisfied, then an error is raised ("Invalid duration value"). Equality of string values are determined according to the collation that is used. The specific node in a collection of values having equal values that is retained is implementation-dependent.

If $srcval 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.2 Equality and Comparison of Strings.

14.2.9 xf:insert

Returns a new sequence constructed from the value of $target with the value of $inserts inserted at the position specified by the value of $position. (The value of $target is not affected by the sequence construction.)

Let the effective value of $position be N computed as cast as unsignedInt(floor($position)).

If N is less than zero (0), the effective value of N is zero (0). If N is greater than the number of items in $target, then the effective value of N is equal to the number of items in $target plus 1.

The value returned by the function consists of all items of $target whose index is less than or equal to N, followed by all items of $inserts, followed by the remaining elements of $target, in that sequence.

If $target is the empty sequence, a copy of $inserts is returned. If $inserts is the empty sequence, a copy of $target is returned.

14.2.10 xf:remove

Returns a new sequence constructed from the value of $target with the item at the position specified by the value of $position removed.

Let the effective value of $position be N computed as cast as unsignedInt(floor($position)).

If N is less than 1 or greater than the number of items in $target, no action is taken. Otherwise, the value returned by the function consists of all items of $target whose index is less than N, followed by all items of $target whose index is greater than N. If $target is the empty sequence, the empty sequence is returned.

14.2.11 xf:subsequence

Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length.

If $length is not specified, then the subsequence includes items to the end of $sourceSeq.

The value of $length can be greater than the number of items in the value of $sourceSeq following the beginning position, in which case the subsequence includes items to the end of $length.

The first item of a sequence is located at position 1, not position 0.

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

14.3.1 xf:sequence-deep-equal

If the sequences that are the values of $parameter1 and $parameter2 have the same values (that is, they have the same number of items and items in corresponding positions in the two sequences compare equal if they are values and deep-equal() if they are nodes.), then the function returns true; otherwise, the function returns false. Returns the empty sequence if one or both of its arguments is the empty sequence.

String values are compared according to the collation that is used.

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

14.3.2 xf:sequence-node-equal

Returns the empty sequence if one or both of its arguments is the empty sequence.

If the sequences that are the values of $parameter1 and $parameter2 have the same nodes as content (that is, they have the same number of items and items in corresponding positions in the two sequences are the identical nodes), then the function returns true; otherwise, the function returns false.

14.3.3 op:union

Constructs a sequence containing every node that occurs in the values of $parameter1 or $parameter2, eliminating duplicate nodes. Nodes are returned in document order. Two nodes are equal if they are xf:node-equal().

This function backs up the "union" or "|" operator.

14.3.4 op:intersect

Constructs a sequence containing every node that occurs in the values of both $parameter1 and $parameter2, eliminating duplicate nodes. Nodes are returned in document order.

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

Two nodes are equal if they are xf:node-equal().

This function backs up the "intersect" operator.

14.3.5 op:except

Constructs a sequence containing every node that occurs in the values of $parameter1, but not in the value of $parameter2, eliminating duplicate nodes. Nodes are returned in document order.

If $parameter1 is the empty sequence, the empty sequence is returned. If $parameter2 is the empty sequence, a copy of $parameter1 is returned.

Two nodes are equal if they are xf:node-equal().

This function backs up the "except" operator.

14.4.1 xf:count

Returns the number of items in the value of $srcval. Returns 0 if $srcval is the empty sequence.

14.4.2 xf:avg

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If after this, $srcval contains only numbers, xf:avg() returns the average of the numbers (computed as sum($srcval) div count($srcval)). If $srcval is the empty sequence, the empty sequence is returned.

If, after extracting the values from nodes, $srcval does not contain only numbers, then an error is raised ("Argument not numeric").

14.4.3 xf:max

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If, after this, $srcval is the empty sequence, the empty sequence is returned. After extracting the values from nodes, $srcval must contain only values of a single type. (For numeric values, the type promotion rules defined in 5.2 Operators on Numeric Values are used to promote all values to a single common type.) In addition, the values in the sequence must have a total order. Date/time values must either all contain a timezone or all not contain a timezone. Duration values must either all be yearMonthDuration values or must all be dayTimeDuration values. If any of these conditions is not true, then an error is raised ("Invalid argument").

xf:max returns the item in the value of $srcval whose value is greater than or equal to the value of every other item in the value of $srcval. If there are two or more such items, then the specific item whose value is returned is implementation-dependent.

If the items in the value of $srcval are strings, then the determination of the greatest item is made according to the collation that is used.

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

14.4.4 xf:min

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If, after this, $srcval is the empty sequence, the empty sequence is returned. After extracting the values from nodes, $srcval must contain only values of a single type. (For numeric values, the type promotion rules defined in 5.2 Operators on Numeric Values are used to promote all values to a single common type.) In addition, the values in the sequence must have a total order. Date/time values must either all contain a timezone or all not contain a timezone. Duration values must either all be yearMonthDuration values or must all be dayTimeDuration values. If any of these conditions is not true, then an error is raised ("Invalid argument").

xf:min returns the item in the value of $srcval whose value is less than or equal to the value of every other item in the value of $srcval. If there are two or more such items, then the specific item whose value is returned is implementation-dependent.

If the items in the value of $srcval are strings, then the determination of the least item is made according to the collation that is used.

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

14.4.5 xf:sum

If $srcval contains nodes, the value of each node is extracted using the xf:data() function. Values that equal the empty sequence are discarded. If, after this, $srcval contains only numbers, xf:sum returns the sum of the numbers. If $srcval is the empty sequence, then 0.0 is returned.

If, after extracting the values from nodes, $srcval does not contain only numbers, then an error is raised ("Non-numeric values").

14.5.1 xf:id

Returns the sequence of element nodes with ID values matching the value of one of the IDREFs in the sequence argument. If the value of $srcval is a single IDREF, it behaves as though a sequence of length one was supplied.

The nodes that are returned all belong to the context document. See 15.4 op:context-document. If the context document is not specified, then an error is raised ("No context document"). If the context document is the empty sequence, returns the empty sequence.

[Issue 168: For compatibility with the XPath 1.0 function of the same name, xf:id() should accept a list of strings.]

14.5.2 xf:idref

Returns the sequence of elements nodes having either an IDREF attribute whose value matches the value of one of the items in the value of $srcval or an IDREFS attribute whose value contains an IDREF value that matches the value of one of the items in the value of $srcval. This function allows reverse navigation from IDs to IDREFs.

The nodes that are returned all belong to the context document. See 15.4 op:context-document. If the context document is not specified, then an error is raised ("No context document"). If the context document is the empty sequence, returns the empty sequence.

14.5.3 xf:document

If $srcval2 is the empty sequence, or a sequence whose first item is not a node, unless all the URIs in $srcval1 are absolute URIs, then an error is raised ("Invalid arguments to document function"). If $srcval2 is a sequence of more than one node, the effect is as if only the first node in the sequence were supplied.

Two documents are treated as the same document if they are identified by the same URI. The URI used for the comparison is the absolute URI into which any relative URI was resolved and does not include any fragment identifier. Thus, the following expression (if it does not cause an error) will always be true:

document("foo.xml") is document("foo.xml")

The result of the document function can be explained in terms of an internal primitive function one-doc, which takes a requested URI and a base URI as arguments and returns a node sequence as its result. The result of the document function is the union of the node sequences obtained by calling one-doc once for each member of $srcval1.

The one-doc function retrieves a document using a request URI R and a base URI B.

For a member of $srcval1 that is a node N, the one-doc function is called with the string-value of N as the request URI and the effective base URI of $srcval2 if $srcval2 is supplied. If srcval2 is not supplied, the base URI is the effective base URI of N.

For a member of $srcval1 that is a simple value, the one-doc function is called using a request URI obtained by converting the simple value to a string as if by using the string function, and the effective base URI of $srcval2 if $srcval2 is supplied. If srvcal2 is not supplied, the base URI is obtained from the static context.

The effective base URI of a node is defined to be the base URI of the node (as defined in [XQuery 1.0 and XPath 2.0 Data Model] in the case of document nodes and element nodes, and the base URI of the parent of the node for any other kind of node. If the node is not a document or element node and has no parent, then an error is raised ("Invalid arguments to document function").

The internal one-doc function operates as follows.

The resource identified by the URI is retrieved. The data resulting from the retrieval action is parsed as an XML document and a tree is constructed in accordance with the [XQuery 1.0 and XPath 2.0 Data Model]. An error retrieving the resource is classed as a dynamic error. In such cases, either an error is raised ("Error retrieving resource"), or the processor must recover by returning an empty sequence. One possible kind of retrieval error is that the implementation does not support the URI scheme used by the URI. An implementation is not required to support any particular URI schemes. The documentation for an implementation should specify which URI schemes the implementation supports.

If the URI reference does not contain a fragment identifier, then the document node of the document is returned. If the URI reference does contain a fragment identifier, the function returns a node sequence containing the nodes in the tree identified by the fragment identifier of the URI reference. The semantics of the fragment identifier are dependent on the media type of the result of retrieving the URI. An error in processing the fragment identifier is classed as a dynamic error. In such cases, then an error is raised ("Error processing fragment identifier"), or the processor must recover by returning an empty sequence. Possible errors include:

• The fragment identifier identifies something that cannot be represented by a node sequence (such as a range of characters within a text node).

• The implementation does not support fragment identifiers for the media-type of the retrieval result. An implementation is not required to support any particular media types. The documentation for an implementation should specify for which media types the implementation supports fragment identifiers.

The data resulting from the retrieval action is parsed as an XML document regardless of the media type of the retrieval result; if the top-level media type is text, then it is parsed in the same way as if the media type were text/xml; otherwise, it is parsed in the same way as if the media type were application/xml.

14.5.4 xf:collection

Takes a string as argument and returns a sequence of nodes obtained by casting $srcval to anyURI and resolving it. If $srcval is not in the lexical space of anyURI or if the value, after casting, does not resolve to a collection, then an error is raised ("Invalid argument to collection function").

14.5.5 xf:input

Returns the input sequence. If no input sequence has been assigned, then an error is raised ("No input sequence"). The means by which an input sequence is assigned depends on the environment.

15.5.1 Examples

• xf:current-dateTime() returns a dateTime corresponding to the current date and time. For example, an invocation of xf:current-dateTime() might return 2002-05-12T18:17:00Z.

15.6.1 Examples

• xf:current-date() returns a date corresponding to the current date and time. For example, an invocation of xf:current-date() might return 2002-05-12+01:00.

15.7.1 Examples

• xf:current-time() returns a time corresponding to the current date and time. For example, an invocation of xf:current-time() might return 23:17:00-05:00.