edu.nrao.sss.measure
Class TimeDuration

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

All Implemented Interfaces:

Serializable, Cloneable, Comparable<TimeDuration>

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

A length of time without a defined starting or ending point. Contrast this with a TimeInterval, which is the span from one instant in time to another.

This duration currently works with only the following units:

• TimeUnits.NANOSECOND
• TimeUnits.MICROSECOND
• TimeUnits.MILLISECOND
• TimeUnits.SECOND
• TimeUnits.MINUTE
• TimeUnits.HOUR

This set of legal units is provided by getLegalUnits().

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

Author:

David M. Harland

See Also:

Serialized Form

Constructor Summary

TimeDuration()
Creates a new duration of zero hours.

TimeDuration(BigDecimal hours)
Creates a new duration of hours hours.

TimeDuration(BigDecimal value, TimeUnits units)
Creates a new duration of the given length.

TimeDuration(String hours)
Creates a new duration of hours hours.

TimeDuration(String value, TimeUnits units)
Creates a new duration of the given length.

Method Summary

TimeDuration	add(TimeDuration other) Adds the given time to this duration.
TimeDuration	clone() Returns a duration that is equal to this one.
int	compareTo(TimeDuration otherDur) Compares this duration with the otherDur for order.
TimeDuration	convertTo(TimeUnits newUnits) Converts this duration to the new units.
boolean	equals(Object o) Returns true if o is equal to this duration.
long	getIntegralPart(TimeUnits units) For a duration that is thought of as HH:MM:SS.xxx, returns the part corresponding to units, truncated to an integral value.
static Set<TimeUnits>	getLegalUnits() Returns a set of TimeUnits that are legal for use with TimeDuration instances.
BigDecimal	getPart(TimeUnits units) For a duration that is thought of as HH:MM:SS.xxx, returns the part corresponding to units.
TimeUnits	getUnits() Returns the units of this duration.
BigDecimal	getValue() Returns the length of this duration.
int	hashCode() Returns a hash code value for this duration.
boolean	isInDefaultState() Returns true if this duration is in its default state, no matter how it got there.
boolean	isInfinite() Returns true if this duration is infinite.
TimeDuration	multiplyBy(BigDecimal multiplier) Multiplies this duration by multiplier.
TimeDuration	multiplyBy(String multiplier) Multiplies this duration by multiplier.
TimeDuration	normalize() Converts the value and units of this time duration so that the value is normal.
static TimeDuration	parse(String timeText) Creates a time duration based on timeText.
static TimeDuration	parse(String timeText, BigDecimal secondsInOneDay) Creates a new time duration by parsing timeText.
void	reset() Resets this duration to its initial state.
void	set(BigDecimal value, TimeUnits units) Sets the length and units of this duration.
void	set(long hours, int minutes, BigDecimal seconds) Sets the length of this duration.
void	set(long hours, int minutes, String seconds) Sets the length of this duration.
void	set(String timeText) Sets the value and units of this duration based on timeText.
void	set(String value, TimeUnits units) Sets the length and units of this duration.
void	set(TimeDuration other) Sets this duration to be equal to other.
void	setUnits(TimeUnits newUnits) Sets the units of this duration to newUnits.
void	setValue(BigDecimal newValue) Sets the length of this duration to newValue.
void	setValue(String newValue) Sets the length of this duration to newValue.
TimeDuration	subtract(TimeDuration other) Subtracts other from this duration.
TimeInterval	toIntervalCenteredOn(Date center) Returns a time interval that is centered on center and lasts as long as this duration.
TimeInterval	toIntervalEndingOn(Date end) Returns a time interval that ends on end and lasts as long as this duration.
TimeInterval	toIntervalStartingOn(Date start) Returns a time interval that begins on start and lasts as long as this duration.
String	toString() Returns a text representation of this time duration.
String	toString(int minFracDigits, int maxFracDigits) Returns a text representation of this duration.
String	toString(String separator) Returns a string where the hours, minutes, and seconds are separated by the given string.
String	toString(String separator, int minFracDigits, int maxFracDigits) Returns a string where the hours, minutes, and seconds are separated by the given string.
String	toStringHms() Returns a text representation of this duration in hours, minutes, and seconds.
String	toStringHms(int minFracDigits, int maxFracDigits) Returns a text representation of this duration in hours, minutes, and seconds.
BigDecimal	toUnits(TimeUnits otherUnits) Returns the length of this duration in otherUnits.
long	toWholeUnits(TimeUnits otherUnits) Returns the length of this duration in a whole number of units.

Methods inherited from class java.lang.Object

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

Constructor Detail

TimeDuration

public TimeDuration()

Creates a new duration of zero hours.

TimeDuration

public TimeDuration(BigDecimal hours)

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

Parameters:

hours - the length of this duration in hours.

TimeDuration

public TimeDuration(String hours)

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

Parameters:

hours - the length of this duration in hours.

TimeDuration

public TimeDuration(BigDecimal value,
                    TimeUnits units)

Creates a new duration of the given length. See set(BigDecimal, TimeUnits) for information about valid parameter values and exceptions that might be thrown.

Parameters:

value - the length of this duration.

units - the units in which value is expressed. See the class comments for a list of legal values.

TimeDuration

public TimeDuration(String value,
                    TimeUnits units)

Creates a new duration of the given length. See set(String, TimeUnits) for information about valid parameter values and exceptions that might be thrown.

Parameters:

value - the length of this duration.

units - the units in which time is expressed. See the class comments for a list of legal values.

Method Detail

reset

public void reset()

Resets this duration to its initial state. A reset duration has the same state as a new duration created with the no-argument constructor.

getValue

public BigDecimal getValue()

Returns the length of this duration.

Returns:

the length of this duration.

getUnits

public TimeUnits getUnits()

Returns the units of this duration.

Returns:

the units of this duration.

set

public final void set(BigDecimal value,
                      TimeUnits units)

Sets the length and units of this duration.

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

Parameters:

value - the length of this duration.

units - the units in which value is expressed.

set

public final void set(String value,
                      TimeUnits units)

Sets the length and units of this duration.

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

Parameters:

value - the length of this duration.

units - the units in which time is expressed.

setValue

public final void setValue(BigDecimal newValue)

Sets the length of this duration to newValue.

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

Parameters:

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

Throws:

NumberFormatException - if newValue is null or negative.

setValue

public final void setValue(String newValue)

Sets the length of this duration to newValue.

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

Parameters:

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

Throws:

NumberFormatException - if newValue is null or negative.

setUnits

public final void setUnits(TimeUnits newUnits)

Sets the units of this duration to newUnits.

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

Parameters:

newUnits - the new units for this duration. See the class comments for a list of legal values.

Throws:

IllegalArgumentException - if the parameter is outside the described range.

set

public final void set(long hours,
                      int minutes,
                      BigDecimal seconds)

Sets the length of this duration.

While there are no restrictions on the values of the individual parameters, their combination must not result in a negative duration.

Throws:

IllegalArgumentException - if the combination of parameters results in a negative duration.

set

public final void set(long hours,
                      int minutes,
                      String seconds)

Sets the length of this duration.

While there are no restrictions on the values of the individual parameters, their combination must not result in a negative duration.

Throws:

IllegalArgumentException - if the combination of parameters results in a negative duration.

set

public void set(TimeDuration other)

Sets this duration to be equal to other.

The code:

   TimeDuration td = new TimeDuration().set(otherDuration);

gives the same result as:

   TimeDuration td = otherDuration.clone();

This method is better suited to those situations where the target duration has already been created.

Parameters:

other - the duration to which this duration will be made equal.

set

public void set(String timeText)

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

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

Parameters:

timeText - a string that will be converted into a time duration.

Throws:

IllegalArgumentException - if timeText is not in the expected form.

Since:

2008-10-01

isInDefaultState

public boolean isInDefaultState()

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

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

Returns:

true if this duration is in its default state.

isInfinite

public boolean isInfinite()

Returns true if this duration is infinite.

Returns:

true if this duration is infinite.

convertTo

public TimeDuration convertTo(TimeUnits newUnits)

Converts this duration to the new units.

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

Parameters:

newUnits - the new units for this duration. If newUnits is null an IllegalArgumentException will be thrown. See the class comments for a list of legal values.

Returns:

this duration. The reason for this return type is to allow code of this nature: BigDecimal hours = myDuration.convertTo(TimeUnits.HOUR).getValue();

Throws:

IllegalArgumentException - if the parameter is outside the described range.

toUnits

public BigDecimal toUnits(TimeUnits otherUnits)

Returns the length of this duration in otherUnits.

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

Example:
Let this duration be of length 2 hours 13 minutes 45.6789 seconds. The values returned by this method for the legal values of unit are (to 5 decimal places):

Units	Value
MILLISECOND	8,025,678.90000
SECOND	8,025.67890
MINUTE	133.76132
HOUR	2.22936

Contrast this with toWholeUnits(TimeUnits).

In addition to working with the legal time units described in the class comments, this method will also convert to:

• TimeUnits.DAY
• TimeUnits.YEAR

Parameters:

otherUnits - the units in which to express this duration's length. If newUnits is null, it will be treated as TimeUnits.HOUR. See the class comments for a list of legal values.

Returns:

this duration's value converted to otherUnits.

Throws:

IllegalArgumentException - if the parameter is outside the described range.

getLegalUnits

public static Set<TimeUnits> getLegalUnits()

Returns a set of TimeUnits that are legal for use with TimeDuration instances.

Returns:

a set of legal TimeUnits.

normalize

public TimeDuration normalize()

Converts the value and units of this time duration so that the value is normal. By "normal" we mean that it falls in the natural range for its units. For example, the natural range for MINUTES is deemed to be [1.0-60.0). For units that are smaller than one second, the natural range is [1.0-1000.0). Even after normalization the numeric value may be outside the natural range of its units if there were no smaller or larger legal units available.

Returns:

this duration, after normalization.

toWholeUnits

public long toWholeUnits(TimeUnits otherUnits)

Returns the length of this duration in a whole number of units.

Example:
Let this duration be of length 2 hours 13 minutes 45.6789 seconds. The values returned by this method for the legal values of unit are:

Units	Value
MILLISECOND	8,025,678
SECOND	8,025
MINUTE	133
HOUR	2

Contrast this with toUnits(TimeUnits).

Parameters:

otherUnits - the units of time in which the return value is expressed. See the class comments for a list of legal values.

Returns:

the length of this duration in a whole number of units.

Throws:

IllegalArgumentException - if the parameter is outside the described range.

getPart

public BigDecimal getPart(TimeUnits units)

For a duration that is thought of as HH:MM:SS.xxx, returns the part corresponding to units.

Range of Returned Value:
The value returned will be in its "natural" range. The table below gives the natural ranges for each unit. Note that since hours is the largest legal unit of time, it has no upper bound.

Units	Range
MICROSECOND	0 <= x < 1000
MILLISECOND	0 <= x < 1000
SECOND	0 <= x < 60
MINUTE	0 <= x < 60
HOUR	0 <= x

Example:
Let this duration be of length 2 hours 13 minutes 45.6789 seconds. The values returned by this method for the legal values of unit are (to 5 decimal places):

Units	Value
MILLISECOND	678.90000
SECOND	45.67890
MINUTE	13.76132
HOUR	2.22936

Parameters:

units - the units of time in which the return value is expressed. See the class comments for a list of legal values.

Returns:

the part of this duration corresponding to units.

Throws:

IllegalArgumentException - if the parameter is outside the described range.

See Also:

getIntegralPart(TimeUnits)

getIntegralPart

public long getIntegralPart(TimeUnits units)

For a duration that is thought of as HH:MM:SS.xxx, returns the part corresponding to units, truncated to an integral value.

Range of Returned Value:
The value returned will be in its "natural" range. The table below gives the natural ranges for each unit. Note that since hours is the largest legal unit of time, it has no upper bound.

Units	Range
MICROSECOND	0 <= x < 1000
MILLISECOND	0 <= x < 1000
SECOND	0 <= x < 60
MINUTE	0 <= x < 60
HOUR	0 <= x

Example:
Let this duration be of length 2 hours 13 minutes 45.6789 seconds. The values returned by this method for the legal values of unit are:

Units	Value
MILLISECOND	678
SECOND	45
MINUTE	13
HOUR	2

Parameters:

units - the units of time in which the return value is expressed. See the class comments for a list of legal values.

Returns:

the part of this duration corresponding to units.

Throws:

IllegalArgumentException - if the parameter is outside the described range.

See Also:

getPart(TimeUnits)

toIntervalStartingOn

public TimeInterval toIntervalStartingOn(Date start)

Returns a time interval that begins on start and lasts as long as this duration.

Parameters:

start - the starting time for the returned interval.

Returns:

an interval of time that begins on start and lasts as long as this duration.

toIntervalEndingOn

public TimeInterval toIntervalEndingOn(Date end)

Returns a time interval that ends on end and lasts as long as this duration.

Parameters:

end - the ending time for the returned interval.

Returns:

an interval of time that ends on end and lasts as long as this duration.

toIntervalCenteredOn

public TimeInterval toIntervalCenteredOn(Date center)

Returns a time interval that is centered on center and lasts as long as this duration.

If rounding prevents us from locating the endpoints the exact same distance from center, this method will have a bias toward creating an interval whose starting point is closer to center than its ending point.

Parameters:

center - the center time for the returned interval.

Returns:

an interval of time that is centered on center and lasts as long as this duration.

add

public TimeDuration add(TimeDuration other)

Adds the given time to this duration.

Parameters:

other - the duration to be added to this duration.

Returns:

this duration, after the addition.

subtract

public TimeDuration subtract(TimeDuration other)

Subtracts other from this duration. If the subtraction would result in a negative interval, this interval is set to a length of zero.

Parameters:

other - the amount by which to reduce this duration.

multiplyBy

public TimeDuration multiplyBy(String multiplier)

Multiplies this duration by multiplier.

Parameters:

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

Returns:

this duration, after the multiplication.

multiplyBy

public TimeDuration multiplyBy(BigDecimal multiplier)

Multiplies this duration by multiplier.

Parameters:

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

Returns:

this duration, after the multiplication.

toString

public String toString()

Returns a text representation of this time duration.

Overrides:

toString in class Object

toString

public String toString(int minFracDigits,
                       int maxFracDigits)

Returns a text representation of this duration.

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.

toStringHms

public String toStringHms()

Returns a text representation of this duration in hours, minutes, and seconds. The parts are separated by the colon (':') character.

toStringHms

public String toStringHms(int minFracDigits,
                          int maxFracDigits)

Returns a text representation of this duration in hours, minutes, and seconds. The parts are separated by the colon (':') character.

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.

toString

public String toString(String separator)

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

Parameters:

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

Returns:

a text representation of this duration.

toString

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

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

Parameters:

separator - the separator to use between the hours 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 duration.

parse

public static TimeDuration parse(String timeText)

Creates a time duration based on timeText.

The parsed text can be in many different forms. All of the forms supported by Longitude.parse(String) are supported here. Additionally, the form mm:ss.s (minutes and seconds) is supported. A naked number will be treated as a number of seconds.

Parameters:

timeText - the text to be parsed and converted into a time duration. If this value is null or "" (the empty string), a new duration of zero length is returned.

Returns:

a new time duration based on timeText.

Throws:

IllegalArgumentException - if timeText cannot be parsed.

parse

public static TimeDuration parse(String timeText,
                                 BigDecimal secondsInOneDay)

Creates a new time duration by parsing timeText. See parse(String) for the expected format of timeText.

Parameters:

timeText - the text to be parsed and converted into a time duration. If this value is null or "" (the empty string), a new duration of zero length is returned.

secondsInOneDay - the length of a day, in seconds. The TimeOfDay class has two constants that express time in SI seconds, TimeOfDay.STANDARD_DAY_LENGTH and TimeOfDay.SIDEREAL_DAY_LENGTH, that my be used here.

Returns:

a new time duration based on timeText.

Throws:

IllegalArgumentException - if timeText cannot be parsed.

clone

public TimeDuration clone()

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

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this duration.

Overrides:

hashCode in class Object

compareTo

public int compareTo(TimeDuration otherDur)

Compares this duration with the otherDur for order.

Specified by:

compareTo in interface Comparable<TimeDuration>