abs: Finds the absolute value of a number

Signature

abs($arg as numeric?) as numeric?

Usage Notes

This function accepts any numeric value and returns its absolute value. 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 INF or -INF, the function returns INF.

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

Examples

Example	Return value
abs(3.5)	3.5
abs(−4)	4
abs(xs:float("-INF"))	INF

adjust-date-to-timezone: Adjusts the time zone of a date

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 the $arg date value already has a time zone and on the value of the time zone provided. Table A-2 shows the possible combinations.

The $timezone argument is expressed as an xs:dayTimeDuration, for example, -PT5H for U.S. 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,^[*] 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, its value is adjusted to that time zone. This may change the actual date in some cases. For example, if $arg is 2006-02-15-05:00, and $timezone is -PT8H, the resulting date is 2006-02-14-08:00, which is the day before. This is because $arg is considered to be 2006-02-15T00:00:00-05:00, which is equivalent to 2006-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" in Chapter 19.

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), the error "Invalid timezone value" (FODT0003) is raised.

Table A-2. Behavior of the adjust-*-to-timezone functions

Does $arg have a time zone?	Value of $timezone argument	Explanation of result
No	An xs:dayTimeDuration	$arg, now associated with the time zone $timezone (but has the same date)
Yes	An xs:dayTimeDuration	$arg, adjusted to the time zone $timezone
No	The empty sequence	$arg, unchanged
Yes	The empty sequence	$arg with no associated time zone (but has the same date)
No	Not provided	$arg, now associated with the implicit time zone (but has the same date)
Yes	Not provided	$arg, adjusted to the implicit time zone

Examples

These six examples represent the six scenarios described in Table A-2.

Example[a]	Return value
[a]
adjust-date-to-timezone(xs:date("2006-02-15"), xs:dayTimeDuration("-PT8H"))	2006-02-15-08:00
adjust-date-to-timezone(xs:date("2006-02-15-03:00"), xs:dayTimeDuration("-PT8H"))	2006-02-14-08:00
adjust-date-to-timezone(xs:date("2006-02-15"), ( ))	2006-02-15
adjust-date-to-timezone(xs:date("2006-02-15-03:00"), ( ))	2006-02-15
adjust-date-to-timezone(xs:date("2006-02-15"))	2006-02-15-05:00
adjust-date-to-timezone(xs:date("2006-02-15-03:00"))	2006-02-14-05:00
[a] This table assumes an implicit time zone of −05:00

adjust-dateTime-to-timezone: Adjusts the time zone of a date/time

Signature

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

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), the error "Invalid timezone value" (FODT0003) is raised.

Examples

These examples represent the scenarios described in Table A-2.

Example[a]	Return value
[a]
adjust-dateTime-to-timezone (xs:dateTime("2006-02-15T17:00:00"), xs:dayTimeDuration("-PT7H"))	2006-02-15T17:00:00-07:00
adjust-dateTime-to-timezone (xs:dateTime("2006-02-15T17:00:00-03:00"), xs:dayTimeDuration("-PT7H"))	2006-02-15T13:00:00-07:00
adjust-dateTime-to-timezone (xs:dateTime("2006-02-15T17:00:00"), ( ))	2006-02-15T17:00:00
adjust-dateTime-to-timezone (xs:dateTime("2006-02-15T17:00:00-03:00"), ( ))	2006-02-15T17:00:00
adjust-dateTime-to-timezone (xs:dateTime("2006-02-15T17:00:00"))	2006-02-15T17:00:00-05:00
adjust-dateTime-to-timezone (xs:dateTime("2006-02-15T17:00:00-03:00"))	2006-02-15T15:00:00-05:00
adjust-dateTime-to-timezone (xs:dateTime("2006-02-15T01:00:00-03:00"), xs:dayTimeDuration("-PT7H"))	2006-02-14T21:00:00-07:00
[a] This table assumes an implicit time zone of −05:00.

adjust-time-to-timezone: Adjusts the time zone of a time

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), the error "Invalid timezone value" (FODT0003) is raised.

Examples

Some examples are shown here. See Table A-2 for a description of the scenarios these examples represent.

Example[a]	Return value
[a]
adjust-time-to-timezone(xs:time("17:00:00"), xs:dayTimeDuration("-PT7H"))	17:00:00-07:00
adjust-time-to-timezone(xs:time("17:00:00-03:00"), xs:dayTimeDuration("-PT7H"))	13:00:00-07:00
adjust-time-to-timezone(xs:time("17:00:00"), ( ))	17:00:00
adjust-time-to-timezone(xs:time("17:00:00-03:00"), ( ))	17:00:00
adjust-time-to-timezone(xs:time("17:00:00"))	17:00:00-05:00
adjust-time-to-timezone(xs:time("17:00:00-03:00"))	15:00:00-05:00
adjust-time-to-timezone(xs:time("22:00:00-08:00"))	01:00:00-05:00
adjust-time-to-timezone(xs:time("01:00:00-02:00"))	22:00:00-05:00
adjust-time-to-timezone(xs:time("17:00:00"), xs:dayTimeDuration("-PT20H"))	Error FODT0003
[a] This table assumes an implicit time zone of −05:00.

avg: Finds the average value of the items in a sequence

Signature

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

Usage Notes

The $arg sequence 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" in Chapter 7.

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, the error "Invalid value for cast/constructor" (FORG0001) is raised.

• If $arg contains typed values that are not numeric or duration values, or values that have a variety of types, the error "Invalid argument type" (FORG0006) is raised.

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

Examples

Example	Return value
avg( (1, 2, 3, 4, 5) )	3
avg( (1, 2, 3, ( ), 4, 5) )	3
avg( (xs:yearMonthDuration("P4M"), xs:yearMonthDuration("P6M") ) )	P5M
avg(doc("order.xml")//item/@quantity)	1.166667 (with implementation-defined precision)
avg( ( ) )	( )
avg(doc("order.xml")//item/@dept)	Error FORG0001

Related Functions

sum, count

base-uri: Gets the base URI of a node

Signature

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

Usage Notes

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

The $arg argument 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.

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" in Chapter 20.

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 node. Note that this is not the same as the base URI from the static context, which is retrieved using the static-base-uri function.

• If $arg is not provided, and the context item is not a node, the error XPTY0004 is raised.

• If $arg is not provided, and the context item is undefined, the error XPDY0002 is raised.

• 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/cats.xml shown in Example A-1.

Example	Return value
base-uri($cats//catalog[1])	http://example.org/ACC/
base-uri($cats//catalog[2]/product)	http://example.org/WMN/
base-uri ($cats//catalog[2]/product/@href)	http://example.org/WMN/
base-uri($cats)	http://datypic.com/cats.xml
base-uri($cats/catalogs)	http://datypic.com/cats.xml

Example A-1. Using xml:base (http://datypic.com/cats.xml)

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

Related Functions

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

boolean: Finds the effective Boolean value

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 Chapter 11.

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 the argument 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 Cases

If the effective Boolean value of $arg is undefined, for example because $arg is a sequence of multiple atomic values, the error "Invalid argument type" (FORG0006) is raised.

Examples

Example	Return value
boolean( ( ) )	false
boolean("")	false
boolean(0)	false
boolean("0")	true
boolean(false())	false
boolean("false")	true
boolean(xs:float("NaN"))	false
boolean((false(), false(), false( )))	Error FORG0006
boolean(doc("order.xml")/order[1])	true
boolean(doc("order.xml")/noSuchChild)	false
boolean(<a>false</a>)	true

ceiling: Rounds a number up to the next integer

Signature

ceiling($arg as numeric?) as numeric?

Usage Notes

This function returns the smallest integer 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 between −0.5 and −0 (inclusive), 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

Example	Return value
ceiling(5)	5
ceiling(5.1)	6
ceiling(5.5)	6
ceiling(-5.5)	−5
ceiling(−5.51)	−5
ceiling( ( ) )	( )

Related Functions

floor, round, round-half-to-even

codepoint-equal: Determines whether two strings contain the same code points

Signature

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

Usage Notes

The function determines whether the two string arguments have the same Unicode code points, 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.

Special Cases

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

Examples

Example	Return value
codepoint-equal("abc", "abc")	true
codepoint-equal("abc", "ab c")	false
codepoint-equal("abc", ( ))	( )

codepoints-to-string: Constructs a string from Unicode code-point values

Signature

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

Usage Notes

The $arg argument is a sequence of integers representing Unicode code-point values.

Special Cases

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

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

Examples

Example	Return value
codepoints-to-string((97, 32, 98, 32, 99))	a b c
codepoints-to-string(97)	a
codepoints-to-string(( ))	A zero-length string

collection: Gets the nodes that make up a collection

Signature

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

Usage Notes

A collection may be any sequence of nodes, identified by a URI. Often, they are sequences of documents that are organized into collections so that they can be queried or managed together.

Exactly how the collection URI ($arg) is associated with the nodes 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, dereferences the URI to retrieve an XML collection document that lists all of the documents in the collection.

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

The collection function is stable. This means that if you call the collection function more than once with the exact same argument, within the same query, the result is the same, even if somehow the resources associated with the URI have changed.

Special Cases

• If $arg is not lexically a valid URI or it cannot be resolved, the error "Error retrieving resource" (FODC0004) is raised.

• If $arg is not the URI of a collection supported by the implementation, the error "Invalid argument to fn:collection( )" (FODC0004) is raised.

• If no argument is provided, or if $arg is the empty sequence, the function returns the default collection as defined by the implementation. If no default collection is defined, the error "Error retrieving resource" (FODC0002) is raised.

Example

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

Related Functions

doc

compare: Compares strings, optionally with an explicit collation

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 (=, !=, <, <=, >, >=) 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" in Chapter 17.

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.

Examples

Example[a]	Return value
[a]
compare("a", "b")	−1
compare("a", "a")	0
compare("b", "a")	1
compare("ab", "abc")	−1
compare("a", "B")	1
compare(upper-case("a"), upper-case("B"))	−1
compare("a", ( ))	( )
compare('Strasse', 'Straße', 'http://datypic.com/german')	0 if the collation equates the ß character with two s's.
compare("a", "b", "FOO")	Error FOCH0002
[a] The examples in this table assume that no default collation is specified.

The fifth example in the table shows that when using the simple code-point 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.

concat: Concatenates two or more strings together

Signature

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

Usage Notes

The concat 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.

Special Cases

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

Examples

Example	Return value
concat("a")	Error XPST0017
concat("a", "b")	ab
concat("a", "b", "c")	abc
concat("a", ( ), "b", "", "c")	abc
concat( ("a", "b", "c") )	Error XPST0017 (use string-join instead)
concat( doc("catalog.xml")//name )	Error XPST0017 (use string-join instead)
concat("a", <x>b</x>, <x>c</x>)	abc

Related Functions

string-join

contains: Determines whether one string contains another

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. Collations are described in Chapter 17.

Examples

Example	Return value
contains("query", "e")	true
contains("query", "ery")	true
contains("query", "query")	true
contains("query", "x")	false
contains("query", "")	true
contains("query", ( ))	true
contains( ( ), "q")	false
contains("","")	true
contains("", "query")	false

Related Functions

starts-with, ends-with, matches

count: Counts the number of items in a sequence

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 Cases

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

Examples

Example	Return value
count( (1, 2, 3) )	3
count(doc("order.xml")//item)	6
count(distinct-values(doc("order.xml")//item/@num))	4
count( (1, 2, 3, ( ) ) )	3
count( ( ) )	0

As shown in the third example, the count function can be combined with the distinct-values function to count only distinct values.

current-date: Gets the current date

Signature

current-date( ) as xs:date

Usage Notes

This function takes no parameters and returns the current date with time zone. The time zone is implementation-dependent. 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 2006-04-10-05:00, which is April 10, 2006 in the −05:00 time zone.

Related Functions

current-dateTime, current-time

current-dateTime: Gets the current date and time

Signature

current-dateTime( ) as xs:dateTime

Usage Notes

This function takes no parameters and returns the current date and time with time zone. If the function is called multiple times within the same query, it returns the same value every time. The time zone and the precision of the seconds part are implementation-dependent. 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(), ( ))

Example

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

Related Functions

current-date, current-time

current-time: Gets the current time

Signature

current-time( ) as xs:time

Usage Notes

This function takes no parameters and returns the current time with time zone. If the function is called multiple times within the same query, it returns the same value every time. The time zone and the precision of the seconds part are implementation-dependent. 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(), ( ))

Example

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

Related Functions

current-dateTime, current-date

data: Extracts the typed value of one or more items

Signature

data($arg as item( )*) as xs:anyAtomicType*

Usage Notes

This function accepts a sequence of items and returns their typed values. For atomic values, this simply means returning the value itself, unchanged. For nodes, this means extracting the typed value of the node.

Calling this function is usually unnecessary because the typed value of a node is extracted automatically (in a process known as atomization) for many XQuery expressions, including comparisons, arithmetic operations, function calls, and sorting in FLWORs. The most common use case for the data function is in element constructors. For example, the expression:

for $prod in doc("catalog.xml")//product
return <newEl>{data($prod/name)}</newEl>

uses the data function to extract the typed value of the name element, in order to put it in the content of newEl. If it had not used the data function, the resulting newEl elements would each have a name child instead of just character data content.

In most cases, the typed value of an element or attribute is simply its string value, cast to the type of the element or attribute. For example, if the number element has the type xs:integer, the string value of the element is 784 (type xs:string), while the typed value is 784 (type xs:integer). If the number element is untyped, its typed value is 784 (type xs:untypedAtomic).

The typed value of an element will not be the empty sequence just because the element has no content. For example, the typed value of <name></name> is the value "" (type xs:untypedAtomic) if name is untyped, not the empty sequence.

There are some additional subtleties for schema-validated elements that are described in "Nodes and Typed Values" in Chapter 13.

Other kinds of nodes have typed values as well, but they are less useful; they are described in the appropriate sections of Chapter 21.

Special Cases

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

• If $arg is an element whose type has element-only content, the error "Argument node does not have a typed value" (FOTY0012) is raised.

Examples

Table A-3 shows some examples of the data function applied to untyped nodes. They assume that the variable $cat is bound to the document node of catalog.xml, which has not been validated with a schema.

Table A-3. Examples of the data function on untyped nodes

Example	Return value	Return type
data($cat//product[1]/number)	557	xs:untypedAtomic
data($cat//number)	(557, 563, 443, 784)	xs:untypedAtomic*
data($cat//product[1]/@dept)	WMN	xs:untypedAtomic
data($cat//product[1]/colorChoices)	navy black	xs:untypedAtomic
data($cat//product[1])	557 Fleece Pullover navy black	xs:untypedAtomic
data($cat//product[4]/desc)	Our favorite shirt!	xs:untypedAtomic

Now suppose you have the schema shown in Example 13-1 in Chapter 13, and catalog.xml was validated using this schema. The typed values of the nodes would then change, as shown in Table A-4.

Table A-4. Examples of the data function on typed nodes

Example	Return value	Return type
data($cat//product[1]/number)	557	xs:integer
data($cat//number)	(557, 563, 443, 784)	xs:integer*
data($cat//product[1]/@dept)	WMN	xs:string
data($cat//product[1]/colorChoices)	(navy, black)	xs:string*
data($cat//product[1])	Error FOTY0012	N/A
data($cat//product[4]/desc)	Our favorite shirt!	xs:untypedAtomic

Related Functions

string

dateTime: Constructs a date/time value from separate date and time values

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, the error "Both arguments to fn:dateTime have a specified timezone" (FORG0008) is raised.

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

Example

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

day-from-date: Gets the day portion of a date

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 Cases

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

Example

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

Related Functions

day-from-dateTime

day-from-dateTime: Gets the day portion of a date/time

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 Cases

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

Example

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

Related Functions

day-from-date

days-from-duration: Gets the normalized number of days in a duration

Signature

days-from-duration($arg as xs:duration?) as xs:integer?

Usage Notes

This function calculates the total number of whole days in an xs:duration value. This is not necessarily the same as the integer that appears before the D in the value. For example, if the duration is P1DT36H, the function returns 2 rather than 1. This is because 36 hours is equal to 1.5 days, and the normalized value is therefore P2DT12H.

The days-from-duration function does not round the number of days; if the duration is 2 days and 23 hours, it returns the integer 2.

Special Cases

• If $arg is a negative duration, the function returns a negative value.

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

Examples

Example	Return value
days-from-duration(xs:duration("P5D"))	5
days-from-duration(xs:duration("-PT24H"))	−1
days-from-duration(xs:duration("PT23H"))	0
days-from-duration(xs:duration("P1DT36H"))	2
days-from-duration(xs:duration("PT1440M"))	1
days-from-duration(xs:duration("P1Y"))	0

deep-equal: Determines whether the values of two sequences of items are equal (contain the same data)

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.

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, values of type xs:string are compared using that collation; otherwise, the default collation is used.

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

Examples

The following two product elements are considered deep-equal:

<product dept="MEN" id="P123">
  <number>784</number>
</product>
<product id="P123" dept="MEN"><!--comment-->
  <number>784</number>
</product>

The examples below assume that the variables $prod1 and $prod2 are bound to the two product elements above.

Example	Return value
deep-equal( 1, 1 )	true
deep-equal( (1, 1), (1, 1) )	true
deep-equal( (1, 2), (1.0, 2.0) )	true
deep-equal( (1, 2), (2, 1) )	false
deep-equal( $prod1, $prod2 )	true
deep-equal( $prod1/number, $prod2/number )	true
deep-equal( $prod1/node(), $prod2/node( ))	false because of the extra comment node

default-collation: Gets the default collation

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 defined, the function returns a value representing the Unicode code-point collation, http://www.w3.org/2005/xpath-functions/collation/codepoint. See "Collations" in Chapter 17 for more information.

Example

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

distinct-values: Selects distinct atomic values from a sequence

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 eliminate nodes by identity instead, you can simply use the expression $seq/., which resorts 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, values of type string are compared using that collation; otherwise, it uses the default collation.

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

Examples

Example	Return value
distinct-values( ("a", "b", "a") )	("a", "b")
distinct-values( (1, 2, 3) )	(1, 2, 3)
distinct-values( ("a", 2, 3) )	("a", 2, 3)
distinct-values( (xs:integer("1"), xs:decimal("1.0"), xs:float("1.0E0") ) )	(1)
distinct-values( (<a>3</a>, <b>5</b>) )	(3, 5)
distinct-values( (<a>3</a>, <b>3</b>) )	(3)
distinct-values( ( ) )	( )

doc: Opens one input document based on its URI

Signature

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

Usage Notes

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

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

returns the document node of the document whose URI is http://datypic.com/order.xml. Relative URI references are also allowed, as in:

doc("order.xml")

If $uri is a relative URI, it is resolved based on the base URI of the static context. The base URI of the static context may be set by the processor outside the scope of the query, typically to the URI of the file from which the query was read. Alternatively, it may be declared in the query prolog.

If you are accessing documents on a filesystem, your implementation may require you to precede the filename with file:///, use forward slashes to separate directory names, and/or escape each space in the filename with %20. For example,

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

The doc function is often 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).

Processors interpret the URI passed to the doc function in different ways. Some, like Saxon, will dereference the URI, that is, go out to the URL and retrieve the resource at that location. Other implementations, such as those embedded in XML databases, consider the URIs to be just names. The processor might take the name and look it up in an internal catalog to find the document associated with that name. Many processors provide user hooks or configuration options allowing the behavior to be controlled by the application, and the result may also depend on the configuration of the underlying environment (for example, HTTP proxy settings).

Implementations also have some leeway in how they handle errors when retrieving documents, how they handle different MIME types, and whether they validate the documents against a schema or DTD.

The doc function is stable, 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 exact 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.

Important

The doc function should not be confused with the XSLT document function, which is not available in XQuery. The document function has different behavior, in that it will accept multiple URIs, allows the specification of a base URI, and has specific processing defined for handling fragment identifiers. These effects can be achieved in XQuery by combining use of doc with other functions such as resolve-uri and base-uri or by using it in a FLWOR expression.

Special Cases

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

• If $uri is not a lexically valid URI, the error "Invalid argument to fn:doc" (FODC0005) is raised.

• If $uri refers to a resource that is not supported by the implementation, the error "Invalid argument to fn:doc" (FODC0005) is 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 the error "Error retrieving resource" (FODC0002) being raised, or in some other error handling behavior (such as a default document being opened).

Example

doc(" http://datypic.com/order.xml ") returns the document node of the document associated with the URI http://datypic.com/order.xml.

Related Functions

collection, doc-available

doc-available: Determines whether a document is available

Signature

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

Usage Notes

The doc-available function is a way to avoid the 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 Cases

• If $uri is not a valid lexical value of xs:anyURI, the error "Invalid argument to fn:doc" (FODC0005) is raised.

• If $arg is the empty sequence, 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 Functions

doc

document-uri: Gets the URI of a document node

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.

Example

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

Related Functions

doc, base-uri

empty: Determines whether a sequence is empty

Signature

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

Usage Notes

A sequence is empty if 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 item children of items, you can use the if clause:

if not($input//catalog/product) then ....

In this case, the sequence of selected item 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

Example	Return value
empty( ("a", "b", "c") )	false
empty( ( ) )	true
empty(0)	false
empty(<desc/>)	false
empty(<desc></desc>)	false
empty(doc("order.xml")/order)	false
empty(doc("order.xml")/foo)	true

Related Functions

exists, boolean

encode-for-uri: Applies URI escaping rules to a string that is to be used as a path segment of a URI

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 code point 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 Cases

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

Examples

The first example below 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 using this function, which can have undesired results. The escape-html-uri function would have been a better choice.

Example	Return value
encode-for-uri("Sales % Numbers.pdf")	Sales%20%25%20Numbers.pdf
encode-for-uri( " http://datypic.com/a%20URI#frag ")	http%3A%2F%2Fdatypic.com%2Fa%2520URI%23frag

Related Functions

escape-html-uri, iri-to-uri

ends-with: Determines whether one string ends with another

Signature

ends-with($arg1 as xs:string?, $arg2 as xs:string?,
          $collation as xs:string) as xs:boolean

Usage Notes

This function returns an xs:boolean value indicating whether one string ($arg1) ends with the characters of a second string ($arg2). Trailing whitespace is significant, so you may want to use the normalize-space function to trim the strings before using this function.

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.

Examples

Example	Return value
ends-with("query", "y")	true
ends-with("query", "query")	true
ends-with("query", "")	true
ends-with("query ", "y")	false
ends-with("", "y")	false

Related Functions

starts-with, contains, matches

error: Explicitly raise an error

Signature

error($error 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 ($product/number))
then error(QName("http://datypic.com/err", "ProdNumReq"),
           "Missing product number.")
else $product/number

results in a ProdNumReq error if $product 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 Cases

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

Examples

Example
[a]
error( )
error (xs:QName("dty:ProdNumReq")) [a]
error(QName("http://datypic.com/err", "ProdNumReq"), "Missing number.")
error(QName("http://datypic.com/err", "ProdNumReq"), "Missing number.", $prod)
[a] Assumes the dty prefix has been declared

Related Functions

trace

escape-html-uri: Escapes all non-ASCII characters in a string

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 code point 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 code point 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 Cases

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

Examples

Example	Return value
escape-html-uri (" http://datypic.com/ ")	http://datypic.com/
escape-html-uri("édition.html")	%C3%A9dition.html
escape-html-uri ("/datypic.com/a URI#frag")	/datypic.com/a URI#frag

Related Functions

encode-for-uri, iri-to-uri

exactly-one: Verifies that a sequence contains exactly one item

Signature

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

Usage Notes

If $arg contains one item, $arg is returned. Otherwise, the error "fn:exactly-one called with a sequence containing zero or more than one item" (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 14.

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

Example	Return value
exactly-one( ( ) )	Error FORG0005
exactly-one("a")	a
exactly-one( ("a", "b") )	Error FORG0005

Related Functions

one-or-more, zero-or-one

exists: Determines whether a sequence is not empty

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 if clause:

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

Example	Return value
exists( ("a", "b", "c") )	true
exists( "" )	true
exists( ( ) )	false
exists( false( ) )	true

Related Functions

empty, one-or-more

false: Constructs a Boolean false value

Signature

false( ) as xs:boolean

Usage Notes

This function, which takes no arguments, is useful for constructing the Boolean value false. XQuery uses the false( ) and true( ) functions 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

floor: Rounds a number down to the next lowest integer

Signature

floor($arg as numeric?) as numeric?

Usage Notes

This function returns the largest integer 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

Example	Return value
floor(5)	5
floor(5.1)	5
floor(5.7)	5
floor(−5.1)	−6
floor(−5.7)	−6
floor( ( ) )	( )

Related Functions

ceiling, round, round-half-to-even

hours-from-dateTime: Gets the hour portion of a date/time

Signature

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

Usage Notes

This function returns the hour portion of an xs:dateTime value, as an integer between 0 and 23 inclusive.

Special Cases

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

• If the time portion of $arg is 24:00:00, the function will return 0.

Examples

Example	Return value
hours-from-dateTime(xs:dateTime("2006-08-15T10:30:23"))	10
hours-from-dateTime(xs:dateTime("2006-08-15T10:30:23-05:00"))	10

Related Functions

hours-from-time

hours-from-duration: Gets the normalized number of hours in a duration

Signature

hours-from-duration($arg as xs:duration?) as xs:integer?

Usage Notes

This function calculates the hours component of a normalized xs:duration value, as an integer between −23 and 23 (inclusive). This is not necessarily the same as the integer that appears before the H in the value. For example, if the duration is PT1H90M, the function returns 2 rather than 1. This is because 90 minutes is equal to 1.5 hours, and the normalized value is therefore PT2H30M. Likewise, if the duration is PT36H, the result is 12, because the normalized value is P1DT12H.

Special Cases

• If $arg is a negative duration, the function returns a negative value.

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

Examples

Example	Return value
hours-from-duration(xs:duration("P1DT5H"))	5
hours-from-duration(xs:duration("-PT36H"))	−12
hours-from-duration(xs:duration("PT1H90M"))	2
hours-from-duration(xs:duration("PT2H59M"))	2
hours-from-duration(xs:duration("PT3600S"))	1
hours-from-duration(xs:duration("P1Y"))	0

hours-from-time: Gets the hour portion of a time

Signature

hours-from-time($arg as xs:time?) as xs:integer?

Usage Notes

This function returns the hour portion of an xs:time value, as an integer between 0 and 23 inclusive.

Special Cases

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

• If $arg is 24:00:00, the function returns 0.

Examples

Example	Return value
hours-from-time(xs:time("10:30:23"))	10
hours-from-time(xs:time("10:30:23-05:00"))	10

Related Functions

hours-from-dateTime

id: Returns elements by their IDs

Signature

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

Usage Notes

Given a sequence of IDs, 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 item. 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 to have a particular ID if either:

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

• The type of the element itself is marked as an ID and its content is that particular ID value.

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's name is xml:id, it is automatically considered to be an ID.

The default collation is not used to match ID values; a simple comparison of Unicode code points is used.

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" in Chapter 20.

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

• The error "No context document" (FODC0001) is raised if:

  • $node is not part of a document (its root is not a document node).

  • $node is not provided and the context node is not part of a document.

• If $node is not provided and no context item is defined, the error XPDY0002 is raised.

• If $node is not provided and the context item is an atomic value rather than a node, the error XPTY0004 is raised.

Examples

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

Example	Return value
doc("book.xml")/id("preface")	The first section element
doc("book.xml")/id( ("context", "preface") )	The first two section elements, in document order
doc("book.xml")/id( "context preface" )	The first two section elements, in document order
doc("book.xml")//section[3]/secRef/id(@refs)	The second section element
doc("book.xml")//section[4]/secRef/id(@refs)	The second and third section elements
doc("book.xml")//secRef/id(@refs)	The second and third section elements
doc("book.xml")/ id( ("preface", "noMatch", "in!valid") )	The first section element

Example A-2. XML document with IDs and IDREFs (book.xml)

<book>
  <section id="preface">This book introduces XQuery...
    The examples are downloadable<fnref ref="fn1"/>...
  </section>
  <section id="context">...</section>
  <section id="language">...Expressions, introduced
   in <secRef refs="context"/>, are...
  </section>
  <section id="types">...As described in
    <secRef refs="context language"/>, you can...
  </section>
  <fn fnid="fn1">See http://datypic.com.</fn>
</book>

Related Functions

idref

idref: Finds references to a specified set of IDs

Signature

idref($arg as xs:string*, $node as node( )) as node( )*

Usage Notes

This function returns the nodes (elements or attributes) that reference one of a specified sequence of IDs. If $node is not provided, the function looks for elements and attributes in the same document as the current context item. If $node is provided, the function looks for elements and attributes in the same document as $node.

In order to be considered to reference an ID, the node must be marked as an IDREF or IDREFS type, and it must contain that ID value. Generally, this means that it was declared to be of type xs:IDREF or xs:IDREFS in an in-scope schema definition (or the equivalent in a DTD). If it is an IDREFS value, only one of the values in the list need match the ID. The default collation is not used to match ID values; a simple comparison of Unicode code points is used.

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. However, there may be several elements or attributes in the results that reference the same ID.

Note that if the IDREF value is contained in an attribute, the function returns the attribute node, not the containing element. This is designed to handle cases where an element has more than one IDREF attribute and you need to know which one matched.

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 a matching invalid IDREF.

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

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

• If $node is not part of a document (its root is not a document node), or if $node is not provided and the context node is not part of a document, the error "No context document" (FODC0001) is raised.

• If $node is not provided and no context item is defined, the error XPDY0002 is raised.

• If $node is not provided and the context item is an atomic value rather than a node, the error XPTY0004 is raised.

Working with IDs and IDREFs is discussed in further detail in "Working with IDs" in Chapter 20.

Examples

These examples use the input document book.xml shown in Example A-2. It is assumed that the input document has been validated, that the type of the id and fnid attributes is xs:ID, the type of the ref attribute is xs:IDREF, and the type of the refs attribute is xs:IDREFS.

Example	Return value
doc("book.xml")/idref("language")	The refs attribute of the second secRef element
doc("book.xml")/idref("context")	The refs attributes of both secRef elements
doc("book.xml")/idref( ("context", "language") )	The refs attributes of both secRef elements
doc("book.xml")//fn[1]/idref(@fnid)	The ref attribute of the fnRef element
doc("book.xml")/idref( ("language", "noMatch", "in!valid") )	The refs attribute of the second secRef element

Related Functions

id

implicit-timezone: Gets the implicit time zone used by the processor

Signature

implicit-timezone( ) as xs:dayTimeDuration

Usage Notes

This function returns the implicit time zone as an xs:dayTimeDuration value. The implicit time zone is used in comparisons and calculations involving date and time values that do not have explicitly defined time zones.

The implicit time zone is implementation-defined. In practice it will often default to the time zone used by the system clock in the operating system, or perhaps it will depend on the locale of the individual user.

Example

implicit-timezone( ) returns -PT5H if the implicit time zone is UTC minus five hours (also represented as −05:00).

in-scope-prefixes: Gets a list of all namespace prefixes that are in the scope of a specified element

Signature

in-scope-prefixes($element as element( )) as xs:string*

Usage Notes

This function returns a sequence of prefixes (as strings) that are used in the in-scope namespaces for the $element element. The results include a zero-length string if there is a default namespace declaration. It also always includes the xml prefix, which is built into the XML recommendation.

Note that the function uses in-scope namespaces, as opposed to statically known namespaces. That is, it returns information about the namespaces declared in the source document, not the namespaces declared in the query. The difference between in-scope and statically known namespaces is described further in "In-Scope Versus Statically Known Namespaces" in Chapter 10. More on working with namespaces and qualified names can be found in "Working with Qualified Names" in Chapter 20.

Example

The query:

in-scope-prefixes(<prefList xmlns="http://datypic.com/prod"
                            xmlns:prod2="http://datypic.com/prod2">xyz</prefList>)

returns the sequence ("", "prod2", "xml") in some arbitrary order.

Related Functions

namespace-uri-for-prefix

index-of: Determines where (and whether) an atomic value appears in a sequence

Signature

index-of($seqParam as xs:anyAtomicType*, $srchParam as xs:anyAtomicType,
         $collation as xs:string) as xs:integer*

Usage Notes

The $seqParam argument is the sequence to be searched, while $srchParam is the value to search for. This function returns a sequence of integers representing the position(s) of the value within the sequence, in order, starting with 1 (not 0).

The items in $seqParam are compared to those in $srchParam by their typed value, not their name or node identity. If either sequence contains nodes, those nodes are atomized to extract their atomic values. Untyped values are treated like strings.

Special Cases

• If $srchParam cannot be compared with a value in $seqParam, for example because $srchParam is a string and $seqParam contains an integer, it will not match that value, but it will not raise an error.

• If the $srchParam value does not appear in $seqParam, the function returns the empty sequence.

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

• If $collation is provided, values of type xs:string are compared using that collation; otherwise, the default collation is used.

Examples

Example	Return value
index-of( ("a", "b", "c"), "a")	1
index-of( ("a", "b", "c"), "d")	( )
index-of( (4, 5, 6, 4), 4)	(1, 4)
index-of( (4, 5, 6, 4), 04.0)	(1, 4)
index-of( ("a", 5, 6), "a")	1
index-of( ( ), "a")	( )
index-of( (<a>1</a>, <b>1</b>), <c>1</c> )	(1, 2)

Related Functions

position

insert-before: Inserts items into a sequence

Signature

insert-before($target as item( )*, $position as xs:integer,
              $inserts as item( )*) as item( )*

Usage Notes

This function returns a copy of the $target sequence with the item(s) in $inserts inserted at the position indicated by $position. Position numbers start at 1, not 0.

Special Cases

• If $inserts is the empty sequence, the function returns the $target sequence.

• If $target is the empty sequence, the function returns the $inserts sequence.

• If $position is greater than the number of items in $target, the $inserts items are appended to the end.

• If $position is less than 1, the $inserts items are inserted at the beginning.

Examples

Example	Return value
insert-before( ("a", "b", "c"), 1, ("x", "y"))	("x", "y", "a", "b", "c")
insert-before( ("a", "b", "c"), 2, ("x", "y"))	("a", "x", "y", "b", "c")
insert-before( ("a", "b", "c"), 10, ("x", "y"))	("a", "b", "c", "x", "y")
insert-before( ("a", "b", "c"), 0, ("x", "y"))	("x", "y", "a", "b", "c")
insert-before( ("a", "b", "c"), 2, ( ))	("a", "b", "c")
insert-before( ( ), 3, ("a", "b", "c") )	("a", "b", "c")

Related Functions

remove

iri-to-uri: Applies URI escaping rules to a string

Signature

iri-to-uri($uri-part as xs:string?) as xs:string

Usage Notes

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

The iri-to-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.

All characters except the following are escaped:

• Letters a through z and A through Z

• Digits 0 through 9

• Hyphen (-), underscore (_), period (.), exclamation point (!), tilde (~), asterisk (*), apostrophe ('), parentheses ("(" and ")"), and hash mark (#)

• Semicolon (;), forward slash (/), question mark (?), colon (:), at sign (@), ampersand (&), equals sign (=), plus sign (+), dollar sign ($), comma (,), square brackets ([ and ]), and percent sign (%)

The last set of characters specified in the preceding list is generally used to delimit parts of URIs. If you are escaping a single step of a URI path (as opposed to an entire URI), it is better to use the encode-for-uri function, which does escape these characters.

Special Cases

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

Examples

Example	Return value
iri-to-uri ("http://datypic.com/édition 2.html")	http://datypic.com/%C3%A9dition%202.html
iri-to-uri ("http://datypic.com/Sales Numbers.pdf")	http://datypic.com/Sales%20Numbers.pdf
iri-to-uri ("http://datypic.com/Sales % Numbers.pdf")	http://datypic.com/Sales%20%%20Numbers.pdf

Related Functions

encode-for-uri, escape-html-uri

lang: Tests whether the language of a node matches a specified language

Signature

lang($testlang as xs:string?, $node as node( )) as xs:boolean

Usage Notes

The language of a node is determined by the existence of an xml:lang attribute on the node itself or among its ancestors. The lang function can be used on any node, not just one containing string values. It is often used in the predicates of path expressions to filter data for a particular language.

The $testlang argument specifies the language to test. The function returns true if the relevant xml:lang attribute of the $node has a value that matches the $testlang value. The function returns false if the relevant xml:lang attribute does not match $testlang, or if there is no relevant xml:lang attribute.

The relevant xml:lang attribute is the one that appears as an attribute of the context node itself, or of one of its ancestors. If more than one xml:lang attribute can be found among the node and its ancestors, the nearest one applies.

The matching process is case-insensitive. If $testlang is en, it matches the xml:lang value EN, and vice versa. Also, the value of the xml:lang attribute can be a sublanguage of the $testlang value. For example, en-US, en-UK, and en-US-UK are all sublanguages of en. Therefore, if $testlang is en, and xml:lang is en-US, the node will be matched. This does not work in reverse; if $testlang is en-US, and xml:lang is en, it will not match.

More information on the format of languages can be found with the description of the xs:language type in Appendix B.

Special Cases

• If $testlang is the empty sequence, it is treated like a zero-length string.

• If $node is not provided, the context item is used.

• If no xml:lang attributes exist on the ancestors of a node, the function will return false.

• If $node is not provided, and the context item is undefined, the error XPDY0002 is raised.

• If $node is not provided, and the context item is not a node, the error XPTY0004 is raised.

Examples

These examples make use of the input document shown in Example A-3.

Example	Return value
doc("descs.xml")//desc[lang("en")]	The first desc element
doc("descs.xml")//desc[lang("en-US")]	The first desc element
doc("descs.xml")//desc[lang("fr")]	The second desc element
doc("descs.xml")//desc/line[lang("en")]	The first line element
doc("descs.xml")/desclist[lang("en-US")]	( )
doc("descs.xml")//desc[lang("FR")]	The second desc element

Example A-3. Document with xml:lang attributes specified (descs.xml)

<desclist xml:lang="en">
  <desc xml:lang="en-US">
     <line>The first line of the description.</line>
  </desc>
  <desc xml:lang="fr">
     <line>La premi&#232;re ligne de la déscription.</line>
  </desc>
</desclist>

last: Gets the number of items in the current context

Signature

last( ) as xs:integer

Usage Notes

The last function returns an integer representing the number of items in the current context. It is most often used in the predicate of path expressions, to retrieve the last item. For example, catalog/product[last( )] returns the last product child of catalog. That is because the last function returns 4, which serves as a positional predicate to retrieve the fourth product. The last function is also useful for testing whether an item is the last one in the sequence.

Special Cases

• If the context item is undefined, the error XPDY0002 is raised.

Examples

doc("catalog.xml")/catalog/product[last( )] returns the last product child of catalog. Example A-4 demonstrates how you might test whether an item is the last one in the sequence. It shows a query that returns a list of all the product numbers, separated by commas. However, after the last product number, it includes a period rather than a comma. It uses the last function and an is expression to compare each product element to the last one in the catalog.

Example A-4. Example of the last function

Query
let $catalog := doc("catalog.xml")/catalog
for $prod in $catalog/product
return concat($prod/number,
            (if ($prod is $catalog/product[last( )]) then (".") else (", ")))
Results
557, 563, 443, 784.

Related Functions

position

local-name: Gets the local part of a node name, as a string

Signature

local-name($arg as node( )?) as xs:string

Usage Notes

This function is useful only for element, attribute, and processing instruction nodes. For an element or attribute, this is simply its name, stripped of any prefix it might have.

To find elements with a particular local name, instead of writing a/*[local-name( )='nnn'], you can write a/*:nnn. However, the predicate test is useful if the name you are looking for is variable.

Special Cases

• If $arg is not provided, the context node is used.

• The function returns a zero-length string if:

  • $arg is the empty sequence.

  • $arg is a node that does not have a name (i.e., a comment, document, or text node).

• If $arg is a processing instruction node, the function returns its target.

• If $arg is not provided, and the context item is undefined, the error XPDY0002 is raised.

• If $arg is not provided, and the context item is not a node, the error XPTY0004 is raised.

Examples

These examples use the input document names.xml shown in Example A-5. They also assume that the prefixes pre and unpre have been mapped to the namespaces http://datypic.com/pre and http://datypic.com/unpre, respectively, in the query prolog.

Example	Return value
local-name(doc("names.xml")//noNamespace)	noNamespace
local-name(doc("names.xml")//pre:prefixed)	prefixed
local-name(doc("names.xml")//unpre:unprefixed)	unprefixed
local-name(doc("names.xml")//@pre:prefAttr)	prefAttr
local-name(doc("names.xml")//@noNSAttr)	noNSAttr

Example A-5. Namespaces in XML (names.xml)

<noNamespace>
  <pre:prefixed xmlns="http://datypic.com/unpre"
           xmlns:pre="http://datypic.com/pre">
    <unprefixed pre:prefAttr="a" noNSAttr="b">123</unprefixed>
  </pre:prefixed>
</noNamespace>

Related Functions

name, node-name, namespace-uri

local-name-from-QName: Gets the local part of a QName

Signature

local-name-from-QName($arg as xs:QName?) as xs:NCName?

Usage Notes

This function returns the local part of an xs:QName. If you want to retrieve the local part of an element or attribute name, you should consider using the local-name function instead; it requires one less step.

Special Cases

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

Examples

Example	Return value
local-name-from-QName(QName(" http://datypic.com/prod ", "number"))	number
local-name-from-QName(QName ("", "number"))	number
local-name-from-QName( ( ) )	( )

Related Functions

local-name, namespace-uri-from-QName, resolve-QName, QName

lower-case: Converts a string to lowercase

Signature

lower-case($arg as xs:string?) as xs:string

Usage Notes

The mappings between lowercase and uppercase characters are determined by Unicode case mappings. If a character in $arg does not have a corresponding lowercase character, it is included in the result string unchanged.

For English, you can do a case-blind comparison by writing lower-case($A)=lower-case($B) (or use upper-case instead). However this doesn't always work well for other languages. It's better to use a case-insensitive collation.

Special Cases

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

Examples

Example	Return value
lower-case("QUERY")	query
lower-case("Query")	query
lower-case("QUERY123")	query123

Related Functions

upper-case

matches: Determines whether a string matches a particular pattern

Signature

matches($input as xs:string?, $pattern as xs:string,
        $flags as xs:string) as xs:boolean

Usage Notes

The $pattern argument is a regular expression, whose syntax is covered in Chapter 18. Unlike many of the string-related functions, the matches function does not use collations at all. Regular expression matching is solely based on Unicode code points. Unless the anchors ^ or $ are used, the function returns true if any substring of $input matches the regular expression.

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

Special Cases

• If $input is the empty sequence, it is treated like a zero-length string.

• If $pattern is a zero-length string, the function will return true.

• If $pattern is not a valid regular expression, the error "Invalid regular expression" (FORX0002) is raised.

• If $flags contains unsupported options, the error "Invalid regular expression flags" (FORX0001) is raised.

Examples

Example	Return value
matches("query", "q")	true
matches("query", "ue")	true
matches("query", "^qu")	true
matches("query", "qu$")	false
matches("query", "[ux]")	true
matches("query", "q.*")	true
matches("query", "[a-z]{5}")	true
matches(( ), "q" )	false
matches("query", "[qu")	Error FORX0002

The additional examples shown in the following table use the $flags argument. They assume that the variable $address is bound to the following string (the line break is significant):

123 Main Street
Traverse City, MI 49684

Example	Return value
matches($address, "Street.*City")	false
matches($address, "Street.*City", "s")	true
matches($address, "Street$")	false
matches($address, "Street$", "m")	true
matches($address, "street")	false
matches($address, "street", "i")	true
matches($address, "Main Street")	true
matches($address, "Main Street", "x")	false
matches($address, "Main s Street", "x")	true
matches($address, "street$", "im")	true
matches($address, "Street$", "q")	Error FORX0001

Related Functions

contains

max: Returns the maximum of the values in a sequence

Signature

max($arg as xs:anyAtomicType*, $collation as xs:string) as xs:anyAtomicType?

Usage Notes

The $arg sequence can only contain values of one type, or of types derived from it. The one exception is that they can be all numeric (of different numeric types), in which case numeric promotion rules apply. That type must be ordered; it must be possible to compare the values using the < and > operators.

This function assumes untyped values are numeric unless they are explicitly cast to xs:string. To treat untyped data as strings, use the string function as shown in the last example.

The max function returns an atomic value, not the node that contains that value. For example, the expression:

max(doc("catalog.xml")//number)

will return the number 784, not the number element that contains 784.

Special Cases

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

• If $arg contains the value NaN, the function returns NaN.

• If $arg contains untyped values that cannot be cast to xs:double, the error "Invalid value for cast/constructor" (FORG0001) is raised.

• If $arg contains values of a type that does not support the < and > operators, the error "Invalid argument type" (FORG0006) is raised.

• If $arg contains values of various types, the error "Invalid argument type" (FORG0006) is raised.

• If $arg contains a date or time with no time zone, it is given the implicit time zone.

• If $collation is provided, values of type xs:string are compared using that collation; otherwise, the default collation is used.

Examples

Example	Return value
max( (2, 1, 5, 4, 3) )	5
max( ("a", "b", "c") )	c
max((xs:date("1999-04-15"), current-date( )) )	The current date
max( ("a", "b", 1) )	Error FORG0006
max( 2 )	2
max(doc("order.xml")//item/@dept)	Type error, if dept is untyped
max(doc("order.xml")//item/string(@dept))	WMN

Related Functions

min

min: Returns the minimum of the values in a sequence

Signature

min($arg as xs:anyAtomicType*, $collation as xs:string) as xs:anyAtomicType?

Usage Notes

The $arg sequence can only contain values of one type, or a type derived from it. The one exception is that they can be all numeric, in which case numeric promotion rules apply. That type must be ordered; it must be possible to compare the values using the < and > operators.

This function assumes untyped values are numeric unless they are explicitly cast to xs:string. To treat untyped data as strings, use the string function as shown in the last example.

The min function returns an atomic value, not the node that contains that value. For example, the expression:

min(doc("catalog.xml")//number)

will return the number 443, not the number element that contains 443.

Special Cases

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

• If $arg contains untyped values that cannot be cast to xs:double, the error "Invalid value for cast/constructor" (FORG0001) is raised.

• If $arg contains values of a type that does not support the < and > operators, the error "Invalid argument type" (FORG0006) is raised.

• If $arg contains values of various types, the error "Invalid argument type" (FORG0006) is raised.

• If $arg contains a date or time with no time zone, it is assumed to be in the implicit time zone.

• If $collation is provided, values of type xs:string are compared using that collation; otherwise, the default collation is used. Collations are described in Chapter 17.

Examples

Example	Return value
min( (2.0, 1, 3.5, 4) )	1
min( ("a", "b", "c") )	a
min(doc("order.xml")//item/@color)	Error FORG0006, if color is untyped
min(doc("order.xml")//item//string(@color))	""
min(doc("order.xml")//item/@color/string(.))	black

Related Functions

max

minutes-from-dateTime: Gets the minutes portion of a date/time

Signature

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

Usage Notes

This function returns the minutes portion of an xs:dateTime value, as an integer between 0 and 59 inclusive.

Special Cases

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

Example

minutes-from-dateTime(xs:dateTime("2006-08-15T10:30:23")) returns 30.

Related Functions

minutes-from-time

minutes-from-duration: Gets the normalized number of minutes in a duration

Signature

minutes-from-duration($arg as xs:duration?) as xs:integer?

Usage Notes

This function calculates the minutes component of a normalized xs:duration value, as an integer between −59 and 59 inclusive. This is not necessarily the same as the integer that appears before the M in the value. For example, if the duration is PT1M90S, the function returns 2 rather than 1. This is because 90 seconds is equal to 1.5 minutes, and the normalized value is therefore PT2M30S. Likewise, if the duration is PT90M, the result is 30, because the normalized value is PT1H30M.

Special Cases

• If $arg is a negative duration, the function returns a negative value.

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

Examples

Example	Return value
minutes-from-duration(xs:duration("PT30M"))	30
minutes-from-duration(xs:duration("-PT90M"))	−30
minutes-from-duration(xs:duration("PT1M90S"))	2
minutes-from-duration(xs:duration("PT3H"))	0
minutes-from-duration(xs:duration("PT60M"))	0

minutes-from-time: Gets the minutes portion of a time

Signature

minutes-from-time($arg as xs:time?) as xs:integer?

Usage Notes

This function returns the minutes portion of an xs:time value, as an integer between 0 and 59 inclusive.

Special Cases

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

Example

minutes-from-time(xs:time("10:30:23")) returns 30.

Related Functions

minutes-from-dateTime

month-from-date: Gets the month portion of a date

Signature

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

Usage Notes

This function returns the month portion of an xs:date value, as an integer between 1 and 12 inclusive.

Special Cases

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

Example

month-from-date(xs:date("2006-08-15")) returns 8.

Related Functions

month-from-dateTime

month-from-dateTime: Gets the month portion of a date/time

Signature

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

Usage Notes

This function returns the month portion of an xs:dateTime value, as an integer between 1 and 12 inclusive.

Special Cases

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

Example

month-from-dateTime(xs:dateTime("2006-08-15T10:30:23")) returns 8.

Related Functions

month-from-date

months-from-duration: Gets the normalized number of months in a duration

Signature

months-from-duration($arg as xs:duration?) as xs:integer?

Usage Notes

This function calculates the months component of a normalized xs:duration value, as an integer between −11 and 11 inclusive. This is not necessarily the same as the integer that appears before the M in the value. For example, if the duration is P18M, the function returns 6 rather than 18. This is because 12 of those months are considered to be one year, and the normalized value is therefore P1Y6M.

Special Cases

• If $arg is a negative duration, the function returns a negative value.

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

Examples

Example	Return value
months-from-duration(xs:duration("P3M"))	3
months-from-duration(xs:duration("-P18M"))	−6
months-from-duration(xs:duration("P1Y"))	0
months-from-duration(xs:duration("P12M"))	0
months-from-duration(xs:duration("P31D"))	0

name: Gets the qualified name of a node as a string

Signature

name($arg as node( )?) as xs:string

Usage Notes

This function returns a string that consists of the namespace prefix and colon (:), concatenated with the local part of the name. If the $arg node's name is not in a namespace, the function returns the local part of the name, with no prefix. If the name is associated with the default namespace, the resulting name will not be prefixed.

The name function returns a value that depends on the choice of prefixes in the source document. This makes it well suited for displaying the name, for example in error messages, but it should never be used to test the name, because choice of prefixes shouldn't affect the result. For this purpose, use node-name instead.

Special Cases

• If $arg is not provided, the context node is used.

• The function returns a zero-length string if:

  • $arg is the empty sequence.

  • $arg is a node that does not have a name (i.e., a document, comment, or text node).

• If $arg is a processing instruction node, the function returns its target.

• If $arg is not provided, and the context item is undefined, the error XPDY0002 is raised.

• If $arg is not provided, and the context item is not a node, the error XPTY0004 is raised.

Examples

These examples use the input document names.xml shown in Example A-5, in the section "local-name." They also assume that the prefixes pre2 and unpre2 have been mapped to the namespaces http://datypic.com/pre and http://datypic.com/unpre, respectively, in the query prolog.

The prefixes pre2 and unpre2 are used rather than pre and unpre to demonstrate that when selecting nodes from an instance document, the prefix used in the instance document is returned (not the query).

Example	Return value
name(doc("names.xml")//noNamespace)	noNamespace
name(doc("names.xml")//pre2:prefixed)	pre:prefixed
name(doc("names.xml")//unpre2:unprefixed)	unprefixed
name(doc("names.xml")//@pre2:prefAttr)	pre:prefAttr
name(doc("names.xml")//@noNSAttr)	noNSAttr

Related Functions

local-name, node-name, namespace-uri