edu.nrao.sss.measure
Class TimeOfDayInterval

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

All Implemented Interfaces:

Cloneable

public class TimeOfDayInterval
extends Object
implements Cloneable

An interval from one time of day to another. The two times of day are assumed to be either in the same day or consecutive days.

There are two endpoints to an interval. In most intervals, the starting endpoint is less than the ending endpoint. However, time of day is best viewed as a circle (like a clock). This means that the starting point could be numerically larger than the ending point. Nonetheless, the interval always proceeds from the starting point to the ending point. In order to make this traversal, it sometimes happens that the reset, or midnight, time is crossed.

This interval is a half-open interval. That is, the interval includes the starting point but not the ending point.

Caveat
July 2006. It might be that some of the query methods that compare one interval to another, or to a point, are not accurate for the degenerate case where one or both intervals have zero length. This possibility will be tested, and corrected, in the future. --DMH

Version Info:

$Revision: 1708 $

$Date: 2008-11-14 10:31:42 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $

Since:

2006-07-27

Author:

David M. Harland

Constructor Summary

TimeOfDayInterval()
Creates a new interval equal to a full day, where the length of the day is a standard 24-hour day.

TimeOfDayInterval(TimeOfDay from, TimeOfDay to)
Creates a new interval using the given times of day.

Method Summary

TimeOfDayInterval	clone() Returns an interval that is equal to this one.
boolean	contains(TimeOfDay time) Returns true if time is contained in this interval.
boolean	contains(TimeOfDayInterval other) Returns true if this interval contains other.
boolean	equals(Object o) Returns true if o is equal to this interval.
TimeOfDay	getCenterTime() Returns the time of day that is midway between the endpoints of this interval.
TimeDuration	getDuration() Returns the time duration represented by this interval.
TimeOfDay	getEnd() Returns this interval's ending time of day.
TimeOfDay	getStart() Returns this interval's starting time of day.
int	hashCode() Returns a hash code value for this interval.
boolean	isAfter(TimeOfDay time) Returns true if this interval starts after the given time.
boolean	isAfter(TimeOfDayInterval other) Returns true if this interval starts after the other one ends.
boolean	isBefore(TimeOfDay time) Returns true if this interval ends before the given time.
boolean	isBefore(TimeOfDayInterval other) Returns true if this interval ends before the other one starts.
boolean	isContainedBy(TimeOfDayInterval other) Returns true if the other interval contains this one.
boolean	isContiguousWith(TimeOfDayInterval other) Returns true if this interval and the other form a contiguous non-overlapping time interval.
boolean	isInDefaultState() Returns true if this interval is in its default state, no matter how it got there.
boolean	overlaps(TimeOfDayInterval other) Returns true if this interval overlaps the other interval.
static TimeOfDayInterval	parse(String intervalText) Creates a new time of day interval by parsing intervalText.
static TimeOfDayInterval	parse(String intervalText, String endPointSeparator) Creates a new time of day interval by parsing intervalText.
void	reset() Resets this interval to its default state.
void	set(String intervalText) Sets the endpoints of this interval based on intervalText.
void	set(String intervalText, String separator) Sets the endpoints of this interval based on intervalText.
void	set(TimeOfDay from, TimeOfDay to) Sets the starting and ending points of this interval.
TimeOfDayInterval[]	split(TimeOfDay pointOfSplit) Returns two new intervals that were formed by splitting this one at the given point.
TimeOfDayInterval[]	splitAtMidnight() Returns two new intervals that were formed by splitting this one at midnight.
void	switchEndpoints() Exchanges the starting and ending points of this interval.
TimeOfDayInterval	toComplement() Creates a new interval whose starting point is this interval's ending point and whose ending point is this interval's starting point.
String	toString() Returns a string representation of this interval.
String	toString(String endPointSeparator) Returns a string representation of this interval.

Methods inherited from class java.lang.Object

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

Constructor Detail

TimeOfDayInterval

public TimeOfDayInterval()

Creates a new interval equal to a full day, where the length of the day is a standard 24-hour day.

TimeOfDayInterval

public TimeOfDayInterval(TimeOfDay from,
                         TimeOfDay to)

Creates a new interval using the given times of day.

The description of the set(TimeOfDay, TimeOfDay) method applies to this constructor as well.

Parameters:

from - the starting point of this interval. The starting point is included in the interval.

to - the ending point of this interval. The ending point is not included in the interval.

Method Detail

reset

public void reset()

Resets this interval to its default state.

A reset interval has the same state as one newly created by the no-argument constructor. Specifically, it has a length of a standard 24-hour day.

set

public void set(TimeOfDay from,
                TimeOfDay to)

Sets the starting and ending points of this interval.

It is acceptable for then starting time of day to be later than the ending time of day. The interval still starts at from; it is just that, in order to reach through, it must cross the midnight point.

If either parameter is null, an IllegalArgumentException will be thrown.

This class will maintain references to from and through; it will not make copies. This means that any changes made by clients to the parameter objects after calling this method will be reflected in this object.

Parameters:

from - the starting point of this interval. The starting point is included in the interval.

to - the ending point of this interval. The ending point is not included in the interval.

set

public void set(String intervalText,
                String separator)

Sets the endpoints of this interval based on intervalText. If intervalText is null or "" (the empty string), the reset() method is called. Otherwise, the parsing is delegated to parse(String, String). See that method for details related to parsing.

set

public void set(String intervalText)

Sets the endpoints of this interval based on intervalText. This is an convenience method equivalent to calling set(intervalText, FormatString.ISO8601_TIME_INTERVAL_SEPARATOR).

switchEndpoints

public void switchEndpoints()

Exchanges the starting and ending points of this interval.

toComplement

public TimeOfDayInterval toComplement()

Creates a new interval whose starting point is this interval's ending point and whose ending point is this interval's starting point.

Returns:

a new interval with endpoints opposite to those of this interval.

split

public TimeOfDayInterval[] split(TimeOfDay pointOfSplit)

Returns two new intervals that were formed by splitting this one at the given point. This interval is not altered by this method.

Scenario One. If this interval contains pointOfSplit, then the first interval in the array runs from this interval's starting point to pointOfSplit, and the second interval runs from pointOfSplit to this interval's ending point.

Scenario Two. If this interval does not contain pointOfSplit, then the first interval in the array will be equal to this one, and the second interval will be a zero length interval whose starting and ending endpoints are both pointOfSplit.

Parameters:

pointOfSplit - the point at which to split this interval in two.

Returns:

an array of two intervals whose combined length equals this interval's length.

splitAtMidnight

public TimeOfDayInterval[] splitAtMidnight()

Returns two new intervals that were formed by splitting this one at midnight. This interval is not altered by this method.

See split(TimeOfDay) for details about the splitting. This method behaves similarly to calling that method with a time of day equal to midnight. The one difference is that, if this interval contains midnight, the first interval in the returned array will have its endpoint set to TimeOfDay.setToEndOfDay().

Returns:

an array of two intervals whose combined length equals this interval's length.

getStart

public TimeOfDay getStart()

Returns this interval's starting time of day. Note that the start time is included in this interval.

The returned time of day, which is guaranteed to be non-null, is the actual time held by this interval, so changes made to it will be reflected in this object.

Returns:

this interval's starting time.

See Also:

set(TimeOfDay, TimeOfDay)

getEnd

public TimeOfDay getEnd()

Returns this interval's ending time of day. Note that the end time is not included in this interval.

The returned time of day, which is guaranteed to be non-null, is the actual time held by this interval, so changes made to it will be reflected in this object.

Returns:

this interval's ending time.

See Also:

set(TimeOfDay, TimeOfDay)

getCenterTime

public TimeOfDay getCenterTime()

Returns the time of day that is midway between the endpoints of this interval.

Understand that while the returned value will always be between the endpoints (or coincident with them, if they are identical), the center may be numerically smaller than the starting point of this interval. For example, if this interval starts at 23:00:00.0 and ends at 09:00:00.0, the duration of this interval is ten hours and the center is at 04:00:00.0, which is a smaller value than that of -- but not "before" -- the starting point.

Returns:

the center of this interval.

getDuration

public TimeDuration getDuration()

Returns the time duration represented by this interval.

Returns:

the time duration represented by this interval.

contains

public boolean contains(TimeOfDay time)

Returns true if time is contained in this interval.

Note that this interval is half-open; it includes the starting point, but not the ending point.

ISSUE: Right now we allow the starting and ending points to be coincident, result in an interval of zero duration. One could argue that this is a point, not an interval. If the starting point is in the interval, but the ending point is not, what is the situation for a time, T, that is both the starting and ending point? Is it, or is it not, in the interval? Right now this class says it is not. One could argue that we should not allow the starting and ending points to be coincident. When we resolve the issue, we will update this class's documentation.

Parameters:

time - the time to be tested for containment.

Returns:

true if time is contained in this interval.

contains

public boolean contains(TimeOfDayInterval other)

Returns true if this interval contains other.

Note that an interval that is equal to this one is not contained by this one. The best analogy is that of a rigid box with infinitely thin walls: a box that is exactly the same as another cannot fit inside it.

Parameters:

other - an interval that might be contained by this one.

Returns:

true if this interval contains other.

isContainedBy

public boolean isContainedBy(TimeOfDayInterval other)

Returns true if the other interval contains this one.

See contains(TimeOfDayInterval) for the definition of containment.

Parameters:

other - an interval that might contain this one.

Returns:

true if the other interval contains this one.

isBefore

public boolean isBefore(TimeOfDayInterval other)

Returns true if this interval ends before the other one starts.

Parameters:

other - an interval that might come after this one.

Returns:

true if this interval ends before other starts.

isAfter

public boolean isAfter(TimeOfDayInterval other)

Returns true if this interval starts after the other one ends.

Parameters:

other - an interval that might come after this one.

Returns:

true if this interval starts after other ends.

isBefore

public boolean isBefore(TimeOfDay time)

Returns true if this interval ends before the given time.

Parameters:

time - a time of day that might come after this interval.

Returns:

true if this interval ends before the given time.

isAfter

public boolean isAfter(TimeOfDay time)

Returns true if this interval starts after the given time.

Parameters:

time - a time of day that might come after this interval.

Returns:

true if this interval starts after the given time.

isContiguousWith

public boolean isContiguousWith(TimeOfDayInterval other)

Returns true if this interval and the other form a contiguous non-overlapping time interval. Since a time interval is half open, this method returns true when either this interval starts at the same time the other one ends, or ends at the same time the other starts.

Parameters:

other - an interval that might be contiguous with this one.

Returns:

true if this interval and the other form a contiguous non-overlapping time interval.

overlaps

public boolean overlaps(TimeOfDayInterval other)

Returns true if this interval overlaps the other interval.

Note that equal intervals overlap, as do intervals that have a container-contained relationship.

Parameters:

other - an interval that might overlap this one.

Returns:

true if this interval overlaps the other interval.

isInDefaultState

public boolean isInDefaultState()

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

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

Returns:

true if this interval is in its default state.

toString

public String toString()

Returns a string representation of this interval. The separator of the endpoints FormatString.ISO8601_TIME_INTERVAL_SEPARATOR.

Overrides:

toString in class Object

Returns:

a string representation of this interval.

toString

public String toString(String endPointSeparator)

Returns a string representation of this interval. See the toString method in TimeOfDay for information about how the endpoints are formatted. The endPointSeparator is used to separate the two endpoints in the returned string.

Parameters:

endPointSeparator - text that separates one endpoint from another in the returned string. Using a null or empty-string value here is a bad idea.

Returns:

a string representation of this interval.

parse

public static TimeOfDayInterval parse(String intervalText)

Creates a new time of day interval by parsing intervalText.

This is a convenience method that is equivalent to:

   parse(intervalText, FormatString.ISO8601_TIME_INTERVAL_SEPARATOR);

That is, the string separating the two endpoints is assumed to be FormatString.ISO8601_TIME_INTERVAL_SEPARATOR.

Parameters:

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

Returns:

a new time interval based on iso8601Interval. If iso8601Interval is null or "" (the empty string), a new time interval of length zero is returned.

Throws:

IllegalArgumentException - if intervalText cannot be parsed.

parse

public static TimeOfDayInterval parse(String intervalText,
                                      String endPointSeparator)

Creates a new time of day interval by parsing intervalText. The general form of intervalText is StartTimeOfDaySeparatorEndTimeOfDay, with the particulars of the time of day format described by the TimeOfDay.parse(String) method of TimeOfDay.

Parameters:

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

endPointSeparator - the text that separates the starting time of day from the ending time of day in intervalText.

Returns:

a new time of day interval based on intervalText.

Throws:

IllegalArgumentException - if intervalText cannot be parsed using endPointSeparator.

clone

public TimeOfDayInterval clone()

Returns an interval 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 interval.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this interval.

Overrides:

hashCode in class Object