edu.nrao.sss.measure
Class Latitude

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

All Implemented Interfaces:

Cloneable, Comparable<Latitude>

public class Latitude
extends EquatorialArc<Latitude>

The latitudinal coordinate of a point on a sphere. The other coordinate is Longitude.

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

Version Info:

$Revision: 161 $

$Date: 2006-12-15 18:48:34 +0000 (Fri, 15 Dec 2006) $

$Author: btruitt $ (last person to update)

Since:

2006-02-27

Author:

David M. Harland

Constructor Summary

Latitude()
Creates a new latitude of 0.0 degrees.

Latitude(Angle latitude)
Creates a new latitude from the given angle.

Latitude(BigDecimal degrees)
Creates a new latitude of degrees degrees.

Latitude(BigDecimal magnitude, ArcUnits units)
Creates a new latitude with the given magnitude and units.

Latitude(String degrees)
Creates a new latitude of degrees degrees.

Latitude(String magnitude, ArcUnits units)
Creates a new latitude with the given magnitude and units.

Method Summary

boolean	getIncreasesNorthward() Returns true if latitude increases when traveling north.
boolean	isEquator() Returns true if this latitude is the equator.
boolean	isNorthOf(Latitude other) Returns true if this latitude is north of other.
boolean	isNorthOfEquator() Returns true if this latitude is north of the equator.
boolean	isNorthPole() Returns true if this latitude is the north pole.
boolean	isPole() Returns true if this latitude is one of the poles.
boolean	isSouthOf(Latitude other) Returns true if this latitude is south of other.
boolean	isSouthOfEquator() Returns true if this latitude is south of the equator.
boolean	isSouthPole() Returns true if this latitude is the north pole.
static Latitude	parse(String text) Returns a new latitude based on the given text.
void	reset() Resets this latitude so that it is equal to a latitude created via the no-argument constructor.
void	set(String text) Sets the value and units of this latitude base on the given text.
void	setIncreasesNorthward(boolean northIsUp) Configures the directional convention for this latitude.
String	toString(String separator) Returns a string where the degrees, minutes, and seconds are separated by the given string.
String	toString(String separator, int minFracDigits, int maxFracDigits) Returns a string where the degrees, 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

Latitude

public Latitude()

Creates a new latitude of 0.0 degrees.

Latitude

public Latitude(Angle latitude)

Creates a new latitude from the given angle.

Parameters:

latitude - an angle of latitude.

Throws:

NullPointerException - if latitude is null

Latitude

public Latitude(BigDecimal degrees)

Creates a new latitude of degrees degrees. If degrees is not a valid value¹ for latitude, 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 -90.0 and less than or equal to +90.0.

Latitude

public Latitude(String degrees)

Creates a new latitude of degrees degrees. If degrees is not a valid value¹ for latitude, 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 -90.0 and less than or equal to +90.0.

Latitude

public Latitude(BigDecimal magnitude,
                ArcUnits units)

Creates a new latitude with the given magnitude and units. If magnitude is not a valid value¹ for latitude, 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 the negative of one-quarter of a circle and less than or equal to one-quarter of a circle, in the given units.

Latitude

public Latitude(String magnitude,
                ArcUnits units)

Creates a new latitude with the given magnitude and units. If magnitude is not a valid value¹ for latitude, 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 the negative of one-quarter of a circle and less than or equal to one-quarter of a circle, in the given units.

Method Detail

reset

public void reset()

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

setIncreasesNorthward

public void setIncreasesNorthward(boolean northIsUp)

Configures the directional convention for this latitude. If northIsUp is true, then latitude values become more positive in a northward direction. If it is false, then they become more positive in a southward direction.

Parameters:

northIsUp - true if latitude increases when traveling north.

getIncreasesNorthward

public boolean getIncreasesNorthward()

Returns true if latitude increases when traveling north.

Returns:

true if latitude increases when traveling north.

isNorthOf

public boolean isNorthOf(Latitude other)

Returns true if this latitude is north of other.

Parameters:

other - the latitude to be tested.

Returns:

true if this latitude is north of other.

isSouthOf

public boolean isSouthOf(Latitude other)

Returns true if this latitude is south of other.

Parameters:

other - the latitude to be tested.

Returns:

true if this latitude is south of other.

isNorthOfEquator

public boolean isNorthOfEquator()

Returns true if this latitude is north of the equator.

Returns:

true if this latitude is north of the equator.

isSouthOfEquator

public boolean isSouthOfEquator()

Returns true if this latitude is south of the equator.

Returns:

true if this latitude is south of the equator.

isPole

public boolean isPole()

Returns true if this latitude is one of the poles.

Returns:

true if this latitude is one of the poles.

Since:

2008-10-15

isNorthPole

public boolean isNorthPole()

Returns true if this latitude is the north pole.

Returns:

true if this latitude is the north pole.

Since:

2008-10-15

isSouthPole

public boolean isSouthPole()

Returns true if this latitude is the north pole.

Returns:

true if this latitude is the north pole.

Since:

2008-10-15

isEquator

public boolean isEquator()

Returns true if this latitude is the equator.

Returns:

true if this latitude is the equator.

Since:

2008-10-15

toString

public String toString(String separator)

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

Parameters:

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

Returns:

a text representation of this latitude.

toString

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

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

Parameters:

separator - the separator to use between the degrees 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 latitude.

parse

public static Latitude parse(String text)

Returns a new latitude based on the given text.

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

1. dd:mm:ss.sss
2. dd mm ss.sss

Both of the above are in degrees, arc-minutes, and arc-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 latitude, 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 to the negative of one-quarter of a circle and less than or equal to one-quarter of a circle, in the given units.

Parameters:

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

Returns:

a new latitude. If parsing was successful, the value of the latitude will be based on the parameter string. If it was not, the returned latitude 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 latitude base on the given text. See parse(String) for the expected format of text.

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

The parsed value, if not a legal value for latitude, 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 to the negative of one-quarter of a circle and less than or equal to one-quarter of a circle, in the given units.

Parameters:

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

Throws:

IllegalArgumentException - if text is not in the expected form.