package jalview.datamodel;

import java.util.BitSet;
import java.util.List;

/**
 * An interface describing the result of a search or other operation which
 * highlights matched regions of an alignment
 */
public interface SearchResultsI
{

  /**
   * Adds one region to the results
   * 
   * @param seq
   *          Sequence
   * @param start
   *          int
   * @param end
   *          int
   * @return
   */
  SearchResultMatchI addResult(SequenceI seq, int start, int end);

  /**
   * Answers true if the search results include the given sequence (or its
   * dataset sequence), else false
   * 
   * @param sequence
   * @return
   */
  boolean involvesSequence(SequenceI sequence);

  /**
   * Returns an array of [from, to, from, to..] matched columns (base 0) between
   * the given start and end columns of the given sequence. Returns null if no
   * matches overlap the specified region.
   * <p>
   * Implementations should provide an optimised method to return locations to
   * highlight on a visible portion of an alignment.
   * 
   * @param sequence
   * @param start
   *          first column of range (base 0, inclusive)
   * @param end
   *          last column of range base 0, inclusive)
   * @return int[]
   */
  int[] getResults(SequenceI sequence, int start, int end);

  /**
   * Returns the number of matches found
   * 
   * @return
   */
  int getSize();

  /**
   * Returns true if no search result matches are held.
   * 
   * @return
   */
  boolean isEmpty();

  /**
   * Returns the list of matches.
   * 
   * @return
   */
  List<SearchResultMatchI> getResults();

  /**
   * Set bits in a bitfield for all columns in the given sequence collection
   * that are highlighted
   * 
   * @param sqcol
   *          the set of sequences to search for highlighted regions
   * @param bs
   *          bitset to set
   * @return number of bits set
   */
  int markColumns(SequenceCollectionI sqcol, BitSet bs);
}