edu.nrao.sss.measure
Class Frequency

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

All Implemented Interfaces:

Cloneable, Comparable<Frequency>

public class Frequency
extends Object
implements Cloneable, Comparable<Frequency>

A measure of frequency.

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-03

Author:

David M. Harland

Constructor Summary

Frequency()
Creates a new frequency of zero gigahertz.

Frequency(BigDecimal gigahertz)
Creates a new frequency of gigahertz gigahertz.

Frequency(BigDecimal magnitude, FrequencyUnits units)
Creates a new frequency with the given magnitude and units.

Frequency(String gigahertz)
Creates a new frequency of gigahertz gigahertz.

Frequency(String magnitude, FrequencyUnits units)
Creates a new frequency with the given magnitude and units.

Method Summary

Frequency	add(Frequency other) Adds other frequency to this one.
Frequency	clone() Returns a frequency that is equal to this one.
int	compareTo(Frequency otherFreq) Compares this frequency with the otherFreq for order.
Frequency	convertTo(FrequencyUnits newUnits) Converts this measure of frequency to the new units.
Frequency	divideBy(BigDecimal divisor) Divides this frequency by divisor.
Frequency	divideBy(String divisor) Divides this frequency by divisor.
BigDecimal	dividedBy(Frequency other) Returns the result of dividing this frequency by other, without altering this frequency.
boolean	equals(Object o) Returns true if o is equal to this frequency.
Frequency	getAbsoluteDistanceFrom(FrequencyRange range) Returns the smallest positive difference between this frequency and range.
FrequencyUnits	getUnits() Returns the units of this frequency.
BigDecimal	getValue() Returns the magnitude of this frequency.
int	hashCode() Returns a hash code value for this frequency.
boolean	isEndPointOf(FrequencyRange range) Returns true if this frequency is equal to either the low or high frequency of range.
boolean	isInDefaultState() Returns true if this frequency is in its default state, no matter how it got there.
boolean	isInfinite() Returns true if the magnitude of this frequency approaches infinity.
Wave	makeWave() Creates and returns a new wave with the speed of light and this frequency.
Wave	makeWave(LinearVelocity speedOfWave) Creates and returns a new wave with the given speed and this frequency.
Frequency	multiplyBy(BigDecimal multiplier) Multiplies this frequency by multiplier.
Frequency	multiplyBy(String multiplier) Multiplies this frequency by multiplier.
Frequency	normalize() Converts the value and units of this frequency so that the value is between one and one thousand.
static Frequency	parse(String frequencyString) Returns a new frequency based on frequencyString.
void	reset() Resets this frequency so that it is equal to a frequency created via the no-argument constructor.
void	set(BigDecimal value, FrequencyUnits units) Sets the magnitude and units of this frequency.
void	set(String frequencyText) Sets the value and units of this frequency based on frequencyText.
void	set(String value, FrequencyUnits units) Sets the magnitude and units of this frequency.
void	setAllowNegativeValues(boolean allow) Configure this frequency so that it allows, or disallows, negative values.
void	setUnits(FrequencyUnits newUnits) Sets the units of this frequency to newUnits.
void	setValue(BigDecimal newValue) Sets the magnitude of this frequency to newValue.
void	setValue(String newValue) Sets the magnitude of this frequency to newValue.
Frequency	subtract(Frequency other) Subtracts other frequency from this one.
String	toString() Returns a text representation of this frequency.
String	toString(int minFracDigits, int maxFracDigits) Returns a text representation of this frequency.
String	toStringNormalized(int minFracDigits, int maxFracDigits) Returns a text representation of a normalized representation of this frequency.
BigDecimal	toUnits(FrequencyUnits otherUnits) Returns the magnitude of this frequency in otherUnits.

Methods inherited from class java.lang.Object

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

Constructor Detail

Frequency

public Frequency()

Creates a new frequency of zero gigahertz.

Frequency

public Frequency(BigDecimal gigahertz)

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

Frequency

public Frequency(String gigahertz)

Creates a new frequency of gigahertz gigahertz. See setValue(String) for information about valid parameter values and exceptions that might be thrown.

Frequency

public Frequency(BigDecimal magnitude,
                 FrequencyUnits units)

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

Frequency

public Frequency(String magnitude,
                 FrequencyUnits units)

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

Method Detail

reset

public void reset()

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

getValue

public BigDecimal getValue()

Returns the magnitude of this frequency.

Returns:

the magnitude of this frequency.

getUnits

public FrequencyUnits getUnits()

Returns the units of this frequency.

Returns:

the units of this frequency.

set

public void set(String frequencyText)

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

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

Parameters:

frequencyText - a string that will be converted into a frequency.

Throws:

IllegalArgumentException - if frequencyText is not in the expected form.

set

public final void set(BigDecimal value,
                      FrequencyUnits units)

Sets the magnitude and units of this frequency.

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

Parameters:

value - the new magnitude for this frequency.

units - the new units for this frequency.

set

public final void set(String value,
                      FrequencyUnits units)

Sets the magnitude and units of this frequency.

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

Parameters:

value - the new magnitude for this frequency.

units - the new units for this frequency.

setValue

public final void setValue(BigDecimal newValue)

Sets the magnitude of this frequency to newValue.

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

Parameters:

newValue - the new magnitude for this frequency. This value is normally be zero or positive, but negative values will be accepted if the user has specifically allowed negative values by calling setAllowNegativeValues(boolean). It is permissible for this value to be infinite, but it may not be null.

Throws:

NumberFormatException - if newValue is null, or if it is negative and negative values have not been expressly allowed.

setValue

public final void setValue(String newValue)

Sets the magnitude of this frequency to newValue.

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

Parameters:

newValue - the new magnitude for this frequency. This value is normally zero or positive, but negative values will be accepted if the user has specifically allowed negative values by calling allowNegativeValues. It is permissible for this value to be infinite, but it may not be NaN. The allowable representations of infinity are "infinity", "+infinity", and "-infinity"; these values are not case sensitive.

Throws:

NumberFormatException - if newValue is null, NaN, or if it is negative and negative values have not been expressly allowed.

setUnits

public final void setUnits(FrequencyUnits newUnits)

Sets the units of this frequency to newUnits.

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

Parameters:

newUnits - the new units for this frequency. If newUnits is null it will be treated as FrequencyUnits.GIGAHERTZ.

setAllowNegativeValues

public void setAllowNegativeValues(boolean allow)

Configure this frequency so that it allows, or disallows, negative values. By default negative values are not allowed.

Parameters:

allow - true if this frequency should be allowed to hold negative values.

Throws:

IllegalStateException - if allow is false and this frequency is currently negative.

isInDefaultState

public boolean isInDefaultState()

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

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

Returns:

true if this frequency is in its default state.

isInfinite

public boolean isInfinite()

Returns true if the magnitude of this frequency approaches infinity.

Returns:

true if the magnitude of this frequency approaches infinity.

isEndPointOf

public boolean isEndPointOf(FrequencyRange range)

Returns true if this frequency is equal to either the low or high frequency of range.

Parameters:

range - a frequency range that may or may not have a low or high frequency equal to this one.

Returns:

true if this frequency is one of the endpoints of range.

Since:

2008-10-14

convertTo

public Frequency convertTo(FrequencyUnits newUnits)

Converts this measure of frequency to the new units.

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

Parameters:

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

Returns:

this frequency. The reason for this return type is to allow code of this nature: BigDecimal gigahertz = myFrequency.convertTo(FrequencyUnits.GIGAHERTZ).getValue();

toUnits

public BigDecimal toUnits(FrequencyUnits otherUnits)

Returns the magnitude of this frequency in otherUnits.

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

Parameters:

otherUnits - the units in which to express this frequency's magnitude. If newUnits is null, it will be treated as FrequencyUnits.GIGAHERTZ.

Returns:

this frequency's value converted to otherUnits.

normalize

public Frequency normalize()

Converts the value and units of this frequency so that the value is between one and one thousand. The units will be 10^x Hertz, where x is evenly divisible by three. The value might not fall in the range [1.0-1000.0) if the units are the smallest or largest available.

If this frequency is exactly zero, the default units, as opposed to the smallest units, will be used.

Returns:

this frequency, after normalization.

add

public Frequency add(Frequency other)

Adds other frequency to this one.

If all of the items below are true:

1. this frequency is positive
2. other is negative
3. the magnitude of other is greater than the magnitude of this frequency
4. this frequency does not allow negative values

the result of this operation will be a frequency of zero. Otherwise the result will be the sum of the two frequencies.

Parameters:

other - the frequency to be added to this frequency.

Returns:

this frequency, after the addition.

subtract

public Frequency subtract(Frequency other)

Subtracts other frequency from this one.

If the result of the subtraction is negative, and if this frequency does not allow negative values, the result of this operation will be a frequency of zero.

Parameters:

other - the frequency to be subtracted from this frequency.

Returns:

this frequency, after the subtraction.

multiplyBy

public Frequency multiplyBy(String multiplier)

Multiplies this frequency by multiplier.

Parameters:

multiplier - the number by which this frequency should be multiplied. This value must not result in a frequency magnitude that is negative or NaN.

Returns:

this frequency, after the multiplication.

Throws:

ArithmeticException - if the multiplication results in a negative value and this frequency is not allowed to be negative.

NumberFormatException - if multiplier is NaN or is otherwise rejected by the BigDecimal class.

NullPointerException - if multiplier is null.

multiplyBy

public Frequency multiplyBy(BigDecimal multiplier)

Multiplies this frequency by multiplier.

Parameters:

multiplier - the number by which this frequency should be multiplied. This value must not result in a frequency magnitude that is negative.

Returns:

this frequency, after the multiplication.

Throws:

ArithmeticException - if the multiplication results in a negative value and this frequency is not allowed to be negative.

NullPointerException - if multiplier is null.

divideBy

public Frequency divideBy(String divisor)

Divides this frequency by divisor.

Parameters:

divisor - the number by which this frequency should be divided. This value must not result in a frequency magnitude that is negative or NaN.

Returns:

this frequency, after the division.

Throws:

ArithmeticException - if the division results in a negative value and this frequency is not allowed to be negative, or if the divisor is zero.

NumberFormatException - if divisor is null, NaN, or is otherwise rejected by the BigDecimal class.

See Also:

dividedBy(Frequency)

divideBy

public Frequency divideBy(BigDecimal divisor)

Divides this frequency by divisor.

Parameters:

divisor - the number by which this frequency should be divided. This value must not result in a frequency magnitude that is negative or NaN.

Returns:

this frequency, after the division.

Throws:

ArithmeticException - if the division results in a negative value and this frequency is not allowed to be negative, or if the divisor is zero.

NumberFormatException - if divisor is null.

dividedBy

public BigDecimal dividedBy(Frequency other)

Returns the result of dividing this frequency by other, without altering this frequency.

Parameters:

other - the frequency by which this one is divided. This parameter is the denominator in the equation quotient = dividend / divisor, this frequency is the numerator, and the quotient is the value returned.

Returns:

the result of dividing this frequency by other.

See Also:

divideBy(BigDecimal), divideBy(String)

getAbsoluteDistanceFrom

public Frequency getAbsoluteDistanceFrom(FrequencyRange range)

Returns the smallest positive difference between this frequency and range.

Parameters:

range - the range to which a distance is computed.

Returns:

the smallest positive difference between this frequency and range. If range is null, null is returned. If range contains this frequency, a frequency of zero hertz is returned.

makeWave

public Wave makeWave()

Creates and returns a new wave with the speed of light and this frequency.

Returns:

a new wave with the speed of light and this frequency.

makeWave

public Wave makeWave(LinearVelocity speedOfWave)

Creates and returns a new wave with the given speed and this frequency.

Parameters:

speedOfWave - the speed of the returned wave.

Returns:

a new wave with the given speed and this frequency.

parse

public static Frequency parse(String frequencyString)

Returns a new frequency based on frequencyString.

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 hertz.

Format Two: wRwSw.

Parameters:

frequencyString - a string that will be converted into a frequency. In addition to the valid formats listed above, this parameter may use the special values "infinity", "+infinity", and "-infinity", with or without units, and without regard to case.

Returns:

a new frequency.

Throws:

IllegalArgumentException - if frequencyString is not in the expected form.

toString

public String toString()

Returns a text representation of this frequency.

Overrides:

toString in class Object

toString

public String toString(int minFracDigits,
                       int maxFracDigits)

Returns a text representation of this frequency.

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 frequency.

toStringNormalized

public String toStringNormalized(int minFracDigits,
                                 int maxFracDigits)

Returns a text representation of a normalized representation of this frequency. This method does not modify this frequency; specifically, it does not normalize this frequency. (See normalize() for the definition of "normalized".)

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 frequency.

clone

public Frequency clone()

Returns a frequency 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 frequency.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this frequency.

Overrides:

hashCode in class Object

compareTo

public int compareTo(Frequency otherFreq)

Compares this frequency with the otherFreq for order.

Specified by:

compareTo in interface Comparable<Frequency>