org.biojava.bio.symbol
Class LocationTools

java.lang.Object
  |
  +--org.biojava.bio.symbol.LocationTools

public final class LocationTools

extends java.lang.Object

Tools class containing a number of operators for working with Location objects.

Most of the methods in this class are simple set-wise binary operators: for example, calculate the intersection of two locations.

Since:

1.2

Author:

Matthew Pocock, Greg Cox, Thomas Down, Mark Schreiber

For general use:

This class provides helpful methods for set-wise manipulation of Location objects.

Method Summary

static boolean	areEqual(Location locA, Location locB) Return whether two locations are equal.
static boolean	contains(Location locA, Location locB) Return true iff all indices in locB are also contained by locA.
static Location	flip(Location loc, int len) Flips a location relative to a length.
static Location	intersection(Location locA, Location locB) Return the intersection of two locations.
static CircularLocation	makeCircularLocation(int min, int max, int seqLength) A simple method to generate a RangeLocation wrapped in a CircularLocation.
static Location	makeLocation(int min, int max) Return a contiguous Location from min to max.
static boolean	overlaps(Location locA, Location locB) Determines whether the locations overlap or not.
static Location	subtract(Location x, Location y) Subtract one location from another.
static Location	union(java.util.Collection locs) The n-way union of a Collection of locations.
static Location	union(Location locA, Location locB) Return the union of two locations.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

union

public static Location union(Location locA,
                             Location locB)

Return the union of two locations.

The union will be a Location instance that contains every index contained by either locA or locB.

Parameters:

locA - the first Location

locB - the second Location

Returns:

a Location that is the union of locA and locB

intersection

public static Location intersection(Location locA,
                                    Location locB)

Return the intersection of two locations.

The intersection will be a Location instance that contains every index contained by both locA and locB.

Parameters:

locA - the first Location

locB - the second Location

Returns:

a Location that is the intersection of locA and locB

overlaps

public static boolean overlaps(Location locA,
                               Location locB)

Determines whether the locations overlap or not.

Two locations overlap if they contain at least one index in common.

Parameters:

locA - the first Location

locB - the second Location

contains

public static boolean contains(Location locA,
                               Location locB)

Return true iff all indices in locB are also contained by locA.

Parameters:

locA - The containing location

locB - The contained location

Returns:

true is locA contains locB

areEqual

public static boolean areEqual(Location locA,
                               Location locB)

Return whether two locations are equal.

They are equal if both a contains b and b contains a. Equivalently, they are equal if for every point p, locA.contains(p) == locB.contains(p).

Parameters:

locA - the first Location

locB - the second Location

Returns:

true if they are equivalent, false otherwise

union

public static Location union(java.util.Collection locs)

The n-way union of a Collection of locations. Returns a Location which covers every point covered by at least one of the locations in locs

Parameters:

locs - A collection of locations.

Returns:

A union location

Throws:

java.lang.ClassCastException - if the collection contains non-Location objects.

makeLocation

public static Location makeLocation(int min,
                                    int max)

Return a contiguous Location from min to max.

If min == max then a PointLocation will be made, otherwise, a RangeLocation will be returned.

Parameters:

min - the Location min value

max - the Location max value

Returns:

a new Location from min to max

makeCircularLocation

public static CircularLocation makeCircularLocation(int min,
                                                    int max,
                                                    int seqLength)

A simple method to generate a RangeLocation wrapped in a CircularLocation. The method will cope with situtations where the min is greater than the max. Either of min or max can be negative, or greater than the underlying sequence length. If min and max are equal a wrapped point location will be made.

Parameters:

min - the "left" end of the location

max - the "right" end of the location

seqLength - the lenght of the sequence that the location will be applied to (for purposes of determining origin).

Throws:

java.lang.IllegalArgumentException - if min, max, or seqLength are 0;

flip

public static Location flip(Location loc,
                            int len)

Flips a location relative to a length.

It is very common in biological sequences to represent locations on a sequence and then reverse that sequence. This method allows locations in the original coordinate space to be transformed int locations in the reverse one.

Parameters:

loc - the Location to flip

len - the length of the region to flip within

Returns:

a flipped view of the location

subtract

public static Location subtract(Location x,
                                Location y)

Subtract one location from another. This methods calculates the set of points which are contains in location x but not in y.

Parameters:

x - A location

y - A location

Returns:

a location containing all points which are in x but not y

Since:

1.3