Location (biojava-legacy 1.9.2 API)

All Known Subinterfaces:

RichLocation

All Known Implementing Classes:

AbstractLocation, AbstractLocationDecorator, AbstractRangeLocation, BetweenLocation, CircularLocation, CompoundRichLocation, EmptyRichLocation, FuzzyLocation, FuzzyPointLocation, MergeLocation, MultiSourceCompoundRichLocation, PointLocation, RangeLocation, SimpleRichLocation
```
public interface Location
```
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.

Working with locations

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, Thomas Down

Field Summary

Fields
Modifier and Type	Field and Description
`static Location`	`empty` The `Location` which contains no points.
`static Location`	`full` The `Location` which contains all points.
`static org.biojava.bio.symbol.LocationComparator`	`naturalOrder` Comparator which orders Locations naturally.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Iterator<Location>`	`blockIterator()` Return an Iterator over the set of maximal contiguous sub-locations.
`boolean`	`contains(int p)` Checks if this location contains a point.
`boolean`	`contains(Location l)` Checks if this location contains the other.
`boolean`	`equals(Object l)` Checks if this location is equivalent to the other.
`Location`	`getDecorator(Class decoratorClass)` Checks the decorator chain for an instance of decoratorClass and return it if found.
`int`	`getMax()` The maximum position contained.
`int`	`getMin()` The minimum position contained.
`Location`	`intersection(Location l)` Returns a Location that contains all points common to both ranges.
`boolean`	`isContiguous()` Determine if a Location is contiguous.
`Location`	`newInstance(Location loc)` Create a new instance of Location with all of the same decorators as this instance but with the data stored in `loc`.
`boolean`	`overlaps(Location l)` Checks if these two locations overlap, using this location's concept of overlapping.
`SymbolList`	`symbols(SymbolList seq)` Return the symbols in a sequence that fall within this range.
`Location`	`translate(int dist)` Create a location that is a translation of this location.
`Location`	`union(Location l)` Return a Location containing all points in either ranges.

- Field Detail
  - empty
```
static final Location empty
```
    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.
  - full
```
static final Location full
```
    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.
  - naturalOrder
```
static final org.biojava.bio.symbol.LocationComparator naturalOrder
```
    Comparator which orders Locations naturally. Locations are sorted primarily on the basis of their getMin() value. In cases where that is equal, they are secondarily sorted by getMax() value.
- Method Detail
  - newInstance
```
Location newInstance(Location loc)
```
    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 unchanged. If the class is a location decorator then it should instantiate an instance of the same type that decorates loc.
    
    Parameters:
    
    loc - the Location to use as template
    
    Returns:
    
    a Location instance based on loc with the same decorators as the current instance
  - getDecorator
```
Location getDecorator(Class decoratorClass)
```
    Checks the decorator chain for an instance of decoratorClass and return it if found.
    The default behavior is to return null. If the current object is a decorator and is an instance of decoratorClass it should return itself. Otherwise, the decorator should chain this method onto the instance it wraps.
    
    Parameters:
    
    decoratorClass - the Class to check
    
    Returns:
    
    a Location if an instance of this class is present in the decorator chain and null otherwise.
  - getMin
```
int getMin()
```
    The minimum 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
    
    Returns:
    
    the minimum position contained
  - getMax
```
int getMax()
```
    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
    
    Returns:
    
    the maximum position contained
  - overlaps
```
boolean overlaps(Location l)
```
    Checks if these two locations overlap, using this location's concept of overlapping.
    Abstractly, two locations overlap if they both contain any point.
    
    Parameters:
    
    l - the Location to check
    
    Returns:
    
    true if they overlap, otherwise false
  - contains
```
boolean contains(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.
    
    Parameters:
    
    l - the Location to check
    
    Returns:
    
    true if this contains l, otherwise false
  - contains
```
boolean contains(int p)
```
    Checks if this location contains a point.
    
    Parameters:
    
    p - the point to check
    
    Returns:
    
    true if this contains p, otherwise false
  - equals
```
boolean equals(Object l)
```
    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.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    l - the Object to check
    
    Returns:
    
    true if this equals l, otherwise false
  - intersection
```
Location intersection(Location l)
```
    Returns a Location that contains all points common to both ranges.
    
    Parameters:
    
    l - the Location to intersect with
    
    Returns:
    
    a Location containing all points common to both, or the empty range if there are no such points
  - union
```
Location union(Location l)
```
    Return a Location containing all points in either ranges.
    
    Parameters:
    
    l - the Location to union with
    
    Returns:
    
    a Location representing the union
  - symbols
```
SymbolList symbols(SymbolList seq)
```
    Return the symbols in a sequence that fall within this range.
    
    Parameters:
    
    seq - the SymbolList to process
    
    Returns:
    
    the SymbolList containing the symbols in seq in this range
  - translate
```
Location translate(int dist)
```
    Create a location that is a translation of this location.
    
    Parameters:
    
    dist - the distance to translate (to the right)
  - isContiguous
```
boolean isContiguous()
```
    Determine if a Location is contiguous.
    
    Returns:
    
    true if and only if this Location contains every point from min to max inclusive.
  - blockIterator
```
Iterator<Location> blockIterator()
```
    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.
    
    Returns:
    
    an Iterator over Location objects that are the maximally contiguous set of locations contained within this location

Interface Location

Working with locations

Field Summary

Method Summary

Field Detail

empty

full

naturalOrder

Method Detail

newInstance

getDecorator

getMin

getMax

overlaps

contains

contains

equals

intersection

union

symbols

translate

isContiguous

blockIterator