2 Accessors

Accessors and their semantics are described in [XQuery and XPath Data Model (XDM) 3.1]. Some of these accessors are exposed to the user through the functions described below.

Each of these functions has an arity-zero signature which is equivalent to the arity-one form, with the context item supplied as the implicit first argument. In addition, each of the arity-one functions accepts an empty sequence as the argument, in which case it generally delivers an empty sequence as the result: the exception is fn:string, which delivers a zero-length string.

Function Accessor Accepts Returns
fn:node-name node-name node (optional) xs:QName (optional)
fn:nilled nilled node (optional) xs:boolean (optional)
fn:string string-value item (optional) xs:string
fn:data typed-value zero or more items a sequence of atomic values
fn:base-uri base-uri node (optional) xs:anyURI (optional)
fn:document-uri document-uri node (optional) xs:anyURI (optional)

2.1 fn:node-name

Summary

Returns the name of a node, as an xs:QName.

Signatures
fn:node-name() as xs:QName?
fn:node-name(
$node as node()? := .
) as xs:QName?
Properties

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

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

Rules

If the argument is omitted, it defaults to the context item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

If $node is the empty sequence, the empty sequence is returned.

Otherwise, the function returns the result of the dm:node-name accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 5.10 node-name AccessorDM40).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

For element and attribute nodes, the name of the node is returned as an xs:QName, retaining the prefix, namespace URI, and local part.

For processing instructions, the name of the node is returned as an xs:QName in which the prefix and namespace URI are absentDM40.

For a namespace node, the function returns an empty sequence if the node represents the default namespace; otherwise it returns an xs:QName in which prefix and namespace URI are absentDM40 and the local part is the namespace prefix being bound.

For all other kinds of node, the function returns the empty sequence.

2.2 fn:nilled

Summary

Returns true for an element that is nilled.

Signatures
fn:nilled() as xs:boolean?
fn:nilled(
$node as node()? := .
) as xs:boolean?
Properties

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

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

Rules

If the argument is omitted, it defaults to the context item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

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

Otherwise the function returns the result of the dm:nilled accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 5.8 nilled AccessorDM40).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

If $node is not an element node, the function returns the empty sequence.

If $node is an untyped element node, the function returns false.

In practice, the function returns true only for an element node that has the attribute xsi:nil="true" and that is successfully validated against a schema that defines the element to be nillable; the detailed rules, however, are defined in [XQuery and XPath Data Model (XDM) 3.1].

2.3 fn:string

Summary

Returns the value of $item represented as an xs:string.

Signatures
fn:string() as xs:string
fn:string(
$item as item()? := .
) as xs:string
Properties

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

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

Rules

In the zero-argument version of the function, $item defaults to the context item. That is, calling fn:string() is equivalent to calling fn:string(.).

If $item is the empty sequence, the function returns the zero-length string.

If $item is a node, the function returns the string value of the node, as obtained using the dm:string-value accessor defined in [XQuery and XPath Data Model (XDM) 3.1] (see Section 5.12 string-value AccessorDM40).

If $item is an atomic value, the function returns the result of the expression $item cast as xs:string (see 19 Casting).

In all other cases, a dynamic error occurs (see below).

Error Conditions

A dynamic error is raised [err:XPDY0002]XP by the zero-argument version of the function if the context item is absentDM40.

A type error is raised [err:FOTY0014] if $item is a function item (this includes maps and arrays).

Notes

Every node has a string value, even an element with element-only content (which has no typed value). Moreover, casting an atomic value to a string always succeeds. Functions, maps, and arrays have no string value, so these are the only arguments that satisfy the type signature but cause failure.

Examples

The expression string(23) returns "23".

The expression string(false()) returns "false".

The expression string("Paris") returns "Paris".

The expression string((1, 2, 3)) raises error XPTY0004.

The expression string([[1, 2], [3, 4]]) raises error FOTY0014.

The expression string(abs#1) raises error FOTY0014.

let $para := 
<para>In a hole in the ground there lived a <term author="Tolkien">hobbit</term>.</para>
         

The expression string($para) returns "In a hole in the ground there lived a hobbit.".

2.4 fn:data

Summary

Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values.

Signatures
fn:data() as xs:anyAtomicType*
fn:data(
$input as item()* := .
) as xs:anyAtomicType*
Properties

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

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

Rules

If the argument is omitted, it defaults to the context item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

The result of fn:data is the sequence of atomic values produced by applying the following rules to each item in $input:

  • If the item is an atomic value, it is appended to the result sequence.

  • If the item is a node, the typed value of the node is appended to the result sequence. The typed value is a sequence of zero or more atomic values: specifically, the result of the dm:typed-value accessor as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 5.14 typed-value AccessorDM40).

  • If the item is an array, the result of applying fn:data to each member of the array, in order, is appended to the result sequence.

Error Conditions

A type error is raised [err:FOTY0012] if an item in the sequence $input is a node that does not have a typed value.

A type error is raised [err:FOTY0013] if an item in the sequence $input is a function item other than an array.

A dynamic error is raised if $input is omitted and the context item is absentDM40.

Notes

The process of applying the fn:data function to a sequence is referred to as atomization. In many cases an explicit call on fn:data is not required, because atomization is invoked implicitly when a node or sequence of nodes is supplied in a context where an atomic value or sequence of atomic values is required.

The result of atomizing an empty sequence is an empty sequence.

The result of atomizing an empty array is an empty sequence.

Examples

The expression data(123) returns 123.

The expression data((123, 456)) returns 123, 456.

The expression data([[1,2],[3,4]]) returns 1, 2, 3, 4.

let $para := 
<para>In a hole in the ground there lived a <term author="Tolkien">hobbit</term>.</para>
         

The expression data($para) returns xs:untypedAtomic("In a hole in the ground there lived a hobbit.").

The expression data($para/term/@author) returns xs:untypedAtomic("Tolkien").

The expression data(abs#1) raises error FOTY0013.

2.5 fn:base-uri

Summary

Returns the base URI of a node.

Signatures
fn:base-uri() as xs:anyURI?
fn:base-uri(
$node as node()? := .
) as xs:anyURI?
Properties

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

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

Rules

The zero-argument version of the function returns the base URI of the context node: it is equivalent to calling fn:base-uri(.).

The single-argument version of the function behaves as follows:

  1. If $node is the empty sequence, the function returns the empty sequence.

  2. Otherwise, the function returns the value of the dm:base-uri accessor applied to the node $node. This accessor is defined, for each kind of node, in the XDM specification (See Section 5.2 base-uri AccessorDM40).

Note:

As explained in XDM, document, element and processing-instruction nodes have a base-uri property which may be empty. The base-uri property for all other node kinds is the empty sequence. The dm:base-uri accessor returns the base-uri property of a node if it exists and is non-empty; otherwise it returns the result of applying the dm:base-uri accessor to its parent, recursively. If the node does not have a parent, or if the recursive ascent up the ancestor chain encounters a parentless node whose base-uri property is empty, the empty sequence is returned. In the case of namespace nodes, however, the result is always an empty sequence — it does not depend on the base URI of the parent element.

See also fn:static-base-uri.

Error Conditions

The following errors may be raised when $node is omitted:

2.6 fn:document-uri

Summary

Returns the URI of a resource where a document can be found, if available.

Signatures
fn:document-uri() as xs:anyURI?
fn:document-uri(
$node as node()? := .
) as xs:anyURI?
Properties

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

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

Rules

If the argument is omitted, it defaults to the context item (.). The behavior of the function if the argument is omitted is exactly the same as if the context item had been passed as the argument.

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

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

Otherwise, the function returns the value of the document-uri accessor applied to $node, as defined in [XQuery and XPath Data Model (XDM) 3.1] (See Section 6.1.2 AccessorsDM40).

Error Conditions

The following errors may be raised when $node is omitted:

Notes

In the case of a document node $D returned by the fn:doc function, or a document node at the root of a tree containing a node returned by the fn:collection function, it will always be true that either fn:document-uri($D) returns the empty sequence, or that the following expression is true: fn:doc(fn:document-uri($D)) is $D. It is ·implementation-defined· whether this guarantee also holds for document nodes obtained by other means, for example a document node passed as the initial context node of a query or transformation.

A consequence of these rules is that it is not possible (within the execution scope of a transformation) for two different documents to have the same value for their document-uri property. This means that in situations where URI stability is not guaranteed (for example, with streamed input documents in XSLT, or for documents returned by fn:collection if document stability has been disabled), the document-uri property should be absent, and fn:document-uri should return an empty sequence.