Class Location

A location on a sequence.
A location is a contiguous range of indices, with a single start and end point.

Internally, location indices are stored in Java "half-open" format: the start is the (origin 0) index of
the first symbol in the range; the end is the origin 0 index of the first symbol PAST the
end of the range, so that end - start == length.

Location objects, once constructed, cannot be changed. Instead, all methods return a new
location. This allows the use of "method chaining" to implement a particular calculation.
For example, consider the chained statement "loc.prefix( 100 ).suffix( 10 )",
which first applies the prefix method to
the variable named loc, and then the suffix method to the result.
Together, the chained operations create a new location object of length 10
whose start is the index of the 90th symbol.
Here's another example. This one returns a location object holding the coordinates of the intron between
the first exon (location exon1) and
the second exon (location exon2) on a sequence (seq): "seq.prefix( exon2 ).suffix( exon1 )"

About the negative (reverse) strand: The location object stores reverse strand locations as
negative indices. For example, the positive strand location from index 12 to index 97 is
on the opposite side as index -97 (start) to index -12 (end). Note that the larger index is
always downstream from the smaller index, (i.e. start <= end, regardless of strand).
Obviously this representation makes it trivial
to convert a location from one strand to the other.

Additional points regarding the use of locations on opposite strands:
(1) Opposite strand locations cannot be compared, eg isBefore() will
throw an exception.
(2) Containment queries ( eg overlaps(), contains() ) also throw exceptions.
(3) The plus() method will map a location to its positive strand equivalent; use it on both args
before calling, for example the intersection() method,
if your code needs to be indifferent to strand.

Exceptions and how they are (typically) used:
IllegalArgumentException - the location given as a parameter is not on the same strand as the location.
IndexOutOfBoundsException - often means the operation caused the location to span the origin, ie
be partially on positive and partially on negative strand.

length

window

Enable a "sliding window" iteration over a location
to use with Java's "for" loop construct.
The returned helper object implements the Iterable interface; the windowSize and increment semantics are implemented
by an underlying LocIterator.

For example, given a location variable "loc":

//use window size of 3 and increment of +3
for( Location temp: loc.window( 3, 3 ))
{
//at each iteration, temp will be the location of the next 3 symbols
}

Parameters:

windowSize - The number of symbols to get on each iteration.

increment - The direction and number of symbols to advance at each iteration.

Returns:

An anonymous iterable object to use with Java's for( ... ) loop construct.