edu.nrao.sss.measure
Class Distance

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

All Implemented Interfaces:

Serializable, Cloneable, Comparable<Distance>

public class Distance
extends Object
implements Cloneable, Comparable<Distance>, Serializable

A measure of distance or length.

Version Info:

$Revision: 1816 $

$Date: 2008-12-23 10:21:00 -0700 (Tue, 23 Dec 2008) $

$Author: dharland $

Since:

2006-05-03

Author:

David M. Harland

See Also:

Serialized Form

Constructor Summary

Distance()
Creates a new distance of zero kilometers.

Distance(BigDecimal kilometers)
Creates a new distance of kilometers kilometers.

Distance(BigDecimal value, DistanceUnits units)
Creates a new distance with the given magnitude and units.

Distance(String kilometers)
Creates a new distance of kilometers kilometers.

Distance(String value, DistanceUnits units)
Creates a new distance with the given magnitude and units.

Method Summary

Distance	add(Distance other) Adds other distance to this one.
Distance	clone() Returns a distance that is equal to this one.
int	compareTo(Distance otherDist) Compares this distance with the otherDist for order.
Distance	convertTo(DistanceUnits newUnits) Converts this measure of distance to the new units.
boolean	equals(Object o) Returns true if o is equal to this distance.
DistanceUnits	getUnits() Returns the units of this distance.
BigDecimal	getValue() Returns the magnitude of this distance.
int	hashCode() Returns a hash code value for this distance.
boolean	isInDefaultState() Returns true if this distance is in its default state, no matter how it got there.
boolean	isInfinite() Returns true if this distance is infinite.
static Distance	parse(String distanceString) Returns a new distance based on distanceString.
void	reset() Resets this distance so that it is equal to a distance created via the no-argument constructor.
void	set(BigDecimal value, DistanceUnits units) Sets the magnitude and units of this distance.
void	set(String distanceString) Sets the value and units of this distance based on distanceString.
void	set(String value, DistanceUnits units) Sets the magnitude and units of this distance.
void	setUnits(DistanceUnits newUnits) Sets the units of this distance to newUnits.
void	setValue(BigDecimal newValue) Sets the magnitude of this distance to newValue.
void	setValue(String newValue) Sets the magnitude of this distance to newValue.
Distance	subtract(Distance other) Subtracts other distance from this one.
String	toString() Returns a text representation of this distance.
String	toString(int minFracDigits, int maxFracDigits) Returns a text representation of this distance.
BigDecimal	toUnits(DistanceUnits otherUnits) Returns the magnitude of this distance in otherUnits.

Methods inherited from class java.lang.Object

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

Constructor Detail

Distance

public Distance()

Creates a new distance of zero kilometers.

Distance

public Distance(BigDecimal kilometers)

Creates a new distance of kilometers kilometers. See setValue(BigDecimal) for information about valid parameter values and exceptions that might be thrown.

Parameters:

kilometers - the magnitude of this distance in kilometers.

Distance

public Distance(String kilometers)

Creates a new distance of kilometers kilometers. See setValue(BigDecimal) for information about valid parameter values and exceptions that might be thrown.

Parameters:

kilometers - the magnitude of this distance in kilometers.

Distance

public Distance(BigDecimal value,
                DistanceUnits units)

Creates a new distance with the given magnitude and units. See set(BigDecimal, DistanceUnits) for information about valid parameter values and exceptions that might be thrown.

Parameters:

value - the magnitude of this distance.

units - the units in which value is expressed.

Distance

public Distance(String value,
                DistanceUnits units)

Creates a new distance with the given magnitude and units. See set(BigDecimal, DistanceUnits) for information about valid parameter values and exceptions that might be thrown.

Parameters:

value - the magnitude of this distance.

units - the units in which value is expressed.

Method Detail

reset

public void reset()

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

getValue

public BigDecimal getValue()

Returns the magnitude of this distance.

Returns:

the magnitude of this distance.

getUnits

public DistanceUnits getUnits()

Returns the units of this distance.

Returns:

the units of this distance.

set

public final void set(BigDecimal value,
                      DistanceUnits units)

Sets the magnitude and units of this distance.

See setValue(BigDecimal) for more information on legal values for value.

Parameters:

value - the new magnitude of this distance.

units - the units in which value is expressed.

set

public final void set(String value,
                      DistanceUnits units)

Sets the magnitude and units of this distance.

See setValue(String) for more information on legal values for value.

Parameters:

value - the new magnitude of this distance.

units - the units in which value is expressed.

setValue

public final void setValue(BigDecimal newValue)

Sets the magnitude of this distance to newValue.

Note that the units of this distance are unaffected by this method.

Parameters:

newValue - the new magnitude for this distance. This value may not be null but may be negative or infinite.

Throws:

NumberFormatException - if newValue is null.

setValue

public final void setValue(String newValue)

Sets the magnitude of this distance to newValue.

Note that the units of this distance are unaffected by this method.

Parameters:

newValue - the new magnitude for this distance. This value may not be null but may be negative or infinite. The allowable representations of infinity are "infinity", "+infinity", and "-infinity"; these values are not case sensitive.

Throws:

NumberFormatException - if newValue is null.

setUnits

public final void setUnits(DistanceUnits newUnits)

Sets the units of this distance to newUnits.

Note that the value of this distance is unaffected by this method. Contrast this with convertTo(DistanceUnits).

Parameters:

newUnits - the new units for this distance. If newUnits is null it will be replaced with a non-null default type.

set

public void set(String distanceString)

Sets the value and units of this distance based on distanceString. See parse(String) for the expected format of distanceString.

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

Parameters:

distanceString - a string that will be converted into a distance.

Throws:

IllegalArgumentException - if distanceString is not in the expected form.

Since:

2008-10-01

isInDefaultState

public boolean isInDefaultState()

Returns true if this distance is in its default state, no matter how it got there.

A distance is in its default state if both its value and its units are the same as those of a distance newly created via the no-argument constructor. A distance whose most recent update came via the reset method is also in its default state.

Returns:

true if this distance is in its default state.

isInfinite

public boolean isInfinite()

Returns true if this distance is infinite.

Returns:

true if this distance is infinite.

convertTo

public Distance convertTo(DistanceUnits newUnits)

Converts this measure of distance to the new units.

After this method is complete this distance will have units of newUnits and its value will have been converted accordingly.

Parameters:

newUnits - the new units for this distance. If newUnits is null an IllegalArgumentException will be thrown.

Returns:

this distance. The reason for this return type is to allow code of this nature: double kilometers = myDistance.convertTo(DistanceUnits.KILOMETERS).getValue();

toUnits

public BigDecimal toUnits(DistanceUnits otherUnits)

Returns the magnitude of this distance in otherUnits.

Note that this method does not alter the state of this distance. Contrast this with convertTo(DistanceUnits).

Parameters:

otherUnits - the units in which to express this distance's magnitude.

Returns:

this distance's value converted to otherUnits.

Throws:

IllegalArgumentException - if otherUnits is null.

add

public Distance add(Distance other)

Adds other distance to this one.

Parameters:

other - the distance to be added to this distance.

Returns:

this distance, after the addition.

subtract

public Distance subtract(Distance other)

Subtracts other distance from this one.

Parameters:

other - the distance to be subtracted from this distance.

Returns:

this distance, after the subtraction.

parse

public static Distance parse(String distanceString)

Returns a new distance based on distanceString.

Valid Formats
Let R be the text representation of a real number.
Let w represent zero or more whitespace characters.
Let S be a valid units symbol.

Format One: wRw. The given number will be defined to be in units of kilometers.

Format Two: wRwSw.

Special Cases
A distanceString of null or "" (the empty string) will not result in an IllegalArgumentException, but will instead return a distance of zero kilometers.

Parameters:

distanceString - a string that will be converted into a distance.

Returns:

a new distance.

Throws:

IllegalArgumentException - if distanceString is not in the expected form.

toString

public String toString()

Returns a text representation of this distance.

Overrides:

toString in class Object

toString

public String toString(int minFracDigits,
                       int maxFracDigits)

Returns a text representation of this distance.

Parameters:

minFracDigits - the minimum number of places after the decimal point.

maxFracDigits - the maximum number of places after the decimal point.

Returns:

a text representation of this distance.

clone

public Distance clone()

Returns a distance that is equal to this one.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this distance.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this distance.

Overrides:

hashCode in class Object

compareTo

public int compareTo(Distance otherDist)

Compares this distance with the otherDist for order.

Specified by:

compareTo in interface Comparable<Distance>