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, empty, 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`