This section specifies functions and operators on nodes. Nodes are formally defined in Section 6 Nodes DM31.
Function | Meaning |
---|---|
fn:name |
Returns the name of a node, as an xs:string that is either the zero-length
string, or has the lexical form of an xs:QName . |
fn:local-name |
Returns the local part of the name of $node as an xs:string
that is either the zero-length string, or has the lexical form of an
xs:NCName . |
fn:namespace-uri |
Returns the namespace URI part of the name of $node , as an
xs:anyURI value. |
fn:lang |
This function tests whether the language of $node , or the context item if
the second argument is omitted, as specified by xml:lang attributes is the
same as, or is a sublanguage of, the language specified by $language . |
fn:root |
Returns the root of the tree to which $node belongs. This will usually, but
not necessarily, be a document node. |
fn:path |
Returns a path expression that can be used to select the supplied node relative to the root of its containing document. |
fn:has-children |
Returns true if the supplied node has one or more child nodes (of any kind). |
fn:innermost |
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated. |
fn:outermost |
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated. |
For the illustrative examples below assume an XQuery or transformation operating on a
PurchaseOrder
document containing a number of line-item
elements. Each line-item has
child elements called description
, price
, quantity
, etc. whose content is different
for each line-item
. Quantity has simple content of type xs:decimal
.
Further assume that variables $item1
, $item2
, etc. are
each bound to single line-item element nodes in the document in sequence and that
the value of the quantity child of the first line-item is 5.0
.
let $po := <PurchaseOrder> <line-item> <description>Large widget</description> <price>8.95</price> <quantity>5.0</quantity> </line-item> <line-item> <description>Small widget</description> <price>3.99</price> <quantity>2.0</quantity> </line-item> <line-item> <description>Tiny widget</description> <price>1.49</price> <quantity>805</quantity> </line-item> </PurchaseOrder>
let $item1 := $po/line-item[1]
let $item2 := $po/line-item[2]
let $item3 := $po/line-item[3]
Returns the name of a node, as an xs:string
that is either the zero-length
string, or has the lexical form of an xs:QName
.
fn:name () as xs:string |
fn:name ( |
||
$node |
as node()? |
:= . |
) as xs:string |
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 the argument is supplied and is the empty sequence, the function returns the zero-length string.
If the node identified by $node
has no name (that is, if it is a document
node, a comment, a text node, or a namespace node having no name), the function returns
the zero-length string.
Otherwise, the function returns the value of the expression
fn:string(fn:node-name($node))
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
Because the result depends on the choice of namespace prefixes in the source document,
it is not good practice to use the result of this function for anything other than display
purposes. For example, the test name(.) = 'my:profile'
will fail if the source
document uses an unexpected namespace prefix. Such a test (assuming it relates to an element node)
is better written as boolean(self::my:profile)
.
Returns the local part of the name of $node
as an xs:string
that is either the zero-length string, or has the lexical form of an
xs:NCName
.
fn:local-name () as xs:string |
fn:local-name ( |
||
$node |
as node()? |
:= . |
) as xs:string |
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 the argument is supplied and is the empty sequence, the function returns the zero-length string.
If the node identified by $node
has no name (that is, if it is a document
node, a comment, a text node, or a namespace node having no name), the function returns
the zero-length string.
Otherwise, the function returns the local part of the expanded-QName of the node
identified by $node
, as determined by the dm:node-name
accessor
defined in Section 5.10 node-name AccessorDM40). This will be an
xs:string
whose lexical form is an xs:NCName
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
Returns the namespace URI part of the name of $node
, as an
xs:anyURI
value.
fn:namespace-uri () as xs:anyURI |
fn:namespace-uri ( |
||
$node |
as node()? |
:= . |
) as xs:anyURI |
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the argument is omitted, it defaults to the context node (.
). 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 the node identified by $node
is neither an element nor an attribute node,
or if it is an element or attribute node whose expanded-QName (as determined by the
dm:node-name
accessor in the Section 5.10 node-name AccessorDM40)
is in no namespace, then the function returns the zero-length xs:anyURI
value.
Otherwise, the result will be the namespace URI part of the expanded-QName of the node
identified by $node
, as determined by the dm:node-name
accessor
defined in Section 5.10 node-name AccessorDM40), returned as an
xs:anyURI
value.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
This function tests whether the language of $node
, or the context item if
the second argument is omitted, as specified by xml:lang
attributes is the
same as, or is a sublanguage of, the language specified by $language
.
fn:lang ( |
||
$language |
as xs:string? |
|
) as xs:boolean |
fn:lang ( |
||
$language |
as xs:string? , |
|
$node |
as node() |
:= . |
) as xs:boolean |
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The behavior of the function if the second argument is omitted is exactly the same as if
the context item (.
) had been passed as the second argument.
The language of the argument $node
, or the context item if the second
argument is omitted, is determined by the value of the xml:lang
attribute
on the node, or, if the node has no such attribute, by the value of the
xml:lang
attribute on the nearest ancestor of the node that has an
xml:lang
attribute. If there is no such ancestor, then the function
returns false
.
If $language
is the empty sequence it is interpreted as the zero-length
string.
The relevant xml:lang
attribute is determined by the value of the XPath
expression:
(ancestor-or-self::*/@xml:lang)[last()]
If this expression returns an empty sequence, the function returns false
.
Otherwise, the function returns true
if and only if, based on a caseless
default match as specified in section 3.13 of [The Unicode Standard], either:
$language
is equal to the string-value of the relevant
xml:lang
attribute, or
$language
is equal to some substring of the string-value of the
relevant xml:lang
attribute that starts at the start of the
string-value and ends immediately before a hyphen, "-" (the character "-" is
HYPHEN-MINUS, #x002D).
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
The expression fn:lang("en")
would return true
if the
context node were any of the following four elements:
<para xml:lang="en"/>
<div xml:lang="en"><para>And now, and
forever!</para></div>
<para xml:lang="EN"/>
<para xml:lang="en-us"/>
The expression fn:lang("fr")
would return false
if the
context node were <para xml:lang="EN"/>
Returns the root of the tree to which $node
belongs. This will usually, but
not necessarily, be a document node.
fn:root () as node() |
fn:root ( |
||
$node |
as node()? |
:= . |
) as node()? |
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the function is called without an argument, the context item (.
) is used
as the default argument. 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 function returns the value of the expression
($arg/ancestor-or-self::node())[1]
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
These examples use some variables which could be defined in [XQuery 4.1: An XML Query Language] as:
let $i := <tool>wrench</tool> let $o := <order> {$i} <quantity>5</quantity> </order> let $odoc := document {$o} let $newi := $o/tool
Or they could be defined in [XSL Transformations (XSLT) Version 4.0] as:
<xsl:variable name="i" as="element()"> <tool>wrench</tool> </xsl:variable> <xsl:variable name="o" as="element()"> <order> <xsl:copy-of select="$i"/> <quantity>5</quantity> </order> </xsl:variable> <xsl:variable name="odoc"> <xsl:copy-of select="$o"/> </xsl:variable> <xsl:variable name="newi" select="$o/tool"/>
fn:root($i)
returns the element node $i
fn:root($o/quantity)
returns the element node $o
fn:root($odoc//quantity)
returns the document node $odoc
fn:root($newi)
returns the element node $o
The final three examples could be made type-safe by wrapping their operands with
fn:exactly-one()
.
Returns a path expression that can be used to select the supplied node relative to the root of its containing document.
fn:path () as xs:string? |
fn:path ( |
||
$node |
as node()? |
:= . |
) as xs:string? |
The one-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The two-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
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 a document node, the function returns the string
"/"
.
Otherwise, the function returns a string that consists of a sequence of steps, one
for each ancestor-or-self of $node
other than the root node. This string is
prefixed by "Q{http://www.w3.org/2005/xpath-functions}root()"
if the root
node is not a document node. Each step consists of the character "/"
followed by a string whose form depends on the kind of node selected by that step, as
follows:
For an element node,
Q{uri}local[position]
,
where uri
is the namespace URI of the node name or the
empty string if the node is in no namespace, local
is
the local part of the node name, and position
is an
integer representing the position of the selected node among its like-named
siblings.
For an attribute node:
if the node is in no namespace, @local
, where
local
is the local part of the node name
otherwise, @Q{uri}local
, where
uri
is the namespace URI of the node name,
and local
is the local part of the node name
For a text node: text()[position]
where
position
is an integer representing the position
of the selected node among its text node siblings
For a comment node: comment()[position]
where
position
is an integer representing the position
of the selected node among its comment node siblings
For a processing-instruction node:
processing-instruction(local)[position]
where local
is the name of the processing instruction
node and position
is an integer representing the
position of the selected node among its like-named processing-instruction node
siblings
For a namespace node:
If the namespace node has a name:
namespace::prefix
, where
prefix
is the local part of the name of the
namespace node (which represents the namespace prefix).
If the namespace node has no name (that is, it represents the default
namespace):
namespace::*[Q{http://www.w3.org/2005/xpath-functions}local-name()=""]
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
let $e := document { <p xmlns="http://example.com/one" xml:lang="de" author="Friedrich von Schiller"> Freude, schöner Götterfunken,<br/> Tochter aus Elysium,<br/> Wir betreten feuertrunken,<br/> Himmlische, dein Heiligtum.</p>}
The expression fn:path($e)
returns '/'
.
The expression fn:path($e/*:p)
returns '/Q{http://example.com/one}p[1]'
.
The expression fn:path($e/*:p/@xml:lang)
returns '/Q{http://example.com/one}p[1]/@Q{http://www.w3.org/XML/1998/namespace}lang'
.
The expression fn:path($e/*:p/@author)
returns '/Q{http://example.com/one}p[1]/@author'
.
The expression fn:path($e/*:p/*:br[2])
returns '/Q{http://example.com/one}p[1]/Q{http://example.com/one}br[2]'
.
The expression fn:path($e//text()[starts-with(normalize-space(),
'Tochter')])
returns '/Q{http://example.com/one}p[1]/text()[2]'
.
let $emp := <employee xml:id="ID21256"> <empnr>E21256</empnr> <first>John</first> <last>Brown</last> </employee>
The expression fn:path($emp)
returns 'Q{http://www.w3.org/2005/xpath-functions}root()'
.
The expression fn:path($emp/@xml:id)
returns 'Q{http://www.w3.org/2005/xpath-functions}root()/@Q{http://www.w3.org/XML/1998/namespace}id'
.
The expression fn:path($emp/empnr)
returns 'Q{http://www.w3.org/2005/xpath-functions}root()/Q{}empnr[1]'
.
Returns true if the supplied node has one or more child nodes (of any kind).
fn:has-children () as xs:boolean |
fn:has-children ( |
||
$node |
as node()? |
:= . |
) as xs:boolean |
The zero-argument form of this function is ·deterministic·, ·context-dependent·, and ·focus-dependent·.
The one-argument form of this function is ·deterministic·, ·context-independent·, and ·focus-independent·.
If the 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.
Provided that the supplied argument $node
matches the expected type
node()?
, the result of the function call
fn:has-children($node)
is defined to be the same as the result of the
expression fn:exists($node/child::node())
.
The following errors may be raised when $node
is omitted:
If the context item is absentDM40, dynamic error [err:XPDY0002]XP
If the context item is not a node, type error [err:XPTY0004]XP.
If $node
is an empty sequence the result is false.
The motivation for this function is to support streamed evaluation. According to the streaming rules in [XSL Transformations (XSLT) Version 4.0], the following construct is not streamable:
<xsl:if test="exists(row)"> <ulist> <xsl:for-each select="row"> <item><xsl:value-of select="."/></item> </xsl:for-each> </ulist> </xsl:if>
This is because it makes two downward selections to read the child row
elements. The use of fn:has-children
in the xsl:if
conditional
is intended to circumvent this restriction.
Although the function was introduced to support streaming use cases, it has general utility as a convenience function.
Returns every node within the input sequence that is not an ancestor of another member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:innermost ( |
||
$nodes |
as node()* |
|
) as node()* |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function call fn:innermost($nodes)
is defined to be
equivalent to the result of the expression:
$nodes except $nodes/ancestor::node()
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.
If the source document contains nested sections represented by div
elements, the expression innermost(//div)
returns those div
elements that do not contain further div
elements.
Returns every node within the input sequence that has no ancestor that is itself a member of the input sequence; the nodes are returned in document order with duplicates eliminated.
fn:outermost ( |
||
$nodes |
as node()* |
|
) as node()* |
This function is ·deterministic·, ·context-independent·, and ·focus-independent·.
The effect of the function call fn:outermost($nodes)
is defined to be
equivalent to the result of the expression:
$nodes[not(ancestor::node() intersect $nodes)]/.
That is, the function takes as input a sequence of nodes, and returns every node within the sequence that does not have another node within the sequence as an ancestor; the nodes are returned in document order with duplicates eliminated.
The formulation $nodes except $nodes/descendant::node()
might appear to be
simpler, but does not correctly account for attribute nodes, as these are not
descendants of their parent element.
The motivation for the function was based on XSLT streaming use cases. There are cases
where the [XSL Transformations (XSLT) Version 4.0] streaming rules allow the construct
outermost(//section)
but do not allow //section
; the
function can therefore be useful in cases where it is known that sections will not be
nested, as well as cases where the application actually wishes to process all sections
except those that are nested within another.
If the source document contains nested sections represented by div
elements, the expression outermost(//div)
returns those div
elements that are not contained within further div
elements.