Package 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

Modifier and Type
Method
Description
`int`
`endOffset()`
The ending offset of the current match, or `-1` if offsets are not available
`int`
`endPosition()`
The end position of the current match, or `-1` if positions are not available
`Query`
`getQuery()`
Returns the Query causing the current match
`MatchesIterator`
`getSubMatches()`
Returns a MatchesIterator that iterates over the positions and offsets of individual terms within the current match
`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
`int`
`startPosition()`
The start position of the current match, or `-1` if positions are not available

## Method Details

### 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, or `-1` if positions are not available

Should only be called after `next()` has returned `true`

### endPosition

int endPosition()
The end position of the current match, or `-1` if positions are not available

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`