Merge branch 'JAL-3878_ws-overhaul-3' into with_ws_overhaul-3
[jalview.git] / 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    * adds all match results in the argument to this set
56    * 
57    * @param toAdd
58    */
59   void addSearchResults(SearchResultsI toAdd);
60
61   /**
62    * Answers true if the search results include the given sequence (or its
63    * dataset sequence), else false
64    * 
65    * @param sequence
66    * @return
67    */
68   boolean involvesSequence(SequenceI sequence);
69
70   /**
71    * Returns an array of [from, to, from, to..] matched columns (base 0) between
72    * the given start and end columns of the given sequence. Returns null if no
73    * matches overlap the specified region.
74    * <p>
75    * Implementations should provide an optimised method to return locations to
76    * highlight on a visible portion of an alignment.
77    * 
78    * @param sequence
79    * @param start
80    *          first column of range (base 0, inclusive)
81    * @param end
82    *          last column of range base 0, inclusive)
83    * @return int[]
84    */
85   int[] getResults(SequenceI sequence, int start, int end);
86
87   /**
88    * Returns the number of matches found. Note that if a match straddles ignored
89    * hidden residues, it is counted as one match, although formally recorded as
90    * two (or more) contiguous matched sequence regions
91    * 
92    * @return
93    */
94   int getCount();
95
96   /**
97    * Returns true if no search result matches are held.
98    * 
99    * @return
100    */
101   boolean isEmpty();
102
103   /**
104    * Returns the list of matches.
105    * 
106    * @return
107    */
108   List<SearchResultMatchI> getResults();
109
110   /**
111    * Set bits in a bitfield for all columns in the given sequence collection
112    * that are highlighted
113    * 
114    * @param sqcol
115    *          the set of sequences to search for highlighted regions
116    * @param bs
117    *          bitset to set
118    * @return number of bits set
119    */
120   int markColumns(SequenceCollectionI sqcol, BitSet bs);
121 }