2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
5 * This file is part of Jalview.
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.
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.
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.
21 package jalview.datamodel;
23 import java.util.BitSet;
24 import java.util.List;
27 * An interface describing the result of a search or other operation which
28 * highlights matched regions of an alignment
30 public interface SearchResultsI
34 * Adds one region to the results (unless already added, to avoid duplicates)
41 SearchResultMatchI addResult(SequenceI seq, int start, int end);
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.
52 void addResult(SequenceI seq, int[] positions);
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
63 * @return true if an existing range was updated with this one
65 boolean appendResult(SequenceI sequence, int start, int end);
68 * adds all match results in the argument to this set
72 void addSearchResults(SearchResultsI toAdd);
75 * Answers true if the search results include the given sequence (or its
76 * dataset sequence), else false
81 boolean involvesSequence(SequenceI sequence);
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.
88 * Implementations should provide an optimised method to return locations to
89 * highlight on a visible portion of an alignment.
93 * first column of range (base 0, inclusive)
95 * last column of range base 0, inclusive)
98 int[] getResults(SequenceI sequence, int start, int end);
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
110 * Returns true if no search result matches are held.
117 * Returns the list of matches.
121 List<SearchResultMatchI> getResults();
124 * Set bits in a bitfield for all columns in the given sequence collection
125 * that are highlighted
128 * the set of sequences to search for highlighted regions
131 * @return number of bits set
133 int markColumns(SequenceCollectionI sqcol, BitSet bs);
136 * Return sub-sequences corresponding to distinct contiguous ranges in the
139 * @return list of sequence objects
141 List<SequenceI> getMatchingSubSequences();