52a0467d841304c1e41b30de5f229634339101c3
[jalview.git] / 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
35    * 
36    * @param seq
37    *          Sequence
38    * @param start
39    *          int
40    * @param end
41    *          int
42    * @return
43    */
44   SearchResultMatchI addResult(SequenceI seq, int start, int end);
45
46   /**
47    * Answers true if the search results include the given sequence (or its
48    * dataset sequence), else false
49    * 
50    * @param sequence
51    * @return
52    */
53   boolean involvesSequence(SequenceI sequence);
54
55   /**
56    * Returns an array of [from, to, from, to..] matched columns (base 0) between
57    * the given start and end columns of the given sequence. Returns null if no
58    * matches overlap the specified region.
59    * <p>
60    * Implementations should provide an optimised method to return locations to
61    * highlight on a visible portion of an alignment.
62    * 
63    * @param sequence
64    * @param start
65    *          first column of range (base 0, inclusive)
66    * @param end
67    *          last column of range base 0, inclusive)
68    * @return int[]
69    */
70   int[] getResults(SequenceI sequence, int start, int end);
71
72   /**
73    * Returns the number of matches found
74    * 
75    * @return
76    */
77   int getSize();
78
79   /**
80    * Returns true if no search result matches are held.
81    * 
82    * @return
83    */
84   boolean isEmpty();
85
86   /**
87    * Returns the list of matches.
88    * 
89    * @return
90    */
91   List<SearchResultMatchI> getResults();
92
93   /**
94    * Set bits in a bitfield for all columns in the given sequence collection
95    * that are highlighted
96    * 
97    * @param sqcol
98    *          the set of sequences to search for highlighted regions
99    * @param bs
100    *          bitset to set
101    * @return number of bits set
102    */
103   int markColumns(SequenceCollectionI sqcol, BitSet bs);
104 }