XML DOM XPathResult Object

The result of an XPath query.

The XPathResult object

The XPathResult object represents the value of an XPath expression. Objects of this type are used by Document.evaluate() And XPathExpression.evaluate() Return. XPath queries can be evaluated to strings, numbers, boolean values, nodes, or lists of nodes. XPath implementations can return lists of nodes in several different ways, so this object defines a somewhat complex API to obtain the actual result of an XPath query.

To use an XPathResult, first check the resultType property. It will save an XPathResult constant. The value of this property tells you which properties and methods to use to determine the result value. Calling a method not defined for the current resultType or reading a property not defined for it will cause an exception.

IE does not support the XPathResult API. To perform XPath queries in IE, see Node.selectNodes() And Node.selectSingleNode() .

Constants of the XPathResult object

The following constants define the types that an XPath query may return. The resultType property of the XPathResult object saves one of these values, specifying what type of result the object will save. These constants are used with Document.evaluate() and XPathExpression.evaluate() to specify the expected result type.

The following constants and their meanings are as follows:

ANY_TYPE
Pass this value to Document.evaluate() or XPathExpression.evaluate() to specify the acceptable result type. The resultType property does not set this value.
NUMBER_TYPE
numbervalue saves the result.
STRING_TYPE
stringvalue saves the result.
BOOLEAN_TYPE
booleanValue saves the result.
UNORDERED_NODE_ITERATOR_TYPE
This result is an unordered collection of nodes, which can be accessed sequentially by repeatedly calling iterateNext() until null is returned. The document must not be modified during this iteration.
ORDERED_NODE_ITERATOR_TYPE
The result is a list of nodes, ordered according to the attributes in the document. It can be accessed sequentially by repeatedly calling iterateNext() until null is returned. The document must not be modified during this iteration.
UNORDERED_NODE_SNAPSHOT_TYPE
The result is a list of randomly accessed nodes. The snapshotLength property specifies the length of the list, and the snapshotItem() method returns the node at the specified index. Nodes may not appear in the order they appear in the document. Since this result is a 'snapshot', it remains valid even if the document changes.
ORDERED_NODE_SNAPSHOT_TYPE
This result is a list of nodes that can be accessed randomly, like UNORDERED_NODE_SNAPSHOT_TYPE, but the list is ordered according to the order in the document.
ANY_UNORDERED_NODE_TYPE
The singleNodeValue property refers to a node that matches the query, or null if no matching node is found. If there are multiple nodes that match the query, singleNodeValue may be any of the matching nodes.
FIRST_ORDERED_NODE_TYPE
singleNodeValue saves the first node in the document that matches the query, or null if no matching node is found.

Instance properties of the XPathResult object

Many of the properties here are only valid when resultType has saved a specific value. Accessing a property not defined for the current resultType will cause an exception.

booleanValue
When the resultType is BOOLEAN_TYPE, save the result value.
invalidIteratorState
If the resultType is one of the ITERATOR_TYPE constants and the document has been modified, then it is true; it makes the iterator invalid because the result has already been returned.
numberValue
When the resultType is NUMBER_TYPE, save the result value.
resultType
What kind of result is returned by the XPath query. Its value is one of the constants listed earlier. The value of this property tells you which other properties and methods you can use.
singleNodeValue
When the resultType is XPathResult.ANY_UNORDERED_NODE_TYPE or XPathResult.FIRST_UNORDERED_NODE_TYPE, save the result value.
snapshotLength
When the resultType is UNORDERED_NODE_SNAPSHOT_TYPE or ORDERED_NODE_ITERATOR_TYPE, specify the number of nodes to be returned. This property is used in conjunction with snapshotItem().
stringValue
When resultType is STRING_TYPE, save the result value.

Methods of XPathResult Object

Method Description
iterateNext() If resultType is UNORDERED_NODE_ITERATOR_TYPE or ORDERED_NODE_ITERATOR_TYPE, use this method.
snapshotItem() Return the node at the specified index in the result node list. This method can only be used when resultType is UNORDERED_NODE_SNAPSHOT_TYPE or ORDERED_NODE_SNAPSHOT_TYPE. The snapshotLength property is used together with this method.

Related Pages

Document.evaluate() And XPathExpression.evaluate()