## org.biojava.bio.symbol
Class CircularLocation

    java.lang.Object
      org.biojava.bio.symbol.AbstractLocationDecorator
          org.biojava.bio.symbol.CircularLocation

All Implemented Interfaces:
  Location

    public class CircularLocation

extends AbstractLocationDecorator

Circular view onto an underlying Location instance. If the location overlaps the origin of the sequence the underlying location will be a CompoundLocation Note that in this case isContiguous() will return false. This behaviour is desirable for proper treatment of the location with LocationTools. To find if a location overlaps the origin use the overlapsOrigin() method

Note also that as a location that overlaps the origin is a compound location it's min will be 1 and its max will be length (by default). In these cases it is imperative to use the block iterator if you wish to know the 'true' min and max (bearing in mind that there is no logical value for a min or max on a circular sequence).

The symbols() method has been overridden to handle the weirdness of a location crossing the origin.

Since:
  1.2
Author:
  Matthew Pocock, Mark Schreiber

Field Summary

Fields inherited from interface org.biojava.bio.symbol.Location
`empty, full, naturalOrder`

Constructor Summary
`CircularLocation(Location wrapped, int length)` Constructs a CircularLocation by wrapping another Location It is preferable to use LocationTools to make CircularLocations
`CircularLocation(Location wrapped, int length, int fivePrimeEnd)` Makes a CircularLocation where the 5' end of the Location is specified.

Method Summary
`boolean` `contains(int p)` Checks if this location contains a point.
`boolean` `contains(Location l)` Checks if this location contains the other.
`protected Location` `decorate(Location loc)`
`boolean` `equals(Object o)` Checks if this location is equivalent to the other.
`ListIterator` `fivePrimeBlockIterator()` Iterates over the location blocks in order starting with the most 5'
`int` `get3PrimeEnd()`
`int` `get5PrimeEnd()` The point at which indicates the 5' end of the Location.
`int` `getLength()`
`int` `getMax()` This will give you the coordinate of the maximum point contained by this Location.
`int` `getMin()` This will give you the coordinate of the minimum point contained by this Location.
`Location` `intersection(Location l)` Returns a Location that contains all points common to both ranges.
`boolean` `isContiguous()` Delegates to the wrapped location.
`boolean` `overlaps(Location l)` Checks if these two locations overlap, using this location's concept of overlapping.
`boolean` `overlapsOrigin()` Does the Location overlap the origin (position 1) of the sequence?
`SymbolList` `symbols(SymbolList seq)` Return the symbols in a sequence that fall within this range.
`String` `toString()`
`Location` `union(Location l)` Return a Location containing all points in either ranges.

Methods inherited from class org.biojava.bio.symbol.AbstractLocationDecorator
`blockIterator, getDecorator, getWrapped, newInstance, translate`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### CircularLocation

    public CircularLocation(Location wrapped,
                            int length)

  Constructs a CircularLocation by wrapping another Location It is preferable to use LocationTools to make CircularLocations

  Parameters:
    `wrapped` - the Location to wrap.
    `length` - the length of the Sequence

### CircularLocation

    public CircularLocation(Location wrapped,
                            int length,
                            int fivePrimeEnd)

  Makes a CircularLocation where the 5' end of the Location is specified. The `fivePrimeEnd` parameter must match one of the minimum coordinates of the wrapped `Location`. This allows the creation of Locations whose polarity can be specified. This method is used internally by `LocationTools.union()` and by the other constructor.

  Parameters:
    `wrapped` - the `Location` to map to a Circle
    `length` - the lenght of the circle
    `fivePrimeEnd` - the 5' polar end of the sequence
  Throws:
    `IllegalArgumentException` - if the 5' end doesn't match the min coordinate of either `wrapped` or one of its blocks.

Method Detail

### getLength

    public final int getLength()

### overlapsOrigin

    public boolean overlapsOrigin()

  Does the Location overlap the origin (position 1) of the sequence?

  If it does the Location will internally be composed of a CompoundLocation.

  Returns:
    true if it does, false otherwise

### decorate

    protected Location decorate(Location loc)

  Specified by:
    `decorate` in class `AbstractLocationDecorator`

### contains

    public boolean contains(int p)

  Description copied from interface: `Location`
  Checks if this location contains a point.

  Specified by:
    `contains` in interface `Location`
  Overrides:
    `contains` in class `AbstractLocationDecorator`
  Parameters:
    `p` - the point to check
  Returns:
    true if this contains p, otherwise false

### intersection

    public Location intersection(Location l)

  Description copied from interface: `Location`
  Returns a Location that contains all points common to both ranges.

  Specified by:
    `intersection` in interface `Location`
  Overrides:
    `intersection` in class `AbstractLocationDecorator`
  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

### overlaps

    public boolean overlaps(Location l)

  Description copied from interface: `Location`
  Checks if these two locations overlap, using this location's concept of overlapping.

  Abstractly, two locations overlap if they both contain any point.

  Specified by:
    `overlaps` in interface `Location`
  Overrides:
    `overlaps` in class `AbstractLocationDecorator`
  Parameters:
    `l` - the Location to check
  Returns:
    true if they overlap, otherwise false

### union

    public Location union(Location l)

  Description copied from interface: `Location`
  Return a Location containing all points in either ranges.

  Specified by:
    `union` in interface `Location`
  Overrides:
    `union` in class `AbstractLocationDecorator`
  Parameters:
    `l` - the Location to union with
  Returns:
    a Location representing the union

### contains

    public boolean contains(Location l)

  Description copied from interface: `Location`
  Checks if this location contains the other.

  Abstractly, a location contains another if every point in the other location is contained within this one.

  Specified by:
    `contains` in interface `Location`
  Overrides:
    `contains` in class `AbstractLocationDecorator`
  Parameters:
    `l` - the Location to check
  Returns:
    true if this contains l, otherwise false

### equals

    public boolean equals(Object o)

  Description copied from interface: `Location`
  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.

  Specified by:
    `equals` in interface `Location`
  Overrides:
    `equals` in class `AbstractLocationDecorator`
  Parameters:
    `o` - the Object to check
  Returns:
    true if this equals l, otherwise false

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

### isContiguous

    public boolean isContiguous()

  Delegates to the wrapped location. Currently as locations that cross the origin are wrapped CompoundLocations they are not considered contiguous. This is desirable from the point of view of logical operations as it greatly simplifies the calculations of things such as contains, overlaps etc.

  Specified by:
    `isContiguous` in interface `Location`
  Overrides:
    `isContiguous` in class `AbstractLocationDecorator`
  Returns:
    true if the location is contiguous and doesn't overlap the origin

### get5PrimeEnd

    public int get5PrimeEnd()

  The point at which indicates the 5' end of the Location. This is needed as compound circular locations have polarity. For example (18..30, 1..12) is not the same as (1..12, 18..30). The 5' coordinate is derived during construction of the Location. In particular during a union operation the 5' coordinate is generally the 5' coordinate of the first location in the union. In the case where this cannot be logically maintained the 5' coordinate will revert to `getMin()`

  Returns:
    the most 5' coordinate
  See Also:
    `fivePrimeBlockIterator()`, `getMin()`, `get3PrimeEnd()`

### get3PrimeEnd

    public int get3PrimeEnd()

  Returns:
    the most 3' coordinate
  See Also:
    `fivePrimeBlockIterator()`, `getMax()`, `get5PrimeEnd()`

### getMin

    public int getMin()

  This will give you the coordinate of the minimum point contained by this Location. Generally this will be the leftmost end however if the Location crosses the origin then it will actually be the origin that is the minimum point and the method will return 1. If you want to be guarenteed of getting the leftmost coordinate then call `get5PrimeEnd()`

  Specified by:
    `getMin` in interface `Location`
  Overrides:
    `getMin` in class `AbstractLocationDecorator`
  Returns:
    the minimum coord
  See Also:
    `get5PrimeEnd()`

### getMax

    public int getMax()

  This will give you the coordinate of the maximum point contained by this Location. Generally this will be the rightmost end however if the Location crosses the origin then it will actually be the point before the origin that is the maximum point and the method will return `getLength()`. If you want to be guarenteed of getting the rightmost coordinate then call `get3PrimeEnd()`

  Specified by:
    `getMax` in interface `Location`
  Overrides:
    `getMax` in class `AbstractLocationDecorator`
  Returns:
    the maximum coord
  See Also:
    `get3PrimeEnd()`

### symbols

    public SymbolList symbols(SymbolList seq)

  Description copied from interface: `Location`
  Return the symbols in a sequence that fall within this range.

  Specified by:
    `symbols` in interface `Location`
  Overrides:
    `symbols` in class `AbstractLocationDecorator`
  Parameters:
    `seq` - the SymbolList to process
  Returns:
    the SymbolList containing the symbols in seq in this range

### fivePrimeBlockIterator

    public ListIterator fivePrimeBlockIterator()

  Iterates over the location blocks in order starting with the most 5'

  Returns:
    a ListIterator
  See Also:
    `AbstractLocationDecorator.blockIterator()`, `get5PrimeEnd()`