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 and Description
    --- | ---
    `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`

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.