Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

edu.nrao.sss.measure
Class Angle

java.lang.Object
  extended by edu.nrao.sss.measure.Angle
All Implemented Interfaces:
Serializable, Cloneable, Comparable<Angle>
public class Angle
extends Object
implements Cloneable, Comparable<Angle>, Serializable

An angle, or measure of arc.

Positive angles are measured in a counter-clockwise direction; negative angles in a clockwise direction.

Note About Accuracy
This class originally used java's primitive double type for storage and calculation. Certain transformations, though, led to results that where not accurate enough for many purposes. Because of that, the internal references to double have been replaced with references to BigDecimal.

Version Info:

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

Since:
2006-05-23
Author:
David M. Harland
See Also:
Serialized Form

Constructor Summary
Angle()
          Creates a new angle of zero degrees.
Angle(BigDecimal degrees)
          Creates a new angle of degrees degrees.
Angle(BigDecimal magnitude, ArcUnits units)
          Creates a new angle with the given magnitude and units.
Angle(String degrees)
          Creates a new angle of degrees degrees.
Angle(String magnitude, ArcUnits units)
          Creates a new angle with the given magnitude and units.
 
Method Summary
 Angle add(Angle other)
          Adds the other angle to this one.
 Angle add(BigDecimal amount)
          Adds the amount, of the same units as this angle, to this angle.
 Angle add(String amount)
          Adds the amount, of the same units as this angle, to this angle.
static Angle arcCosine(double cosine)
          Returns a new angle whose cosine is cosine.
static Angle arcSine(double sine)
          Returns a new angle whose sine is sine.
static Angle arcTangent(double tangent)
          Returns a new angle whose tangent is tangent.
 Angle clone()
          Returns an angle that is equal to this one.
 int compareTo(Angle otherAngle)
          Compares this angle with the otherAngle for order.
 Angle convertTo(ArcUnits newUnits)
          Converts this angle to the new units.
 Angle convertToMinAbsValueNormal()
          Converts this angle to the normalized value that has the smaller absolute value.
 Angle convertToNegativeNormal()
          Converts this angle to a negative normalized angle.
 Angle convertToPositiveNormal()
          Converts this angle to a positive normalized angle.
 double cosecant()
          Returns the cosecant of this angle.
 double cosine()
          Returns the cosine of this angle.
 double cotangent()
          Returns the cotangent of this angle.
 Angle divideBy(BigDecimal divisor)
          Divides this angle by divisor.
 Angle divideBy(String divisor)
          Divides this angle by divisor.
 boolean equals(Object o)
          Returns true if o is equal to this angle.
 int getFullCircles()
          Returns the number of full circles made by this angle.
 ArcUnits getUnits()
          Returns the units of this angle.
 BigDecimal getValue()
          Returns the magnitude of this angle.
 int hashCode()
          Returns a hash code value for this angle.
 boolean isClockwise()
          Returns true if this angle is traversed in a clockwise direction.
 boolean isInDefaultState()
          Returns true if this angle is in its default state, no matter how it got there.
 boolean isInfinite()
          Returns true if the magnitude of this angle approaches infinity.
 boolean isNegative()
          Returns true if the value of this angle is less than zero.
 boolean isPositive()
          Returns true if the value of this angle is greater than zero.
 Angle multiplyBy(BigDecimal multiplier)
          Multiplies this angle by multiplier.
 Angle multiplyBy(String multiplier)
          Multiplies this angle by multiplier.
 Angle negate()
          Negates the value of this angle.
 Angle normalize()
          Normalizes this angle so that its absolute value is less than that of a full circle.
static Angle parse(String angleString)
          Returns a new angle based on angleString.
 void reset()
          Resets this angle so that it is equal to a angle created via the no-argument constructor.
 Angle reverseDirection()
          Reverses the direction of this angle.
 double secant()
          Returns the secant of this angle.
 void set(BigDecimal value, ArcUnits units)
          Sets the magnitude and units of this angle.
 void set(String angleString)
          Sets the value and units of this angle based on angleString.
 void set(String value, ArcUnits units)
          Sets the magnitude and units of this angle.
 void setUnits(ArcUnits newUnits)
          Sets the units of this angle to newUnits.
 void setValue(BigDecimal newValue)
          Sets the magnitude of this angle to newValue.
 void setValue(String newValue)
          Sets the magnitude of this angle to newValue.
 double sine()
          Returns the sine of this angle.
 Angle subtract(Angle other)
          Subtracts the other angle from this one.
 Angle subtract(BigDecimal amount)
          Subtracts the amount, of the same units as this angle, from this angle.
 Angle subtract(String amount)
          Subtracts the amount, of the same units as this angle, from this angle.
 double tangent()
          Returns the tangent of this angle.
 Number[] toDms()
          Returns a representation of this angle in degrees, minutes, and seconds.
 Number[] toHms()
          Returns a representation of this angle in hours, minutes, and seconds.
 String toString()
          Returns a text representation of this angle in its native units.
 String toString(int minFracDigits, int maxFracDigits)
          Returns a text representation of this angle in its native units.
 String toStringDms()
          Returns a text representation of this angle in degrees, arc-minutes, and arc-seconds.
 String toStringDms(int minFracDigits, int maxFracDigits)
          Returns a text representation of this angle in degrees, arc-minutes, and arc-seconds.
 String toStringDmsHtml(int minFracDigits, int maxFracDigits)
          Returns a text representation of this angle in degrees, arc-minutes, and arc-seconds, with HTML-friendly symbols.
 String toStringHms()
          Returns a text representation of this angle in hours, minutes, and seconds.
 String toStringHms(int minFracDigits, int maxFracDigits)
          Returns a text representation of this angle in hours, minutes, and seconds.
 String toStringHtml(int minFracDigits, int maxFracDigits)
          Returns a text representation of this angle in its native units, using an HTML-friendly symbol.
 BigDecimal toUnits(ArcUnits otherUnits)
          Returns the magnitude of this angle in otherUnits.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Angle

public Angle()
Creates a new angle of zero degrees.

Angle

public Angle(BigDecimal degrees)
Creates a new angle of degrees degrees.

Angle

public Angle(String degrees)
Creates a new angle of degrees degrees.

Angle

public Angle(BigDecimal magnitude,
             ArcUnits units)
Creates a new angle with the given magnitude and units.

Angle

public Angle(String magnitude,
             ArcUnits units)
Creates a new angle with the given magnitude and units.

Method Detail

reset

public void reset()
Resets this angle so that it is equal to a angle created via the no-argument constructor.

getValue

public BigDecimal getValue()
Returns the magnitude of this angle.

Returns:
the magnitude of this angle.

getUnits

public ArcUnits getUnits()
Returns the units of this angle.

Returns:
the units of this angle.

set

public final void set(BigDecimal value,
                      ArcUnits units)
Sets the magnitude and units of this angle.

Parameters:
value - the new magnitude for this angle.
units - the new units for this angle.

set

public final void set(String value,
                      ArcUnits units)
Sets the magnitude and units of this angle.

Parameters:
value - the new magnitude for this angle.
units - the new units for this angle.

setValue

public final void setValue(BigDecimal newValue)
Sets the magnitude of this angle to newValue.

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

Parameters:
newValue - the new magnitude for this angle.
Throws:
NumberFormatException - if newValue is null.

setValue

public final void setValue(String newValue)
Sets the magnitude of this angle to newValue.

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

Parameters:
newValue - the new magnitude for this angle.
Throws:
NumberFormatException - if newValue is null.

setUnits

public final void setUnits(ArcUnits newUnits)
Sets the units of this angle to newUnits.

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

Parameters:
newUnits - the new units for this angle. If newUnits is null it will be treated as ArcUnits.getDefault().

set

public void set(String angleString)
Sets the value and units of this angle based on angleString. See parse(String) for the expected format of angleString.

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

Parameters:
angleString - a string that will be converted into an angle.
Throws:
IllegalArgumentException - if angleString is not in the expected form.

getFullCircles

public int getFullCircles()
Returns the number of full circles made by this angle. The value returned is never negative.

For example, an angle of +60.0° has made zero full circles, an angle of -400.0° one full circle, and an angle of +900.0° two full circles.

Returns:
the number of full circles made by this angle.

isNegative

public boolean isNegative()
Returns true if the value of this angle is less than zero.

Returns:
true if the value of this angle is less than zero.

isPositive

public boolean isPositive()
Returns true if the value of this angle is greater than zero.

Returns:
true if the value of this angle is greater than zero.

isClockwise

public boolean isClockwise()
Returns true if this angle is traversed in a clockwise direction. The convention of this class is that negative angles are considered to be clockwise.

Returns:
true if this angle is traversed in a clockwise direction.

isInDefaultState

public boolean isInDefaultState()
Returns true if this angle is in its default state, no matter how it got there.

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

Returns:
true if this angle is in its default state.

isInfinite

public boolean isInfinite()
Returns true if the magnitude of this angle approaches infinity.

Returns:
true if the magnitude of this angle approaches infinity.

negate

public Angle negate()
Negates the value of this angle.

For example, if this angle is currently -45.0°, it will be +45.0° after this call. The negation here is a simple sign flip. Contrast this with reverseDirection().

Returns:
this angle, after the negation.

reverseDirection

public Angle reverseDirection()
Reverses the direction of this angle. The reversal results in a sign change, unless this angle has a value of zero.

For example, if this angle is currently -45.0°, it will be +315.0° after this call. Contrast this with negate().

Returns:
this angle, after the reversal of direction.

normalize

public Angle normalize()
Normalizes this angle so that its absolute value is less than that of a full circle. The method does not change the direction, or sign, of the angle.

For example, if this angle is currently 765.0°, it will be 45.0° after this call. Likewise, if this angle is currently -765.0°, it will be -45.0° after this call.

Returns:
this angle, after the normalization.

convertToPositiveNormal

public Angle convertToPositiveNormal()
Converts this angle to a positive normalized angle. The conversion is done first by normalizing this angle (see normalize()) and then by creating a positive angle, not by a simple sign flip, but instead by reversing direction to complete the circle.

For example, if this angle is currently -765.0°, it is first normalized to -45.0°. The result is then converted to a positive number by traveling the circle in the opposite direction, for a final result of +315°.

Returns:
this angle, after the conversion.

convertToNegativeNormal

public Angle convertToNegativeNormal()
Converts this angle to a negative normalized angle. The conversion is done first by normalizing this angle (see normalize()) and then by creating a negative angle not by a simple sign flip, but instead by reversing direction to complete the circle.

For example, if this angle is currently +765.0°, it is first normalized to +45.0°. The result is then converted to a negative number by traveling the circle in the opposite direction, for a final result of -315°.

Returns:
this angle, after the conversion.

convertToMinAbsValueNormal

public Angle convertToMinAbsValueNormal()
Converts this angle to the normalized value that has the smaller absolute value. This may involve a reversal of direction.

For example, if this angle is currently +920.0°, it is first normalized to +200.0°. By reversing direction, we wind up with an angle of -160.0°, which has a smaller absolute value than +200.0°, so that is our end result. For the special situations where the normalized value is either +180.0° or -180.0°, the original direction is preserved.

Returns:
this angle, after the conversion.

convertTo

public Angle convertTo(ArcUnits newUnits)
Converts this angle to the new units.

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

Parameters:
newUnits - the new units for this angle. If newUnits is null an IllegalArgumentException will be thrown.
Returns:
this angle. The reason for this return type is to allow code of this nature: BigDecimal radians = myAngle.convertTo(ArcUnits.RADIAN).getValue();

toUnits

public BigDecimal toUnits(ArcUnits otherUnits)
Returns the magnitude of this angle in otherUnits.

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

Parameters:
otherUnits - the units in which to express this angle's magnitude.
Returns:
this angle's value converted to otherUnits.

toDms

public Number[] toDms()
Returns a representation of this angle in degrees, minutes, and seconds.

Returns:
an array of size three in this order:
  1. An integral number of degrees.
  2. An integral number of arc minutes.
  3. A real number of arc seconds.

toHms

public Number[] toHms()
Returns a representation of this angle in hours, minutes, and seconds.

Returns:
an array of size three in this order:
  1. An integral number of hours.
  2. An integral number of minutes.
  3. A real number of seconds.

add

public Angle add(Angle other)
Adds the other angle to this one.

Parameters:
other - an angle to be added to this one.
Returns:
this angle, after the addition.

subtract

public Angle subtract(Angle other)
Subtracts the other angle from this one.

Parameters:
other - an angle to be subtracted from this one.
Returns:
this angle, after the subtraction.

add

public Angle add(BigDecimal amount)
Adds the amount, of the same units as this angle, to this angle.

Parameters:
amount - the amount to add to this angle.
Returns:
this angle, after the addition.

add

public Angle add(String amount)
Adds the amount, of the same units as this angle, to this angle.

Parameters:
amount - the amount to add to this angle.
Returns:
this angle, after the addition.

subtract

public Angle subtract(BigDecimal amount)
Subtracts the amount, of the same units as this angle, from this angle.

Parameters:
amount - the amount to subtract from this angle.
Returns:
this angle, after the subtraction.

subtract

public Angle subtract(String amount)
Subtracts the amount, of the same units as this angle, from this angle.

Parameters:
amount - the amount to subtract from this angle.
Returns:
this angle, after the subtraction.

multiplyBy

public Angle multiplyBy(BigDecimal multiplier)
Multiplies this angle by multiplier.

Parameters:
multiplier - the number by which this angle should be multiplied.
Returns:
this angle, after the multiplication.

multiplyBy

public Angle multiplyBy(String multiplier)
Multiplies this angle by multiplier.

Parameters:
multiplier - the number by which this angle should be multiplied.
Returns:
this angle, after the multiplication.

divideBy

public Angle divideBy(BigDecimal divisor)
Divides this angle by divisor.

Parameters:
divisor - the number by which this angle should be divided.
Returns:
this angle, after the division.

divideBy

public Angle divideBy(String divisor)
Divides this angle by divisor.

Parameters:
divisor - the number by which this angle should be divided.
Returns:
this angle, after the division.

cosine

public double cosine()
Returns the cosine of this angle.

Returns:
the cosine of this angle.

sine

public double sine()
Returns the sine of this angle.

Returns:
the sine of this angle.

tangent

public double tangent()
Returns the tangent of this angle.

Returns:
the tangent of this angle.

secant

public double secant()
Returns the secant of this angle.

Returns:
the secant of this angle.

cosecant

public double cosecant()
Returns the cosecant of this angle.

Returns:
the cosecant of this angle.

cotangent

public double cotangent()
Returns the cotangent of this angle.

Returns:
the cotangent of this angle.

arcCosine

public static Angle arcCosine(double cosine)
Returns a new angle whose cosine is cosine.

Parameters:
cosine - the value whose arc cosine is to be returned.
Returns:
a new angle whose cosine is cosine.

arcSine

public static Angle arcSine(double sine)
Returns a new angle whose sine is sine.

Parameters:
sine - the value whose arc sine is to be returned.
Returns:
a new angle whose sine is sine.

arcTangent

public static Angle arcTangent(double tangent)
Returns a new angle whose tangent is tangent.

Parameters:
tangent - the value whose arc tangent is to be returned.
Returns:
a new angle whose tangent is tangent.

parse

public static Angle parse(String angleString)
Returns a new angle based on angleString.

Valid Formats
Let I be the text representation of an integer.
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 degrees. Examples:

Format Two: wRwSw Format Three: wIwSwIwSwRwSw. The first S must be the symbol for either hours or degrees. The second S must be the symbol for either minutes or arc minutes. The final S must be the symbol for either seconds or arc seconds. This format has been updated so that only two of the three number/units pairs are required. For example, each of the following is valid:

Special Cases
An angleString of null or "" (the empty string) will not result in an IllegalArgumentException, but will instead return an angle of zero degrees.

Parameters:
angleString - a string that will be converted into an angle.
Throws:
IllegalArgumentException - if angleString is not in the expected form.

toString

public String toString()
Returns a text representation of this angle in its native units.

Overrides:
toString in class Object

toString

public String toString(int minFracDigits,
                       int maxFracDigits)
Returns a text representation of this angle in its native units.

toStringHtml

public String toStringHtml(int minFracDigits,
                           int maxFracDigits)
Returns a text representation of this angle in its native units, using an HTML-friendly symbol.

toStringHms

public String toStringHms()
Returns a text representation of this angle in hours, minutes, and seconds.

toStringHms

public String toStringHms(int minFracDigits,
                          int maxFracDigits)
Returns a text representation of this angle in hours, minutes, and seconds.

Parameters:
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. If this value is less than zero, no rounding or truncating will be performed.

toStringDms

public String toStringDms()
Returns a text representation of this angle in degrees, arc-minutes, and arc-seconds.

toStringDms

public String toStringDms(int minFracDigits,
                          int maxFracDigits)
Returns a text representation of this angle in degrees, arc-minutes, and arc-seconds.

Parameters:
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. If this value is less than zero, no rounding or truncating will be performed.

toStringDmsHtml

public String toStringDmsHtml(int minFracDigits,
                              int maxFracDigits)
Returns a text representation of this angle in degrees, arc-minutes, and arc-seconds, with HTML-friendly symbols.

Parameters:
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. If this value is less than zero, no rounding or truncating will be performed.

clone

public Angle clone()
Returns an angle 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 angle.

Overrides:
equals in class Object

hashCode

public int hashCode()
Returns a hash code value for this angle.

Overrides:
hashCode in class Object

compareTo

public int compareTo(Angle otherAngle)
Compares this angle with the otherAngle for order.

Specified by:
compareTo in interface Comparable<Angle>
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2009. All Rights Reserved.