edu.nrao.sss.measure
Class TimeOfDay

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

All Implemented Interfaces:

Cloneable, Comparable<TimeOfDay>

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

A time of day.

This class represents the time of day in hours, minutes, and seconds, without regard to any particular date. The default length of a day is 24 hours, or 86,400 seconds. However, clients may create days whose lengths are equal to any positive number of seconds.

Rollover
Many operations on a time-of-day object can lead to a time that is less than zero or greater than the length of the day. These operations may choose not to raise an exception, but to instead roll past midnight in either direction. For example, using a 24-hour day, the add methods might take a time of 22:00:00 and an addend of 5 hours 43 minutes to give a new time of day of 03:43:00. In general, rollover is the preferred behavior for methods of this class.

Start of Day vs. End of Day
Related to rollover is the representation of an end-of-day time. If we use a 24-hour day, midnight can be represented by both 00:00:00.0 and 24:00:00.0. In general this class represents midnight only by 00:00:00.0. For example the following method call, myTime.set(24, 0, 0.0);, will result in a time of day that behaves as a beginning-of-day value, not as an end-of-day value. Likewise, any addition or subtraction that lands exactly on 24:00:00.0 will behave like 00:00:00.0.

There is, however, one way to set an end-of-day value, and that is by calling the setToEndOfDay method. After a call to this method, the time of day will act like an end-of-day value and will have a text representation of 24:00:00.0.

Version Info:

$Revision: 1707 $

$Date: 2008-11-14 10:23:59 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $

Since:

2006-07-27

Author:

David M. Harland

Field Summary

static BigDecimal	SIDEREAL_DAY_LENGTH The length of a sidereal day, in SI seconds.
static BigDecimal	STANDARD_DAY_LENGTH The popular notion that a day is 24 hours long.

Constructor Summary

TimeOfDay()
Creates instance whose length of day is the standard twenty four hours.

TimeOfDay(BigDecimal secondsInOneDay)
Creates instance whose length of day is given by secondsInDay.

Method Summary

TimeOfDay	add(BigDecimal value, TimeUnits units) Adds the given amount of time to this time of day.
TimeOfDay	add(String value, TimeUnits units) Adds the given amount of time to this time of day.
TimeOfDay	add(TimeDuration duration) Adds the given amount of time to this time of day.
TimeOfDay	clone() Returns a time of day that is equal to this one.
int	compareTo(TimeOfDay other) Compares this time of day to other for order.
boolean	equals(Object o) Returns true if o is equal to this time of day.
int	getHourOfDay() Returns the hour of the day.
TimeDuration	getLengthOfDay() Returns the length of day on which this time of day is based.
BigDecimal	getMilliOfSecond() Returns the number of milliseconds in this time of day's seconds.
int	getMinuteOfHour() Returns the minute of this time of day's hour.
BigDecimal	getSecondOfMinute() Returns the second of this time of day's minute.
int	getSecondOfMinuteWhole() Returns the whole number of seconds of this time of day's minute.
TimeDuration	getTimeSinceMidnight() Returns the amount of time that has elapsed from midnight until this time of day.
TimeDuration	getTimeUntilMidnight() Returns the amount of time that will elapse from this time of day until midnight.
int	hashCode() Returns a hash code value for this time of day.
boolean	isAfter(TimeOfDay other) Returns true if this time of day is later than other.
boolean	isBefore(TimeOfDay other) Returns true if this time of day is earlier than other.
boolean	isInDefaultState() Returns true if this time of day is in its default state, no matter how it got there.
static TimeOfDay	parse(String timeText) Creates a new time of day based on timeText.
static TimeOfDay	parse(String timeText, BigDecimal secondsInOneDay) Creates a new time of day by parsing timeText.
void	set(BigDecimal secondOfDay) Sets the time of day to the given seconds-of-day.
void	set(int hourOfDay, int minuteOfHour, BigDecimal secondOfMinute) Sets the time of day.
void	set(int hourOfDay, int minuteOfHour, String secondOfMinute) Sets the time of day.
void	set(String timeText) Sets the value and units of this time of day based on timeText.
void	setToEndOfDay() Sets this time of day to the end of the day.
TimeOfDay	subtract(BigDecimal value, TimeUnits units) Subtracts the given amount of time from this time of day.
TimeOfDay	subtract(String value, TimeUnits units) Subtracts the given amount of time from this time of day.
TimeOfDay	subtract(TimeDuration duration) Subtracts the given amount of time from this time of day.
TimeDuration	timeUntil(TimeOfDay other) Returns the amount of time until this time of day equals other.
Angle	toAngle() Creates an angular representation of this time of day.
BigDecimal	toFractionOfDay() Returns the time of day as a fraction of the length of day.
String	toString() Creates a text representation of this time of day.
String	toString(int minFracDigits, int maxFracDigits) Creates a text representation of this time of day.

Methods inherited from class java.lang.Object

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

Field Detail

STANDARD_DAY_LENGTH

public static final BigDecimal STANDARD_DAY_LENGTH

The popular notion that a day is 24 hours long. This corresponds to 86,400.0 SI seconds.

SIDEREAL_DAY_LENGTH

public static final BigDecimal SIDEREAL_DAY_LENGTH

The length of a sidereal day, in SI seconds. The is value is 86,164.0905382.

Constructor Detail

TimeOfDay

public TimeOfDay()

Creates instance whose length of day is the standard twenty four hours. The time of day is 00:00:00.0.

TimeOfDay

public TimeOfDay(BigDecimal secondsInOneDay)

Creates instance whose length of day is given by secondsInDay. The time of day is 00:00:00.0.

Parameters:

secondsInOneDay - the number of seconds in one day.

Method Detail

parse

public static TimeOfDay parse(String timeText)

Creates a new time of day based on timeText.

The parsed text can be in any of the forms supported by Longitude.parse(String). The most commonly used forms are hh:mm:ss.s and 99h 99m 99.9s.

Parameters:

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

Returns:

a new time of day based on timeText.

Throws:

IllegalArgumentException - if timeText cannot be parsed.

See Also:

parse(String, BigDecimal)

parse

public static TimeOfDay parse(String timeText,
                              BigDecimal secondsInOneDay)

Creates a new time of day by parsing timeText.

The parsed text can be in any of the forms supported by Longitude.parse(String). The most commonly used forms are hh:mm:ss.s and 99h 99m 99.9s.

Parameters:

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

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

Returns:

a new time of day based on timeText.

Throws:

IllegalArgumentException - if timeText cannot be parsed.

set

public void set(int hourOfDay,
                int minuteOfHour,
                BigDecimal secondOfMinute)

Sets the time of day.

While there are no restrictions on the values of the individual parameters, their combination must result in a positive finite number of seconds.

Parameters:

hourOfDay - meant to represent the hour of the day. Typically this is a value in the range [0,23].

minuteOfHour - meant to represent the minute of an hour. Typically this is a value in the range [0,59].

secondOfMinute - meant to represent the second of a minute. Typically this is a value in the range [0.0,60.0).

Throws:

IllegalArgumentException - if the number of seconds calculated from the parameters is negative, infinite, or not a number.

set

public void set(int hourOfDay,
                int minuteOfHour,
                String secondOfMinute)

Sets the time of day.

While there are no restrictions on the values of the individual parameters, their combination must result in a positive finite number of seconds.

Parameters:

hourOfDay - meant to represent the hour of the day. Typically this is a value in the range [0,23].

minuteOfHour - meant to represent the minute of an hour. Typically this is a value in the range [0,59].

secondOfMinute - meant to represent the second of a minute. Typically this is a value in the range [0.0,60.0).

Throws:

IllegalArgumentException - if the number of seconds calculated from the parameters is negative, infinite, or not a number.

set

public void set(BigDecimal secondOfDay)

Sets the time of day to the given seconds-of-day.

The secondOfDay parameter must be a non-negative finite value. If it is greater than the length of a day, it will be rolled passed as many midnights as it takes to make it less than the length of a day.

Parameters:

secondOfDay - the number of seconds that have elapsed since midnight to the desired time of day.

Throws:

IllegalArgumentException - if secondOfDay is negative, infinite, or not a number.

setToEndOfDay

public void setToEndOfDay()

Sets this time of day to the end of the day.

This end-of-day value can be reached in no other way. It can not be set by the other setters, and it can not be reached via addition or subtraction.

After this method has been called, this time of day behaves like an end-of-day value. All other values will be before, and less than, this value. Note that any non-negative increment to this time of day -- even an increment of zero -- will result in rollover.

set

public void set(String timeText)

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

If the parsing fails, this time of day will be kept in its current state.

Parameters:

timeText - a string that will be converted into a time of day.

Throws:

IllegalArgumentException - if timeText is not in the expected form.

getHourOfDay

public int getHourOfDay()

Returns the hour of the day. For example, if the time of day is 12:34:56.789, the value returned will be 12. Contrast this with the call:

   getTimeSinceMidnight().toUnits(TimeUnits.HOUR);

which would return 12.58244138888889.

Returns:

the hour of this time of day's day.

getMinuteOfHour

public int getMinuteOfHour()

Returns the minute of this time of day's hour. For example, if the time of day is 12:34:56.789, the value returned will be 34. Contrast this with the call:

   getTimeSinceMidnight().toUnits(TimeUnits.MINUTE);

which would return 754.9464833333333.

Returns:

the minute of this time of day's hour.

getSecondOfMinute

public BigDecimal getSecondOfMinute()

Returns the second of this time of day's minute. For example, if the time of day is 12:34:56.789, the value returned will be 56.789. Contrast this with the call:

   getTimeSinceMidnight().toUnits(TimeUnits.SECOND);

which would return 45,296.789, and to:

   getSecondOfMinuteWhole();

which would return 56;

Returns:

the second of this time of day's minute.

getSecondOfMinuteWhole

public int getSecondOfMinuteWhole()

Returns the whole number of seconds of this time of day's minute. For example, if the time of day is 12:34:56.789, the value returned will be 56. Contrast this with the call:

   getTimeSinceMidnight().toUnits(TimeUnits.SECOND);

which would return 45,296.789, and to:

   getSecondOfMinute();

which would return 56.789;

Returns:

the whole number of seconds in this time of day's minute.

Since:

2008-09-26

getMilliOfSecond

public BigDecimal getMilliOfSecond()

Returns the number of milliseconds in this time of day's seconds. For example, if the time of day is 12:34:56.7890123, the value returned will be 789.0123.

Returns:

the number of milliseconds in this time of day's seconds.

Since:

2008-09-26

getTimeSinceMidnight

public TimeDuration getTimeSinceMidnight()

Returns the amount of time that has elapsed from midnight until this time of day.

Returns:

the amount of time since the previous midnight.

getTimeUntilMidnight

public TimeDuration getTimeUntilMidnight()

Returns the amount of time that will elapse from this time of day until midnight.

Returns:

the amount of time until the next midnight.

isBefore

public boolean isBefore(TimeOfDay other)

Returns true if this time of day is earlier than other.

Parameters:

other - the time to be tested against this one.

Returns:

true if this time of day is earlier than other.

isAfter

public boolean isAfter(TimeOfDay other)

Returns true if this time of day is later than other.

Parameters:

other - the time to be tested against this one.

Returns:

true if this time of day is later than other.

isInDefaultState

public boolean isInDefaultState()

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

A time of day is in its default state if both its current time and the length of its day are the same as those of a time of day newly created via the no-argument constructor.

Returns:

true if this time of day is in its default state.

timeUntil

public TimeDuration timeUntil(TimeOfDay other)

Returns the amount of time until this time of day equals other.

If the other time of day is equal to this one, the duration returned will have a length of zero. If the other time is later than this one, the duration will be a simple subtraction of this from other. If the other time, though, is earlier than this one, the duration will represent the distance from this time, through midnight, to the other time traveling forward in time. That is, the direction of time is always from this one to the other, even if that represents a longer duration than traversing time in the opposite direction.

Note that the other time must have the same length of day as this one.

Parameters:

other - the time of day to be reached from this one.

Returns:

the duration from this time of day to other.

Throws:

IllegalArgumentException - if other's length of day is not equal to this object's length of day.

toFractionOfDay

public BigDecimal toFractionOfDay()

Returns the time of day as a fraction of the length of day. The length of day is set at the time this time of day is constructed.

Returns:

the fraction of the day that has passed from midnight to this time of day.

getLengthOfDay

public TimeDuration getLengthOfDay()

Returns the length of day on which this time of day is based.

Returns:

the length of day on which this time of day is based.

add

public TimeOfDay add(String value,
                     TimeUnits units)

Adds the given amount of time to this time of day. If the addition causes a time less than zero or greater than the last moment of the day, rollovers will occur until the result is a valid time of day.

Parameters:

value - an amount of time.

units - the units in which value is expressed.

Returns:

this time of day, after the addition has been performed.

Throws:

IllegalArgumentException - if value is infinite.

add

public TimeOfDay add(BigDecimal value,
                     TimeUnits units)

Adds the given amount of time to this time of day. If the addition causes a time less than zero or greater than the last moment of the day, rollovers will occur until the result is a valid time of day.

Parameters:

value - an amount of time.

units - the units in which value is expressed.

Returns:

this time of day, after the addition has been performed.

Throws:

IllegalArgumentException - if value is infinite.

add

public TimeOfDay add(TimeDuration duration)

Adds the given amount of time to this time of day. If the addition causes a time less than zero or greater than the last moment of the day, rollovers will occur until the result is a valid time of day.

Parameters:

duration - a length of time.

Returns:

this time of day, after the addition has been performed.

Throws:

IllegalArgumentException - if duration's value is infinite or NaN.

subtract

public TimeOfDay subtract(String value,
                          TimeUnits units)

Subtracts the given amount of time from this time of day. If the subtraction causes a time less than zero or greater than the last moment of the day, rollovers will occur until the result is a valid time of day.

Parameters:

value - an amount of time.

units - the units in which value is expressed.

Returns:

this time of day, after the subtraction has been performed.

Throws:

IllegalArgumentException - if value is infinite.

subtract

public TimeOfDay subtract(BigDecimal value,
                          TimeUnits units)

Subtracts the given amount of time from this time of day. If the subtraction causes a time less than zero or greater than the last moment of the day, rollovers will occur until the result is a valid time of day.

Parameters:

value - an amount of time.

units - the units in which value is expressed.

Returns:

this time of day, after the subtraction has been performed.

Throws:

IllegalArgumentException - if value is infinite.

subtract

public TimeOfDay subtract(TimeDuration duration)

Subtracts the given amount of time from this time of day. If the subtraction causes a time less than zero or greater than the last moment of the day, rollovers will occur until the result is a valid time of day.

Parameters:

duration - a length of time.

Returns:

this time of day, after the subtraction has been performed.

Throws:

IllegalArgumentException - if duration's value is infinite.

toAngle

public Angle toAngle()

Creates an angular representation of this time of day. The angle returned is based on the ratio of the time of day to the length of a day. The best way to understand this is to picture a round clock with a single hand and with the zero point, or start of the day, at the top. The angle made, in a clockwise direction, between the current position of the hand and the top of the clock is the value returned.

Returns:

this time of day, expressed as an angle.

toString

public String toString()

Creates a text representation of this time of day. The format of the returned string is H:M:S, where H, M, and S are as described in parse(String).

Overrides:

toString in class Object

See Also:

toString(int, int)

toString

public String toString(int minFracDigits,
                       int maxFracDigits)

Creates a text representation of this time of day. The format of the returned string is H:M:S, where H, M, and S are as described in parse(String).

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.

clone

public TimeOfDay clone()

Returns a time of day that is equal to this one.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this time of day.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this time of day.

Overrides:

hashCode in class Object

compareTo

public int compareTo(TimeOfDay other)

Compares this time of day to other for order.

One time is deemed to be "less than" the other if it is proportionately closer to the beginning of its day than the other.

Specified by:

compareTo in interface Comparable<TimeOfDay>

Parameters:

other - the time to which this one is compared.

Returns:

a negative integer, zero, or a positive integer as this time is less than, equal to, or greater than the other time.