| Overview | Package | Class | Use | Tree | Deprecated | Index | Help |
|
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectedu.nrao.sss.measure.FrequencyRange
public class FrequencyRange
A range of frequencies. The range is a closed interval; that is, both endpoints are themselves part of the range.
TODO: Discuss if that's a bad idea. It's often nice to have half-open intervals so that one can create multiple ranges that fit together perfectly w/ no overlap. On the other hand, if the normal usage pattern is not to set up these kinds of ranges, the closed interval can be more intuitive.
Jan 2007 Note: Now that we've added more methods to this class, the closed-interval choice seems less wise; half-open intervals lead to better algorithms. Eg, if you want the gap between the lower range [l1-h1] and the higher range [l2-h2], the natural gap range is [h1-l2]. If the range were half-open, we now have 3 contiguous, non-overlapping ranges. By keeping the range closed, we must either have overlap on the endpoints, or say that the gap-range is [(h1+epsilon)-(l2-epsilon)]. The main reason for having a closed interval was to allow someone to say "this receiver has a range from 40GHz to 50GHz", where "to" is usually intended to be "through".
Version Info:
| $Revision: 2295 $ |
| $Date: 2009-05-12 12:59:07 -0600 (Tue, 12 May 2009) $ |
| $Author: dharland $ |
| Constructor Summary | |
|---|---|
FrequencyRange()
Creates a new instance that contains all positive frequencies. |
|
FrequencyRange(Frequency center)
Creates a new frequency range with the given center and an extremely narrow width. |
|
FrequencyRange(Frequency frequency1,
Frequency frequency2)
Creates a new instance with the given endpoints. |
|
| Method Summary | |
|---|---|
FrequencyRange |
changeWidthTo(Frequency newWidth)
Changes the width of this range to newWidth. |
FrequencyRange |
clone()
Creates a copy of this frequency range. |
int |
compareTo(FrequencyRange other)
Compares this range to other for order. |
boolean |
contains(Frequency frequency)
Returns true if this range contains frequency. |
boolean |
contains(FrequencyRange other)
Returns true if this range contains other. |
FrequencyRange |
convertTo(FrequencyUnits newUnits)
Converts both endpoints of this range to the given units. |
boolean |
equals(Object o)
Returns true if o is equal to this frequency range. |
Frequency |
getCenterFrequency()
Returns the frequency that is midway between the endpoints of this range. |
List<FrequencyRange> |
getComplementIn(FrequencyRange other)
Returns zero, one, or two ranges that represent the portions of other that are not also found in this range. |
FrequencyRange |
getGapBetween(FrequencyRange other)
Returns a new range that represents the region of frequency space between this range and other. |
Frequency |
getHighFrequency()
Returns the high endpoint of this range. |
Frequency |
getLowFrequency()
Returns the low endpoint of this range. |
FrequencyRange |
getOverlapWith(FrequencyRange other)
Returns a new range that represents the region of overlap between this range and other. |
FrequencySpectrum |
getOverlapWith(FrequencySpectrum spectrum)
Returns a frequency spectrum that represents the overlap of this range with spectrum. |
Frequency |
getWidth()
Returns the width of this range. |
int |
hashCode()
Returns a hash code value for this frequency range. |
FrequencyRange |
intersectWith(FrequencyRange other)
Modifies this range to be the intersection of this range and other. |
boolean |
isContiguousWith(FrequencyRange other)
Returns true if this frequency range is contiguous with other. |
boolean |
isInDefaultState()
Returns true if this frequency range is in its default state, no matter how it got there. |
FrequencyRange |
mergeWith(FrequencyRange other)
Modifies this range to be the union of this range and other,
but only if the two ranges overlap or are contiguous. |
FrequencyRange |
moveCenterTo(Frequency newCenter)
Moves this range so that its new center frequency is newCenter. |
FrequencyRange |
multiplyBy(BigDecimal multiplier)
Multiplies the low and high frequencies of this range by multiplier. |
FrequencyRange |
multiplyBy(String multiplier)
Multiplies the low and high frequencies of this range by multiplier. |
FrequencyRange |
normalize()
Recasts each endpoint separately by calling its normalize method. |
boolean |
overlaps(FrequencyRange other)
Returns true if this frequency range overlaps with other. |
boolean |
overlaps(FrequencySpectrum spectrum)
Returns true if this range overlaps any of the covered ranges of spectrum. |
static FrequencyRange |
parse(String rangeText)
Creates and returns a new frequency range, based on rangeText
and a separator string of FormatString.ENDPOINT_SEPARATOR. |
static FrequencyRange |
parse(String rangeText,
String endPointSeparator)
Creates and returns a new frequency range, based on rangeText. |
void |
reset()
Resets this range so that it contains all positive frequencies. |
void |
set(Frequency frequency1,
Frequency frequency2)
Sets the frequencies of this range. |
void |
set(String rangeText)
Sets the endpoints of this range based on rangeText. |
FrequencyRange |
setCenterAndWidth(Frequency center,
Frequency width)
Sets the endpoints of this range based on the given center frequency and bandwidth. |
FrequencyRange |
shiftDownBy(Frequency shiftSize)
Moves both the low and high endpoints of this range down by shiftSize. |
FrequencyRange |
shiftUpBy(Frequency shiftSize)
Moves both the low and high endpoints of this range up by shiftSize. |
String |
toString()
Returns a text representation of this frequency range. |
String |
toString(boolean lowToHigh)
Returns a text representation of this frequency range. |
String |
toString(int minFracDigits,
int maxFracDigits)
Returns a text representation of this frequency range. |
String |
toString(int minFracDigits,
int maxFracDigits,
boolean lowToHigh)
Returns a text representation of this frequency range. |
| Methods inherited from class java.lang.Object |
|---|
finalize, getClass, notify, notifyAll, wait, wait, wait |
| Constructor Detail |
|---|
public FrequencyRange()
public FrequencyRange(Frequency frequency1,
Frequency frequency2)
This method will set the lower value of its range to the lesser of the two parameter values. If either parameter is null, it will be interpreted as a signal to create a new default frequency.
Note that this method makes copies of the parameters; it does not maintain a reference to either parameter. This is done in order to maintain the integrity of the relationship between the starting and ending points of this interval.
frequency1 - one endpoint of this range.frequency2 - the other endpoint of this range.public FrequencyRange(Frequency center)
center - the center of this frequency range.| Method Detail |
|---|
public void reset()
public final void set(Frequency frequency1,
Frequency frequency2)
This method will set the lower value of its range to the lesser of the two parameter values. If either parameter is null, it will be interpreted as a signal to create a new default frequency.
Note that this method makes copies of the parameters; it does not maintain a reference to either parameter. This is done in order to maintain the integrity of the relationship between the starting and ending points of this interval.
frequency1 - one endpoint of this range.frequency2 - the other endpoint of this range.public void set(String rangeText)
rangeText.
See parse(String) for the expected format of
rangeText.
If the parsing fails, this range will be kept in its current state.
rangeText - a string that will be converted into a frequency range.
IllegalArgumentException - if rangeText is not in the expected form.public Frequency getHighFrequency()
Note that the value returned is a copy of the one held internally by this range. This means that any changes made by a client to the returned frequency will not be reflected in this range.
public Frequency getLowFrequency()
Note that the value returned is a copy of the one held internally by this range. This means that any changes made by a client to the returned frequency will not be reflected in this range.
public Frequency getCenterFrequency()
The units for the returned frequency will be the same as those of the high frequency of this range.
public Frequency getWidth()
The units for the returned frequency will be the same as those of the high frequency of this range.
public boolean contains(Frequency frequency)
frequency.
frequency - the frequency to test for inclusion in this range.
frequency.
If frequency is null, the return value
will be false.Frequency.isEndPointOf(FrequencyRange)public boolean contains(FrequencyRange other)
other.
Range A is said to contain range B if A's low frequency is less than or equal to B's low frequency and A's high frequency is greater than or each to B's high frequency. Notice that this means that if A equals B, it also contains B.
other - the range to test for inclusion in this range.
other.
If other is null, the return value
will be false.public boolean overlaps(FrequencyRange other)
other.
Remember that this range is a closed interval, that is, one that
contains both of its endpoints.
If other is null, the return value is false.
other - another range that may overlap this one.
other.public boolean overlaps(FrequencySpectrum spectrum)
spectrum.
spectrum - the covered ranges of which are tested for overlap
with this range.
spectrum.public boolean isContiguousWith(FrequencyRange other)
other. Two ranges are contiguous if one's low frequency
is equal to the other's high frequency.
If other is null, the return value is false.
Note: we are using this definition even though this class currently defines the range as inclusive of both endpoints. So, at this time, continguous ranges technically overlap on their endpoints. If this class is changed to a half-open interval, the behavior of this method will not change.
other - another range that may be contiguous this one.
other.public FrequencySpectrum getOverlapWith(FrequencySpectrum spectrum)
spectrum. If spectrum is null, or has no
covered regions that overlap with this range, the returned spectrum
will have no covered ranges.
spectrum - the spectrum to check for covered ranges that overlap
with this range.
spectrum.public FrequencyRange getOverlapWith(FrequencyRange other)
other. If there is no overlap, null is returned.
See overlaps(FrequencyRange) for how the closed-interval
definition of this class impacts the results of this method.
other - another range that may overlap this one.
other.public FrequencyRange getGapBetween(FrequencyRange other)
other. If the other range is coincident with, or
overlaps, this range, null is returned. If the other range is
null, null is returned.
See overlaps(FrequencyRange) for how the closed-interval
definition of this class impacts the results of this method.
other - another range that might not overlap this one.
other.public List<FrequencyRange> getComplementIn(FrequencyRange other)
other - the provider of frequencies that are in the returned range
but not in this one.
public boolean isInDefaultState()
A frequency range is in its default state if both the values
and units for the low and high points are the same as those of a range
newly created via
the no-argument constructor.
A frequency range whose most recent update came via the
reset method is also in its default state.
public FrequencyRange convertTo(FrequencyUnits newUnits)
After this method is complete both endpoints of this range will have units
of units, and their values will have been converted
accordingly.
newUnits - the new units for the endpoints of this range.
If newUnits
is null, it will be treated as
FrequencyUnits.GIGAHERTZ.
public FrequencyRange normalize()
normalize method.
The one exception to the above process is when the low frequency
is zero and the high is not. In that case the low frequency
will be converted to the same units as the normalized high.
public FrequencyRange mergeWith(FrequencyRange other)
other,
but only if the two ranges overlap or are contiguous.
If the two ranges are disjoint, this range is unaltered.
other - the range to merge into this range.
other.public FrequencyRange intersectWith(FrequencyRange other)
other.
If this range does not intersect with other, it is modified
so that the value of both its low and high frequencies is zero, while
leaving their units unchanged.
other - the range to intersect with this one.
other.
public FrequencyRange setCenterAndWidth(Frequency center,
Frequency width)
center frequency.
If either parameter is null this method will take no action and this range will have the same state as immediately before the call.
If either center or width is infinite, this range will
be reset so that its low frequency has a value of zero and its high
frequency has an infinite value.
If neither of the two conditions above exist, an attempt will be made to honor the new center and width. However, if doing so would lead to a negative value for the low endpoint of this range, the width will be honored, but the center will not. The center would instead be a frequency equal to one half the width, as the low frequency would be zero and the high frequency equal to the width.
center - the new center frequency of this range.width - the new bandwidth of this range.
public FrequencyRange shiftDownBy(Frequency shiftSize)
shiftSize.
If shiftSize is null this method will take no action
and this range will have the same state as immediately before the call.
If the size of the shift is infinite, this range will be reset so that its both its low and high frequencies have a value of zero.
If neither of the two conditions above exist, an attempt will be made to honor the shift while leaving the width of this range unchanged. If, however, doing so would lead to a negative value for the low endpoint of this range, this range's width will be preserved and the value of the low frequency will be set to zero. In otherwords, this method will make the biggest legal shift that is less than or equal than the requested shift.
shiftSize - the amount by which to decrease both the high and
low frequencies of this range.
public FrequencyRange shiftUpBy(Frequency shiftSize)
shiftSize.
If shiftSize is null this method will take no action
and this range will have the same state as immediately before the call.
If the size of the shift is infinite, this range will
be reset so that its both its low and high frequencies have a value
of Double.POSITIVE_INFINITY.
If neither of the two conditions above exist, the requested shift will be made.
shiftSize - the amount by which to increase both the high and
low frequencies of this range.
public FrequencyRange multiplyBy(String multiplier)
multiplier.
multiplier - the number by which the end points of this range should be multiplied.
This value must not result in a frequency magnitude that is
negative.
ArithmeticException - if the multiplication results in a negative value for an end point, and
that end point is not allowed to be negative.
NullPointerException - if multiplier is null.public FrequencyRange multiplyBy(BigDecimal multiplier)
multiplier.
multiplier - the number by which the end points of this range should be multiplied.
This value must not result in a frequency magnitude that is
negative.
ArithmeticException - if the multiplication results in a negative value for an end point, and
that end point is not allowed to be negative.
NullPointerException - if multiplier is null.public FrequencyRange moveCenterTo(Frequency newCenter)
newCenter.
If newCenter is null this method will take no action
and this range will have the same state as immediately before the call.
If the new center is infinite, this range will
be reset so that its both its low and high frequencies have a value
of Double.POSITIVE_INFINITY.
If neither of the two conditions above exist, an attempt will be made
to honor the shift to the new center while leaving the width of this
range unchanged.
If, however, doing so would lead to
a negative value for the low endpoint of this range, this range's
width will be preserved and the value of the low frequency will be
set to zero. In otherwords, this method will make the biggest legal
shift that is less than or equal than the requested shift, and the
resulting center might not be equal to newCenter.
newCenter - the new center frequency of this range.
public FrequencyRange changeWidthTo(Frequency newWidth)
newWidth.
If newWidth is null this method will take no action
and this range will have the same state as immediately before the call.
If the new width is infinite, this range will be reset so that its low frequency has a value of zero and its high frequency has an infinite value.
If neither of the two conditions above exist, an attempt will be made to honor the new width while leaving the center frequency unchanged. However, if doing so would lead to a negative value for the low endpoint of this range, the new width will be honored, but the center will be altered. The new center will be a frequency equal to one half the width, as the low frequency would be zero and the high frequency equal to the width.
newWidth - the new bandwidth of this range.
public String toString()
toString in class Objectpublic String toString(boolean lowToHigh)
lowToHigh - if
public String toString(int minFracDigits,
int maxFracDigits)
minFracDigits - the minimum number of places after the decimal point.maxFracDigits - the maximum number of places after the decimal point.
public String toString(int minFracDigits,
int maxFracDigits,
boolean lowToHigh)
minFracDigits - the minimum number of places after the decimal point.maxFracDigits - the maximum number of places after the decimal point.lowToHigh - if public static FrequencyRange parse(String rangeText)
rangeText
and a separator string of FormatString.ENDPOINT_SEPARATOR.
See parse(String, String) for more details.
rangeText - text that represents a frequency range.
rangeText and a separator
string of FormatString.ENDPOINT_SEPARATOR.
public static FrequencyRange parse(String rangeText,
String endPointSeparator)
rangeText.
The general form rangeText is
frequencyOne
EndPointSeparator
frequencyTwo,
where frequencyOne and frequencyTwo follow the rules set
forth in Frequency.parse(String) and endPointSeparator
is text that does not collide with text that is normally found in
the frequency text. (That is, it would be unwise to use a number,
period, or any of the alpha characters that might be present in
the units portion of a frequency in the endpoint separator.
Typical separators might be " - " or ",".)
Note: using "-" (without spaces) as a separator will cause problems if either
endpoint is negative.
If rangeText is null or the empty string (""),
the returned range will be equal to one created via the no-argument
constructor.
rangeText - text that represents a frequency range.endPointSeparator - the text that separates one endpoint of the range
from the other.
rangeText.public FrequencyRange clone()
clone in class Objectpublic boolean equals(Object o)
o is equal to this frequency range.
equals in class Objectpublic int hashCode()
hashCode in class Objectpublic int compareTo(FrequencyRange other)
other for order.
One range is deemed to be "less than" the other if it begins before the other. In the case that two ranges start at the same point, the one with a lesser endpoint is considered to be less than the other.
compareTo in interface Comparable<FrequencyRange>other - the range to which this one is compared.
|
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||