org.apache.lucene.search

## Interface MatchesIterator

All Known Implementing Classes:
  FilterMatchesIterator

    public interface MatchesIterator

An iterator over match positions (and optionally offsets) for a single document and field To iterate over the matches, call `next()` until it returns `false`, retrieving positions and/or offsets after each call. You should not call the position or offset methods before `next()` has been called, or after `next()` has returned `false`. Matches from some queries may span multiple positions. You can retrieve the positions of individual matching terms on the current match by calling `getSubMatches()`. Matches are ordered by start position, and then by end position. Match intervals may overlap.

See Also:
  `Weight.matches(LeafReaderContext, int)`
WARNING: This API is experimental and might change in incompatible ways in the next release.

### Method Summary

All Methods Instance Methods Abstract Methods
`int` `endOffset()` The ending offset of the current match, or `-1` if offsets are not available Should only be called after `next()` has returned `true`
`int` `endPosition()` The end position of the current match Should only be called after `next()` has returned `true`
`Query` `getQuery()` Returns the Query causing the current match If this `MatchesIterator` has been returned from a `getSubMatches()` call, then returns a `TermQuery` equivalent to the current match Should only be called after `next()` has returned `true`
`MatchesIterator` `getSubMatches()` Returns a MatchesIterator that iterates over the positions and offsets of individual terms within the current match Returns `null` if there are no submatches (ie the current iterator is at the leaf level) Should only be called after `next()` has returned `true`
`boolean` `next()` Advance the iterator to the next match position
`int` `startOffset()` The starting offset of the current match, or `-1` if offsets are not available Should only be called after `next()` has returned `true`
`int` `startPosition()` The start position of the current match Should only be called after `next()` has returned `true`

### Method Detail

#### next

    boolean next()
          throws IOException

Advance the iterator to the next match position

Returns:
  `true` if matches have not been exhausted
Throws:
  `IOException`

#### startPosition

    int startPosition()

The start position of the current match Should only be called after `next()` has returned `true`

#### endPosition

    int endPosition()

The end position of the current match Should only be called after `next()` has returned `true`

#### startOffset

    int startOffset()
             throws IOException

The starting offset of the current match, or `-1` if offsets are not available Should only be called after `next()` has returned `true`

Throws:
  `IOException`

#### endOffset

    int endOffset()
           throws IOException

The ending offset of the current match, or `-1` if offsets are not available Should only be called after `next()` has returned `true`

Throws:
  `IOException`

#### getSubMatches

    MatchesIterator getSubMatches()
                           throws IOException

Returns a MatchesIterator that iterates over the positions and offsets of individual terms within the current match Returns `null` if there are no submatches (ie the current iterator is at the leaf level) Should only be called after `next()` has returned `true`

Throws:
  `IOException`

#### getQuery

    Query getQuery()

Returns the Query causing the current match If this `MatchesIterator` has been returned from a `getSubMatches()` call, then returns a `TermQuery` equivalent to the current match Should only be called after `next()` has returned `true`