IntervalIterator (Lucene 10.5.0 queries API)
Description: declaration: package: org.apache.lucene.queries.intervals, class: IntervalIterator

Package org.apache.lucene.queries.intervals

# Class IntervalIterator

java.lang.Object
org.apache.lucene.search.DocIdSetIterator
org.apache.lucene.queries.intervals.IntervalIterator

Direct Known Subclasses:
  `IntervalFilter`

public abstract class IntervalIterator extends DocIdSetIterator
A `DocIdSetIterator` that also allows iteration over matching intervals in a document.

Once the iterator is positioned on a document by calling `DocIdSetIterator.advance(int)` or `DocIdSetIterator.nextDoc()`, intervals may be retrieved by calling `nextInterval()` until `NO_MORE_INTERVALS` is returned.

The limits of the current interval are returned by `start()` and `end()`. When the iterator has been moved to a new document, but before `nextInterval()` has been called, both these methods return `-1`.

Note that it is possible for a document to return `NO_MORE_INTERVALS` on the first call to `nextInterval()`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `NO_MORE_INTERVALS`
  When returned from `nextInterval()`, indicates that there are no more matching intervals on the current document

  ### Fields inherited from class org.apache.lucene.search.DocIdSetIterator

  `NO_MORE_DOCS`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `IntervalIterator()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract int`
  `end()`
  The end of the current interval
  `abstract int`
  `gaps()`
  The number of gaps within the current interval
  `abstract float`
  `matchCost()`
  An indication of the average cost of iterating over all intervals in a document
  `abstract int`
  `nextInterval()`
  Advance the iterator to the next interval
  `abstract int`
  `start()`
  The start of the current interval
  `String`
  `toString()`
  `int`
  `width()`
  The width of the current interval

  ### Methods inherited from class org.apache.lucene.search.DocIdSetIterator

  `advance, all, cost, docID, docIDRunEnd, empty, intoBitSet, nextDoc, range, slowAdvance`

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

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

- ## Field Details

  - ### NO_MORE_INTERVALS

    public static final int NO_MORE_INTERVALS
    When returned from `nextInterval()`, indicates that there are no more matching intervals on the current document
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### IntervalIterator

    public IntervalIterator()

- ## Method Details

  - ### start

    public abstract int start()
    The start of the current interval

    Returns -1 if `nextInterval()` has not yet been called and `NO_MORE_INTERVALS` once the iterator is exhausted.

  - ### end

    public abstract int end()
    The end of the current interval

    Returns -1 if `nextInterval()` has not yet been called and `NO_MORE_INTERVALS` once the iterator is exhausted.

  - ### gaps

    public abstract int gaps()
    The number of gaps within the current interval

    Note that this returns the number of gaps between the immediate sub-intervals of this interval, and does not include the gaps inside those sub-intervals.

    Should not be called before `nextInterval()`, or after it has returned `NO_MORE_INTERVALS`

  - ### width

    public int width()
    The width of the current interval

  - ### nextInterval

    public abstract int nextInterval() throws IOException
    Advance the iterator to the next interval

    Should not be called after `DocIdSetIterator.NO_MORE_DOCS` is returned by `DocIdSetIterator.nextDoc()` or `DocIdSetIterator.advance(int)`. If that's the case in some existing code, please consider opening an issue. However, after `NO_MORE_INTERVALS` is returned by this method, it might be called again.

    Returns:
      the start of the next interval, or `NO_MORE_INTERVALS` if there are no more intervals on the current document
    Throws:
      `IOException`

  - ### matchCost

    public abstract float matchCost()
    An indication of the average cost of iterating over all intervals in a document
    See Also:
      - `TwoPhaseIterator.matchCost()`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`