25.332. XPathResult: the result of an XPath query Firefox 1.0; Safari 2.01; Opera 9: Object  XPathResult 25.332.1. Constants The following constants define the possible types an XPath query can return. The resultType property of an XPathResult object holds one of these values to specify which kind of result the object holds. These constants are also used with Document.evaluate( ) and XPathExpression.evaluate( ) methods to specify the desired result type. The constants and their meanings are as follows:
ANY_TYPE Passes this value to Document.evaluate( ) or XPathExpression.evaluate( ) to specify that any type of result is acceptable. The resultType property is never set to this value.
NUMBER_TYPE numberValue holds the result.
STRING_TYPE stringValue holds the result.
BOOLEAN_TYPE booleanValue holds the result.
UNORDERED_NODE_ITERATOR_TYPE The result is an unordered set of nodes, which can be accessed sequentially by calling iterateNext( ) repeatedly until it returns null. The document must not be modified during this iteration.
ORDERED_NODE_ITERATOR_TYPE The result is a list of nodes, arranged in document order, which can be accessed sequentially by calling iterateNext( ) repeatedly until it returns null. The document must not be modified during this iteration.
UNORDERED_NODE_SNAPSHOT_TYPE The result is a random-access list of nodes. The snapshotLength property specifies the length of the list, and the snapshotItem( ) method returns the node at a specified index. The nodes may not be in the same order they appear in the document. Since this kind of result is a "snapshot," it remains valid even if the document is changed.
ORDERED_NODE_SNAPSHOT_TYPE The result is a random-access list of nodes, just like UNORDERED_NODE_SNAPSHOT_TYPE, except that this list is arranged in document order.
ANY_UNORDERED_NODE_TYPE The singleNodeValue property refers to a node that matches the query or null if no nodes matched. If more than one node matches the query, singleNodeValue may be any one of the matching nodes.
FIRST_ORDERED_NODE_TYPE singleNodeValue holds the first node in the document that matched the query, or null if no nodes matched. 25.332.2. Instance Properties Many of these properties are valid only when resultType holds a particular value. Accessing properties that are not defined for the current resultType causes an exception.
readonly boolean booleanValue Holds the result value when resultType is BOOLEAN_TYPE.
readonly boolean invalidIteratorState Is TRue if resultType is one of the ITERATOR_TYPE constants and the document has been modified, making the iterator invalid, because the result was returned.
readonly float numberValue Holds the result value when resultType is NUMBER_TYPE.
readonly short resultType Specifies what kind of result the XPath query returned. Its value is one of the constants listed earlier. The value of this property tells you which other properties or methods you can use.
readonly Node singleNodeValue Holds the result value when resultType is XPathResult.ANY_UNORDERED_NODE_TYPE or XPathResult.FIRST_UNORDERED_NODE_TYPE.
snapshotLength Specifies the number of nodes returned when resultType is UNORDERED_NODE_SNAPSHOT_TYPE or ORDERED_NODE_SNAPSHOT_TYPE. Use this property in conjunction with snapshotItem( ).
stringValue Holds the result value when resultType is STRING_TYPE. 25.332.3. Methods
iterateNext( ) Returns the next node in the node set. Use this method if the resultType is UNORDERED_NODE_ITERATOR_TYPE or ORDERED_NODE_ITERATOR_TYPE.
snapshotItem( ) Returns the node at the specified index in the list of result nodes. This method may be used only if resultType is UNORDERED_NODE_SNAPSHOT_TYPE or ORDERED_NODE_SNAPSHOT_TYPE. Use the snapshotLength property in conjunction with this method. 25.332.4. Description An XPathResult object represents the value of an XPath expression. Objects of this type are returned by Document.evaluate( ) and XPathExpression.evaluate( ). XPath queries can evaluate to strings, numbers, booleans, nodes, and lists of nodes. XPath implementations can return lists of nodes in several different ways, so this object defines a slightly complex API for obtaining the actual result of an XPath query. To use an XPathResult, first check the resultType property. It will hold one of the XPathResult constants. The value of this property tells you which property or method you need to use to determine the result value. Calling methods or reading properties that are not defined for the current resultType causes an exception. Internet Explorer does not support the XPathResult API. To perform XPath queries in IE, see Node.selectNodes( ) and Node.selectSingleNode( ). 25.332.5. See Also Document.evaluate( ), XPathExpression.evaluate( ) |
