src/jalview/datamodel/SearchResultsI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.datamodel;
  22
  23 import java.util.BitSet;
  24 import java.util.List;
  25
  26 /**
  27  * An interface describing the result of a search or other operation which
  28  * highlights matched regions of an alignment
  29  */
  30 public interface SearchResultsI
  31 {
  32
  33   /**
  34    * Adds one region to the results (unless already added, to avoid duplicates)
  35    *
  36    * @param seq
  37    * @param start
  38    * @param end
  39    * @return
  40    */
  41   SearchResultMatchI addResult(SequenceI seq, int start, int end);
  42
  43   /**
  44    * Adds one ore more [start, end] ranges to the results (unless already added
  45    * to avoid duplicates). This method only increments the match count by 1.
  46    * This is for the case where a match spans ignored hidden residues - it is
  47    * formally two or more contiguous matches, but only counted as one match.
  48    *
  49    * @param seq
  50    * @param positions
  51    */
  52   void addResult(SequenceI seq, int[] positions);
  53
  54
  55   /**
  56    * Adds the given start/end region to this search result. If sequence already
  57    * has a search result and the range is adjacent to already highlighted
  58    * positions, they will be merged
  59    *
  60    * @param sequence
  61    * @param start
  62    * @param end
  63    * @return true if an existing range was updated with this one
  64    */
  65   boolean appendResult(SequenceI sequence, int start, int end);
  66
  67   /**
  68    * adds all match results in the argument to this set
  69    *
  70    * @param toAdd
  71    */
  72   void addSearchResults(SearchResultsI toAdd);
  73
  74   /**
  75    * Answers true if the search results include the given sequence (or its
  76    * dataset sequence), else false
  77    *
  78    * @param sequence
  79    * @return
  80    */
  81   boolean involvesSequence(SequenceI sequence);
  82
  83   /**
  84    * Returns an array of [from, to, from, to..] matched columns (base 0) between
  85    * the given start and end columns of the given sequence. Returns null if no
  86    * matches overlap the specified region.
  87    * <p>
  88    * Implementations should provide an optimised method to return locations to
  89    * highlight on a visible portion of an alignment.
  90    *
  91    * @param sequence
  92    * @param start
  93    *          first column of range (base 0, inclusive)
  94    * @param end
  95    *          last column of range base 0, inclusive)
  96    * @return int[]
  97    */
  98   int[] getResults(SequenceI sequence, int start, int end);
  99
 100   /**
 101    * Returns the number of matches found. Note that if a match straddles ignored
 102    * hidden residues, it is counted as one match, although formally recorded as
 103    * two (or more) contiguous matched sequence regions
 104    *
 105    * @return
 106    */
 107   int getCount();
 108
 109   /**
 110    * Returns true if no search result matches are held.
 111    *
 112    * @return
 113    */
 114   boolean isEmpty();
 115
 116   /**
 117    * Returns the list of matches.
 118    *
 119    * @return
 120    */
 121   List<SearchResultMatchI> getResults();
 122
 123   /**
 124    * Set bits in a bitfield for all columns in the given sequence collection
 125    * that are highlighted
 126    *
 127    * @param sqcol
 128    *          the set of sequences to search for highlighted regions
 129    * @param bs
 130    *          bitset to set
 131    * @return number of bits set
 132    */
 133   int markColumns(SequenceCollectionI sqcol, BitSet bs);
 134
 135   /**
 136    * Return sub-sequences corresponding to distinct contiguous ranges in the
 137    * matching set
 138    *
 139    * @return list of sequence objects
 140    */
 141   List<SequenceI> getMatchingSubSequences();
 142 }