XPath/XQuery element-with-id function

Summary

Returns the sequence of element nodes that have an ID value matching the value of one or more of the IDREF values supplied in $arg.

Signatures

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

Properties

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.

Rules

The effect of this function is identical to fn:id in respect of elements that have an attribute with the is-id property. However, it behaves differently in respect of element nodes with the is-id property. Whereas the fn:id function, for legacy reasons, returns the element that has the is-id property, this function returns the element identified by the ID, which is the parent of the element having the is-id property.

The function returns a sequence, in document order with duplicates eliminated, containing every element node E that satisfies all the following conditions:

  1. E is in the target document. The target document is the document containing $node, or the document containing the context item (.) if the second argument is omitted. The behavior of the function if $node is omitted is exactly the same as if the context item had been passed as $node.

  2. E has an ID value equal to one of the candidate IDREF values, where:

    An element has an ID value equal to V if either or both of the following conditions are true:

    The element has an child element node whose is-id property (See .) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

    The element has an attribute node whose is-id property (See .) is true and whose typed value is equal to V under the rules of the eq operator using the Unicode code point collation (http://www.w3.org/2005/xpath-functions/collation/codepoint).

    Each xs:string in $arg is parsed as if it were of type IDREFS, that is, each xs:string in $arg is treated as a whitespace-separated sequence of tokens, each acting as an IDREF. These tokens are then included in the list of candidate IDREFs. If any of the tokens is not a lexically valid IDREF (that is, if it is not lexically an xs:NCName), it is ignored. Formally, the candidate IDREF values are the strings in the sequence given by the expression:

    for $s in $arg return fn:tokenize(fn:normalize-space($s), ' ')[. castable as xs:IDREF]
  3. If several elements have the same ID value, then E is the one that is first in document order.

Examples

let $emp :=

The expression $emp/fn:element-with-id('ID21256')/name() returns "employee".

The expression $emp/fn:element-with-id('E21256')/name() returns "employee".

Error Conditions

A dynamic error is raised if $node, or the context item if the second argument is omitted, is a node in a tree whose root is not a document node.

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

If the context item is absent, dynamic error

If the context item is not a node, type error .

Notes

This function is equivalent to the fn:id function except when dealing with ID-valued element nodes. Whereas the fn:id function selects the element containing the identifier, this function selects its parent.

If the data model is constructed from an Infoset, an attribute will have the is-id property if the corresponding attribute in the Infoset had an attribute type of ID: typically this means the attribute was declared as an ID in a DTD.

If the data model is constructed from a PSVI, an element or attribute will have the is-id property if its typed value is a single atomic value of type xs:ID or a type derived by restriction from xs:ID.

No error is raised in respect of a candidate IDREF value that does not match the ID of any element in the document. If no candidate IDREF value matches the ID value of any element, the function returns the empty sequence.

It is not necessary that the supplied argument should have type xs:IDREF or xs:IDREFS, or that it should be derived from a node with the is-idrefs property.

An element may have more than one ID value. This can occur with synthetic data models or with data models constructed from a PSVI where the element and one of its attributes are both typed as xs:ID.

If the source document is well-formed but not valid, it is possible for two or more elements to have the same ID value. In this situation, the function will select the first such element.

It is also possible in a well-formed but invalid document to have an element or attribute that has the is-id property but whose value does not conform to the lexical rules for the xs:ID type. Such a node will never be selected by this function.