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 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

    All Methods Instance Methods Abstract Methods Concrete Methods
    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, empty, nextDoc, range, slowAdvance`

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

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

- - ### Field Detail

    - #### 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 Detail

    - #### IntervalIterator

          public IntervalIterator()

  - ### Method Detail

    - #### 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`