edu.nrao.sss.measure
Class Longitude

java.lang.Object
  edu.nrao.sss.measure.EquatorialArc<Longitude>
      edu.nrao.sss.measure.Longitude

All Implemented Interfaces:

Cloneable, Comparable<Longitude>

public class Longitude
extends EquatorialArc<Longitude>

The longitudal coordinate of a point on a sphere. The other coordinate is Latitude. As a pair, these form an EquatorialCoordinate point.

The major usage of this class is as a right ascension. See Wikipedia for an explanation of right ascension.

Version Info:

$Revision: 1279 $

$Date: 2008-05-07 20:52:51 -0600 (Wed, 07 May 2008) $

$Author: dharland $ (last person to update)

Since:

2006-02-27

Author:

David M. Harland

Constructor Summary

Longitude()
Creates a new longitude of 0.0 degrees.

Longitude(Angle longitude)
Creates a new longitude from the given angle.

Longitude(BigDecimal degrees)
Creates a new longitude of degrees degrees.

Longitude(BigDecimal magnitude, ArcUnits units)
Creates a new longitude with the given magnitude and units.

Longitude(String degrees)
Creates a new longitude of degrees degrees.

Longitude(String magnitude, ArcUnits units)
Creates a new longitude with the given magnitude and units.

Method Summary

boolean	getIncreasesEastward() Returns true if longitude generally increases when traveling east.
boolean	isEastOf(Longitude other) Returns true if this longitude is east of other.
boolean	isOpposite(Longitude other) Returns true if this longitude and other are separated by one half circle.
boolean	isWestOf(Longitude other) Returns true if this longitude is west of other.
static Longitude	parse(String text) Returns a new longitude based on the given text.
void	reset() Resets this longitude so that it is equal to a longitude created via the no-argument constructor.
void	set(String text) Sets the value and units of this longitude based on the given text.
void	setIncreasesEastward(boolean increasesToTheEast) Configures the directional convention for this longitude.
void	setToFullCircle() Sets the value of this longitude to the value of a full circle in its current units.
String	toString(String separator) Returns a string where the hours, minutes, and seconds are separated by the given string.
String	toString(String separator, int minFracDigits, int maxFracDigits) Returns a string where the hours, minutes, and seconds are separated by the given string.

Methods inherited from class edu.nrao.sss.measure.EquatorialArc

add, add, add, add, add, add, clone, compareTo, convertTo, equals, getUnits, getValue, hashCode, set, set, subtract, subtract, subtract, subtract, subtract, subtract, toAngle, toDms, toHms, toString, toString, toStringDms, toStringDms, toStringDmsHtml, toStringHms, toStringHms, toUnits

Methods inherited from class java.lang.Object

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

Constructor Detail

Longitude

public Longitude()

Creates a new longitude of 0.0 degrees.

Longitude

public Longitude(Angle longitude)

Creates a new longitude from the given angle.

Parameters:

longitude - an angle of longitude.

Throws:

NullPointerException - if longitude is null

Longitude

public Longitude(BigDecimal degrees)

Creates a new longitude of degrees degrees. If degrees is not a valid value¹ for longitude, it will be normalized in a way that will transform it to a legal value.

¹ To be legal, degrees must be greater than or equal to 0.0 and less than +360.0.

Longitude

public Longitude(String degrees)

Creates a new longitude of degrees degrees. If degrees is not a valid value¹ for longitude, it will be normalized in a way that will transform it to a legal value.

¹ To be legal, degrees must be greater than or equal to 0.0 and less than +360.0.

Longitude

public Longitude(BigDecimal magnitude,
                 ArcUnits units)

Creates a new longitude with the given magnitude and units. If magnitude is not a valid value¹ for longitude, it will be normalized in a way that will transform it to a legal value.

¹ To be legal, magnitude must be greater than or equal to zero and less than one full circle, in the given units.

Longitude

public Longitude(String magnitude,
                 ArcUnits units)

Creates a new longitude with the given magnitude and units. If magnitude is not a valid value¹ for longitude, it will be normalized in a way that will transform it to a legal value.

¹ To be legal, magnitude must be greater than or equal to zero and less than one full circle, in the given units.

Method Detail

reset

public void reset()

Resets this longitude so that it is equal to a longitude created via the no-argument constructor.

setIncreasesEastward

public void setIncreasesEastward(boolean increasesToTheEast)

Configures the directional convention for this longitude. If increasesToTheEast is true, then longitude values become more positive in an eastward direction. If it is false, then they become more positive in a westward direction.

Parameters:

increasesToTheEast - true if longitude generally increases when traveling east.

getIncreasesEastward

public boolean getIncreasesEastward()

Returns true if longitude generally increases when traveling east.

Returns:

true if longitude generally increases when traveling east.

isOpposite

public boolean isOpposite(Longitude other)

Returns true if this longitude and other are separated by one half circle.

Parameters:

other - the other longitude to be tested.

Returns:

true if other is separated from this longitude by one half circle.

isEastOf

public boolean isEastOf(Longitude other)

Returns true if this longitude is east of other. One longitude is east of another if there are fewer lines of longitude to cross by traveling eastward along a given latitude than there would be by traveling westward along that same latitude.

Two special cases are worth noting. First, a longitude that is equal to this one is neither east nor west of this one. Second, a longitude that is opposite this one is both east and west of this one.

Parameters:

other - the longitude to be tested.

Returns:

true if this longitude is east of other.

isWestOf

public boolean isWestOf(Longitude other)

Returns true if this longitude is west of other. One longitude is west of another if there are fewer lines of longitude to cross by traveling westward along a given latitude than there would be by traveling eastward along that same latitude.

Two special cases are worth noting. First, a longitude that is equal to this one is neither east nor west of this one. Second, a longitude that is opposite this one is both east and west of this one.

Parameters:

other - the longitude to be tested.

Returns:

true if this longitude is west of other.

setToFullCircle

public void setToFullCircle()

Sets the value of this longitude to the value of a full circle in its current units. This value would usually be normalized to a value of zero, but not in this case. This method is useful for the LongitudeInterval class.

toString

public String toString(String separator)

Returns a string where the hours, minutes, and seconds are separated by the given string.

Parameters:

separator - the separator to use between the hours and minutes, and minutes and seconds, fields.

Returns:

a text representation of this declination.

toString

public String toString(String separator,
                       int minFracDigits,
                       int maxFracDigits)

Returns a string where the hours, minutes, and seconds are separated by the given string.

Parameters:

separator - the separator to use between the hours and minutes, and minutes and seconds, fields.

minFracDigits - the minimum number of places after the decimal point for the seconds field.

maxFracDigits - the maximum number of places after the decimal point for the seconds field.

Returns:

a text representation of this declination.

parse

public static Longitude parse(String text)

Returns a new longitude based on the given text.

See the parse method of Angle for information on the format of text. This Longitude class offers two other formats:

1. hh:mm:ss.sss
2. hh mm ss.sss

Both of the above are in hours, minutes, and seconds. For the first alternative form, whitespace is permitted around the colon characters. For the second alternative form, any type and number of whitespace characters may be used in between the three parts.

The parsed value, if not a legal value for longitude, will be normalized in such a way that it is transformed to a legal value. To be legal, magnitude must be greater than or equal zero and less than or equal to one full circle, in the given units.

Parameters:

text - a string that will be converted into a longitude.

Returns:

a new longitude. If parsing was successful, the value of the longitude will be based on the parameter string. If it was not, the returned longitude will be of zero degrees.

Throws:

IllegalArgumentException - if text is not in the expected form.

set

public void set(String text)

Sets the value and units of this longitude based on the given text.

See the parse method of Angle for information on the format of text.

The parsed value, if not a legal value for longitude, will be normalized in such a way that it is transformed to a legal value. To be legal, magnitude must be greater than or equal zero and less than or equal to one full circle, in the given units.

If the parsing fails, this longitude will be kept in its current state.

Parameters:

text - a string that will be converted into a longitude.

Throws:

IllegalArgumentException - if text is not in the expected form.