/* * BioJava development code * * This code may be freely distributed and modified under the * terms of the GNU Lesser General Public Licence. This should * be distributed with the code. If you do not have a copy, * see: * * http://www.gnu.org/copyleft/lesser.html * * Copyright for this code is held jointly by the individual * authors. These should be listed in @author doc comments. * * For more information on the BioJava project and its aims, * or to join the biojava-l mailing list, visit the home page * at: * * http://www.biojava.org/ * */ package org.biojava.bio.symbol; import java.util.Iterator; /** * A set of integers, often used to represent positions on biological sequences. * *
* The location will contain some indices between getMin and getMax inclusive.
* It is not required to contain all indices within this range. It is meant
* to contain the indices returned by the getMin or getMax. In the event that
* an operation would produce an
* invalid or nonsensical range, Location.empty
should be returned.
*
* Location objects are always immutable. *
* ** Locations can be constructed in a number of ways: *
* ** Location l1 = LocationTools.makeLocation(10, 20); // Makes a RangeLocation * Location l2 = LocationTools.makeLocation(25, 25); // Makes a PointLocation * Location l3 = LocationTools.union(l1, l2); // Construct a non-contiguous * // location containing the * // points from l1 and l2 ** * @author Matthew Pocock * @author Thomas Down */ public interface Location { /** * Create a new instance of Location with all of the same decorators as this * instance but with the data stored in
loc
.
*
* The default behavior is to return loc
.
*
* @param loc the Location to use as template
* @return a Location instance based on loc with the same decorators as the
* current instance
*/
Location newInstance(Location loc);
/**
* Checks the decorator chain for an instance of
* The default behavior is to return null. If the current object is a
* decorator and is an instance of
* WARNING: The location will not contain every point between getMin()
* and getMax()
if isContiguous()
is false. If isContiguous()
* does return false you should use the Iterator
returned by blockIterator()
* to iterate over the minimum set of contiguous blocks that make up this Location
*
* @return the minimum position contained
*/
int getMin();
/**
* The maximum position contained.
*
* WARNING: The location will not contain every point between getMin()
* and getMax()
if isContiguous()
is false. If isContiguous()
* does return false you should use the Iterator
returned by blockIterator()
* to iterate over the minimum set of contiguous blocks that make up this Location
*
* @return the maximum position contained
*/
int getMax();
/**
* Checks if these two locations overlap, using this location's
* concept of overlapping.
*
* Abstractly, two locations overlap if they both contain any point. * * @param l the Location to check * @return true if they overlap, otherwise false * */ boolean overlaps(Location l); /** * Checks if this location contains the other. *
* Abstractly, a location contains another if every point in the * other location is contained within this one. * * @param l the Location to check * @return true if this contains l, otherwise false * */ boolean contains(Location l); /** * Checks if this location contains a point. * * @param p the point to check * @return true if this contains p, otherwise false */ boolean contains(int p); /** * Checks if this location is equivalent to the other. *
* Abstractly, a location is equal to another if for every point in one
* it is also in the other. This is equivalent to
* a.contains(b) && b.contains(a). You should call LocationTools.areEqual
* after casting l to Location.
*
* @param l the Object to check
* @return true if this equals l, otherwise false
*/
boolean equals(Object l);
/**
* Returns a Location that contains all points common to both ranges.
*
* @param l the Location to intersect with
* @return a Location containing all points common to both, or
* the empty range if there are no such points
*
*/
Location intersection(Location l);
/**
* Return a Location containing all points in either ranges.
*
* @param l the Location to union with
* @return a Location representing the union
*
*/
Location union(Location l);
/**
* Return the symbols in a sequence that fall within this range.
*
* @param seq the SymbolList to process
* @return the SymbolList containing the symbols in seq in this range
*
*/
SymbolList symbols(SymbolList seq);
/**
* Create a location that is a translation of this location.
*
* @param dist the distance to translate (to the right)
*/
Location translate(int dist);
/**
* Determine if a Location is contiguous.
*
* @return true
if and only if this Location
* contains every point from min
to
* max
inclusive.
*/
boolean isContiguous();
/**
* Return an Iterator over the set of maximal contiguous sub-locations.
*
* Given any location, it can be considered to contain zero or more * maximal contiguous blocks of width 1 or greater. The empty location is * composed from nothing. A contiguous location is composed from itself. * A non-contiguous location is composed from contiguous blocks seperated by * gaps. *
* This method should return an Iterator over these maximally contiguous blocks
* starting with the left-most block, and finishing at the right-most block.
*
* @return an Iterator over Location objects that are the maximally contiguous
* set of locations contained within this location
*/
Iterator blockIterator();
/**
* The Location
which contains no points.
*
*
* This object contains nothing. Its minimum value is Integer.MAX_VALUE. * Its maximum value is Integer.MIN_VALUE. It overlaps nothing. It is * equal to nothing. Intersection results in the empty range. Union * results in the argument range. Symbols returns an empty array. *
* Every day, in every way, empty becomes more and more boring.
*/
public static final Location empty = new EmptyLocation();
/**
* The Location
which contains all points.
*
*
* This object contains every point. It's minimum value is Integer.MIN_VALUE, * and it's maximum value is Integer.MAX_VALUE. It overlaps and contains * everything. *
*/ public static final Location full = new RangeLocation(Integer.MIN_VALUE, Integer.MAX_VALUE); /** * Comparator which orders Locations naturally. Locations * are sorted primarily on the basis of theirgetMin()
* value. In cases where that is equal, they are secondarily sorted
* by getMax()
value.
*/
static final LocationComparator naturalOrder = new LocationComparator();
}