Signature

math:acos($arg as xs:double?) as xs:double?

Usage Notes

This function returns the arc cosine of $arg. The result is an angle in radians, in the range zero to +π, inclusive.

Special Cases

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

• If the absolute value of $arg is greater than one or NaN, the function returns NaN.

• This function is new in XQuery 3.0.

Examples

Related Functions

math:asin, math:atan, math:atan2, math:cos, math:sin, math:tan

Signature

adjust-date-to-timezone($arg as xs:date?,
                        $timezone as xs:dayTimeDuration?) as xs:date?

Usage Notes

The behavior of this function depends on whether $arg already has a time zone and on the value of the time zone provided. Table A-2 shows the possible combinations.

The $timezone is expressed as an xs:dayTimeDuration, for example, -PT5H for US Eastern Standard Time. If $timezone is the empty sequence, it is assumed that the desired result is a date value that is in no time zone. If $timezone is omitted from the function call (as opposed to being the empty sequence) it is assumed to be the implicit time zone.

The $arg date is assumed for the sake of time zone calculation to be just like an xs:dateTime value whose time is midnight (00:00:00). If $arg does not already have a time zone, its date part stays the same, but it is now associated with the specified time zone.

If $arg already has a time zone, the value is adjusted to that time zone. This may change the actual date in some cases. For example, if $arg is 2015-02-15-05:00, and $timezone is -PT8H, the resulting date is 2015-02-14-08:00, which is the day before. This is because $arg is considered to be 2015-02-15T00:00:00-05:00, which is equivalent to 2015-02-14T21:00:00-08:00. In other words, midnight in the U.S. Eastern time zone is equal to 9 P.M. the day before in the U.S. Pacific time zone.

For more information on time zones in XQuery, see “Time Zones”.

Special Cases

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

• If the value of $timezone is not between -PT14H and PT14H, inclusive, or if it does not have an integral number of minutes (i.e., the number of seconds is not 0), error FODT0003 is raised.

Examples

These six examples represent the six scenarios described in Table A-2. They assume an implicit time zone of -05:00.

Related Functions

adjust-dateTime-to-timezone, adjust-time-to-timezone

Signature

adjust-time-to-timezone($arg as xs:time?,
                        $timezone as xs:dayTimeDuration?) as xs:time?

Usage Notes

The behavior of this function is identical to that of adjust-date-to-timezone, described in Table A-2, except that the actual time, not midnight, is used.

Special Cases

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

• If the value of $timezone is not between -PT14H and PT14H, inclusive, or if it does not have an integral number of minutes (i.e., the number of seconds is not 0), error FODT0003 is raised.

Examples

The first six examples represent the six scenarios described in Table A-2. They assume an implicit time zone of -05:00.

Related Functions

adjust-dateTime-to-timezone, adjust-date-to-timezone

Signature

analyze-string($input as xs:string?, $pattern as xs:string, 
               $flags as xs:string) as element(fn:analyze-string-result)

Usage Notes

This function captures parts of a string $input that do and do not match a regular expression $pattern. The result is an XML element named fn:analyze-string-result that contains elements called fn:match for each part of a string that matches the regular expression, and fn:non-match for each part that does not match.

This function is useful if you need to keep both the matching and non-matching parts of a string. If you want to discard the matching parts (e.g., because they represent a delimiter), it is simpler to use the tokenize function instead.

The fn:match element can contain fn:group elements in the case that parentheses are used in the regular expression. This allows you to query which parts of the matching string matched specific parts of the regular expression. fn:group elements can themselves contain other fn:group elements, in the case where there are parentheses within parentheses in the regular expression. Each fn:group has an nr attribute that indicates which group it is, based on its starting position in the regular expression, starting with 1. The fn:non-match, on the other hand, will always contain only text with no child elements.

The $flags parameter allows for additional options in the interpretation of the regular expression. It is discussed in detail in “Using Flags”.

Special Cases

• If $pattern is not a valid regular expression, error FORX0002 is raised.

• If $flags contains unsupported options, error FORX0001 is raised.

• If the entire $pattern matches a zero-length string, for example, q?, error FORX0003 is raised.

• If $input is the empty sequence or a zero-length string, the function returns an empty fn:analyze-string-result element.

• This function is new in XQuery 3.0.

Examples

Indentation is added to the example results for clarity. In reality, the whitespace would not be included.

Related Functions

tokenize, matches

Signature

array:append($array as array(*), $appendage as item()*) as array(*)

Usage Notes

This function returns a new array with all the members of $array, plus an additional member at the end whose value is $appendage. If $appendage is a sequence of multiple items, each item does not become a member, but rather a single member is added whose value is the sequence of all the items in $appendage.

Special Cases

• If $appendage is an array, the entire array becomes a single member of the outer array; the two arrays are not merged. The array:join function can be used to merge two arrays.

• If $appendage is the empty sequence, a member is still added to the array, whose value is the empty sequence.

• This function is new in XQuery 3.1.

Examples

The examples assume this variable declaration:

declare variable $array1 := ["abc", "def", "ghi"];

Related Functions

array:join, array:insert-before, array:put

Signature

apply($function as function(*), $array as array(*)) as item()*

Usage Notes

This function calls the function $function, using the members of the $array as arguments, in order. Calling the apply function is the same as making a dynamic function call. For example:

let $f := upper-case#1
return apply($f, ["a"])

is equivalent to:

let $f := upper-case#1
return $f("a")

Therefore, this function is most useful for dynamic programming, when the arity of the function is not known in advance.

Special Cases

• If the arity of the function in $function is not the same as the size of the array $array, error FOAP0001 is raised.

• This function is new in XQuery 3.1, and only supported by implementations that support higher-order functions. If the function is called by a 3.1 processor but is not supported, error XPST0017 is raised.

Examples

Related Functions

function-arity, function-name, function-lookup

Signature

math:asin($arg as xs:double?) as xs:double?

Usage Notes

This function returns the arc sine of $arg. The result is an angle in radians, in the range -π/2 to +π/2, inclusive.

Special Cases

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

• If $arg is zero (positive or negative), the function returns $arg.

• If $arg is NaN, or if its absolute value is greater than one, the function returns NaN.

• This function is new in XQuery 3.0.

Examples

Related Functions

math:acos, math:atan, math:atan2, math:cos, math:sin, math:tan

Signature

math:atan($arg as xs:double?) as xs:double?

Usage Notes

This function returns the arc tangent of $arg. The result is an angle in radians, is in the range -π/2 to +π/2, inclusive.

Special Cases

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

• If $arg is zero (positive or negative), the function returns $arg.

• If $arg is NaN, the function returns NaN.

• This function is new in XQuery 3.0.

Examples

Related Functions

math:acos, math:asin, math:atan2, math:cos, math:sin, math:tan

Signature

math:atan2($y as xs:double, $x as xs:double) as xs:double

Usage Notes

This function returns the angle, in radians, subtended at the origin by the point on a plane with coordinates ($x, $y) and the positive x-axis. The result is in the range -π to +π, inclusive.

If $y is positive and $x is positive and finite, then the value of atan2($y, $x) is atan($y div $x). If $y is positive and $x is negative and finite, then the value of atan2($y, $x) is π - atan($y div $x).

Special Cases

• If either argument is NaN, the function returns NaN.

• This function is new in XQuery 3.0.

Examples

Related Functions

math:acos, math:asin, math:atan, math:cos, math:sin, math:tan

Signature

available-environment-variables() as xs:string*

Usage Notes

This function returns a list of the names of the environment variables that are available in the dynamic context. The result is a list of strings, in an implementation-dependent order, with no duplicates. Each name in the returned list can be passed to the environment-variable function to return its value. The definition of environment variable is processor- and platform-dependent.

Special Cases

• If access to environment variables has been disabled by the processor, for example, for security reasons, the function will return the empty sequence.

• This function is new in XQuery 3.0.

Example

When evaluating the function call available-environment-variables() in a Windows environment, a standalone XQuery processor might return a list of Windows environment variable names such as JAVA_HOME, COMPUTERNAME, and CLASSPATH.

Related Function

environment-variable

Signature

avg($arg as xs:anyAtomicType*) as xs:anyAtomicType?

Usage Notes

This function finds the average of the items in $arg, which can contain a mixture of numeric and untyped values. Numeric values are promoted as necessary to make them all the same type. Untyped values are cast as numeric xs:double values.

The function can also be used on duration values, so the $arg sequence can contain all xs:yearMonthDuration values or all xs:dayTimeDuration values (but not a mixture of the two). The $arg sequence cannot contain a mixture of duration and numeric values.

Special care should be taken with any “missing” values when using the avg function. This is described further in “Counting “Missing” Values”.

Special Cases

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

• If $arg contains untyped values that cannot be cast to numbers, error FORG0001 is raised.

• If $arg contains typed values that are not numeric or duration values, or values that have a variety of types, error FORG0006 is raised.

• If $arg contains values that are NaN, the function returns NaN.

Examples

Related Functions

sum, count

Signature

base-uri($arg as node()?) as xs:anyURI?

Usage Notes

This function returns the base URI of a node. The essential purpose of a base URI is to establish a baseline for resolving any relative URIs in the content.

$arg may be any kind of node. If $arg is a document node, this function usually returns the URI from which the document was retrieved, if it is known. This can also be achieved by using the document-uri function.

An example where the base URI might not be known is where the document is created by parsing an anonymous input stream. Check your processor’s documentation for details of how to supply a base URI in such cases. An example of where the base URI might be different from the URI used to retrieve it is in the case of a multipart MIME message.

If $arg is an element, the function returns the value of its xml:base attribute, if any, or the xml:base attribute of its nearest ancestor. If no xml:base attributes appear among its ancestors, it defaults to the base URI of the document node. If the original document consisted of multiple external entities (files), the base URI would be the URI of the containing entity.

If $arg is any other kind of node, the function returns the same value as if the argument were its parent element or document.

For more information on URIs, see “Working with URIs”.

Special Cases

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

• If $arg is not provided, the function returns the base URI of the current context item. Note that this is not the same as the base URI from the static context, which is retrieved using the static-base-uri function. In this case, it is an error if the context item is absent (XPDY0002) or not a node (XPTY0004).

• If no base URI can be found, for example because the element node has no base URI and does not have a document node as its root, the function returns the empty sequence.

Examples

These examples assume that the variable $cats is bound to the input document http://datypic.com/input/cats.xml shown in Example A-1, as follows:

declare variable $cats := doc("http://datypic.com/input/cats.xml");

<catalogs>
  <catalog name="ACC" xml:base="http://datypic.com/ACC/">
    <product number="443" href="prod443.html"/>
    <product number="563" href="prod563.html"/>
  </catalog>
  <catalog name="WMN" xml:base="http://datypic.com/WMN/">
    <product number="557" href="prod557.html"/>
  </catalog>
</catalogs>

Related Functions

static-base-uri, resolve-uri, document-uri

Signature

boolean($arg as item()*) as xs:boolean

Usage Notes

This function calculates the effective boolean value of a sequence (that is, any value). For more information, see “Effective Boolean Value”.

In most cases, it is unnecessary to call this function because the effective boolean value is calculated automatically in many expressions, including conditional and logical expressions, where clauses, and predicates.

This boolean function, which can also be written as fn:boolean, should not be confused with the xs:boolean constructor, which casts a value to xs:boolean. In some cases, they return different results, namely when $arg is:

• A single node that contains the value false (xs:boolean returns false because it atomizes the node, while fn:boolean returns true)

• The string value false (xs:boolean returns false, fn:boolean returns true)

• A zero-length string, or any string other than true, false, 0, or 1 (xs:boolean raises an error, fn:boolean returns false if it’s a zero-length string; otherwise, true)

• A sequence of more than one node (xs:boolean raises an error, fn:boolean returns true)

Special Case

• If the effective boolean value of $arg cannot be determined, for example because $arg is a sequence of multiple atomic values or an array, error FORG0006 is raised.

Examples

Related Functions

true, false, empty, exists

Signature

ceiling($arg as xs:numeric?) as xs:numeric?

Usage Notes

This function returns the smallest whole number that is not less than $arg. It returns a numeric value of type xs:float, xs:double, xs:decimal, or xs:integer, depending on which type the argument is derived from. If $arg is untyped, it is cast to xs:double.

Special Cases

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

• If $arg is greater than -1 but less than zero, the function may return 0 or -0 (it is implementation-dependent).

• If $arg is one of the values 0, -0, NaN, INF, or -INF, the function returns this same value.

Examples

Related Functions

floor, round, round-half-to-even

Signature

codepoint-equal($comparand1 as xs:string?,
                $comparand2 as xs:string?) as xs:boolean?

Usage Notes

This function determines whether $comparand1 and $comparand2 have the same Unicode codepoints, in the same order. This is similar to calling the compare function with the simple collation http://www.w3.org/2005/xpath-functions/collation/codepoint, except that the result is a Boolean value. It is also possible to compare strings using comparison operators = or eq.

Special Case

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

Examples

Related Function

compare

Signature

codepoints-to-string($arg as xs:integer*) as xs:string

Usage Notes

This function accepts a sequence of integers $arg that represent Unicode codepoint values. It converts each integer to a character, then concatenates all the characters into a single string.

Special Cases

• If one or more of the $arg integers does not refer to a valid XML character, error FOCH0001 is raised.

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

Examples

Related Function

string-to-codepoints

Signature

collation-key($key as xs:string, $collation as xs:string) as xs:base64Binary

Usage Notes

Collations are used to specify the order in which characters should be compared and sorted. The collation-key function applies a collation to a string, generating an identifier for that string so that it can be compared or sorted with other strings. How (and even whether) a collation key is generated is implementation-dependent. The key is a binary value. A collation key will always be generated in such a way that two strings that are equal according to the collation will have the same collation key returned by this function, and two strings that are not equal will have different collation keys.

This function is most useful for comparing keys in maps. If your intent is to compare strings according to a collation, you may find it more convenient to use the compare function with its third $collation argument. If you are sorting strings, you can specify a predetermined collation in an order by clause of a FLWOR expression. If you need to dynamically choose a collation, the collation-key function may be helpful. More information can be found in “Collations”.

Special Cases

• If $collation is a relative URI, it is resolved against the static base URI.

• If $collation is omitted, the default collation is used.

• If the collation does not support the generation of collation keys, error FOCH0004 is raised.

• This function is new in XQuery 3.1.

Example

Given a hypothetical collation http://datypic.com/collation/custom that collapses whitespace when comparing strings, you could write the following query:

let $coll := "http://datypic.com/collation/custom"
let $m := map{collation-key("A", $coll): "first", 
              collation-key("B", $coll): "second"}
return $m(collation-key(" A ", $coll))

which would return the value "first". It would compare "A" with " A " and find them equal according to the specified collation. The collation-key function would need to be called both when creating the map and when retrieving entries.

Signature

collection($arg as xs:string?) as item()*

Usage Notes

This function returns a collection, which is a sequence of items, identified by a URI. In practice, a collection is most often a sequence of documents that are organized so that they can be queried or managed together.

Exactly how the collection URI ($arg) is associated with the items is defined by the implementation. Most XML database implementations allow you to define collections (and add documents to them) using the product’s user interface or implementation-specific functions. Saxon, on the other hand, allows you to specify a directory where the input documents reside, optionally with parameters. For example:

collection("file:///C:/Users/PW/My%20Documents/?select=*.xml;recurse=yes")

returns the collection of documents in the directory C:/Users/PW/My Documents/ whose file extension is .xml, including subdirectories.

If $arg is a relative URI, it is resolved based on the static base URI. The static base URI may be set by the processor outside the scope of the query, or it may be declared in the query prolog.

By default, the collection function is deterministic. This means that if you call it more than once with the same argument, within the same query, the result is the same, even if somehow the resources associated with the URI have changed. Implementations may, however, offer users a way to indicate that determinism is not important, for performance reasons.

Special Cases

• If $arg is not a collection URI known to the processor, error FODC0002 is raised.

• If $arg is a collection URI known to the processor, but it is empty, the empty sequence is returned.

• If a resource in the collection cannot be retrieved or parsed, for example, because it does not reference a resource, or the resource is not well-formed XML, error FODC0002 is raised.

• If $arg is a relative URI and there is no static base URI to use to resolve the relative URI, error FODC0002 is raised.

• If $arg is not provided or is the empty sequence, the function returns the default collection. If the default collection is absent, error FODC0002 is raised.

• If $arg is not a lexically valid URI, error FODC0004 may be raised.

• If the processor cannot return deterministic results, error FODC0003 is raised.

Example

The expression collection("myXMLdocs") might return all the document nodes of the XML documents associated with the collection myXMLdocs.

Related Functions

doc , uri-collection

Signature

compare($comparand1 as xs:string?, $comparand2 as xs:string?,
        $collation as xs:string) as xs:integer?

Usage Notes

This function returns one of the values:

• -1 if $comparand1 is less than $comparand2

• 0 if $comparand1 is equal to $comparand2

• 1 if $comparand1 is greater than $comparand2

A comparand is greater than the other comparand if it starts with the other comparand and has additional characters. For example, abc is greater than ab.

Comparison operators (=, !=, <, <=, >, and >=) can also be used to compare strings, and you may find the syntax more convenient. However, compare is also useful if you want to take different action in each of the three result cases. Also, if you need to use a specific collation other than the default, you must use the compare function. More information can be found in “Collations”.

Special Cases

• If either comparand is the empty sequence, the function returns the empty sequence.

• If $collation is provided, the comparison uses that collation; otherwise, it uses the default collation. For more information, see “Collations”.

Examples

These examples assume that no default collation is specified.

The fifth example in the table shows that when using the simple codepoint collation, a lowercase a comes after an uppercase B. If you do not want case to be taken into account when comparing strings, convert the strings to uppercase first, as shown in the sixth example. Alternatively, you could use a case-insensitive collation.

Related Function

codepoint-equal

Signature

concat($arg1 as xs:anyAtomicType?,
       $arg2 as xs:anyAtomicType?, ...) as xs:string

Usage Notes

This function requires at least two arguments (which can be the empty sequence) and accepts an unlimited number of additional arguments. This is the only XQuery function that has a flexible number of arguments, for compatibility with XPath 1.0. The function is also unusual in that arguments that are not of type xs:string will be cast to xs:string.

The function does not accept a sequence of multiple values, just individual atomic values (or nodes) passed as separate arguments. To concatenate a sequence of multiple values, use the string-join function instead.

Another alternative to the concat function, starting in version 3.0, is the string concatenation operator ||, described in “Concatenating Strings”.

Special Case

• If an argument is the empty sequence, it is treated as a zero-length string.

Examples

Related Function

string-join

Signature

contains($arg1 as xs:string?, $arg2 as xs:string?,
         $collation as xs:string) as xs:boolean

Usage Notes

This function returns true if $arg1 contains the characters of $arg2 anywhere in its contents, including at the beginning or end. Note that contains does not test whether a sequence of multiple strings contains a given value. For that, use the = operator.

Special Cases

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

• If $arg1 is a zero-length string or the empty sequence, but $arg2 is not, the function returns false.

• If $collation is provided, the comparison uses that collation; otherwise, it uses the default collation. For more information, see “Collations”.

Examples

Related Functions

contains-token, starts-with, ends-with, matches

Signature

map:contains($map as map(*), $key as xs:anyAtomicType) as xs:boolean

Usage Notes

This function returns true if $map contains an entry whose key is $key. The $key value is compared to the map’s keys in a type-aware manner, e.g., the string “1” and the integer 1 are not considered the same value.

Special Cases

• If $key has a type that is not comparable to the types of the keys of the map, for example $key is a string but the keys of $map are integers, the function returns false rather than returning an error.

• If $key is untyped, it is compared to the keys of the map as a string value.

• When strings are compared, they are compared as Unicode codepoints only; the default collation is not used.

• This function is new in XQuery 3.1.

Examples

The examples assume these variable declarations:

declare variable $map1 := map {1:"first", 2:"second", 3:"third", 4:()};
declare variable $map2 := map {};

Related Functions

map:find , map:keys, map:get, collation-key

Signature

contains-token($input as xs:string*, $token as xs:string,
               $collation as xs:string) as xs:boolean

Usage Notes

This function returns true if at least one of the strings in $input contains the characters of $token surrounded by whitespace (or the beginning or ending of the string). If $token has leading or trailing whitespace, it is trimmed before doing the evaluation.

Special Cases

• The function returns false if $input is the empty sequence, a zero-length string, an all-whitespace string, or a string that contains interior whitespace.

• If $collation is provided, the comparison uses that collation; otherwise, it uses the default collation. For more information, see “Collations”.

• This function is new in XQuery 3.1.

Examples

Related Functions

contains, starts-with, ends-with, matches

Signature

math:cos($θ as xs:double?) as xs:double?

Usage Notes

This function finds the cosine of $θ, which is an angle in radians. The result is in the range -1.0e0 to +1.0e0, inclusive.

Special Cases

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

• If $θ is INF, -INF, or NaN, the function returns NaN.

• This function is new in XQuery 3.0.

Examples

Related Functions

math:acos, math:asin, math:atan, math:atan2, math:sin, math:tan

Signature

count($arg as item()*) as xs:integer

Usage Notes

This function returns the number of items in a sequence as an xs:integer.

To test whether or not the number of items in a sequence is zero, use the exists or empty function instead. Depending on your processor’s optimizer, exists($x) may be more efficient than count($x) = 0.

Special Case

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

Examples

The third example shows that the count function can be combined with the distinct-values function to count only distinct values.

Related Functions

array:size , map:size , string-length

Signature

current-date() as xs:date

Usage Notes

This function takes no parameters and returns the current date, with the implicit time zone. To eliminate the time zone from the value, you can call adjust-date-to-timezone with the empty sequence as the second argument, as in:

adjust-date-to-timezone(current-date(), ())

Example

current-date() might return the xs:date value 2015-04-10-05:00, which is April 10, 2015 in the -05:00 time zone.

Related Functions

current-dateTime, current-time

Signature

current-dateTime() as xs:dateTimeStamp

Usage Notes

This function takes no parameters and returns the current date and time, with the implicit time zone. If the function is called multiple times within the same query, it returns the same value every time. To eliminate the time zone from the value, you can call adjust-dateTime-to-timezone with the empty sequence as the second argument, as in:

adjust-dateTime-to-timezone(current-dateTime(), ())

This function is deterministic, which means that multiple calls to current-dateTime in the same query execution will return the same value.

Example

current-dateTime() might return the xs:dateTime value 2015-04-10T13:40:23.83-05:00.

Related Functions

current-date, current-time

Signature

current-time() as xs:time

Usage Notes

This function takes no parameters and returns the current time, with the implicit time zone. If the function is called multiple times within the same query, it returns the same value every time. To eliminate the time zone from the value, you can call adjust-time-to-timezone with the empty sequence as the second argument, as in:

adjust-time-to-timezone(current-time(), ())

This function is deterministic, which means that multiple calls to current-time in the same query execution will return the same value.

Example

current-time() might return the xs:time value 13:40:23.83-05:00.

Related Functions

current-dateTime, current-date

Signature

dateTime($arg1 as xs:date?, $arg2 as xs:time?) as xs:dateTime?

Usage Notes

This function constructs an xs:dateTime value from an xs:date value and an xs:time value. It should not be confused with the xs:dateTime constructor, which accepts a single argument that includes the date and time.

Time zone is taken into account when constructing the date/time. If neither the date nor the time has a time zone, the result has no time zone. If only one of the arguments has a time zone, or they both have the same time zone, the result has that time zone.

Special Cases

• If the two arguments have different time zones, error FORG0008 is raised.

• If either of the two arguments is the empty sequence, the function returns the empty sequence.

Example

dateTime(xs:date("2015-08-15"), xs:time("12:30:45-05:00")) returns the xs:dateTime value 2015-08-15T12:30:45-05:00.

Signature

day-from-date($arg as xs:date?) as xs:integer?

Usage Notes

This function returns the day portion from an xs:date value as an integer between 1 and 31, inclusive.

Special Case

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

Example

day-from-date(xs:date("2015-08-15")) returns 15.

Related Function

day-from-dateTime

Signature

day-from-dateTime($arg as xs:dateTime?) as xs:integer?

Usage Notes

This function returns the day portion from an xs:dateTime value as an integer between 1 and 31, inclusive.

Special Case

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

Example

day-from-dateTime(xs:dateTime("2015-08-15T10:30:23")) returns 15.

Related Function

day-from-date

Signature

deep-equal($parameter1 as item()*, $parameter2 as item()*,
           $collation as xs:string) as xs:boolean

Usage Notes

This function returns true if the $parameter1 and $parameter2 sequences contain the same values, in the same order.

Atomic values are compared based on their typed values, using the eq operator. If two atomic values cannot be compared (e.g., because one is a number and the other is a string), the function returns false rather than raising an error.

The comparison of nodes takes into account the descendants and attributes. In order to be considered deep-equal, two nodes must:

• Have the same qualified name.

• Have the same node kind.

• If they are elements, have the exact same attributes with the same qualified names and the same values (possibly in a different order).

• If they are attributes or elements with simple content (no children), their typed values must be equal. For example, 2 is considered the same as 02 if they are both typed as integers, but not if they are both strings.

• If they are elements with children, have element children and text nodes in the same order, that are themselves deep-equal.

• If they are document nodes, have element and text children in the same order, that are themselves deep-equal.

• If they are processing-instruction nodes, have the same name (target) and the exact same string value.

• If they are text or comment nodes, have the exact same string value.

The two nodes do not have to have the same type, parent, or base URI. Namespace declarations are considered only to the extent that they affect element and attribute names or values typed as QNames; “unused” namespaces are ignored.

When comparing two element or document nodes, child comments and processing instructions are ignored. However, the presence of a comment that splits a text node in two will cause the text nodes to be unequal. Whitespace-only text nodes are considered significant.

The deep-equal function can also be used to compare arrays and maps. Two arrays are deep-equal if all of their members are deep-equal (in the same order). Two maps are deep-equal if they have all the same entries (with equal keys and values), regardless of order.

Special Cases

• If both $parameter1 and $parameter2 are the empty sequence, the function returns true.

• If only one of $parameter1 or $parameter2 is the empty sequence, the function returns false.

• If $collation is provided, the comparison uses that collation; otherwise, it uses the default collation. For more information, see “Collations”.

• In the context of this function, NaN is considered equal to itself. This is to ensure that a node is always deep-equal to itself, even if some descendant has a typed value of NaN.

• If $parameter1 or $parameter2 contains a function item other than an array or map, error FOTY0015 is raised.

Examples

The examples below assume that the variables $prod1 and $prod2 are bound to the two product elements as shown:

declare variable $prod1 := <product dept="MEN" id="P123">
  <number>784</number>
</product>;
declare variable $prod2 := <product id="P123" dept="MEN"><!--comment-->
  <number>784</number>
</product>;

Signature

default-collation() as xs:string

Usage Notes

This function returns the default collation that is used in most operations where a collation is not explicitly specified. If no default collation is specified in the query prolog, the function returns the system default collation. If no system default collation is provided, the function returns a value representing the Unicode Codepoint Collation, http://www.w3.org/2005/xpath-functions/collation/codepoint. See “Collations” for more information.

Example

default-collation() might return http://datypic.com/collation/custom if that is the name of the default collation declared in the query prolog.

Signature

default-language() as xs:language

Usage Notes

This function returns the default language used by the format-date, format-dateTime, format-time, and format-integer functions.

Example

default-language() might return en if English is the default language used by the implementation.

Signature

distinct-values($arg as xs:anyAtomicType*,
                $collation as xs:string) as xs:anyAtomicType*

Usage Notes

This function returns a sequence of unique atomic values from $arg. Values are compared based on their typed value. Values of different numeric types may be equal—for example, the xs:integer value 1 is equal to the xs:decimal value 1.0, so the function only returns one of these values. If two values have incomparable types, e.g., xs:string and xs:integer, they are considered distinct, and no error is raised. Untyped values are treated like strings.

The $arg sequence can contain atomic values or nodes, or a combination of the two. The nodes in the sequence have their typed values extracted using the usual function conversion rules. This means that only the contents of the nodes are compared, not any other properties of the nodes (for example, their names or identities). To get distinct nodes by identity instead, you can simply use the expression $seq/., which re-sorts the nodes and removes duplicates.

Because XQuery does not specify which of the duplicates to exclude, there may be some variation among implementations in the order and type of items in the result sequence.

Special Cases

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

• If $arg contains more than one NaN value, only one of them is returned (even though one NaN value is technically not equal to other NaN values).

• Dates and times with no time zone component are assumed to be in the implicit time zone.

• If $collation is provided, the function uses that collation to compare string values; otherwise, it uses the default collation. For more information, see “Collations”.

• If $arg contains an element whose schema type has element-only content, the type error FOTY0012 is raised, because such nodes do not have typed values.

Examples

Signature

doc($uri as xs:string?) as document-node()?

Usage Notes

This function returns the document node of the resource associated with the URI $uri. For example:

doc("http://datypic.com/input/order.xml")

returns the document node of the document whose URI is http://datypic.com/input/order.xml. The doc function can be combined with a path expression to retrieve specific children, as in:

doc("catalog.xml")/catalog/product

Note that the doc function returns the document node, not the outermost element node. Therefore, you need to include the outermost element node in your path (catalog in the previous example).

The rules for how the function resolves the URI in $uri are described in “Resolving URIs of input documents”.

By default, the doc function is deterministic, meaning that it returns the same results each time it is called within a query. If you call the doc function more than once with the same argument, within the same query, the result is the same, even if somehow the resource at $uri has changed. Furthermore, the document nodes retrieved from each of these calls are identical to each other. Implementations may, however, offer users a way to indicate that determinism is not important, for performance reasons.

Special Cases

• If $uri is the empty sequence, the function returns the empty sequence.

• If $uri is not a lexically valid URI, error FODC0005 may be raised.

• If the resource cannot be retrieved or parsed, for example, because it does not reference a resource, or the resource is not well-formed XML, the behavior is implementation-defined. It may result in error FODC0002, or in some other error handling behavior (such as a default document being opened).

• If the processor cannot return deterministic results, error FODC0003 is raised.

Example

Depending on the processor and on the location of the file, any of the following might be used to return the document node of the order document:

• doc("order.xml")

• doc("http://datypic.com/input/order.xml")

• doc("file:///C:/Documents%20and%20Settings/my%20order.xml")

Related Functions

collection, doc-available, document-uri, parse-xml, parse-xml-fragment, json-to-xml

Signature

doc-available($uri as xs:string?) as xs:boolean

Usage Notes

This function provides a way to avoid errors returned by the doc function if a document is not available. This function will return true if calling the doc function on the same URI will result in a document node. It will return false if the doc function will not return a document node.

Special Case

• If $uri is the empty sequence or is not a lexically valid or retrievable URI, the function returns false.

Example

This query will check if an XML document named http://datypic.com/new_order.xml is available:

if (doc-available("http://datypic.com/new_order.xml"))
then doc("http://datypic.com/new_order.xml")
else ()

If a document is available, it will return its document node. Otherwise, it will return the empty sequence. If the doc function had been called without verifying the existence of the document first, an error might have been raised.

Related Function

doc

Signature

document-uri($arg as node()?) as xs:anyURI?

Usage Notes

This function is basically the inverse of the doc function. Where the doc function accepts a URI and returns a document node, the document-uri function accepts a document node and returns the absolute URI associated with it. The URI may represent the location from which it was retrieved, or simply the URI that serves as its name in an XML database.

In most cases, calling this function has the same result as calling the base-uri function with the document node.

Special Cases

• If $arg is not a document node, the function returns the empty sequence.

• If $arg does not have a document URI (for example, because it is constructed), the function returns the empty sequence.

• If the $arg node’s document URI is a relative URI that cannot be resolved, the function returns the empty sequence.

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

• If $arg is not provided, the context item is used. In this case, it is an error if the context item is absent (XPDY0002) or not a node (XPTY0004).

• When using XQuery 1.0, the zero-argument version of this function is not available, so $arg must be provided.

Example

If the variable $orderDoc is bound to the result of doc("http://datypic.com/input/order.xml"), then document-uri($orderDoc) returns http://datypic.com/input/order.xml.

Related Functions

doc, base-uri

Signature

element-with-id($arg as xs:string*, $node as node()) as element()*

Usage Notes

Given a sequence of IDs ($arg), this function returns the elements with those IDs. If $node is not provided, the function looks for elements in the same document as the current context node. If $node is provided, the function looks for elements in the same document as $node.

The strings in the $arg sequence can either be individual ID values or space-separated lists of ID values. Although $arg is a sequence of xs:string values, you can also pass values of type xs:IDREF or xs:IDREFS, since these types are derived from xs:string.

An element is considered by the element-with-id function to have a particular ID if either:

• It has an attribute that is marked as an ID, that has that ID value.

• It has a child element that is marked as an ID and its content is that particular ID value.

This behavior is in contrast with the id function, which, in the latter case returns the element that is marked an ID, not its parent.

An element or attribute node can become “marked as an ID” by being validated by a schema where it is declared as having type xs:ID, or (for an attribute) being described in a DTD as being of type ID. Also, if it is an attribute named xml:id, it is automatically considered to be an ID.

The function returns the nodes in document order, not the order designated by the sequence of $arg values. The result sequence contains no duplicate elements, even if an ID value was included twice in $arg.

Working with IDs and IDREFs is discussed in further detail in “Working with IDs”.

Special Cases

• Any values in $arg that are not lexically valid IDs (i.e., XML NCNames) are ignored, even if there is an element with that invalid ID.

• If there is no element with a specified ID, an error is not raised, but no element is returned for that ID value.

• In the case of an invalid (but well-formed) document where more than one element has the same ID, the function returns the first element in the document with that ID.

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

• If no matching elements were found, the function returns the empty sequence.

• If $node is not provided, the context item is used. In this case, it is an error if the context item is absent (XPDY0002) or not a node (XPTY0004).

• Error FODC0001 is raised if $node is not part of a document (its root is not a document node).

• This function was optionally supported in XQuery 1.0, and always supported in XQuery 3.0 and later.

Examples

These examples use the input document catalog-with-ids.xml shown in Example A-2. It is assumed that the input document has been validated and that the type of the id element is xs:ID.

The final example shows the difference between the element-with-id function and the id function. See the discussion of the id function for a more typical example, where the IDs are attributes instead of elements.

<catalog>
  <product dept="WMN">
    <id>A1</id>
    <number>557</number>
    <name language="en">Fleece Pullover</name>
  </product>
  <product dept="ACC">
    <id>A2</id>
    <number>563</number>
    <name language="en">Floppy Sun Hat</name>
  </product>
</catalog>

Related Functions

id, idref

Signature

empty($arg as item()*) as xs:boolean

Usage Notes

This function determines whether a sequence is empty, i.e., whether it contains zero items. A sequence is not considered empty just because it only contains a zero-length string, the value 0, or an element with empty content. To test whether an element has empty content, use the expression:

string($node1) = ""

It is often unnecessary to call the empty function because sequences are automatically converted to their effective boolean value where a Boolean value is expected. For example, if you want to test whether there are any product elements in the catalog, you can use the test expression:

if (not(doc("catalog.xml")//product) then ...

In this case, the sequence of selected product elements is converted to the Boolean value true if the sequence is not empty, and false if the sequence is empty. There is no need to call the empty function to determine this. But beware: this only works for node sequences, not for atomic values.

Examples

Related Functions

exists, boolean

Signature

encode-for-uri($uri-part as xs:string?) as xs:string

Usage Notes

URIs require that some characters be escaped with their hexadecimal Unicode codepoint preceded by the % character. This includes non-ASCII characters and some ASCII characters, namely control characters, spaces, and several others.

In addition, certain characters in URIs are separators that are intended to delimit parts of URIs, namely the characters ; , / ? : @ & = + $ [ ] %. If the intended use of a string is as a segment of a URI path, where such separators have special meaning, the encode-for-uri function allows you to escape these separator characters, while also escaping the other necessary special characters.

Like the escape-html-uri and iri-to-uri functions, the encode-for-uri function replaces each special character with an escape sequence in the form %xx (possible repeating), where xx is two hexadecimal digits (in uppercase) that represent the character in UTF-8. For example, édition.html is changed to %C3%A9dition.html, with the é escaped as %C3%A9.

The encode-for-uri function is the most aggressive of the three encoding functions. All characters except the following are escaped:

• Letters a through z and A through Z

• Digits 0 through 9

• Hyphen (-), underscore (_), period (.), and tilde (~)

Because the function escapes delimiter characters, it’s unsuitable for escaping a complete URI. Instead, it’s useful for escaping strings before they are assembled into a URI—for example, the values of query parameters.

Special Case

• If $uri-part is the empty sequence, the function returns a zero-length string.

Examples

The first example shows a typical use case, where a filename contains the separator % character and some spaces that need to be escaped. The second example shows the escaping of an entire URL by using this function, which can have undesired results. The escape-html-uri function would have been a better choice.

Related Functions

escape-html-uri, iri-to-uri, resolve-uri

Signature

map:entry($key as xs:anyAtomicType, $value as item()*) as map(*)

Usage Notes

This function returns a map with a single entry, whose key is $key and whose value is $value. It is not particularly useful when constructing a map from a fixed number of entries; the map constructor described in “Constructing Maps” can do that. For example, the map constructor map { "ACC":"Accessories"} is equivalent to the function call map:entry("ACC", "Accessories").

The function is most useful when creating a map from a variable number of entries. It can be used with the map:merge function for this purpose, for example:

map:merge(doc("catalog.xml")//product !
map:entry(string(number), string(name)))

creates a map that contains an entry for each product, whose key is the product number and whose value is the name (both strings).

Special Case

• This function is new in XQuery 3.1.

Examples

The examples assume this variable declaration:

declare variable $map1 := map {1:"first", 2:"second"};

Related Functions

map:put, map:merge

Signature

environment-variable($name as xs:string) as xs:string?

Usage Notes

This function is used to return the value of an environment variable based on its name. The available-environment-variables function can be used to get a list of the names of all the available environment variables. The definition of environment variable is processor- and platform-dependent.

Special Cases

• If there is no environment variable with the name $name, the function returns the empty sequence.

• This function is new in XQuery 3.0.

Example

When evaluating the function call environment-variable("JAVA_HOME") in a Windows environment, a standalone XQuery processor might return the value of that Windows environment variable, e.g., C:Program FilesJavajdk1.8.0_25.

Related Function

available-environment-variables

Signature

error($code as xs:QName?, $description as xs:string,
      $error-object as item()*) as none

Usage Notes

This function allows you to stop execution of the query, with a specific error message. This is useful if an unexpected or invalid condition exists, such as a missing or invalid data item. You can incorporate calls to the error function in your query to signal such problems to the query user. For example:

if (not ($prod/number))
then error(QName("http://datypic.com/err", "ProdNumReq"),
           "Missing product number.")
else $prod/number

results in a ProdNumReq error if $prod has no number child.

How a processor will use the optional $description and $error-object arguments is implementation-dependent. Most processors will report the $description as part of the error message to the user.

Some processors may report the error name as a URI, where the local part is a fragment identifier, as in http://datypic.com/err#ProdNumReq.

The error function is the same function that the processor calls implicitly whenever there is an error during query evaluation. The return type of none is only used for the error function and is not available to query authors. It simply means that the error function never returns any value; evaluation of the query stops once the error function is called.

Remember that order of execution in XQuery is undefined. You can’t always rely on the fact that your error test will be evaluated before some other expression that it is designed to guard. In fact, you can’t always rely on the error expression being evaluated at all if, for example, it appears as part of a larger expression (perhaps a variable assignment) whose result is never used. However, simple cases such as if ($condition) then $value else error() should be safe.

Special Case

• If $code is not provided, the error name defaults to FOER0000 (“Unidentified error”), in the http://www.w3.org/2005/xqt-errors namespace.

Examples

The second example assumes the prod prefix has been declared in the query.

Related Function

trace

Signature

escape-html-uri($uri as xs:string?) as xs:string

Usage Notes

HTML agents require that some URI characters be escaped with their hexadecimal Unicode codepoint preceded by the % character. This includes non-ASCII characters and some ASCII characters, namely control characters, spaces, and several others.

The escape-html-uri function replaces each of these special characters with an escape sequence in the form %xx (possible repeating), where xx is two hexadecimal digits (in uppercase) that represent the character in UTF-8. For example, édition.html is changed to %C3%A9dition.html, with the é escaped as %C3%A9. Specifically, it escapes everything except those ASCII characters whose decimal codepoint is between 32 and 126, inclusive. This allows these URIs to be appropriately handled by HTML agents such as web browsers, for example, in HTML href attributes.

The way this function is specified is a pragmatic compromise. HTTP requires special characters such as spaces to be escaped. However, HTML documents often contain URIs designed for local use within the browser—for example, JavaScript function calls—and these local URIs (which are never sent over HTTP) will often fail if spaces and other ASCII characters are escaped. This function therefore only escapes non-ASCII characters.

Special Case

• If $uri is the empty sequence, the function returns a zero-length string.

Examples

Related Functions

encode-for-uri, iri-to-uri

Signature

exactly-one($arg as item()*) as item()

Usage Notes

This function returns $arg unchanged if it contains exactly one item. Otherwise, error FORG0005 is raised.

This function is useful when static typing is in effect, to avoid apparent static type errors. For example, to use a computed element constructor, you might be tempted to write the expression:

element {node-name($prod)}  { 563 }

However, if static typing is used, this expression causes a static error. This is because the node-name function returns 0 or 1 xs:QName values, while the computed element constructor requires that one and only one xs:QName value be provided. A static error can be avoided by using the expression:

element {exactly-one(node-name($prod))}  { 563 }

In this case, no static error is raised. Rather, a dynamic error is raised if node-name returns the empty sequence. For more information on static typing, see Chapter 15.

If static typing is NOT in effect, calling exactly-one is not usually necessary, but it does no harm. The effect is usually to make explicit a runtime type check that would otherwise have been done automatically.

Examples

Related Functions

exists, empty, one-or-more, zero-or-one

Signature

exists($arg as item()*) as xs:boolean

Usage Notes

This function returns true if the sequence contains one or more items; it is the opposite of the empty function. It is often unnecessary to call the exists function because sequences are automatically converted to the effective boolean value where a Boolean value is expected. For example, if you want to test whether there are any product elements in catalog.xml, you can use the test expression:

if (doc("catalog.xml")//product)  then ...

In this case, the sequence of selected product elements is converted to the Boolean value true if the sequence is not empty, and false if the sequence is empty. There is no need to call the exists function to determine this. But beware: this only works for node sequences, not for atomic values.

Examples

Related Functions

empty, one-or-more

Signature

math:exp($arg as xs:double?) as xs:double?

Usage Notes

This function returns the mathematical constant e (approximately 2.71828) raised to the power of $arg.

Special Cases

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

• This function is new in XQuery 3.0.

Examples

Related Functions

math:exp10, math:pow

Signature

math:exp10($arg as xs:double?) as xs:double?

Usage Notes

This function returns the number 10 raised to the power of $arg.

Special Cases

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

• This function is new in XQuery 3.0.

Examples

Related Functions

math:exp, math:pow

Signature

false() as xs:boolean

Usage Notes

This function, which takes no arguments, is useful for constructing the Boolean value false. XQuery uses false() and true() function calls instead of keywords false and true. This is most commonly used to supply a value in a function call where a Boolean value is required.

Example

The expression false() returns the xs:boolean value false.

Related Functions

true, boolean

Signature

filter($seq as item()*, $f as function(item()) as xs:boolean) as item()*

Usage Notes

This function returns those items in $seq for which the supplied function $f returns true. The order of the items is preserved. The supplied function must return one and only one boolean value. Calling the filter function is similar to using a predicate that calls a supplied function. For example:

let $f := starts-with#2
let $seq := ("ab", "aa", "xy")
return filter($seq, $f(?, "a"))

is equivalent to:

let $f := starts-with#2
let $seq := ("ab", "aa", "xy")
return $seq[$f(., "a")]

Both return the sequence ("ab", "aa") because those are the items that start with “a”. Using the filter function is stricter because the supplied function must return a boolean value, whereas in the second example the supplied function could return any sequence and it would be interpreted as an effective boolean value.

Special Cases

• If $seq is the empty sequence, then the empty sequence is returned.

• This function is new in XQuery 3.0, and only supported by implementations that support higher-order functions. If the function is called by a 3.0 processor but not supported, error XPST0017 will be raised.

Examples

Signature

array:filter($array as array(*), 
             $function as function(item()*) as xs:boolean) as array(*)

Usage Notes

This function returns a new array containing those members of $array for which the function $function returns true. The order of the members is preserved. The function $function must return one and only one boolean value.

Special Cases

• If $array is an empty array, an empty array is returned.

• This function is new in XQuery 3.1, and only supported by implementations that support higher-order functions. If the function is called by a 3.1 processor but not supported, error XPST0017 will be raised.

Examples

Signature

map:find($input as item()*, $key as xs:anyAtomicType) as array(*)

Usage Notes

This function recursively searches $input for map entries whose key is $key and returns their values as an array. The $input sequence can contain any kind of items. If an array is included, each member of the array is then searched. If a map is included, the value of each map entry is searched. The search is recursive, so multiple levels of nested maps and arrays (e.g., maps within maps, or maps within arrays within map values) will be searched. Other items, such as atomic values or XML nodes, are ignored.

Special Cases

• If $input is an empty sequence or an empty map or array, or no entries with the $key are found, the function returns an empty array.

• This function is new in XQuery 3.1.

Examples

The examples assume these variable declarations:

declare variable $map1 := map {1:"first", 2:"second"};
declare variable $map2 := map {
    "A": map {1: "1-in-A"},
    "B": map {2: "2-in-B"},
    "C": map {1: "1-in-C"} 
    };
declare variable $array1 := [map {1:"1-in-array"}, 32];

Related Functions

map:contains, map:get

Signature

array:flatten($input as item()*) as item()*

Usage Notes

This function takes the $input items and removes arrays from them, replacing them with the members of the array as a sequence, in order. This is done recursively, so that if there are multiple levels of arrays, they are all removed. The result is a sequence of items at a single level.

Special Cases

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

• If $input does not contain any arrays, $input is returned unchanged.

• This function is new in XQuery 3.1.

Examples

Signature

floor($arg as xs:numeric?) as xs:numeric?

Usage Notes

This function returns the largest whole number that is not greater than $arg. It returns a numeric value of type xs:float, xs:double, xs:decimal, or xs:integer, depending on which type the argument is derived from. If $arg is untyped, it is cast to xs:double.

Special Cases

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

• If $arg is one of the values 0, -0, NaN, INF, or -INF, the function returns this same value.

Examples

Related Functions

ceiling, round, round-half-to-even

Signature

fold-left($seq as item()*, $zero as item()*,
          $f as function(item()*, item()) as item()*) as item()*

Usage Notes

This function performs an operation (the function $f) on two items at a time, accumulating a result as it goes. It first calls the function using $zero as the first argument and the first item in $seq as the second argument. It then calls it a second time using the result of the previous function call as the first argument, and the second item in $seq as the second argument. It continues until there are no further items in $seq. For example, the function call:

fold-left(1 to 3, 0, function($a, $b) { $a + $b })

passes a function that adds the two values together. It adds 0 (the $zero argument) to 1, takes the result of that and adds it to 2, and takes the result of that and adds it to 3, finally returning 6.

For functions that perform associative operations such as addition, fold-left and fold-right return the same value.

Special Cases

• If $seq is the empty sequence, $zero is returned.

• This function is new in XQuery 3.0, and only supported by implementations that support higher-order functions. If the function is called by a 3.0 processor but not supported, error XPST0017 will be raised.

Examples

Related Functions

fold-right, array:fold-left, array:fold-right

Signature

fold-right($seq as item()*, $zero as item()*,
           $f as function(item(), item()*) as item()*) as item()*

Usage Notes

This function performs an operation (the function $f) on two items at a time, accumulating a result as it goes. It first calls the function, using the last item in $seq as the first argument and $zero as the second argument. It then calls it a second time, using the second to last item in $seq as the first argument and the result of the first function call as the second argument. It continues until there are no further items in $seq. For example, the function call:

fold-right(1 to 3, 0, function($a, $b) { $a + $b })

passes a function that adds the two values together. It adds 3 to 0 (the $zero argument), takes the result of that and adds it to 2, and takes the result of that and adds it to 1, finally returning 6.

For functions that perform associative operations such as addition, fold-left and fold-right return the same value.

Special Cases

• If $seq is the empty sequence, $zero is returned.

• This function is new in XQuery 3.0, and only supported by implementations that support higher-order functions. If the function is called by a 3.0 processor but not supported, error XPST0017 will be raised.

Examples

Related Functions

fold-left, array:fold-left, array:fold-right

Signature

array:fold-right($array as array(*), $zero as item()*,
                 $function as function(item()*, item()*) as item()*) as item()*

Usage Notes

This function performs an operation (the function $function) on two arguments at a time (one of which is a member of $array), accumulating a result as it goes. It first applies the function to two values: taking the last member of $array as the first argument and $zero as the second argument. It then calls the function a second time, with the second-to-last member in $array as the first argument and the result of the previous function call as the second argument. It continues until there are no further members in $array. For example, the function call:

array:fold-right([1, 2, 3], 0, function($a, $b) { $a + $b })

passes a function that adds the two values together. It adds 3 to 0 (the $zero argument), takes the result of that and adds it to 2, and takes the result of that and adds it to 1, finally returning 6.

The array:fold-right function is similar to the fold-right function, but works on an array rather than a sequence. One consequence of that is that array:fold-right can operate on multiple items (since multiple items can be a single member of an array).

Special Cases

• If $array is an empty array, $zero is returned.

• This function is new in XQuery 3.1, and only supported by implementations that support higher-order functions. If the function is called by a 3.1 processor but not supported, error XPST0017 will be raised.

Examples

Related Functions

array:fold-left, fold-left, fold-right

Signature

for-each($seq as item()*, $action as function(item()) as item()*) as item()*

Usage Notes

This function applies the function $action to each of the items in $seq and concatenates all the results together in order. It is a shorthand that avoids having to use a FLWOR expression for simple cases. For example, for-each( ("a", "b"), $f) is equivalent to for $x in ("a", "b") return $f($x), where $f is a variable bound to a function.

Special Cases

• If $seq is the empty sequence, the empty sequence is returned.

• This function is new in XQuery 3.0, and only supported by implementations that support higher-order functions. If the function is called by a 3.0 processor but not supported, error XPST0017 will be raised.

Examples

Related Functions

for-each-pair, array:for-each, array:for-each-pair, map:for-each

Signature

array:for-each($array as array(*), 
               $action as function(item()*) as item()*) as array(*)

Usage Notes

This function applies the function $action to each of the members in $array. The result of the function is an array where each member is the result of calling the function $action once. It is a shorthand that avoids having to use a FLWOR expression for simple cases.

This function is similar to the for-each function except that it works on an array instead of a sequence.

Special Cases

• If $array is an empty array, an empty array is returned.

• This function is new in XQuery 3.1, and only supported by implementations that support higher-order functions. If the function is called by a 3.1 processor but not supported, error XPST0017 will be raised.

Examples

Related Functions

array:for-each-pair, for-each, for-each-pair, map:for-each

Signature

map:for-each($map as map(*), 
           $action as function(xs:anyAtomicType, item()*) as item()*) as item()*

Usage Notes

This function applies the function $action to every entry in the map $map. The result of the map:for-each function is the concatenation of the results of the function in $action applied to each entry in the map. The order of the items in the result is implementation-dependent.

The $action function must accept two arguments. The first is the map key, and the second is the map value.

This function is similar to the for-each function except that it works on a map instead of a sequence.

Special Cases

• If $map is an empty map, the empty sequence is returned.

• This function is new in XQuery 3.1, and only supported by implementations that support higher-order functions. If the function is called by a 3.1 processor but not supported, error XPST0017 will be raised.

Examples

The examples assume this variable declaration:

declare variable $map1 := map {1:"first", 2:"second"};

Related Functions

array:for-each, for-each

Signature

for-each-pair($seq1 as item()*, $seq2 as item()*,
              $action as function(item(), item()) as item()*) as item()*

Usage Notes

This function takes two sequences ($seq1 and $seq2) and applies the supplied function $action to pairs of values from each sequence. For example, if each of $seq1 and $seq2 contain three items, the supplied function will be called three times, first with the first item from $seq1 and the first item from $seq2, next with the second item from $seq1 and the second item from $seq2, and so on. The results of the function calls are concatenated in order.

Special Cases

• If either $seq1 or $seq2 is the empty sequence, the empty sequence is returned.

• If $seq1 and $seq2 contain a different number of items, the function is only applied as many times as there are items in the smaller sequence. For example, if $seq1 has three items and $seq2 has five items, the function is only applied three times.

• This function is new in XQuery 3.0, and only supported by implementations that support higher-order functions. If the function is called by a 3.0 processor but not supported, error XPST0017 will be raised.

Examples

Related Functions

for-each, array:for-each-pair, array:for-each

Signature

format-date($value as xs:date?, $picture as xs:string,
            $language as xs:string?, $calendar as xs:string?,
            $place as xs:string?) as xs:string?

Usage Notes

This function formats the date $value according to the pattern $picture. Three additional arguments allow specification of a $language, $calendar, and $place. If any of these three arguments are specified, all must be present. In other words, the function accepts either two arguments or five arguments, but the empty sequence can be used as a placeholder.

Details on how these five arguments are interpreted is identical for the format-date, format-time, and format-dateTime functions. See the “format-dateTime” section for a detailed explanation of the arguments. The only difference is that format-date cannot use time-related component specifiers, namely H, h, P, m, s, and f.

Special Cases

• If $value is the empty sequence, the function returns the empty sequence.

• If $picture refers to time-related components like H, error FOFD1350 is raised.

• If $picture or $calendar is invalid, error FOFD1340 is raised.

• This function is new in XQuery 3.0.

Examples

Related Functions

format-time, format-dateTime

Signature

format-dateTime($value as xs:dateTime?, $picture as xs:string, 
                $language as xs:string?, $calendar as xs:string?,
                $place as xs:string?) as xs:string?

Usage Notes

This function formats the date/time $value according to the pattern $picture. Three additional arguments allow specification of a $language, $calendar, and $place. If any of these three arguments are specified, all must be present. In other words, the function accepts either two arguments or five arguments, but the empty sequence can be used as a placeholder.

The picture string contains variable markers, which appear in square brackets. Anything between the variable markers (outside square brackets) is considered a literal character and is copied to the formatted output unchanged. To escape a square bracket so that it can be used as a literal character, it can be doubled ([[ or ]]).

Each variable marker has up to three parts in between the square brackets:

• A mandatory component specifier, which is one of the case-sensitive letters from the first column of Table A-6.

• An optional one or two presentation modifiers. If not specified, the default value from the third column of Table A-6 is used.

• An optional comma followed by a width modifier.

The presentation modifier, which comes directly after the component specifier, specifies how to format that component. For numeric values like day of the month, you can use the values allowed by the $picture argument to the format-integer function. For example, 0 (or 1, the digits are interchangeable) will simply format it as a number, 00 will pad it with zeros to make it two digits, and Ww indicates a word, like Two.

If the component is a day of the week, month of the year, time zone or era, it can also be spelled out as a name, for example Monday or JUNE. If the presentation modifier is n, it is all lowercase; if it is N, it is all uppercase; and if it is Nn, it is in title case.

To use ordinal numbers, for example 1st or First, the first presentation modifier can be followed by the letter o. The letters c (cardinal), a (alphabetic), and t (traditional) are also allowed, with the same meanings they have when used with the format-integer function.

The last part of a variable marker is a width modifier that indicates the allowed length of the output. It is separated from the rest of the variable marker with a comma, and indicates a minimum and maximum length separated by a hyphen. For example, ,3-4 indicates that it must be a minimum of three characters and a maximum of four. An asterisk can be used on either side of the hyphen to indicate that there is no minimum or maximum length. If no hyphen or maximum width is used, it means that there is no maximum length. One use for this is to abbreviate names, for example [MNn,3-3] outputs three-letter abbreviations for month names (Jan, Feb, etc.). Some implementations will use conventional abbreviations, while others simply truncate the value. For year components (Y), setting a width left-truncates the year, so if the year is 2015 and the variable marker is [Y,2-2], it is formatted as 15.

$language specifies the natural language to use when formatting words. It is used, for example, in names of days of the week, month names, and numbers expressed as words such as two. It should be a value as described by the xs:language type, with typical values being language codes like en (English) or de (German), optionally including a regional modifier like en-US (English, United States).

$calendar specifies the calendar to use to format the date.

$place specifies a place, which can allow for regional differences within a language. It is typically a country code, or an Olson Timezone name such as America/New_York.

The names of calendars and places, and how they affect the formatted dates, is implementation-defined. The documentation for your XQuery processor should list the options available to you. If a $language, $calendar, or $place is not recognized by the processor, it will not raise an error but will instead fall back to its default value and indicate that it did so at the beginning of the output string, for example:

format-dateTime(xs:dateTime("2015-05-31T12:00:00"),
                "[Mn]", "x-Klingon", (), () )

might return [Language: en]may if the processor does not recognize the language x-Klingon.

Special Cases

• If $value is the empty sequence, the function returns the empty sequence.

• If $picture or $calendar is invalid, error FOFD1340 is raised.

• This function is new in XQuery 3.0.

Examples

Additional examples are provided in the “format-date” and “format-time” sections.

Related Functions

format-date, format-time

Signature

format-integer($value as xs:integer?, $picture as xs:string, 
               $lang as xs:string?) as xs:string

Usage Notes

This function formats the integer $value according to the pattern $picture. This can be used to pad integers with leading zeros, insert grouping separators between segments of an integer, or convert integers to other formats like letters or Roman numerals. The $picture has two parts: the primary format token and the format modifier. They are separated by a semicolon. The primary format token can be a decimal digit pattern, which has three parts:

1. A “#” character that represents an optional digit

2. A number that represents a mandatory digit (any number in the digit family can be used; they are interchangeable)

3. A grouping separator that is anything other than a letter or number

For example, the pattern 0000 represents four mandatory digits, so the result will contain at least four digits (padding with leading zeros, if necessary). The pattern #,##0 uses the optional digit sign #, which does not insert leading zeros but causes a comma to be inserted between each group of three digits that is present. Optional digits are only needed to show the placement of the grouping separator; otherwise they have no effect. There are several rules regarding the placement of the three parts of the decimal digit pattern:

• At least one mandatory digit must be present.

• All mandatory digits must be from the same digit family (i.e., the same 10 consecutive codepoints defined by Unicode).

• Optional digits (if present) must appear before mandatory digits.

• A grouping separator must not appear at the beginning or end of the pattern, or next to another grouping separator.

As an alternative to the decimal digit pattern, the primary format token can instead be one of the following values:

The primary format token can optionally be followed by a semicolon and a format modifier, which can have three parts, in order:

1. One of the letters c (for cardinal, the default) or o (for ordinal). If the letter o is specified, ordinal numbers such as 1st and 2nd are used, rather than cardinal numbers like 1 and 2.

2. An optional implementation-defined sequence of characters in parentheses that allow other possible variations of cardinal and ordinal numbering sequences.

3. One of the letters a (for alphabetic) or t (for traditional). This is not used in English, but in some languages it is necessary to distinguish between two numbering sequences that use letters.

Special Cases

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

• If $picture has an invalid format, error FODF1310 is raised.

• This function is new in XQuery 3.0.

Examples

Related Function

format-number

Signature

format-number($value as xs:numeric?, $picture as xs:string, 
              $decimal-format-name as xs:string?) as xs:string

Usage Notes

This function formats the number $value according to the pattern $picture and the decimal format $decimal-format-name. It can be used to format values of any numeric type, but for integers it may be best to use the format-integer function, because of its support for different number styles.

$picture can be used to pad numbers with leading or trailing zeros, insert grouping separators between segments of a number, or show numbers with exponents. For example, the pattern 0000 represents four mandatory digits, so the result will contain at least four digits (padding with leading zeros, if necessary). The pattern #,##0 uses the optional digit sign #, which will not insert leading zeros but will cause a comma to be inserted between each group of three digits that is present.

There are a variety of characters that can be specified in the picture string. Each is listed here with its default value in parentheses.

Decimal separator (“.”)

Separates the integer part of the number from the fractional part, sometimes referred to as a decimal point. It can be used in both the picture string (to indicate its position) and in the formatted number. For example, the picture string 00.00 causes the number 12.5 to be formatted as 12.50. If no decimal separator appears in the picture string, the number will be rounded according to the rules of the round-half-to-even function.

Grouping separator (“,”)

Separates groups of numbers, typically used as a thousands separator. It can be used in both the picture string (to indicate its position) and in the formatted number. For example, the picture string #,##0 causes the number 12345 to be formatted as 12,345. A larger number like 123456789 is formatted with a grouping separator separating every three digits (123,456,789), using the same picture string; it is not necessary to put multiple grouping separators in the picture string. If no grouping separator appears in the picture string, none will appear in the formatted number.

Mandatory (zero) digit (“0”)

Used in a picture string to indicate a mandatory digit. If the number being formatted has fewer digits than there are mandatory digits in the picture string, zeros are padded. Leading zeros may be added for mandatory digits to the left of the decimal separator, and trailing zeros may be added for mandatory digits to the right. For example, the picture string 000.00 will cause the number 18 to be formatted as 018.00. Although zero (“0”) is commonly used, actually using any digit in the same family will have the same effect. The picture string 123.45 would work equally well in the previous example, although it is less clear.

Optional digit (“#”)

Used in a picture string to indicate an optional digit. It is only useful if used in conjunction with a grouping separator, to indicate how many digits should be in each group. For example, in the picture string #,##0.00, the optional digit character is used to create three characters between the grouping separator and the decimal separator, so that the processor knows to group the number in sets of three digits.

Pattern separator (“;”)

Divides a picture string into two parts, the first to handle positive numbers and the second to handle negative numbers. For example, the picture string #,##0.00;(#,##0.00) could be used to surround negative currency amounts with parentheses as is done in financial statements. If there is no pattern separator, negative numbers are formatted just like positive numbers, except that they are preceded by a minus sign.

Percent sign (“%”)

Used in a picture string to indicate that the number should be multiplied by 100. It also indicates the position of the percent sign in the results (either at the beginning or the end). For example, the picture string 0% will cause the number 0.18 to be formatted as 18%.

Per-mille sign (“‰”)

Used in a picture string to indicate that the number should be multiplied by 1000. It also indicates the position of the per-mille sign in the results (either at the beginning or the end). For example, the picture string 0‰ will cause the number 0.018 to be formatted as 18‰.

Exponent separator (“e”)

Used in a picture string to indicate that the number should be formatted using scientific notation. For example, the picture string 00.0e0 will cause the number 1234 to be formatted as 12.3e2. To be effective, the exponent separator must be between digit characters.

Any other characters

Any other characters not listed above can also appear in the picture string. These characters will be considered “passive” characters that should just be copied to the formatted output. For example, the picture string a000z will cause the number 18 to be formatted as a018z. These other characters must appear at the beginning and/or the end, not between any of the other special characters described.