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

    All Methods Instance Methods Abstract Methods
    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
    `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

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