edu.nrao.sss.measure
Class LongitudeInterval

java.lang.Object
  edu.nrao.sss.measure.LongitudeInterval

All Implemented Interfaces:

Cloneable

public class LongitudeInterval
extends Object
implements Cloneable

An interval from one line of longitude to another.

This interval is half-open; it includes the starting point but does not include the ending point.

The motivation for this class is the desire to test, for example, if a given point is between a longitude of 355 degrees and 10 degrees, which is different that testing if that point is between 10 degrees and 355 degrees. Because there is a discontinuity where once we reach the maximum longitude we proceed to the minimum, we cannot use the typical range concept that allows us to test whether a point is at or above a minimum and below a maximum, as the example above shows. Instead, we need to know if a point is on or after a starting point and before an ending, where the starting point could be numerically greater than the ending point. The TimeInterval class encapsulates the same concept for the time of day.

Version Info:

$Revision: 1707 $

$Date: 2008-11-14 10:23:59 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $ (last person to modify)

Since:

2007-06-13

Author:

David M. Harland

Constructor Summary

LongitudeInterval()
Creates a new interval that encompasses the entire circle.

LongitudeInterval(Longitude from, Longitude to)
Creates a new interval using the given longitudes.

Method Summary

LongitudeInterval	clone() Returns a copy of this interval.
boolean	contains(Longitude longitude) Returns true if longitude is contained in this interval.
boolean	equals(Object o) Returns true if o is equal to this interval.
Longitude	getCenter() Returns the longitude that is midway between the endpoints of this interval.
Longitude	getEnd() Returns this interval's ending longitude.
Angle	getLength() Returns the length of this this interval.
Longitude	getStart() Returns this interval's starting longitude.
int	hashCode() Returns a hash code value for this interval.
static LongitudeInterval	parse(String intervalText) Creates a new longitude interval by parsing intervalText.
static LongitudeInterval	parse(String intervalText, String endPointSeparator) Creates a new longitude interval by parsing intervalText.
void	reset() Resets this interval to its default state.
void	set(Longitude from, Longitude to) Sets the starting and ending points of this interval.
void	set(String intervalText) Sets the endpoints of this interval based on intervalText.
LongitudeInterval[]	split(Longitude pointOfSplit) Returns two new intervals that were formed by splitting this one at the given point.
void	switchEndpoints() Exchanges the starting and ending points of this interval.
LongitudeInterval	toComplement() Creates a new interval whose starting point is this interval's ending point and whose ending point is this interval's starting point.
String	toString() Returns a string representation of this interval.
String	toString(String endPointSeparator) Returns a string representation of this interval.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

LongitudeInterval

public LongitudeInterval()

Creates a new interval that encompasses the entire circle.

LongitudeInterval

public LongitudeInterval(Longitude from,
                         Longitude to)

Creates a new interval using the given longitudes.

The description of the set(Longitude, Longitude) method applies to this constructor as well.

Parameters:

from - the starting point of this interval. The starting point is included in the interval.

to - the ending point of this interval. The ending point is not included in the interval.

Method Detail

reset

public void reset()

Resets this interval to its default state.

A reset interval has the same state as one newly created by the no-argument constructor. Specifically, it is an interval that encompasses a full circle.

set

public void set(Longitude from,
                Longitude to)

Sets the starting and ending points of this interval.

It is acceptable for the starting longitude to be later than the ending longitude. The interval still starts at from; it is just that, in order to reach to, it must cross the "top" of the circle (0, or 360, degrees).

If either parameter is null, an IllegalArgumentException will be thrown.

This class will maintain references to from and to; it will not make copies. This means that any changes made by clients to the parameter objects after calling this method will be reflected in this object.

Parameters:

from - the starting point of this interval. The starting point is included in the interval.

to - the ending point of this interval. The ending point is not included in the interval.

set

public void set(String intervalText)

Sets the endpoints of this interval based on intervalText. If intervalText is null or "" (the empty string), the reset() method is called. Otherwise, the parsing is delegated to parse(String). See that method for details related to parsing.

switchEndpoints

public void switchEndpoints()

Exchanges the starting and ending points of this interval.

toComplement

public LongitudeInterval toComplement()

Creates a new interval whose starting point is this interval's ending point and whose ending point is this interval's starting point.

Returns:

a new interval with endpoints opposite to those of this interval.

split

public LongitudeInterval[] split(Longitude pointOfSplit)

Returns two new intervals that were formed by splitting this one at the given point. This interval is not altered by this method.

Scenario One. If this interval contains pointOfSplit, then the first interval in the array runs from this interval's starting point to pointOfSplit, and the second interval runs from pointOfSplit to this interval's ending point.

Scenario Two. If this interval does not contain pointOfSplit, then the first interval in the array will be equal to this one, and the second interval will be a zero length interval whose starting and ending endpoints are both pointOfSplit.

Parameters:

pointOfSplit - the point at which to split this interval in two.

Returns:

an array of two intervals whose combined length equals this interval's length.

getStart

public Longitude getStart()

Returns this interval's starting longitude. Note that the starting longitude is included in this interval.

The returned longitude, which is guaranteed to be non-null, is the actual longitude held by this interval, so changes made to it will be reflected in this object.

Returns:

this interval's starting longitude.

See Also:

set(Longitude, Longitude)

getEnd

public Longitude getEnd()

Returns this interval's ending longitude. Note that the end longitude is not included in this interval.

The returned longitude, which is guaranteed to be non-null, is the actual longitude held by this interval, so changes made to it will be reflected in this object.

Returns:

this interval's ending longitude.

See Also:

set(Longitude, Longitude)

getCenter

public Longitude getCenter()

Returns the longitude that is midway between the endpoints of this interval.

Understand that while the returned value will always be between the endpoints (or coincident with them, if they are identical), the center may be numerically smaller than the starting point of this interval. For example, if this interval starts at 340 degrees and ends at 60 degrees, the length of this interval is 80 degrees, and the center is at 20 degrees, which is a smaller value than that of -- but is not "before" -- the starting point.

Returns:

the center of this interval.

getLength

public Angle getLength()

Returns the length of this this interval.

Returns:

the length of this this interval.

contains

public boolean contains(Longitude longitude)

Returns true if longitude is contained in this interval.

Note that this interval is half-open; it includes the starting point, but not the ending point.

Parameters:

longitude - the longitude to be tested for containment.

Returns:

true if longitude is contained in this interval.

toString

public String toString()

Returns a string representation of this interval. The separator of the endpoints is FormatString.ENDPOINT_SEPARATOR.

Overrides:

toString in class Object

Returns:

a string representation of this interval.

toString

public String toString(String endPointSeparator)

Returns a string representation of this interval. See the toString method in Longitude for information about how the endpoints are formatted. The endPointSeparator is used to separate the two endpoints in the returned string.

Parameters:

endPointSeparator - text that separates one endpoint from another in the returned string. Using a null or empty-string value here is a bad idea.

Returns:

a string representation of this interval.

parse

public static LongitudeInterval parse(String intervalText)

Creates a new longitude interval by parsing intervalText.

This is a convenience method that is equivalent to:

   parse(intervalText, FormatString.ENDPOINT_SEPARATOR);

That is, the string separating the two endpoints is assumed to be FormatString.ENDPOINT_SEPARATOR.

Parameters:

intervalText - the text to be parsed and converted into a longitude interval. If this value is null or "" (the empty string), a new interval of length zero is returned.

Returns:

a new time interval based on intervalText.\ If intervalText is null or "" (the empty string), a new interval of length zero is returned.

Throws:

IllegalArgumentException - if intervalText cannot be parsed.

parse

public static LongitudeInterval parse(String intervalText,
                                      String endPointSeparator)

Creates a new longitude interval by parsing intervalText. The general form of intervalText is StartTimeOfDaySeparatorEndTimeOfDay, with the particulars of the longitude format described by the Longitude.parse(String) method of Longitude.

Parameters:

intervalText - the text to be parsed and converted into a longitude interval. If this value is null or "" (the empty string), a new interval of length zero is returned.

endPointSeparator - the text that separates the starting longitude from the ending longitude in intervalText.

Returns:

a new longitude interval based on intervalText.

Throws:

IllegalArgumentException - if the combination intervalText and endPointSeparator cannot be parsed successfully.

clone

public LongitudeInterval clone()

Returns a copy of this interval.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this interval.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this interval.

Overrides:

hashCode in class Object