http://lucene.apache.org/lucene-parent/lucene-core: Apache Lucene Java Core (The Apache Software Foundation) 
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.lucene.search;

import java.io.IOException;

import org.apache.lucene.index.LeafReaderContext;


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:
@lucene.experimental
/**
 * An iterator over match positions (and optionally offsets) for a single document and field
 *
 * To iterate over the matches, call {@link #next()} until it returns {@code false}, retrieving
 * positions and/or offsets after each call.  You should not call the position or offset methods
 * before {@link #next()} has been called, or after {@link #next()} has returned {@code false}.
 *
 * Matches from some queries may span multiple positions.  You can retrieve the positions of
 * individual matching terms on the current match by calling {@link #getSubMatches()}.
 *
 * Matches are ordered by start position, and then by end position.  Match intervals may overlap.
 *
 * @see Weight#matches(LeafReaderContext, int)
 *
 * @lucene.experimental
 */
public interface MatchesIterator {

  
Advance the iterator to the next match position

Returns:true if matches have not been exhausted
/**
   * Advance the iterator to the next match position
   * @return {@code true} if matches have not been exhausted
   */
  boolean next() throws IOException;

  
The start position of the current match Should only be called after next() has returned true 
/**
   * The start position of the current match
   *
   * Should only be called after {@link #next()} has returned {@code true}
   */
  int startPosition();

  
The end position of the current match Should only be called after next() has returned true 
/**
   * The end position of the current match
   *
   * Should only be called after {@link #next()} has returned {@code true}
   */
  int endPosition();

  
The starting offset of the current match, or -1 if offsets are not available Should only be called after next() has returned true 
/**
   * The starting offset of the current match, or {@code -1} if offsets are not available
   *
   * Should only be called after {@link #next()} has returned {@code true}
   */
  int startOffset() 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 
/**
   * The ending offset of the current match, or {@code -1} if offsets are not available
   *
   * Should only be called after {@link #next()} has returned {@code true}
   */
  int endOffset() 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 
/**
   * Returns a MatchesIterator that iterates over the positions and offsets of individual
   * terms within the current match
   *
   * Returns {@code null} if there are no submatches (ie the current iterator is at the
   * leaf level)
   *
   * Should only be called after {@link #next()} has returned {@code true}
   */
  MatchesIterator getSubMatches() throws IOException;

  
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 
/**
   * Returns the Query causing the current match
   *
   * If this {@link MatchesIterator} has been returned from a {@link #getSubMatches()}
   * call, then returns a {@link TermQuery} equivalent to the current match
   *
   * Should only be called after {@link #next()} has returned {@code true}
   */
  Query getQuery();

}