MatchesIterator (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.search, interface: MatchesIterator

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`