Calling the fn:error function raises an application-defined error.

This function is nondeterministic, context-independent, and focus-independent.

This function never returns a value. Instead it always raises an error. The effect of the error is identical to the effect of dynamic errors raised implicitly, for example when an incorrect argument is supplied to a function.

The parameters to the fn:error function supply information that is associated with the error condition and that is made available to a caller that asks for information about the error. The error may be caught either by the host language (using a try/catch construct in XSLT or XQuery, for example), or by the calling application or external processing environment. The way in which error information is returned to the external processing environment is implementation-dependent.

There are three pieces of information that may be associated with an error:

This function always raises a dynamic error. By default, it raises

The value of the $description parameter may need to be localized.

The type none is a special type defined in and is not available to the user. It indicates that the function never returns and ensures that it has the correct static type.

Any QName may be used as an error code; there are no reserved names or namespaces. The error is always classified as a dynamic error, even if the error code used is one that is normally used for static errors or type errors.

The expression fn:error() raises error FOER0000. (This returns the URI http://www.w3.org/2005/xqt-errors#FOER0000 (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

The expression fn:error(fn:QName('http://www.example.com/HR', 'myerr:toohighsal'), 'Does not apply because salary is too high') raises error myerr:toohighsal. (This returns http://www.example.com/HR#toohighsal and the xs:string "Does not apply because salary is too high" (or the corresponding xs:QName) to the external processing environment, unless the error is caught using a try/catch construct in the host language.)

Provides an execution trace intended to be used in debugging queries.

This function is deterministic, context-independent, and focus-independent.

The function returns the value of $value, unchanged.

In addition, the values of $value, converted to an xs:string, and $label (if supplied) may be directed to a trace data set. The destination of the trace output is implementation-defined. The format of the trace output is implementation-dependent. The ordering of output from calls of the fn:trace function is implementation-dependent.

Sometimes there is a need to output trace information unrelated to a specific value. In such cases it can be useful to set $value to an empty string or an empty sequence, and to compute the value of the $label argument: fn:trace((), "Processing item " || $i).

Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will put the strings "124.84" and "the value of $v is:" in the trace data set in implementation dependent order.

Returns the arithmetic sum of its operands: ($arg1 + $arg2).

Defines the semantics of the "+" operator when applied to two numeric values

General rules: see .

For xs:float or xs:double values, if one of the operands is a zero or a finite number and the other is INF or -INF, INF or -INF is returned. If both operands are INF, INF is returned. If both operands are -INF, -INF is returned. If one of the operands is INF and the other is -INF, NaN is returned.

Returns the arithmetic difference of its operands: ($arg1 - $arg2).

Defines the semantics of the "-" operator when applied to two numeric values.

General rules: see .

For xs:float or xs:double values, if one of the operands is a zero or a finite number and the other is INF or -INF, an infinity of the appropriate sign is returned. If both operands are INF or -INF, NaN is returned. If one of the operands is INF and the other is -INF, an infinity of the appropriate sign is returned.

Returns the arithmetic product of its operands: ($arg1 * $arg2).

Defines the semantics of the "*" operator when applied to two numeric values.

General rules: see .

For xs:float or xs:double values, if one of the operands is a zero and the other is an infinity, NaN is returned. If one of the operands is a non-zero number and the other is an infinity, an infinity with the appropriate sign is returned.

Returns the arithmetic quotient of its operands: ($arg1 div $arg2).

Defines the semantics of the "div" operator when applied to two numeric values.

General rules: see .

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

A dynamic error is raised for xs:decimal and xs:integer operands, if the divisor is (positive or negative) zero.

For xs:float and xs:double operands, floating point division is performed as specified in . A positive number divided by positive zero returns INF. A negative number divided by positive zero returns -INF. Division by negative zero returns -INF and INF, respectively. Positive or negative zero divided by positive or negative zero returns NaN. Also, INF or -INF divided by INF or -INF returns NaN.

Performs an integer division.

Defines the semantics of the "idiv" operator when applied to two numeric values.

General rules: see .

If $arg2 is INF or -INF, and $arg1 is not INF or -INF, then the result is zero.

Otherwise, subject to limits of precision and overflow/underflow conditions, the result is the largest (furthest from zero) xs:integer value $N such that the following expression is true:

The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where implementation-dependent or implementation-defined behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division.

A dynamic error is raised if the divisor is (positive or negative) zero.

A dynamic error is raised if either operand is NaN or if $arg1 is INF or -INF.

Except in situations involving errors, loss of precision, or overflow/underflow, the result of $a idiv $b is the same as ($a div $b) cast as xs:integer.

The semantics of this function are different from integer division as defined in programming languages such as Java and C++.

The expression op:numeric-integer-divide(10,3) returns 3.

The expression op:numeric-integer-divide(3,-2) returns -1.

The expression op:numeric-integer-divide(-3,2) returns -1.

The expression op:numeric-integer-divide(-3,-2) returns 1.

The expression op:numeric-integer-divide(9.0,3) returns 3.

The expression op:numeric-integer-divide(-3.5,3) returns -1.

The expression op:numeric-integer-divide(3.0,4) returns 0.

The expression op:numeric-integer-divide(3.1E1,6) returns 5.

The expression op:numeric-integer-divide(3.1E1,7) returns 4.

Returns the remainder resulting from dividing $arg1, the dividend, by $arg2, the divisor.

Defines the semantics of the "mod" operator when applied to two numeric values.

General rules: see .

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.

For xs:float and xs:double operands the following rules apply:

A dynamic error is raised for xs:integer and xs:decimal operands, if $arg2 is zero.

The expression op:numeric-mod(10,3) returns 1.

The expression op:numeric-mod(6,-2) returns 0.

The expression op:numeric-mod(4.5,1.2) returns 0.9.

The expression op:numeric-mod(1.23E2, 0.6E1) returns 3.0E0.

Returns its operand with the sign unchanged: (+ $arg).

Defines the semantics of the unary "+" operator applied to a numeric value.

General rules: see .

The returned value is equal to $arg, and is an instance of xs:integer, xs:decimal, xs:double, or xs:float depending on the type of $arg.

Because function conversion rules are applied in the normal way, the unary + operator can be used to force conversion of an untyped node to a number: the result of +@price is the same as xs:double(@price) if the type of @price is xs:untypedAtomic.

Returns its operand with the sign reversed: (- $arg).

Defines the semantics of the unary "-" operator when applied to a numeric value.

General rules: see .

The returned value is an instance of xs:integer, xs:decimal, xs:double, or xs:float depending on the type of $arg.

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 returns -INF. -INF returns INF.

Returns true if and only if the value of $arg1 is equal to the value of $arg2.

Defines the semantics of the "eq" operator when applied to two numeric values, and is also used in defining the semantics of "ne", "le" and "ge".

General rules: see and .

For xs:float and xs:double values, positive zero and negative zero compare equal. INF equals INF, and -INF equals -INF. NaN does not equal itself.

Returns true if and only if $arg1 is numerically less than $arg2.

Defines the semantics of the "lt" operator when applied to two numeric values, and is also used in defining the semantics of "le".

General rules: see and .

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.

Returns true if and only if $arg1 is numerically greater than $arg2.

Defines the semantics of the "gt" operator when applied to two numeric values, and is also used in defining the semantics of "ge".

The function call op:numeric-greater-than($A, $B) is defined to return the same result as op:numeric-less-than($B, $A)

Returns the absolute value of $arg.

This function is deterministic, context-independent, and focus-independent.

General rules: see .

If $arg is negative the function returns -$arg, otherwise it returns $arg.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $arg is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $arg is an instance of xs:positiveInteger then the value of $arg may be returned unchanged.

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

The expression fn:abs(10.5) returns 10.5.

The expression fn:abs(-10.5) returns 10.5.

Rounds $arg upwards to a whole number.

This function is deterministic, context-independent, and focus-independent.

General rules: see .

The function returns the smallest (closest to negative infinity) number with no fractional part that is not less than the value of $arg.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $arg is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $arg is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is less than zero and greater than -1, negative zero is returned.

The expression fn:ceiling(10.5) returns 11.

The expression fn:ceiling(-10.5) returns -10.

Rounds $arg downwards to a whole number.

This function is deterministic, context-independent, and focus-independent.

General rules: see .

The function returns the largest (closest to positive infinity) number with no fractional part that is not greater than the value of $arg.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $arg is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $arg is an instance of xs:decimal then the result may be an instance of xs:integer.

For xs:float and xs:double arguments, if the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned.

The expression fn:floor(10.5) returns 10.

The expression fn:floor(-10.5) returns -11.

Rounds a value to a specified number of decimal places, rounding upwards if two such values are equally near.

This function is deterministic, context-independent, and focus-independent.

General rules: see .

The function returns the nearest (that is, numerically closest) value to $arg that is a multiple of ten to the power of minus $precision. If two such values are equally near (for example, if the fractional part in $arg is exactly .5), the function returns the one that is closest to positive infinity.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $arg is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $arg is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

The single-argument version of this function produces the same result as the two-argument version with $precision=0 (that is, it rounds to a whole number).

When $arg is of type xs:float and xs:double:

This function is typically used with a non-zero $precision in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counter-intuitive. For example, consider round(35.425e0, 2). The result is not 35.43, as might be expected, but 35.42. This is because the xs:double written as 35.425e0 has an exact value equal to 35.42499999999..., which is closer to 35.42 than to 35.43.

The expression fn:round(2.5) returns 3.0.

The expression fn:round(2.4999) returns 2.0.

The expression fn:round(-2.5) returns -2.0. (Not the possible alternative, -3).

The expression fn:round(1.125, 2) returns 1.13.

The expression fn:round(8452, -2) returns 8500.

The expression fn:round(3.1415e0, 2) returns 3.14e0.

Rounds a value to a specified number of decimal places, rounding to make the last digit even if two such values are equally near.

This function is deterministic, context-independent, and focus-independent.

General rules: see .

The function returns the nearest (that is, numerically closest) value 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...), the function returns the one whose least significant digit is even.

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $arg is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $arg is an instance of xs:decimal and $precision is less than one, then the result may be an instance of xs:integer.

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:

This function is typically used in financial applications where the argument is of type xs:decimal. For arguments of type xs:float and xs:double the results may be counter-intuitive. For example, consider round-half-to-even(xs:float(150.015), 2). The result is not 150.02 as might be expected, but 150.01. This is because the conversion of the xs:float value represented by the literal 150.015 to an xs:decimal produces the xs:decimal value 150.014999389..., which is closer to 150.01 than to 150.02.

The expression fn:round-half-to-even(0.5) returns 0.0.

The expression fn:round-half-to-even(1.5) returns 2.0.

The expression fn:round-half-to-even(2.5) returns 2.0.

The expression fn:round-half-to-even(3.567812e+3, 2) returns 3567.81e0.

The expression fn:round-half-to-even(4.7564e-3, 2) returns 0.0e0.

The expression fn:round-half-to-even(35612.25, -2) returns 35600.

Returns the value indicated by $arg or, if $arg is not specified, the context item after atomization, converted to an xs:double.

The zero-argument form of this function is deterministic, context-dependent, and focus-dependent.

The one-argument form of this function is deterministic, context-independent, and focus-independent.

Calling the zero-argument version of the function is defined to give the same result as calling the single-argument version with the context item (.). That is, fn:number() is equivalent to fn:number(.), as defined by the rules that follow.

If $arg is the empty sequence or if $arg cannot be converted to an xs:double, the xs:double value NaN is returned.

Otherwise, $arg is converted to an xs:double following the rules of . If the conversion to xs:double fails, the xs:double value NaN is returned.

A dynamic error is raised if $arg is omitted and the context item is absent.

As a consequence of the rules given above, a type error occurs if the context item cannot be atomized, or if the result of atomizing the context item is a sequence containing more than one atomic value.

XSD 1.1 allows the string +INF as a representation of positive infinity; XSD 1.0 does not. It is implementation-defined whether XSD 1.1 is supported.

Generally fn:number returns NaN rather than raising a dynamic error if the argument cannot be converted to xs:double. However, a type error is raised in the usual way if the supplied argument cannot be atomized or if the result of atomization does not match the required argument type.

The expression fn:number($item1/quantity) returns 5.0e0.

The expression fn:number($item2/description) returns xs:double('NaN').

Assume that the context item is the xs:string value "15". Then fn:number() returns 1.5e1.

Formats an integer according to a given picture string, using the conventions of a given natural language if specified.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on default language.

The three-argument form of this function is deterministic, context-independent, and focus-independent.

If $value is an empty sequence, the function returns a zero-length string.

In all other cases, the $picture argument describes the format in which $value is output.

The rules that follow describe how non-negative numbers are output. If the value of $value is negative, the rules below are applied to the absolute value of $value, and a minus sign is prepended to the result.

The value of $picture consists of a primary format token, optionally followed by a format modifier. The primary format token is always present and must not be zero-length. If the string contains one or more semicolons then everything that precedes the last semicolon is taken as the primary format token and everything that follows is taken as the format modifier; if the string contains no semicolon then the entire picture is taken as the primary format token, and the format modifier is taken to be absent (which is equivalent to supplying a zero-length string).

The primary format token is classified as one of the following:

For all format tokens other than a decimal-digit-pattern, there may be implementation-defined lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the format token ① (circled digit one, â‘ ) has a range imposed by the Unicode character repertoire — zero to 20 in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1.

The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. There are various conventions in use for how alphabetic sequences continue when the alphabet is exhausted, and differing conventions for how roman numerals are written (for example, IV versus IIII as the representation of the number 4). Sometimes alphabetic sequences are used that omit letters such as i and o. This specification does not prescribe the detail of any sequence other than those sequences consisting entirely of decimal digits.

Many numbering sequences are language-sensitive. This applies especially to the sequence selected by the tokens w, W and Ww. It also applies to other sequences, for example different languages using the Cyrillic alphabet use different sequences of characters, each starting with the letter #x410 (Cyrillic capital letter A). In such cases, the $lang argument specifies which language's conventions are to be used. If the argument is specified, the value should be either an empty sequence or a value that would be valid for the xml:lang attribute (see ). Note that this permits the identification of sublanguages based on country codes (from ISO 3166-1) as well as identification of dialects and regions within a country.

The set of languages for which numbering is supported is implementation-defined. If the $lang argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context.

The format modifier must be a string that matches the regular expression ^([co](\(.+\))?)?[at]?$. That is, if it is present it must consist of one or more of the following, in order:

If the o modifier is present, this indicates a request to output ordinal numbers rather than cardinal numbers. For example, in English, when used with the format token 1, this outputs the sequence 1st 2nd 3rd 4th ..., and when used with the format token w outputs the sequence first second third fourth ....

The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is implementation-defined. No error occurs if the implementation does not define any interpretation for the defined string.

It is implementation-defined what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead.

The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is implementation-defined.

A dynamic error is raised if the format token is invalid, that is, if it violates any mandatory rules (indicated by an emphasized must or required keyword in the above rules). For example, the error is raised if the primary format token contains a digit but does not match the required regular expression.

The expression format-integer(123, '0000') returns "0123".

format-integer(123, 'w') might return "one hundred and twenty-three"

Ordinal numbering in Italian: The specification "1;o(-º)" with $lang equal to it, if supported, should produce the sequence:

The specification "Ww;o" with $lang equal to it, if supported, should produce the sequence:

The expression format-integer(21, '1;o', 'en') returns "21st".

format-integer(14, 'Ww;o(-e)', 'de') might return "Vierzehnte"

The expression format-integer(7, 'a') returns "g".

The expression format-integer(57, 'I') returns "LVII".

The expression format-integer(1234, '#;##0;') returns "1;234".

Returns a string containing a number formatted according to a given picture string, taking account of decimal formats specified in the static context.

The two-argument form of this function is deterministic, context-independent, and focus-independent.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on decimal formats, and namespaces.

The effect of the two-argument form of the function is equivalent to calling the three-argument form with an empty sequence as the value of the third argument.

The function formats $value as a string using the picture string specified by the $picture argument and the decimal-format named by the $decimal-format-name argument, or the unnamed decimal-format, if there is no $decimal-format-name argument. The syntax of the picture string is described in .

The $value argument may be of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes including xs:integer). Note that if an xs:decimal is supplied, it is not automatically promoted to an xs:double, as such promotion can involve a loss of precision.

If the supplied value of the $value argument is an empty sequence, the function behaves as if the supplied value were the xs:double value NaN.

The value of $decimal-format-name, if present and non-empty, must be a string which after removal of leading and trailing whitespace is in the form of an EQName as defined in the XPath 3.0 grammar, that is one of the following:

The decimal format that is used is the decimal format in the static context whose name matches $decimal-format-name if supplied, or the unnamed decimal format in the static context otherwise.

The evaluation of the fn:format-number function takes place in two phases, an analysis phase described in and a formatting phase described in .

The analysis phase takes as its inputs the picture string and the variables derived from the relevant decimal format in the static context, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.

The result of the function is the formatted string representation of the supplied number.

A dynamic error is raised if the name specified as the $decimal-format-name argument is neither a valid lexical QName nor a valid URIQualifiedName, or if it uses a prefix that is not found in the statically known namespaces, or if the static context does not contain a declaration of a decimal-format with a matching expanded QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

A string is an ordered sequence of characters, and this specification uses terms such as "left" and "right", "preceding" and "following" in relation to this ordering, irrespective of the position of the characters when visually rendered on some output medium. Both in the picture string and in the result string, digits with higher significance (that is, representing higher powers of ten) always precede digits with lower significance, even when the rendered text flow is from right to left.

The following examples assume a default decimal format in which the chosen digits are the ASCII digits 0-9, the decimal separator is ".", the grouping separator is ",", the minus-sign is "-", and the percent-sign is "%".

The expression format-number(12345.6, '#,###.00') returns "12,345.60".

The expression format-number(12345678.9, '9,999.99') returns "12,345,678.90".

The expression format-number(123.9, '9999') returns "0124".

The expression format-number(0.14, '01%') returns "14%".

The expression format-number(-6, '000') returns "-006".

The following example assumes the existence of a decimal format named 'ch' in which the grouping separator is ʹ and the decimal separator is ·:

The expression format-number(1234.5678, '#ʹ##0·00', 'ch') returns "1ʹ234·57".

The following examples assume that the exponent separator is in decimal format 'fortran' is 'E':

The expression format-number(1234.5678, '00.000E0', 'fortran') returns "12.346E2".

The expression format-number(0.234, '0.0E0', 'fortran') returns "2.3E-1".

The expression format-number(0.234, '#.00E0', 'fortran') returns "0.23E0".

The expression format-number(0.234, '.00E0', 'fortran') returns ".23E0".

Returns an approximation to the mathematical constant π.

This function is deterministic, context-independent, and focus-independent.

This function returns the xs:double value whose lexical representation is 3.141592653589793e0

The expression 2*math:pi() returns 6.283185307179586e0.

The expression 60 * (math:pi() div 180) converts an angle of 60 degrees to radians.

Returns the value of e^x.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is the mathematical constant e raised to the power of $arg, as defined in the specification of the exp function applied to 64-bit binary floating point values.

The treatment of overflow and underflow is defined in .

The expression math:exp(()) returns ().

The expression math:exp(0) returns 1.0e0.

The expression math:exp(1) returns 2.7182818284590455e0 (approximately).

The expression math:exp(2) returns 7.38905609893065e0.

The expression math:exp(-1) returns 0.36787944117144233e0.

The expression math:exp(math:pi()) returns 23.140692632779267e0.

The expression math:exp(xs:double('NaN')) returns xs:double('NaN').

The expression math:exp(xs:double('INF')) returns xs:double('INF').

The expression math:exp(xs:double('-INF')) returns 0.0e0.

Returns the value of 10^x.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is ten raised to the power of $arg, as defined in the specification of the exp10 function applied to 64-bit binary floating point values.

The treatment of overflow and underflow is defined in .

The expression math:exp10(()) returns ().

The expression math:exp10(0) returns 1.0e0.

The expression math:exp10(1) returns 1.0e1.

The expression math:exp10(0.5) returns 3.1622776601683795e0.

The expression math:exp10(-1) returns 1.0e-1.

The expression math:exp10(xs:double('NaN')) returns xs:double('NaN').

The expression math:exp10(xs:double('INF')) returns xs:double('INF').

The expression math:exp10(xs:double('-INF')) returns 0.0e0.

Returns the natural logarithm of the argument.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is the natural logarithm of $arg, as defined in the specification of the log function applied to 64-bit binary floating point values.

The treatment of divideByZero and invalidOperation exceptions is defined in . The effect is that if the argument is zero, the result is -INF, and if it is negative, the result is NaN.

The expression math:log(()) returns ().

The expression math:log(0) returns xs:double('-INF').

The expression math:log(math:exp(1)) returns 1.0e0.

The expression math:log(1.0e-3) returns -6.907755278982137e0.

The expression math:log(2) returns 0.6931471805599453e0.

The expression math:log(-1) returns xs:double('NaN').

The expression math:log(xs:double('NaN')) returns xs:double('NaN').

The expression math:log(xs:double('INF')) returns xs:double('INF').

The expression math:log(xs:double('-INF')) returns xs:double('NaN').

Returns the base-ten logarithm of the argument.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is the base-10 logarithm of $arg, as defined in the specification of the log10 function applied to 64-bit binary floating point values.

The treatment of divideByZero and invalidOperation exceptions is defined in . The effect is that if the argument is zero, the result is -INF, and if it is negative, the result is NaN.

The expression math:log10(()) returns ().

The expression math:log10(0) returns xs:double('-INF').

The expression math:log10(1.0e3) returns 3.0e0.

The expression math:log10(1.0e-3) returns -3.0e0.

The expression math:log10(2) returns 0.3010299956639812e0.

The expression math:log10(-1) returns xs:double('NaN').

The expression math:log10(xs:double('NaN')) returns xs:double('NaN').

The expression math:log10(xs:double('INF')) returns xs:double('INF').

The expression math:log10(xs:double('-INF')) returns xs:double('NaN').

Returns the result of raising the first argument to the power of the second.

This function is deterministic, context-independent, and focus-independent.

If $x is the empty sequence, the function returns the empty sequence.

If $y is an instance of xs:integer, the result is $x raised to the power of $y as defined in the specification of the pown function applied to a 64-bit binary floating point value and an integer.

Otherwise $y is converted to an xs:double by numeric promotion, and the result is the value of $x raised to the power of $y as defined in the specification of the pow function applied to two 64-bit binary floating point values.

The treatment of the divideByZero and invalidOperation exceptions is defined in . Some of the consequences are illustrated in the examples below.

The expression math:pow((), 93.7) returns ().

The expression math:pow(2, 3) returns 8.0e0.

The expression math:pow(-2, 3) returns -8.0e0.

The expression math:pow(2, -3) returns 0.125e0.

The expression math:pow(-2, -3) returns -0.125e0.

The expression math:pow(2, 0) returns 1.0e0.

The expression math:pow(0, 0) returns 1.0e0.

The expression math:pow(xs:double('INF'), 0) returns 1.0e0.

The expression math:pow(xs:double('NaN'), 0) returns 1.0e0.

The expression math:pow(-math:pi(), 0) returns 1.0e0.

The expression math:pow(0e0, 3) returns 0.0e0.

The expression math:pow(0e0, 4) returns 0.0e0.

The expression math:pow(-0e0, 3) returns -0.0e0.

The expression math:pow(0, 4) returns 0.0e0.

The expression math:pow(0e0, -3) returns xs:double('INF').

The expression math:pow(0e0, -4) returns xs:double('INF').

The expression math:pow(-0e0, -3) returns xs:double('-INF').

The expression math:pow(0, -4) returns xs:double('INF').

The expression math:pow(16, 0.5e0) returns 4.0e0.

The expression math:pow(16, 0.25e0) returns 2.0e0.

The expression math:pow(0e0, -3.0e0) returns xs:double('INF').

The expression math:pow(-0e0, -3.0e0) returns xs:double('-INF'). (Odd-valued whole numbers are treated specially).

The expression math:pow(0e0, -3.1e0) returns xs:double('INF').

The expression math:pow(-0e0, -3.1e0) returns xs:double('INF').

The expression math:pow(0e0, 3.0e0) returns 0.0e0.

The expression math:pow(-0e0, 3.0e0) returns -0.0e0. (Odd-valued whole numbers are treated specially).

The expression math:pow(0e0, 3.1e0) returns 0.0e0.

The expression math:pow(-0e0, 3.1e0) returns 0.0e0.

The expression math:pow(-1, xs:double('INF')) returns 1.0e0.

The expression math:pow(-1, xs:double('-INF')) returns 1.0e0.

The expression math:pow(1, xs:double('INF')) returns 1.0e0.

The expression math:pow(1, xs:double('-INF')) returns 1.0e0.

The expression math:pow(1, xs:double('NaN')) returns 1.0e0.

The expression math:pow(-2.5e0, 2.0e0) returns 6.25e0.

The expression math:pow(-2.5e0, 2.00000001e0) returns xs:double('NaN').

Returns the non-negative square root of the argument.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is the mathematical non-negative square root of $arg as defined in the specification of the squareRoot function applied to 64-bit binary floating point values.

The treatment of the invalidOperation exception is defined in . The effect is that if the argument is less than zero, the result is NaN.

If $arg is positive or negative zero, positive infinity, or NaN, then the result is $arg. (Negative zero is the only case where the result can have negative sign)

The expression math:sqrt(()) returns ().

The expression math:sqrt(0.0e0) returns 0.0e0.

The expression math:sqrt(-0.0e0) returns -0.0e0.

The expression math:sqrt(1.0e6) returns 1.0e3.

The expression math:sqrt(2.0e0) returns 1.4142135623730951e0.

The expression math:sqrt(-2.0e0) returns xs:double('NaN').

The expression math:sqrt(xs:double('NaN')) returns xs:double('NaN').

The expression math:sqrt(xs:double('INF')) returns xs:double('INF').

The expression math:sqrt(xs:double('-INF')) returns xs:double('NaN').

Returns the sine of the argument. The argument is an angle in radians.

This function is deterministic, context-independent, and focus-independent.

If $θ is the empty sequence, the function returns the empty sequence.

Otherwise the result is the sine of $θ (which is treated as an angle in radians) as defined in the specification of the sin function applied to 64-bit binary floating point values.

The treatment of the invalidOperation and underflow exceptions is defined in .

If $θ is positive or negative zero, the result is $θ.

If $θ is positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is always in the range -1.0e0 to +1.0e0

The expression math:sin(()) returns ().

The expression math:sin(0) returns 0.0e0.

The expression math:sin(-0.0e0) returns -0.0e0.

The expression math:sin(math:pi() div 2) returns 1.0e0 (approximately).

The expression math:sin(-math:pi() div 2) returns -1.0e0 (approximately).

The expression math:sin(math:pi()) returns 0.0e0 (approximately).

The expression math:sin(xs:double('NaN')) returns xs:double('NaN').

The expression math:sin(xs:double('INF')) returns xs:double('NaN').

The expression math:sin(xs:double('-INF')) returns xs:double('NaN').

Returns the cosine of the argument. The argument is an angle in radians.

This function is deterministic, context-independent, and focus-independent.

If $θ is the empty sequence, the function returns the empty sequence.

If $θ is positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is the cosine of $θ (which is treated as an angle in radians) as defined in the specification of the cos function applied to 64-bit binary floating point values.

The treatment of the invalidOperation exception is defined in .

If $θ is positive or negative zero, the result is $θ.

If $θ is positive or negative infinity, or NaN, then the result is NaN.

Otherwise the result is always in the range -1.0e0 to +1.0e0

The expression math:cos(()) returns ().

The expression math:cos(0) returns 1.0e0.

The expression math:cos(-0.0e0) returns 1.0e0.

The expression math:cos(math:pi() div 2) returns 0.0e0 (approximately).

The expression math:cos(-math:pi() div 2) returns 0.0e0 (approximately).

The expression math:cos(math:pi()) returns -1.0e0 (approximately).

The expression math:cos(xs:double('NaN')) returns xs:double('NaN').

The expression math:cos(xs:double('INF')) returns xs:double('NaN').

The expression math:cos(xs:double('-INF')) returns xs:double('NaN').

Returns the tangent of the argument. The argument is an angle in radians.

This function is deterministic, context-independent, and focus-independent.

If $θ is the empty sequence, the function returns the empty sequence.

Otherwise the result is the tangent of $θ (which is treated as an angle in radians) as defined in the specification of the tan function applied to 64-bit binary floating point values.

The treatment of the invalidOperation and underflow exceptions is defined in .

If $θ is positive or negative infinity, or NaN, then the result is NaN.

The expression math:tan(()) returns ().

The expression math:tan(0) returns 0.0e0.

The expression math:tan(-0.0e0) returns -0.0e0.

The expression math:tan(math:pi() div 4) returns 1.0e0 (approximately).

The expression math:tan(-math:pi() div 4) returns -1.0e0 (approximately).

The expression 1 div math:tan(math:pi() div 2) returns 0.0e0 (approximately). (Mathematically, tan(Ï€/2) is positive infinity. But because math:pi() div 2 returns an approximation, the result of math:tan(math:pi() div 2) will be a large but finite number.)

The expression 1 div math:tan(-math:pi() div 2) returns -0.0e0 (approximately). (Mathematically, tan(-Ï€/2) is negative infinity. But because -math:pi() div 2 returns an approximation, the result of math:tan(-math:pi() div 2) will be a large but finite negative number.)

The expression math:tan(math:pi()) returns 0.0e0 (approximately).

The expression math:tan(xs:double('NaN')) returns xs:double('NaN').

The expression math:tan(xs:double('INF')) returns xs:double('NaN').

The expression math:tan(xs:double('-INF')) returns xs:double('NaN').

Returns the arc sine of the argument.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is the arc sine of $arg as defined in the specification of the asin function applied to 64-bit binary floating point values. The result is in the range -Ï€/2 to +Ï€/2 radians.

The treatment of the invalidOperation and underflow exceptions is defined in .

If $arg is positive or negative zero, the result is $arg.

If $arg is NaN, or if its absolute value is greater than one, then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range -Ï€/2 <= θ <= +Ï€/2.

The expression math:asin(()) returns ().

The expression math:asin(0) returns 0.0e0.

The expression math:asin(-0.0e0) returns -0.0e0.

The expression math:asin(1.0e0) returns 1.5707963267948966e0 (approximately).

The expression math:asin(-1.0e0) returns -1.5707963267948966e0 (approximately).

The expression math:asin(2.0e0) returns xs:double('NaN').

The expression math:asin(xs:double('NaN')) returns xs:double('NaN').

The expression math:asin(xs:double('INF')) returns xs:double('NaN').

The expression math:asin(xs:double('-INF')) returns xs:double('NaN').

Returns the arc cosine of the argument.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is the arc cosine of $arg, as defined in the specification of the acos function applied to 64-bit binary floating point values. The result is in the range zero to +Ï€ radians.

The treatment of the invalidOperation exception is defined in .

If $arg is NaN, or if its absolute value is greater than one, then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range 0 <= θ <= +Ï€.

The expression math:acos(()) returns ().

The expression math:acos(0) returns 1.5707963267948966e0 (approximately).

The expression math:acos(-0.0e0) returns 1.5707963267948966e0 (approximately).

The expression math:acos(1.0e0) returns 0.0e0.

The expression math:acos(-1.0e0) returns 3.141592653589793e0 (approximately).

The expression math:acos(2.0e0) returns xs:double('NaN').

The expression math:acos(xs:double('NaN')) returns xs:double('NaN').

The expression math:acos(xs:double('INF')) returns xs:double('NaN').

The expression math:acos(xs:double('-INF')) returns xs:double('NaN').

Returns the arc tangent of the argument.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise the result is the arc tangent of $arg, as defined in the specification of the atan function applied to 64-bit binary floating point values. The result is in the range -Ï€/2 to +Ï€/2 radians.

The treatment of the underflow exception is defined in .

If $arg is positive or negative zero, the result is $arg.

If $arg is NaN then the result is NaN.

In other cases the result is an xs:double value representing an angle θ in radians in the range -Ï€/2 <= θ <= +Ï€/2.

The expression math:atan(()) returns ().

The expression math:atan(0) returns 0.0e0.

The expression math:atan(-0.0e0) returns -0.0e0.

The expression math:atan(1.0e0) returns 0.7853981633974483e0 (approximately).

The expression math:atan(-1.0e0) returns -0.7853981633974483e0 (approximately).

The expression math:atan(xs:double('NaN')) returns xs:double('NaN').

The expression math:atan(xs:double('INF')) returns 1.5707963267948966e0 (approximately).

The expression math:atan(xs:double('-INF')) returns -1.5707963267948966e0 (approximately).

Returns the angle in radians subtended at the origin by the point on a plane with coordinates (x, y) and the positive x-axis.

This function is deterministic, context-independent, and focus-independent.

The result is the value of atan2(y, x) as defined in the specification of the atan2 function applied to 64-bit binary floating point values. The result is in the range -Ï€ to +Ï€ radians.

The treatment of the underflow exception is defined in .

If either argument is NaN then the result is NaN.

If $y is positive and $x is positive and finite, then (subject to rules for overflow, underflow and approximation) the value of atan2($y, $x) is atan($y div $x).

If $y is positive and $x is negative and finite, then (subject to the same caveats) the value of atan2($y, $x) is Ï€ - atan($y div $x).

Some results for special values of the arguments are shown in the examples below.

The expression math:atan2(+0.0e0, 0.0e0) returns 0.0e0.

The expression math:atan2(-0.0e0, 0.0e0) returns -0.0e0.

The expression math:atan2(+0.0e0, -0.0e0) returns 3.141592653589793e0.

The expression math:atan2(-0.0e0, -0.0e0) returns -3.141592653589793e0.

The expression math:atan2(-1, 0.0e0) returns -1.5707963267948966e0.

The expression math:atan2(+1, 0.0e0) returns 1.5707963267948966e0.

The expression math:atan2(-0.0e0, -1) returns -3.141592653589793e0.

The expression math:atan2(+0.0e0, -1) returns 3.141592653589793e0.

The expression math:atan2(-0.0e0, +1) returns -0.0e0.

The expression math:atan2(+0.0e0, +1) returns +0.0e0.

Returns a random number generator, which can be used to generate sequences of random numbers.

This function is deterministic, context-independent, focus-independent, and higher-order.

The function returns a random number generator. A random number generator is represented as a map containing three entries. The keys of each entry are strings:

Calling the fn:random-number-generator function with no arguments is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

Calling the fn:random-number-generator function with an empty sequence as the value of $seed is equivalent to calling the single-argument form of the function with an implementation-dependent seed.

If a $seed is supplied, it may be an atomic value of any type.

Both forms of the function are : calling the function twice with the same arguments, within a single execution scope, produces the same results.

The value of the number entry should be such that all eligible xs:double values are equally likely to be chosen.

The function returned in the permute entry should be such that all permutations of the supplied sequence are equally likely to be chosen.

The map returned by the fn:random-number-generator function may contain additional entries beyond those specified here, but it must match the type map(xs:string, item()). The meaning of any additional entries is implementation-defined. To avoid conflict with any future version of this specification, the keys of any such entries should start with an underscore character.

It is not meaningful to ask whether the functions returned in the next and permute functions resulting from two separate calls with the same seed are "the same function", but the functions must be equivalent in the sense that calling them produces the same sequence of random numbers.

The repeatability of the results of function calls in different execution scopes is outside the scope of this specification. It is recommended that when the same seed is provided explicitly, the same random number sequence should be delivered even in different execution scopes; while if no seed is provided, the processor should choose a seed that is likely to be different from one execution scope to another. (The same effect can be achieved explicitly by using fn:current-dateTime() as a seed.)

The specification does not place strong conformance requirements on the actual randomness of the result; this is left to the implementation. It is desirable, for example, when generating a sequence of random numbers that the sequence should not get into a repeating loop; but the specification does not attempt to dictate this.

The following example returns a random permutation of the integers in the range 1 to 100: fn:random-number-generator()?permute(1 to 100)

The following example returns a 10% sample of the items in an input sequence $seq, chosen at random: fn:random-number-generator()?permute($seq)[position() = 1 to (count($seq) idiv 10)]

The following code defines a function that can be called to produce a random sequence of xs:double values in the range zero to one, of specified length:

Returns an xs:string whose characters have supplied codepoints.

This function is deterministic, context-independent, and focus-independent.

The function returns the string made up from the characters whose Unicode codepoints are supplied in $arg. This will be the zero-length string if $arg is the empty sequence.

A dynamic error is raised if any of the codepoints in $arg is not a permitted XML character.

The expression fn:codepoints-to-string((66, 65, 67, 72)) returns "BACH".

The expression fn:codepoints-to-string((2309, 2358, 2378, 2325)) returns "अशॊक".

The expression fn:codepoints-to-string(()) returns "".

The expression fn:codepoints-to-string(0) raises error FOCH0001.

Returns the sequence of codepoints that constitute an xs:string value.

This function is deterministic, context-independent, and focus-independent.

The function returns a sequence of integers, each integer being the Unicode codepoint of the corresponding character in $arg.

If $arg is a zero-length string or the empty sequence, the function returns the empty sequence.

The expression fn:string-to-codepoints("Thérèse") returns (84, 104, 233, 114, 232, 115, 101).

Returns -1, 0, or 1, depending on whether $comparand1 collates before, equal to, or after $comparand2 according to the rules of a selected collation.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI.

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 this function is determined according to the rules in .

If either $comparand1 or $comparand2 is the empty sequence, the function returns the empty sequence.

This function, called with the first signature, defines the semantics of the "eq", "ne", "gt", "lt", "le" and "ge" operators on xs:string values.

The expression fn:compare('abc', 'abc') returns 0.

The expression fn:compare('Strasse', 'Straße') returns 0. (Assuming the default collation includes provisions that equate ss and the (German) character ß (sharp-s). Otherwise, the returned value depends on the semantics of the default collation.)

The expression fn:compare('Strasse', 'Straße', 'http://www.w3.org/2013/collation/UCA?lang=de;strength=primary') returns 0. (The specified collation equates ss and the (German) character ß (sharp-s).)

The expression fn:compare('Strassen', 'Straße') returns 1. (Assuming the default collation includes provisions that treat differences between ss and the (German) character ß (sharp-s) with less strength than the differences between the base characters, such as the final n. ).

Returns true if two strings are equal, considered codepoint-by-codepoint.

This function is deterministic, context-independent, and focus-independent.

If either argument is the empty sequence, the function returns the empty sequence.

Otherwise, the function returns true or false depending on whether the value of $comparand1 is equal to the value of $comparand2, according to the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

This function allows xs:anyURI values to be compared without having to specify the Unicode codepoint collation.

The expression fn:codepoint-equal("abcd", "abcd") returns true().

The expression fn:codepoint-equal("abcd", "abcd ") returns false().

The expression fn:codepoint-equal("", "") returns true().

The expression fn:codepoint-equal("", ()) returns ().

The expression fn:codepoint-equal((), ()) returns ().

Given a string value and a collation, generates an internal value called a collation key, with the property that the matching and ordering of collation keys reflects the matching and ordering of strings under the specified collation.

This function is deterministic, context-dependent, and focus-independent. It depends on collations.

Calling the one-argument version of this function is equivalent to calling the two-argument version supplying the default collation as the second argument.

The function returns an implementation-dependent value with the property that, for any two strings $K1 and $K2:

The collation used by this function is determined according to the rules in . Collation keys are defined as xs:base64Binary values to ensure unambiguous and context-free comparison semantics.

An implementation is free to generate a collation key in any convenient way provided that it always generates the same collation key for two strings that are equal under the collation, and different collation keys for strings that are not equal. This holds only within a single execution scope; an implementation is under no obligation to generate the same collation keys during a subsequent unrelated query or transformation.

It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an implementation-defined property of the collation.

An error is raised if the specified collation does not support the generation of collation keys.

The function is provided primarily for use with maps. If a map is required where codepoint equality is inappropriate for comparing keys, then a common technique is to normalize the key so that equality matching becomes feasible. There are many ways keys can be normalized, for example by use of functions such as fn:upper-case, fn:lower-case, fn:normalize-space, or fn:normalize-unicode, but this function provides a way of normalizing them according to the rules of a specified collation. For example, if the collation ignores accents, then the function will generate the same collation key for two input strings that differ only in their use of accents.

The result of the function is defined to be an xs:base64Binary value. Binary values are chosen because they have unambiguous and context-free comparison semantics, because the value space is unbounded, and because the ordering rules are such that between any two values in the ordered value space, an arbitrary number of further values can be interpolated. The choice between xs:base64Binary and xs:hexBinary is arbitrary; the only operation that behaves differently between the two binary data types is conversion to/from a string, and this operation is not one that is normally required for effective use of collation keys.

For collations based on the Unicode Collation Algorithm, an algorithm for computing collation keys is provided in . Implementations are not required to use this algorithm.

This specification does not mandate that collation keys should retain ordering. This is partly because the primary use case is for maps, where only equality comparisons are required, and partly to allow the use of binary data types (which are currently unordered types) for the result. The specification may be revised in a future release to specify that ordering is preserved.

The fact that collation keys are ordered can be exploited in XQuery, whose order by clause does not allow the collation to be selected dynamically. This restriction can be circumvented by rewriting the clause order by $e/@key collation "URI" as order by fn:collation-key($e/@key, $collation), where $collation allows the collation to be chosen dynamically.

Note that xs:base64Binary becomes an ordered type in XPath 3.1, making binary collation keys possible.

The expression map:merge((map{collation-key("A", $C):1}, map{collation-key("a", $C):2}), map{"duplicates":"use-last"})(collation-key("A", $C)) returns 2. (Given that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence.)

The expression let $M := map{collation-key("A", $C):1, collation-key("B", $C):2} return $M(collation-key("a", $C)) returns 1. (The strings "A" and "a" have the same collation key under this collation.)

As the above examples illustrate, it is important that when the collation-key function is used to add entries to a map, then it must also be used when retrieving entries from the map. This process can be made less error-prone by encapsulating the map within a function: function($k) {$M(collation-key($k, $collation)}.

Determines whether or not any of the supplied strings, when tokenized at whitespace boundaries, contains the supplied token, under the rules of the supplied collation.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI.

If $input is the empty sequence, the function returns false.

Leading and trailing whitespace is trimmed from the supplied value of $token. If the trimmed value of $token is a zero-length string, the function returns false.

The collation used by this function is determined according to the rules in .

The function returns true if and only if there is string in $input which, after tokenizing at whitespace boundaries, contains a token that is equal to the trimmed value of $token under the rules of the selected collation.

That is, the function returns the value of the expression:

Interior whitespace within $token will cause the function to return false, unless such whitespace is ignored by the selected collation.

This function can be used for processing space-separated attribute values (for example, the XHTML and DITA class attribute), where one often needs to test for the presence of a single token in a space-separated list. The function is designed to work both when the attribute has been validated against an XSD list type, and when it appears as a single untyped string. It differs from the HTML 5 definition in that HTML 5 recognizes form feed (x0C) as a separator. To reproduce the HTML token matching behavior, the HTML ASCII case-insensitive collation should be used: see .

The expression fn:contains-token("red green blue ", "red") returns true().

The expression fn:contains-token(("red", "green", "blue"), " red ") returns true().

The expression fn:contains-token("red, green, blue", "red") returns false().

The expression fn:contains-token("red green blue", "RED", "http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive") returns true().

Returns the concatenation of the string values of the arguments.

The two-argument form of this function defines the semantics of the "||" operator.

This function is deterministic, context-independent, and focus-independent.

This function accepts two or more xs:anyAtomicType arguments and casts each one to xs:string. The function returns the xs:string that is the concatenation of the values of its arguments after conversion. If any argument is the empty sequence, that argument is treated as the zero-length string.

The fn:concat function is specified to allow two or more arguments, which are concatenated together. This is the only function specified in this document that allows a variable number of arguments. This capability is retained for compatibility with .

As mentioned in Unicode normalization is not automatically applied to the result of fn:concat. If a normalized result is required, fn:normalize-unicode can be applied to the xs:string returned by fn:concat. The following XQuery:

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:

"I plan to go to Mu?nchen in September"

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈". It is worth noting that the returned value is not normalized in NFC; however, it is normalized in NFD.

However, the following XQuery:

where the "?" represents either the actual Unicode character COMBINING DIARESIS (Unicode codepoint U+0308) or "̈", will return:

"I plan to go to München in September"

This returned result is normalized in NFC.

The expression fn:concat('un', 'grateful') returns "ungrateful".

The expression fn:concat('Thy ', (), 'old ', "groans", "", ' ring', ' yet', ' in', ' my', ' ancient',' ears.') returns "Thy old groans ring yet in my ancient ears.".

The expression fn:concat('Ciao!',()) returns "Ciao!".

The expression fn:concat('Ingratitude, ', 'thou ', 'marble-hearted', ' fiend!') returns "Ingratitude, thou marble-hearted fiend!".

The expression fn:concat(01, 02, 03, 04, true()) returns "1234true".

The expression 10 || '/' || 6 returns "10/6".

Returns a string created by concatenating the items in a sequence, with a defined separator between adjacent items.

This function is deterministic, context-independent, and focus-independent.

The effect of calling the single-argument version of this function is the same as calling the two-argument version with $arg2 set to a zero-length string.

The function returns an xs:string created by casting each item in the sequence $arg1 to an xs:string, and then concatenating the result strings in order, using the value of $arg2 as a separator between adjacent strings. 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 function returns the zero-length string.

The expression fn:string-join(1 to 9) returns "123456789".

The expression fn:string-join(('Now', 'is', 'the', 'time', '...'), ' ') returns "Now is the time ...".

The expression fn:string-join(('Blow, ', 'blow, ', 'thou ', 'winter ', 'wind!'), '') returns "Blow, blow, thou winter wind!".

The expression fn:string-join((), 'separator') returns "".

The expression fn:string-join(1 to 5, ', ') returns "1, 2, 3, 4, 5".

The expression $doc//@xml:id ! fn:string-join((node-name(), '="', ., '"')) returns 'xml:id="xyz"'.

The expression $doc//section ! fn:string-join(ancestor-or-self::*/name(), '/') returns "doc/chap/section".

Returns the portion of the value of $sourceString beginning at the position indicated by the value of $start and continuing for the number of characters indicated by the value of $length.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise, the function returns a string comprising those characters of $sourceString whose index position (counting from one) is greater than or equal to the value of $start (rounded to an integer), and (if $length is specified) less than the sum of $start and $length (both rounded to integers).

The characters returned do not extend beyond $sourceString. If $start is zero or negative, only those characters in positions greater than zero are returned.

More specifically, the three argument version of the function returns the characters in $sourceString whose position $p satisfies:

fn:round($start) <= $p and $p < fn:round($start) + fn:round($length)

The two argument version of the function assumes that $length is infinite and thus returns the characters in $sourceString whose position $p satisfies:

fn:round($start) <= $p

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

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

The second and third arguments allow xs:double values (rather than requiring xs:integer) in order to achieve compatibility with XPath 1.0.

A surrogate pair counts as one character, not two.

The consequences of supplying values such as NaN or positive or negative infinity for the $start or $length arguments follow from the above rules, and are not always intuitive.

The expression fn:substring("motor car", 6) returns " car". (Characters starting at position 6 to the end of $sourceString are selected.)

The expression fn:substring("metadata", 4, 3) returns "ada". (Characters at positions greater than or equal to 4 and less than 7 are selected.)

The expression fn:substring("12345", 1.5, 2.6) returns "234". (Characters at positions greater than or equal to 2 and less than 5 are selected.)

The expression fn:substring("12345", 0, 3) returns "12". (Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2.)

The expression fn:substring("12345", 5, -3) returns "". (Characters at positions greater than or equal to 5 and less than 2 are selected.)

The expression fn:substring("12345", -3, 5) returns "1". (Characters at positions greater than or equal to -3 and less than 2 are selected. Since the first position is 1, this is the character at position 1.)

The expression fn:substring("12345", 0 div 0E0, 3) returns "". (Since 0 div 0E0 returns NaN, and NaN compared to any other number returns false, no characters are selected.)

The expression fn:substring("12345", 1, 0 div 0E0) returns "". (As above.)

The expression fn:substring((), 1, 3) returns "".

The expression fn:substring("12345", -42, 1 div 0E0) returns "12345". (Characters at positions greater than or equal to -42 and less than INF are selected.)

The expression fn:substring("12345", -1 div 0E0, 1 div 0E0) returns "". (Since the value of -INF + INF is NaN, no characters are selected.)

Returns the number of characters in a string.

The zero-argument form of this function is deterministic, context-dependent, and focus-dependent.

The one-argument form of this function is deterministic, context-independent, and focus-independent.

The function returns an xs:integer equal to the length in characters of the value of $arg.

Calling the zero-argument version of the function is equivalent to calling fn:string-length(fn:string(.)).

If the value of $arg is the empty sequence, the function returns the xs:integer value zero (0).

If $arg is not specified and the context item is absent, a dynamic error is raised: .

Unlike some programming languages, a codepoint greater than 65535 counts as one character, not two.

There are situations where fn:string-length() has a different effect from fn:string-length(.). For example, if the context item is an attribute node typed as an xs:integer with the string value 000001, then fn:string-length() returns 6 (the length of the string value of the node), while fn:string-length(.) raises a type error (because the result of atomization is not an xs:string).

The expression fn:string-length("Harp not on that string, madam; that is past.") returns 45.

The expression fn:string-length(()) returns 0.

Returns the value of $arg with leading and trailing whitespace removed, and sequences of internal whitespace reduced to a single space character.

The zero-argument form of this function is deterministic, context-dependent, and focus-dependent.

The one-argument form of this function is deterministic, context-independent, and focus-independent.

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

The function returns a string constructed by stripping leading and trailing whitespace from the value of $arg, and replacing sequences of one or more adjacent whitespace characters with a single space, #x20.

The whitespace characters are defined in the metasymbol S (Production 3) of .

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

If no argument is supplied and the context item is absent then a dynamic error is raised: .

The definition of whitespace is unchanged in . It is repeated here for convenience:

S ::= (#x20 | #x9 | #xD | #xA)+

The expression fn:normalize-space(" The    wealthy curled darlings                                         of    our    nation. ") returns "The wealthy curled darlings of our nation.".

The expression fn:normalize-space(()) returns "".

Returns the value of $arg after applying Unicode normalization.

This function is deterministic, context-independent, and focus-independent.

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

If the single-argument version of the function is used, the result is the same as calling the two-argument version with $normalizationForm set to the string "NFC".

Otherwise, the function returns the value of $arg normalized according to the rules of the normalization form identified by the value of $normalizationForm.

The effective value of $normalizationForm is the value of the expression fn:upper-case(fn:normalize-space($normalizationForm)).

Normalization forms NFC, NFD, NFKC, and NFKD, and the algorithms to be used for converting a string to each of these forms, are defined in .

The motivation for normalization form FULLY-NORMALIZED is explained in . However, as that specification did not progress beyond working draft status, the normative specification is as follows:

Conforming implementations must support normalization form "NFC" and may support normalization forms "NFD", "NFKC", "NFKD", and "FULLY-NORMALIZED". They may also support other normalization forms with implementation-defined semantics.

It is implementation-defined which version of Unicode (and therefore, of the normalization algorithms and their underlying data) is supported by the implementation. See for details of the stability policy regarding changes to the normalization rules in future versions of Unicode. If the input string contains codepoints that are unassigned in the relevant version of Unicode, or for which no normalization rules are defined, the fn:normalize-unicode function leaves such codepoints unchanged. If the implementation supports the requested normalization form then it must be able to handle every input string without raising an error.

A dynamic error is raised if the effective value of the $normalizationForm argument is not one of the values supported by the implementation.

Converts a string to upper case.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise, the function returns the value of $arg after translating every character to its upper-case correspondent as defined in the appropriate case mappings section in the Unicode standard . For versions of Unicode beginning with the 2.1.8 update, only locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and likely future versions) of Unicode, precise mappings are described in default case operations, which are full case mappings in the absence of tailoring for particular languages and environments. Every lower-case character that does not have an upper-case correspondent, as well as every upper-case character, is included in the returned value in its original form.

Case mappings may change the length of a string. In general, the fn:upper-case and fn:lower-case functions are not inverses of each other: fn:lower-case(fn:upper-case($arg)) is not guaranteed to return $arg, nor is fn:upper-case(fn:lower-case($arg)). The Latin small letter dotless i (as used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The Latin capital letter i with dot above is the most prominent upper-case letter which will not round trip; there are others, such as Latin capital letter Sharp S (#1E9E) which was introduced in Unicode 5.1.

These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.

Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of "è" is "È", while in metropolitan France it is more commonly "E"; only one of these is supported by the functions as defined.

Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.

The expression fn:upper-case("abCd0") returns "ABCD0".

Converts a string to lower case.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise, the function returns the value of $arg after translating every character to its lower-case correspondent as defined in the appropriate case mappings section in the Unicode standard . For versions of Unicode beginning with the 2.1.8 update, only locale-insensitive case mappings should be applied. Beginning with version 3.2.0 (and likely future versions) of Unicode, precise mappings are described in default case operations, which are full case mappings in the absence of tailoring for particular languages and environments. Every upper-case character that does not have a lower-case correspondent, as well as every lower-case character, is included in the returned value in its original form.

Case mappings may change the length of a string. In general, the fn:upper-case and fn:lower-case functions are not inverses of each other: fn:lower-case(fn:upper-case($arg)) is not guaranteed to return $arg, nor is fn:upper-case(fn:lower-case($arg)). The Latin small letter dotless i (as used in Turkish) is perhaps the most prominent lower-case letter which will not round-trip. The Latin capital letter i with dot above is the most prominent upper-case letter which will not round trip; there are others, such as Latin capital letter Sharp S (#1E9E) which was introduced in Unicode 5.1.

These functions may not always be linguistically appropriate (e.g. Turkish i without dot) or appropriate for the application (e.g. titlecase). In cases such as Turkish, a simple translation should be used first.

Because the function is not sensitive to locale, results will not always match user expectations. In Quebec, for example, the standard uppercase equivalent of "è" is "È", while in metropolitan France it is more commonly "E"; only one of these is supported by the functions as defined.

Many characters of class Ll lack uppercase equivalents in the Unicode case mapping tables; many characters of class Lu lack lowercase equivalents.

The expression fn:lower-case("ABc!D") returns "abc!d".

Returns the value of $arg modified by replacing or removing individual characters.

This function is deterministic, context-independent, and focus-independent.

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

Otherwise, the function returns a result string constructed by processing each character in the value of $arg, in order, according to the following rules:

If $mapString is the zero-length string then the function returns $arg unchanged.

If a character occurs more than once in $mapString, then the first occurrence determines the action taken.

If $transString is longer than $mapString, the excess characters are ignored.

The expression fn:translate("bar","abc","ABC") returns "BAr".

The expression fn:translate("--aaa--","abc-","ABC") returns "AAA".

The expression fn:translate("abcdabc", "abc", "AB") returns "ABdAB".

Returns true if the string $arg1 contains $arg2 as a substring, taking collations into account.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI.

If the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, 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.

The collation used by this function is determined according to the rules in .

The function returns an xs:boolean indicating whether or not the value of $arg1 contains (at the beginning, at the end, or anywhere within) at least one sequence of collation units that provides a minimal match to the collation units in the value of $arg2, according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in .

The expression fn:contains ( "tattoo", "t") returns true().

The expression fn:contains ( "tattoo", "ttt") returns false().

The expression fn:contains ( "", ()) returns true(). (The first rule is applied, followed by the second rule.)

The expression fn:contains ( "abcdefghi", "-d-e-f-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:contains ( "a*b*c*d*e*f*g*h*i*", "d-ef-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:contains ( "abcd***e---f*--*ghi", "def", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:contains ( (), "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true(). (The second argument contains only ignorable collation units and is equivalent to the zero-length string.)

Returns true if the string $arg1 contains $arg2 as a leading substring, taking collations into account.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI.

If the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, 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 this function is determined according to the rules in .

The function returns an xs:boolean indicating whether or not the value of $arg1 starts with a sequence of collation units that provides a match to the collation units of $arg2 according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in .

The expression fn:starts-with("tattoo", "tat") returns true().

The expression fn:starts-with ( "tattoo", "att") returns false().

The expression fn:starts-with ((), ()) returns true().

The expression fn:starts-with ( "abcdefghi", "-a-b-c-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:starts-with ( "a*b*c*d*e*f*g*h*i*", "a-bc-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:starts-with ( "abcd***e---f*--*ghi", "abcdef", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:starts-with ( (), "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true(). (The second argument contains only ignorable collation units and is equivalent to the zero-length string.)

The expression fn:starts-with ( "-abcdefghi", "-abc", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

Returns true if the string $arg1 contains $arg2 as a trailing substring, taking collations into account.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI.

If the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, 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 this function is determined according to the rules in .

The function returns an xs:boolean indicating whether or not the value of $arg1 ends with a sequence of collation units that provides a match to the collation units of $arg2 according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in .

The expression fn:ends-with ( "tattoo", "tattoo") returns true().

The expression fn:ends-with ( "tattoo", "atto") returns false().

The expression fn:ends-with ((), ()) returns true().

The expression fn:ends-with ( "abcdefghi", "-g-h-i-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:ends-with ( "abcd***e---f*--*ghi", "defghi", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:ends-with ( "abcd***e---f*--*ghi", "defghi", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

The expression fn:ends-with ( (), "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true(). (The second argument contains only ignorable collation units and is equivalent to the zero-length string.)

The expression fn:ends-with ( "abcdefghi", "ghi-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns true().

Returns the part of $arg1 that precedes the first occurrence of $arg2, taking collations into account.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI.

If the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, 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 this function is determined according to the rules in .

The function returns the substring of the value of $arg1 that precedes in the value of $arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in .

The expression fn:substring-before ( "tattoo", "attoo") returns "t".

The expression fn:substring-before ( "tattoo", "tatto") returns "".

The expression fn:substring-before ((), ()) returns "".

The expression fn:substring-before ( "abcdefghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "abc".

The expression fn:substring-before ( "abc--d-e-fghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "abc--".

The expression fn:substring-before ( "a*b*c*d*e*f*g*h*i*", "***cde", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "a*b*".

The expression fn:substring-before ( "Eureka!", "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "". (The second argument contains only ignorable collation units and is equivalent to the zero-length string.)

Returns the part of $arg1 that follows the first occurrence of $arg2, taking collations into account.

The two-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations.

The three-argument form of this function is deterministic, context-dependent, and focus-independent. It depends on collations, and static base URI.

If the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, 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 this function is determined according to the rules in .

The function returns the substring of the value of $arg1 that follows in the value of $arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used.

A dynamic error may be raised if the specified collation does not support collation units.

The collation used in these examples, http://example.com/CollationA is a collation in which both "-" and "*" are ignorable collation units.

"Ignorable collation unit" is equivalent to "ignorable collation element" in .

The expression fn:substring-after("tattoo", "tat") returns "too".

The expression fn:substring-after("tattoo", "tattoo") returns "".

The expression fn:substring-after((), ()) returns "".

The expression fn:substring-after("abcdefghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "fghi".

The expression fn:substring-after("abc--d-e-fghi", "--d-e-", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "-fghi".

The expression fn:substring-after ( "a*b*c*d*e*f*g*h*i*", "***cde***", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "*f*g*h*i*".

The expression fn:substring-after ( "Eureka!", "--***-*---", "http://www.w3.org/2013/collation/UCA?lang=en;alternate=blanked;strength=primary") returns "Eureka!". (The second argument contains only ignorable collation units and is equivalent to the zero-length string.)

Returns true if the supplied string matches a given regular expression.

This function is deterministic, context-independent, and focus-independent.

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 .

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

The function returns true if $input or some substring of $input matches the regular expression supplied as $pattern. Otherwise, the function returns false. The matching rules are influenced by the value of $flags if present.

A dynamic error is raised if the value of $pattern is invalid according to the rules described in .

A dynamic error is raised if the value of $flags is invalid according to the rules described in .

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 multi-line mode).

This is different from the behavior of patterns in , where regular expressions are implicitly anchored.

Regular expression matching is defined on the basis of Unicode code points; it takes no account of collations.

The expression fn:matches("abracadabra", "bra") returns true().

The expression fn:matches("abracadabra", "^a.*a$") returns true().

The expression fn:matches("abracadabra", "^bra") returns false().

Given the source document:

the following function calls produce the following results, with the poem element as the context node:

The expression fn:matches($poem, "Kaum.*krähen") returns false().

The expression fn:matches($poem, "Kaum.*krähen", "s") returns true().

The expression fn:matches($poem, "^Kaum.*gesehen,$", "m") returns true().

The expression fn:matches($poem, "^Kaum.*gesehen,$") returns false().

The expression fn:matches($poem, "kiki", "i") returns true().

Returns a string produced from the input string by replacing any substrings that match a given regular expression with a supplied replacement string.

This function is deterministic, context-independent, and focus-independent.

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 .

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.

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.

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.

If the q flag is present, the replacement string is used as is.

Otherwise, within the $replacement string, a variable $N may be used to refer to the substring captured by the Nth parenthesized sub-expression in the regular expression. For each match of the pattern, these variables are assigned the value of the content matched by the relevant sub-expression, and the modified replacement string is then substituted for the characters in $input that matched the pattern. $0 refers to the substring captured by the regular expression as a whole.

More specifically, the rules are as follows, where S is the number of parenthesized sub-expressions in the regular expression, and N is the decimal number formed by taking all the digits that consecutively follow the $ character:

For example, if the replacement string is "$23" and there are 5 substrings, the result contains the value of the substring that matches the second sub-expression, followed by the digit 3.

Unless the q flag is used, a literal $ character within the replacement string must be written as \$, and a literal \ character must be written as \\.

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:

A dynamic error is raised if the value of $pattern is invalid according to the rules described in section .

A dynamic error is raised if the value of $flags is invalid according to the rules described in section .

A dynamic error is raised 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.

In the absence of the q flag, a dynamic error is raised if the value of $replacement contains a dollar sign ($) character that is not immediately followed by a digit 0-9 and not immediately preceded by a backslash (\).

In the absence of the q flag, a dynamic error is raised if the value of $replacement contains a backslash (\) character that is not part of a \\ pair, unless it is immediately followed by a dollar sign ($) character.

If the input string contains no substring that matches the regular expression, the result of the function is a single string identical to the input string.

The expression fn:replace("abracadabra", "bra", "*") returns "a*cada*".

The expression fn:replace("abracadabra", "a.*a", "*") returns "*".

The expression fn:replace("abracadabra", "a.*?a", "*") returns "*c*bra".

The expression fn:replace("abracadabra", "a", "") returns "brcdbr".

The expression fn:replace("abracadabra", "a(.)", "a$1$1") returns "abbraccaddabbra".

The expression fn:replace("abracadabra", ".*?", "$1") raises an error, because the pattern matches the zero-length string

The expression fn:replace("AAAA", "A+", "b") returns "b".

The expression fn:replace("AAAA", "A+?", "b") returns "bbbb".

The expression fn:replace("darted", "^(.*?)d(.*)$", "$1c$2") returns "carted". (The first d is replaced.)

Returns a sequence of strings constructed by splitting the input wherever a separator is found; the separator is any substring that matches a given regular expression.

This function is deterministic, context-independent, and focus-independent.

The one-argument form of this function splits the supplied string at whitespace boundaries. More specifically, calling fn:tokenize($input) is equivalent to calling fn:tokenize(fn:normalize-space($input), ' ')) where the second argument is a single space character (x20).

The effect of calling the two-argument form of this function (omitting the argument $flags) is the same as the effect of calling the three-argument version with the $flags argument set to a zero-length string. Flags are defined in .

The following rules apply to the three-argument form of the function:

A dynamic error is raised if the value of $pattern is invalid according to the rules described in section .

A dynamic error is raised if the value of $flags is invalid according to the rules described in section .

A dynamic error is raised if the supplied $pattern matches a zero-length string, that is, if fn:matches("", $pattern, $flags) returns true.

If the input string is not zero length, and no separators are found in the input string, the result of the function is a single string identical to the input string.

The one-argument form of the function has a similar effect to the two-argument form with \s+ as the separator pattern, except that the one-argument form strips leading and trailing whitespace, whereas the two-argument form delivers an extra zero-length token if leading or trailing whitespace is present.

The function returns no information about the separators that were found in the string. If this information is required, the fn:analyze-string function can be used instead.

The separator used by the one-argument form of the function is any sequence of tab (x09), newline (x0A), carriage return (x0D) or space (x20) characters. This is the same as the separator recognized by list-valued attributes as defined in XSD. It is not the same as the separator recognized by list-valued attributes in HTML5, which also treats form-feed (x0C) as whitespace. If it is necessary to treat form-feed as a separator, an explicit separator pattern should be used.

The expression fn:tokenize(" red green blue ") returns ("red", "green", "blue").

The expression fn:tokenize("The cat sat on the mat", "\s+") returns ("The", "cat", "sat", "on", "the", "mat").

The expression fn:tokenize(" red green blue ", "\s+") returns ("", "red", "green", "blue", "").

The expression fn:tokenize("1, 15, 24, 50", ",\s*") returns ("1", "15", "24", "50").

The expression fn:tokenize("1,15,,24,50,", ",") returns ("1", "15", "", "24", "50", "").

fn:tokenize("abba", ".?") raises the dynamic error .

The expression fn:tokenize("Some unparsed <br> HTML <BR> text", "\s*<br>\s*", "i") returns ("Some unparsed", "HTML", "text").