com.programix.time
Class PlainDateRange

java.lang.Object
  com.programix.time.PlainDateRange

All Implemented Interfaces:

Serializable, Cloneable, Comparable

public final class PlainDateRange
extends Object
implements Serializable, Comparable, Cloneable

Immutable encapsulation of a period of time as expressed by a starting PlainDate and an ending PlainDate. Either the starting date or the ending date or both can be null. If you need a time span that also includes time-of-day and/or time zone information, see DateTimeRange.

The PlainDate class itself and the utility DateTools have handy utilities for formatting and parsing PlainDate instances to and from more human-readable Strings.

Author:

Paul Hyde

See Also:

PlainDate, DateTime, DateTimeRange, Serialized Form

Field Summary

static PlainDateRange	BOTH_OPEN This PlainDateRange has both an undefined start and an undefined end.
static Comparator	NEWEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "newest" or "most recent" first.
static Comparator	OLDEST_FIRST_COMPARATOR Compares two ranges placing ranges that are considered "oldest" first.
static PlainDate	OPEN This constant can be used to specify that either the start or end of of the range is "open" (that is, it is not defined and can be considered to stretch out to infinity).

Constructor Summary

PlainDateRange(PlainDate start, PlainDate end)
Creates a new instance with the specified start and end dates.

PlainDateRange(String start, String end)
Creates a new instance with the specified start and end dates.

PlainDateRange(Value start, Value end)
Creates a new instance with the specified start and end dates.

Method Summary

Object	clone() Simply returns a reference to this instance.
int	compareTo(Object otherRange) Used to meet the requirements of the Comparable interface.
int	compareTo(PlainDateRange otherRange) Compares this instance to otherRange as defined by OLDEST_FIRST_COMPARATOR.
boolean	contains(PlainDate plainDate) Returns true if the specified PlainDate falls within this range (inclusive of both endpoints).
static PlainDateRange	createWithOpenEnd(PlainDate start) Creates a new instance with an open end date and the specified start date.
static PlainDateRange	createWithOpenStart(PlainDate end) Creates a new instance with an open start and the specified end date.
boolean	equals(Object obj) Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance.
boolean	equals(PlainDateRange otherPlainDate) Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance.
PlainDate	forceIntoRange(PlainDate value) Forces the specified PlainDate into this range.
PlainDate	getEnd() Returns the end of this range.
String	getEndString() Returns the end of this range as a String in the ISO format yyyy-mm-dd.
Value	getEndValue() Returns the end of this range as a Value.
PlainDate	getStart() Returns the start of this range.
String	getStartString() Returns the start of this range as a String in the ISO format yyyy-mm-dd.
Value	getStartValue() Returns the start of this range as a Value.
boolean	hasDefinedEnd() Returns true if this range has a defined end date.
boolean	hasDefinedStart() Returns true if this range has a defined start date.
int	hashCode()
PlainDateRange	setEnd(PlainDate newEnd) Returns a new instance with the specified newEnd date and this instance's start date.
PlainDateRange	setEnd(String newEnd) Returns a new instance with the specified newEnd date and this instance's start date.
PlainDateRange	setEnd(Value newEnd) Returns a new instance with the specified newEnd date and this instance's start date.
PlainDateRange	setStart(PlainDate newStart) Returns a new instance with the specified newStart date and this instance's end date.
PlainDateRange	setStart(String newStart) Returns a new instance with the specified newStart date and this instance's end date.
PlainDateRange	setStart(Value newStart) Returns a new instance with the specified newStart date and this instance's end date.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

OPEN

public static final PlainDate OPEN

This constant can be used to specify that either the start or end of of the range is "open" (that is, it is not defined and can be considered to stretch out to infinity). A range with an open starting date would be considered to "have always been" or considered to have an "unknown beginning date". A range with an open end date would be considered to "be for all future time" or considered to have an "unknown ending date".

BOTH_OPEN

public static final PlainDateRange BOTH_OPEN

This PlainDateRange has both an undefined start and an undefined end. This is a shareable instance as all instances of PlainDateRange are immutable. In addition, there is no need to create any other instances that have both ends open (although is it permissible to create those instances).

OLDEST_FIRST_COMPARATOR

public static final Comparator OLDEST_FIRST_COMPARATOR

Compares two ranges placing ranges that are considered "oldest" first. Open start dates are considered to come before defined start dates. Open end dates are considered to come after defined end dates. The following are listed in the order that would result by using this Comparator:

    open    to 1997-02-02
    open    to 1997-09-09
    open    to 2000-02-02
    open    to 2000-03-03
    open    to    open
 1997-02-02 to 1997-02-02
 1997-02-03 to 1997-02-03
 1997-06-06 to 1997-09-09
 1997-06-06 to 1997-10-10
 1997-06-06 to    open
 1997-07-07 to 1997-08-08
 1997-08-08 to 1997-09-09
 1997-08-08 to    open
 1997-09-09 to    open     
 

Also see NEWEST_FIRST_COMPARATOR as it is not simply the reverse of this comparator.

For additional permutations, see NullFirstComparator, NullLastComparator, and ReverseComparator.

NEWEST_FIRST_COMPARATOR

public static final Comparator NEWEST_FIRST_COMPARATOR

Compares two ranges placing ranges that are considered "newest" or "most recent" first. Open end dates are considered to come before defined end dates. Open start dates are considered to come after defined start dates. The following are listed in the order that would result by using this Comparator:

 1997-09-09 to    open
 1997-08-08 to    open
 1997-06-06 to    open
    open    to    open
    open    to 2000-03-03
    open    to 2000-02-02
 1997-06-06 to 1997-10-10
 1997-08-08 to 1997-09-09
 1997-06-06 to 1997-09-09
    open    to 1997-09-09
 1997-07-07 to 1997-08-08
 1997-02-03 to 1997-02-03
 1997-02-02 to 1997-02-02
    open    to 1997-02-02
 

Also see OLDEST_FIRST_COMPARATOR as it is not simply the reverse of this comparator.

For additional permutations, see NullFirstComparator, NullLastComparator, and ReverseComparator.

Constructor Detail

PlainDateRange

public PlainDateRange(PlainDate start,
                      PlainDate end)
               throws IllegalArgumentException

Creates a new instance with the specified start and end dates. The constant OPEN (or null) can be used to indicate that one end or the other is open-ended. Both the start and the end can be open, and if you prefer, there is a shared, immutable instance that can be used instead: BOTH_OPEN.

Parameters:

start - the beginning of the date range. Use OPEN or null to indicate that the range is open-ended and has no starting date.

end - the ending of the date range. Use OPEN or null to indicate that the range is open-ended and has no end date.

Throws:

IllegalArgumentException - if the start date comes after the end date.

See Also:

PlainDateRange(Value, Value), PlainDateRange(String, String)

PlainDateRange

public PlainDateRange(String start,
                      String end)
               throws IllegalArgumentException

Creates a new instance with the specified start and end dates. You can use null or an empty string to indicate that one end or the other (or both) is open-ended.

Parameters:

start - the beginning of the date range. Use null or an empty string to indicate that the range is open-ended and has no starting date.

end - the ending of the date range. Use null or an empty string to indicate that the range is open-ended and has no end date.

Throws:

IllegalArgumentException - if the start date comes after the end date. Or, if one of the String's is not empty and can not be parsed as a PlainDate (see PlainDate.create(String)).

See Also:

PlainDateRange(PlainDate, PlainDate), PlainDateRange(Value, Value), PlainDate.create(String)

PlainDateRange

public PlainDateRange(Value start,
                      Value end)
               throws IllegalArgumentException

Creates a new instance with the specified start and end dates. You can use null for either parameter to indicate that one end or the other (or both) is open-ended. You can also use a Value who's isEmpty() method returns true to indicate that one end or the other (or both) is open-ended.

Parameters:

start - the beginning of the date range. Use null or an empty Value to indicate that the range is open-ended and has no starting date.

end - the ending of the date range. Use null or an empty Value to indicate that the range is open-ended and has no ending date.

Throws:

IllegalArgumentException - if the start date comes after the end date. Or, if one of the Value's is not empty and can not be parsed as a PlainDate (see Value.getPlainDateOrNull()).

See Also:

PlainDateRange(PlainDate, PlainDate), PlainDateRange(String, String), PlainDate.create(String)

Method Detail

createWithOpenStart

public static PlainDateRange createWithOpenStart(PlainDate end)

Creates a new instance with an open start and the specified end date.

Parameters:

end - the end of the date range.

createWithOpenEnd

public static PlainDateRange createWithOpenEnd(PlainDate start)

Creates a new instance with an open end date and the specified start date.

Parameters:

start - the start of the date range.

setStart

public PlainDateRange setStart(PlainDate newStart)
                        throws IllegalArgumentException

Returns a new instance with the specified newStart date and this instance's end date.

Parameters:

newStart - the new start date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end.

See Also:

PlainDateRange(PlainDate, PlainDate)

setStart

public PlainDateRange setStart(String newStart)
                        throws IllegalArgumentException

Returns a new instance with the specified newStart date and this instance's end date.

Parameters:

newStart - the new start date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if the start is not empty and can't be parsed.

See Also:

PlainDateRange(String, String)

setStart

public PlainDateRange setStart(Value newStart)
                        throws IllegalArgumentException

Returns a new instance with the specified newStart date and this instance's end date.

Parameters:

newStart - the new start date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if the start is not empty and can't be parsed.

See Also:

PlainDateRange(Value, Value)

setEnd

public PlainDateRange setEnd(PlainDate newEnd)
                      throws IllegalArgumentException

Returns a new instance with the specified newEnd date and this instance's start date.

Parameters:

newEnd - the new end date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end.

See Also:

PlainDateRange(PlainDate, PlainDate)

setEnd

public PlainDateRange setEnd(String newEnd)
                      throws IllegalArgumentException

Returns a new instance with the specified newEnd date and this instance's start date.

Parameters:

newEnd - the new end date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if the end is not empty and can't be parsed.

See Also:

PlainDateRange(String, String)

setEnd

public PlainDateRange setEnd(Value newEnd)
                      throws IllegalArgumentException

Returns a new instance with the specified newEnd date and this instance's start date.

Parameters:

newEnd - the new end date for the new instance or null.

Returns:

the new range derived from this one.

Throws:

IllegalArgumentException - if the start comes after the end or if the end is not empty and can't be parsed.

See Also:

PlainDateRange(Value, Value)

hasDefinedStart

public boolean hasDefinedStart()

Returns true if this range has a defined start date. If no start is defined, then this range is open-ended and false is returned.

See Also:

getStart()

getStart

public PlainDate getStart()

Returns the start of this range. If no starting date was specified, then this range is open-ended and OPEN (null) is returned.

See Also:

hasDefinedStart(), getStartString(), getStartValue()

getStartString

public String getStartString()

Returns the start of this range as a String in the ISO format yyyy-mm-dd. If no starting date was specified, then this range is open-ended and null is returned.

See Also:

hasDefinedStart(), getStart(), getStartValue()

getStartValue

public Value getStartValue()

Returns the start of this range as a Value. If no starting date was specified, then this range is open-ended and an empty Value is returned. Unlike most of the other getters, a Value is always returned—null is never returned.

See Also:

hasDefinedStart(), getStart(), getStartString()

hasDefinedEnd

public boolean hasDefinedEnd()

Returns true if this range has a defined end date. If no end is defined, then this range is open-ended and false is returned.

See Also:

getEnd()

getEnd

public PlainDate getEnd()

Returns the end of this range. If no ending date was specified, then this range is open-ended and OPEN (null) is returned.

See Also:

hasDefinedEnd()

getEndString

public String getEndString()

Returns the end of this range as a String in the ISO format yyyy-mm-dd. If no ending date was specified, then this range is open-ended and null is returned.

See Also:

hasDefinedEnd(), getEnd(), getEndValue()

getEndValue

public Value getEndValue()

Returns the end of this range as a Value. If no ending date was specified, then this range is open-ended and an empty Value is returned. Unlike most of the other getters, a Value is always returned—null is never returned.

See Also:

hasDefinedEnd(), getEnd(), getEndString()

contains

public boolean contains(PlainDate plainDate)

Returns true if the specified PlainDate falls within this range (inclusive of both endpoints). If null is passed in, then false is always returned (regardless of the values of either endpoint). If this instance has a defined start, but an unknown end, then true is returned if the passed date is equal to or comes after the start. If this instance has a defined end, but an unknown start, then true is returned if the passed date is equal to or comes before the end. If this instance has both ends open and the passed parameter is not null, then true is returned.

forceIntoRange

public PlainDate forceIntoRange(PlainDate value)
                         throws IllegalArgumentException

Forces the specified PlainDate into this range. If the specified date is contained with this range (see contains(PlainDate)), then the passed date is simply returned (no forcing is necessary). If the range has a defined start and the specified date comes before that start, then the start is returned. If the range has a defined end and the specified date comes after that end, then the end is returned.

Parameters:

value - the date to force into this range.

Returns:

a date that is within this range.

Throws:

IllegalArgumentException - if the specified date is null.

compareTo

public int compareTo(PlainDateRange otherRange)
              throws IllegalArgumentException

Compares this instance to otherRange as defined by OLDEST_FIRST_COMPARATOR.

Throws:

IllegalArgumentException - if null if passed.

compareTo

public int compareTo(Object otherRange)

Used to meet the requirements of the Comparable interface. Simply casts the passed value and calls compareTo(PlainDateRange). If a type other than PlainDate is passed in, a ClassCastException is thrown.

Specified by:

compareTo in interface Comparable

equals

public boolean equals(PlainDateRange otherPlainDate)

Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance. If null is passed, false is returned.

equals

public boolean equals(Object obj)

Returns true if this instance's start and end dates exactly match the start and end dates of the passed instance. If null is passed, false is returned. If a type other than PlainDateRange is passed in, false is returned (ClassCastException is not thrown).

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

clone

public Object clone()

Simply returns a reference to this instance. No need to actually clone since objects of this type are immutable.

Overrides:

clone in class Object