Package net.sf.saxon.tree.iter

## Interface GroundedIterator

- All Superinterfaces:
    `java.lang.AutoCloseable`, `java.io.Closeable`, `SequenceIterator`
  All Known Subinterfaces:
    `ConstrainedIterator<T>`
  All Known Implementing Classes:
    `ArrayIterator`, `ArrayIterator.OfNodes`, `EmptyIterator`, `FocusTrackingIterator`, `GroupByIterator.ManualGroupByIterator`, `ListIterator`, `ListIterator.Atomic`, `ListIterator.OfNodes`, `ManualGroupIterator`, `ManualIterator`, `ManualRegexIterator`, `MemoSequence.ProgressiveIterator`, `MergeGroupingIterator.ManualMergeGroupingIterator`, `MultithreadedFocusTrackingIterator`, `RangeIterator`, `SingleAtomicIterator`, `SingleNodeIterator`, `SingletonIterator`, `ValueTailIterator`

      public interface GroundedIterator
      extends SequenceIterator

  This interface is an extension to the SequenceIterator interface; it represents a SequenceIterator that is based on an in-memory representation of a sequence, and that is therefore capable of returning a Sequence containing all the items in the sequence.

  We stretch the concept to consider an iterator over a MemoClosure as a grounded iterator, on the basis that the in-memory sequence might exist already or might be created as a side-effect of navigating the iterator. This is why materializing the iterator can raise an exception.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface net.sf.saxon.om.SequenceIterator

      `SequenceIterator.Property`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `GroundedValue` | `getResidue()` | Return a GroundedValue containing all the remaining items in the sequence returned by this SequenceIterator, starting at the current position.
    `GroundedValue` | `materialize()` | Return a GroundedValue containing all the items in the sequence returned by this SequenceIterator.

    - ### Methods inherited from interface net.sf.saxon.om.SequenceIterator

      `close, forEachOrFail, getProperties, next`

- - ### Method Detail

    - #### materialize

          GroundedValue materialize()
                             throws XPathException

      Return a GroundedValue containing all the items in the sequence returned by this SequenceIterator. This should be an "in-memory" value, not a Closure. This method does not change the state of the iterator (in particular, it does not consume the iterator).
      Specified by:
        `materialize` in interface `SequenceIterator`
      Returns:
        the corresponding Value
      Throws:
        `XPathException` - in the cases of subclasses (such as the iterator over a MemoClosure) which cause evaluation of expressions while materializing the value.

    - #### getResidue

          GroundedValue getResidue()
                            throws XPathException

      Return a GroundedValue containing all the remaining items in the sequence returned by this SequenceIterator, starting at the current position. This should be an "in-memory" value, not a Closure. This method does not change the state of the iterator (in particular, it does not consume the iterator).
      Returns:
        the corresponding Value
      Throws:
        `XPathException` - in the cases of subclasses (such as the iterator over a MemoClosure) which cause evaluation of expressions while materializing the value.