Package net.sf.saxon.tree.util

## Class Navigator

- java.lang.Object
- - net.sf.saxon.tree.util.Navigator

-     public final class Navigator
      extends java.lang.Object

  The Navigator class provides helper classes for navigating a tree, irrespective of its implementation

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `Navigator.AncestorEnumeration` | General-purpose implementation of the ancestor and ancestor-or-self axes
    `static class` | `Navigator.AxisFilter` | AxisFilter is an iterator that applies a NodeTest filter to the nodes returned by an underlying AxisIterator.
    `static class` | `Navigator.DescendantEnumeration` | General-purpose implementation of the descendant and descendant-or-self axes, in terms of the child axis.
    `static class` | `Navigator.EmptyTextFilter` | EmptyTextFilter is an iterator that applies removes any zero-length text nodes returned by an underlying AxisIterator.
    `static class` | `Navigator.FollowingEnumeration` | General purpose implementation of the following axis, in terms of the ancestor, child, and following-sibling axes
    `static class` | `Navigator.PrecedingEnumeration` | Helper method to iterate over the preceding axis, or Saxon's internal preceding-or-ancestor axis, by making use of the ancestor, descendant, and preceding-sibling axes.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `alphaKey​(int value)` | Construct an alphabetic key from an positive integer; the key collates in the same sequence as the integer
    `static void` | `appendSequentialKey​(SiblingCountingNode node, FastStringBuffer sb, boolean addDocNr)` | Get a character string that uniquely identifies this node and that collates nodes into document order
    `static int` | `compareOrder​(SiblingCountingNode first, SiblingCountingNode second)` | Generic (model-independent) method to determine the relative position of two nodes in document order.
    `static int` | `comparePosition​(NodeInfo first, NodeInfo second)` | Generic (model-independent) method to determine the relative position of two node in document order.
    `static void` | `copy​(NodeInfo node, Outputter out, int copyOptions, Location locationId)` | Generic (model-independent) implementation of deep copy algorithm for nodes.
    `static void` | `copy​(NodeInfo node, Receiver out, int copyOptions, Location locationId)` | Generic (model-independent) implementation of deep copy algorithm for nodes.
    `static AxisIterator` | `filteredSingleton​(NodeInfo node, java.util.function.Predicate<? super NodeInfo> nodeTest)` | Create an iterator over a singleton node, if it exists and matches a nodetest; otherwise return an empty iterator
    `static AbsolutePath` | `getAbsolutePath​(NodeInfo node)` | Get the absolute path to a node
    `static java.lang.String` | `getAttributeValue​(NodeInfo element, java.lang.String uri, java.lang.String localName)` | Get the string value of an attribute of a given element, given the URI and local part of the attribute name.
    `static java.lang.String` | `getBaseURI​(NodeInfo node)` | Helper method to get the base URI of an element or processing instruction node
    `static java.lang.String` | `getBaseURI​(NodeInfo node, java.util.function.Predicate<NodeInfo> isTopElementWithinEntity)` | Helper method to get the base URI of an element or processing instruction node
    `static java.lang.String` | `getInheritedAttributeValue​(NodeInfo element, java.lang.String uri, java.lang.String localName)` | Get the string value of an inherited attribute of a given element, given the URI and local part of the attribute name.
    `static StructuredQName` | `getNodeName​(NodeInfo node)` | Helper method to get the name of a node as a structuredQName.
    `static int` | `getNumberAny​(Expression inst, NodeInfo node, Pattern count, Pattern from, XPathContext context, boolean hasVariablesInPatterns)` | Get node number (level="any").
    `static java.util.List<java.lang.Long>` | `getNumberMulti​(NodeInfo node, Pattern count, Pattern from, XPathContext context)` | Get node number (level="multiple").
    `static int` | `getNumberSimple​(NodeInfo node, XPathContext context)` | Get simple node number.
    `static int` | `getNumberSingle​(NodeInfo node, Pattern count, Pattern from, XPathContext context)` | Get node number (level="single").
    `static NodeInfo` | `getOutermostElement​(TreeInfo doc)` | Helper method to get the outermost element of a document, given the document node
    `static java.lang.String` | `getPath​(NodeInfo node)` | Get an absolute XPath expression that identifies a given node within its document
    `static java.lang.String` | `getPath​(NodeInfo node, XPathContext context)` | Get an absolute XPath expression that identifies a given node within its document.
    `static int` | `getSiblingPosition​(NodeInfo node, NodeTest nodeTest, int max)` | Get the sibling position of a node: specifically, count how many preceding siblings of a node satisfy the nodetest.
    `static boolean` | `haveSameName​(NodeInfo n1, NodeInfo n2)` | Ask whether two nodes have the same name
    `static boolean` | `isAncestorOrSelf​(NodeInfo a, NodeInfo d)` | Test if one node is an ancestor-or-self of another

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getAttributeValue

          public static java.lang.String getAttributeValue​(NodeInfo element,
                                                           java.lang.String uri,
                                                           java.lang.String localName)

      Get the string value of an attribute of a given element, given the URI and local part of the attribute name.
      Parameters:
        `element` - the element on which the required attribute appears
        `uri` - The namespace URI of the attribute name. The "no namespace" case is represented as an empty string.
        `localName` - The local part of the attribute name.
      Returns:
        the attribute value, or null if the attribute is not present
      Since:
        9.0

    - #### getInheritedAttributeValue

          public static java.lang.String getInheritedAttributeValue​(NodeInfo element,
                                                                    java.lang.String uri,
                                                                    java.lang.String localName)

      Get the string value of an inherited attribute of a given element, given the URI and local part of the attribute name. If the element does not have such an attribute, go up the ancestor axis to find such an attribute
      Parameters:
        `element` - the element where the search should start
        `uri` - The namespace URI of the attribute name. The "no namespace" case is represented as an empty string.
        `localName` - The local part of the attribute name.
      Returns:
        the attribute value, or null if the attribute is not present on any ancestor
      Since:
        9.9

    - #### getNodeName

          public static StructuredQName getNodeName​(NodeInfo node)

      Helper method to get the name of a node as a structuredQName. Used from bytecode
      Parameters:
        `node` - the node
      Returns:
        the name of the node if it has a name, or null otherwise

    - #### getOutermostElement

          public static NodeInfo getOutermostElement​(TreeInfo doc)

      Helper method to get the outermost element of a document, given the document node
      Parameters:
        `doc` - the document node at the root of the document
      Returns:
        the first element child of the document node, if there is one, else null. This is often referred to as the "root element" or "document element". No error is reported if the document node has multiple element children, which can happen in a document constructed using XSLT or XQuery.
      Since:
        9.3

    - #### getBaseURI

          public static java.lang.String getBaseURI​(NodeInfo node)

      Helper method to get the base URI of an element or processing instruction node
      Parameters:
        `node` - the node whose base URI is required
      Returns:
        the base URI of the node
      Since:
        8.7

    - #### getBaseURI

          public static java.lang.String getBaseURI​(NodeInfo node,
                                                    java.util.function.Predicate<NodeInfo> isTopElementWithinEntity)

      Helper method to get the base URI of an element or processing instruction node
      Parameters:
        `node` - the node whose base URI is required
        `isTopElementWithinEntity` - a predicate applied to a node that can be tested to determine if the node is an element that originated as the outermost element within an external entity. If this is the case, the rules for determining the base URI are slightly different; in particular, any @xml:base attribute on such a node is interpreted relative to the system ID of the entity, not relative to the base URI of the parent node.
      Returns:
        the base URI of the node
      Since:
        9.9

    - #### getPath

          public static java.lang.String getPath​(NodeInfo node)

      Get an absolute XPath expression that identifies a given node within its document
      Parameters:
        `node` - the node whose path is required. If null is supplied, an empty string is returned - this fact is used in making a recursive call for a parentless node.
      Returns:
        a path expression that can be used to retrieve the node

    - #### getPath

          public static java.lang.String getPath​(NodeInfo node,
                                                 XPathContext context)

      Get an absolute XPath expression that identifies a given node within its document. The resulting path is intended for human readers, not for software evaluation. It uses lexical QNames (prefix:localname) for element and attribute names, with the original prefix as it appears in the source document. The sibling position of an element (a/b[2]) is included unless the node is a streamed node.
      Parameters:
        `node` - the node whose path is required. If null is supplied, an empty string is returned - this fact is used in making a recursive call for a parentless node.
        `context` - the XPath dynamic evaluation context. May be null if no context is known
      Returns:
        a path expression that can be used to retrieve the node

    - #### getAbsolutePath

          public static AbsolutePath getAbsolutePath​(NodeInfo node)

      Get the absolute path to a node
      Parameters:
        `node` - the node in question
      Returns:
        an object representing the path to the node

    - #### haveSameName

          public static boolean haveSameName​(NodeInfo n1,
                                             NodeInfo n2)

      Ask whether two nodes have the same name
      Parameters:
        `n1` - the first node
        `n2` - the second node
      Returns:
        true if they have the same namespace and local part

    - #### getNumberSimple

          public static int getNumberSimple​(NodeInfo node,
                                            XPathContext context)

      Get simple node number. This is defined as one plus the number of previous siblings of the same node type and name. It is not accessible directly in XSL.
      Parameters:
        `node` - The node whose number is required
        `context` - Used for remembering previous result, for performance. May be null.
      Returns:
        the node number, as defined above

    - #### getNumberSingle

          public static int getNumberSingle​(NodeInfo node,
                                            Pattern count,
                                            Pattern from,
                                            XPathContext context)
                                     throws XPathException

      Get node number (level="single"). If the current node matches the supplied pattern, the returned number is one plus the number of previous siblings that match the pattern. Otherwise, return the element number of the nearest ancestor that matches the supplied pattern.
      Parameters:
        `node` - the current node, the one whose node number is required
        `count` - Pattern that identifies which nodes should be counted. Default (null) is the element name if the current node is an element, or "node()" otherwise.
        `from` - Pattern that specifies where counting starts from. Default (null) is the root node. (This parameter does not seem useful but is included for the sake of XSLT conformance.)
        `context` - the dynamic context of the transformation, used if the patterns reference context values (e.g. variables)
      Returns:
        the node number established as follows: go to the nearest ancestor-or-self that matches the 'count' pattern and that is a descendant of the nearest ancestor that matches the 'from' pattern. Return one plus the nunber of preceding siblings of that ancestor that match the 'count' pattern. If there is no such ancestor, return 0.
      Throws:
        `XPathException` - when any error occurs in processing

    - #### getNumberAny

          public static int getNumberAny​(Expression inst,
                                         NodeInfo node,
                                         Pattern count,
                                         Pattern from,
                                         XPathContext context,
                                         boolean hasVariablesInPatterns)
                                  throws XPathException

      Get node number (level="any"). Return one plus the number of previous nodes in the document that match the supplied pattern
      Parameters:
        `inst` - Identifies the xsl:number expression; this is relevant when the function is memoised to support repeated use of the same instruction to number multiple nodes
        `node` - The node being numbered
        `count` - Pattern that identifies which nodes should be counted. Default (null) is the element name if the current node is an element, or "node()" otherwise.
        `from` - Pattern that specifies where counting starts from. Default (null) is the root node. Only nodes at or after the first (most recent) node that matches the 'from' pattern are counted.
        `context` - The dynamic context for the transformation
        `hasVariablesInPatterns` - if the count or from patterns contain variables, then it's not safe to get the answer by adding one to the number of the most recent node that matches
      Returns:
        one plus the number of nodes that precede the current node, that match the count pattern, and that follow the first node that matches the from pattern if specified.
      Throws:
        `XPathException` - if any dynamic error occurs

    - #### getNumberMulti

          public static java.util.List<java.lang.Long> getNumberMulti​(NodeInfo node,
                                                                      Pattern count,
                                                                      Pattern from,
                                                                      XPathContext context)
                                                               throws XPathException

      Get node number (level="multiple"). Return a vector giving the hierarchic position of this node. See the XSLT spec for details.
      Parameters:
        `node` - The node to be numbered
        `count` - Pattern that identifies which nodes (ancestors and their previous siblings) should be counted. Default (null) is the element name if the current node is an element, or "node()" otherwise.
        `from` - Pattern that specifies where counting starts from. Default (null) is the root node. Only nodes below the first (most recent) node that matches the 'from' pattern are counted.
        `context` - The dynamic context for the transformation
      Returns:
        a vector containing for each ancestor-or-self that matches the count pattern and that is below the nearest node that matches the from pattern, an Integer which is one greater than the number of previous siblings that match the count pattern.
      Throws:
        `XPathException` - if an error occurs

    - #### copy

          public static void copy​(NodeInfo node,
                                  Receiver out,
                                  int copyOptions,
                                  Location locationId)
                           throws XPathException

      Generic (model-independent) implementation of deep copy algorithm for nodes. This is available for use by any node implementations that choose to use it.
      Parameters:
        `node` - The node to be copied.
        `out` - The receiver to which events will be sent
        `copyOptions` - Options for copying namespaces, type annotations, etc, as defined in `CopyOptions`
        `locationId` - The location of the instruction invoking the copy
      Throws:
        `XPathException` - on any failure reported by the Receiver
        `java.lang.IllegalArgumentException` - if the node is an attribute or namespace node

    - #### copy

          public static void copy​(NodeInfo node,
                                  Outputter out,
                                  int copyOptions,
                                  Location locationId)
                           throws XPathException

      Generic (model-independent) implementation of deep copy algorithm for nodes. This is available for use by any node implementations that choose to use it.
      Parameters:
        `node` - The node to be copied.
        `out` - The outputter to which events will be sent
        `copyOptions` - Options for copying namespaces, type annotations, etc, as defined in `CopyOptions`
        `locationId` - The location of the instruction invoking the copy
      Throws:
        `XPathException` - on any failure reported by the Receiver

    - #### compareOrder

          public static int compareOrder​(SiblingCountingNode first,
                                         SiblingCountingNode second)

      Generic (model-independent) method to determine the relative position of two nodes in document order. The nodes must be in the same tree.
      Parameters:
        `first` - The first node
        `second` - The second node, whose position is to be compared with the first node
      Returns:
        -1 if this node precedes the other node, +1 if it follows the other node, or 0 if they are the same node. (In this case, isSameNode() will always return true, and the two nodes will produce the same result for generateId())

    - #### comparePosition

          public static int comparePosition​(NodeInfo first,
                                            NodeInfo second)

      Generic (model-independent) method to determine the relative position of two node in document order. The nodes must be in the same tree.
      Parameters:
        `first` - The first node
        `second` - The second node, whose position is to be compared with the first node
      Returns:
        `AxisInfo.PRECEDING` if this node is on the preceding axis of the other node; `AxisInfo.FOLLOWING` if it is on the following axis; `AxisInfo.ANCESTOR` if the first node is an ancestor of the second; `AxisInfo.DESCENDANT` if the first is a descendant of the second; `AxisInfo.SELF` if they are the same node.
      Throws:
        `java.lang.UnsupportedOperationException` - if either node is an attribute or namespace
      Since:
        9.5

    - #### appendSequentialKey

          public static void appendSequentialKey​(SiblingCountingNode node,
                                                 FastStringBuffer sb,
                                                 boolean addDocNr)

      Get a character string that uniquely identifies this node and that collates nodes into document order
      Parameters:
        `node` - the node whose unique identifier is reuqired
        `sb` - a buffer to which the unique identifier will be appended
        `addDocNr` - true if a unique document number is to be included in the information

    - #### alphaKey

          public static java.lang.String alphaKey​(int value)

      Construct an alphabetic key from an positive integer; the key collates in the same sequence as the integer
      Parameters:
        `value` - The positive integer key value (negative values are treated as zero).
      Returns:
        the alphabetic key value

    - #### isAncestorOrSelf

          public static boolean isAncestorOrSelf​(NodeInfo a,
                                                 NodeInfo d)

      Test if one node is an ancestor-or-self of another
      Parameters:
        `a` - the putative ancestor-or-self node
        `d` - the putative descendant node
      Returns:
        true if a is an ancestor-or-self of d

    - #### filteredSingleton

          public static AxisIterator filteredSingleton​(NodeInfo node,
                                                       java.util.function.Predicate<? super NodeInfo> nodeTest)

      Create an iterator over a singleton node, if it exists and matches a nodetest; otherwise return an empty iterator
      Parameters:
        `node` - the singleton node, or null if the node does not exist
        `nodeTest` - the test to be applied
      Returns:
        an iterator over the node if it exists and matches the test.

    - #### getSiblingPosition

          public static int getSiblingPosition​(NodeInfo node,
                                               NodeTest nodeTest,
                                               int max)

      Get the sibling position of a node: specifically, count how many preceding siblings of a node satisfy the nodetest.
      Parameters:
        `node` - the starting node, which is assumed to satisfy the node test
        `nodeTest` - the node test
        `max` - the maximum number of nodes to be counted
      Returns:
        the number of preceding siblings that satisfy the node test, plus one, unless the number exceeds max, in which case return some number greater than or equal to max.