com.programix.time
Class PlainDate

java.lang.Object
  com.programix.time.PlainDate

All Implemented Interfaces:

Serializable, Cloneable, Comparable<PlainDate>

public final class PlainDate
extends Object
implements Comparable<PlainDate>, Serializable, Cloneable

This class represents a simple calendar date without any time components and without any sense of a time zone. It holds a year, month, and day.

PlainDate v. DateTime
The DateTime class has some of the same uses as a PlainDate but DateTime represents a moment in time as the number of milliseconds since January 1, 1970 began in UTC (see the "Time Information" section in DateTools for links to all kinds of information about dates and times and time zones). To interpret a DateTime as a year, month, and day, a time zone must be supplied to properly calculate what day it is (even what month or what year it is!). For example, consider it to be 12:30AM on January 1, 2007 [2007-01-01 00:30] in New York City. That same moment in time is interpreted as 11:30PM on December 31, 2006 [2006-12-31 11:30] in Minneapolis, Minnesota. That's a different day, a different month, and even a different year! Clearly the time zone used to interpret a DateTime is critical.

The PlainDate class has some of the same uses as a DateTime but PlainDate represents a year, month, and day without regard to any time zone. Also, PlainDate does not contain any time of day information (like hours, minutes, seconds, etc.).

This class uses the Immutability pattern. That is, instances are not changeable after construction.

Author:

Paul Hyde

See Also:

DateTime, PlainDateRange, DateTimeRange, DateTools, Serialized Form

Method Summary

PlainDate	addDays(int offset) Returns a new PlainDate offset from this instance by the specified number of days.
PlainDate	addDaysUntil(DayOfWeek targetDayOfWeek) Adds days (as needed) to roll this PlainDate forward until the specified targetDayOfWeek is matched.
PlainDate	addMonths(int offset) Returns a new PlainDate offset from this instance by the specified number of months.
PlainDate	addWeeks(int offset) Returns a new PlainDate offset from this instance by the specified number of weeks.
PlainDate	addYears(int offset) Returns a new PlainDate offset from this instance by the specified number of years.
boolean	after(PlainDate otherPlainDate) Returns true if the this instance's date comes after the date passed as a parameter.
boolean	afterOrEqualTo(PlainDate otherPlainDate) Returns true if the this instance's date comes after or is the same as the date passed as a parameter.
boolean	before(PlainDate otherPlainDate) Returns true if the this instance's date comes before the date passed as a parameter.
boolean	beforeOrEqualTo(PlainDate otherPlainDate) Returns true if the this instance's date comes before or is the same as the date passed as a parameter.
Object	clone() Simply returns this instance as instances are immutable and our flyweight pattern keeps there from being more than one instance for the same year, month, and day.
int	compareTo(PlainDate otherPlainDate) Returns -1 if this instance's date comes before the passed date, 0 if they are the same, and -1 if the passed date comes after.
static PlainDate	create(int year, int month, int day) Returns an instance of PlainDate for the specified year, month, and day.
static PlainDate	create(String dateStr) Creates an instance by parsing the passed String into a year, month, and day according to the specification stated below.
static PlainDate	createToday(TimeZone tz) Creates an instance for today in the specified time zone.
static PlainDate	createTodayLocal() Creates an instance for today in the local VM time zone.
static PlainDate	createTodayUTC() Creates an instance for today in the UTC time zone.
static PlainDate	createTomorrow(TimeZone tz) Creates an instance for tomorrow in the specified time zone.
static PlainDate	createTomorrowLocal() Creates an instance for tomorrow in the local VM time zone.
static PlainDate	createTomorrowUTC() Creates an instance for tomorrow in the UTC time zone.
static PlainDate	createYesterday(TimeZone tz) Creates an instance for yesterday in the specified time zone.
static PlainDate	createYesterdayLocal() Creates an instance for yesterday in the local VM time zone.
static PlainDate	createYesterdayUTC() Creates an instance for yesterday in the UTC time zone.
boolean	equals(Object other)
boolean	equals(PlainDate other)
String	formatMdy() Returns this date in a mmddyyyy format.
String	formatMdyDash() Returns this date in a mm-dd-yyyy format.
String	formatMdyDot() Returns this date in a mm.dd.yyyy format.
String	formatMdySlash() Returns this date in a mm/dd/yyyy format.
String	formatYmd() Returns this date in a yyyymmdd format.
String	formatYmdDash() Returns this date in a yyyy-mm-dd format.
String	formatYmdDot() Returns this date in a yyyy.mm.dd format.
String	formatYmdSlash() Returns this date in a yyyy/mm/dd format.
int	getDay() Returns the day as a int in the range 1..31 (as appropriate for the specific month).
DayOfWeek	getDayOfWeek() Returns the DayOfWeek for this date.
String	getDayStr() Returns the day as a 2-digit string.
PlainDate	getFirstDayOfCurrentMonth() Returns a new PlainDate for the first day of the month for this instance's year and month.
PlainDate	getLastDayOfCurrentMonth() Returns a new PlainDate for the last day of the month for this instance's year and month.
int	getMonth() Returns the month as a int in the range 1..12
String	getMonthStr() Returns the month as a 2-digit string.
int	getYear() Returns the four-digit year as an int.
int	getYearsBefore(PlainDate otherPlainDate) Returns the integer number of years that this date is before the specified otherPlainDate.
String	getYearStr() Returns the year as a 4-digit string.
int	hashCode()
PlainDate	subtractDaysUntil(DayOfWeek targetDayOfWeek) Subtracts days (as needed) to roll this PlainDate backward until the specified targetDayOfWeek is matched.
DateTime	toDateTime(TimeZone tz) Converts this PlainDate into a DateTime using noon for the time of day and using the specified timezone.
DateTime	toDateTimeLocal() Converts this PlainDate into a DateTime using noon for the time of day and using the local Java VM's timezone.
DateTime	toDateTimeUTC() Converts this PlainDate into a DateTime using noon for the time of day and using the UTC timezone.
String	toString() Returns the date in the ISO format: yyyy-mm-dd.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static PlainDate create(int year,
                               int month,
                               int day)
                        throws PlainDateException

Returns an instance of PlainDate for the specified year, month, and day. If the combination of year, month, and day is not valid, then an exception is thrown (see DateTools.isValidDate(int, int, int)).

Parameters:

year - the four digit year, for example 2006.

month - the month number, from the set [1..12].

day - the day of the month, from the set [1..31].

Throws:

PlainDateException - if the specified year, month, and day do not produce a valid combination.

create

public static PlainDate create(String dateStr)
                        throws PlainDateException

Creates an instance by parsing the passed String into a year, month, and day according to the specification stated below. Also see parsePlainDate() method on DateTools.

Ideal Format:

 yyyy-mm-dd
 yyyy/mm/dd
 yyyy.mm.dd
 yyyymmdd
 

Also accepted is the format commonly used in the USA:

 mm-dd-yyyy
 mm/dd/yyyy
 mm.dd.yyyy
 mmddyyyy
 

Examples of source strings and the date that they imply:

Source (String)	Result (PlainDate)	Comments
"2005-02-14"	2005-02-14	Ideal format
"20050214"	2005-02-14	No delimiters
"2005/02/14"	2005-02-14	Slash date delimiter
"2005.02.14"	2005-02-14	Dot date delimiter
"2005#02#14"	2005-02-14	Crazy date delimiter
"2005/5/6"	2005-05-06	Slash with single digits
"2005-5-6"	2005-05-06	Dash with single digits
"2005.5.6"	2005-05-06	Dot with single digits
"2005^5^6"	2005-05-06	Crazy with single digits
"02-14"	2006-02-14	Default to current year (2006)
"02/14"	2006-02-14	Default to current year (2006)
"02.14"	2006-02-14	Default to current year (2006)
"0214"	2006-02-14	Default to current year (2006)
"2.14"	2006-02-14	Default to current year (2006)
"0405"	2006-04-05	Default to current year (2006)
"4/5"	2006-04-05	Default to current year (2006)
"02-14-2005"	2005-02-14	MDY (USA) format
"02142005"	2005-02-14	MDY (USA) format, no delimiters
"02/14/2005"	2005-02-14	MDY (USA) with slash date delimiter
"02.14.2005"	2005-02-14	MDY (USA) with dot date delimiter
"5/6/2005"	2005-05-06	MDY (USA) with slash with single digits
"5-6-2005"	2005-05-06	MDY (USA) with dash with single digits
"5.6.2005"	2005-05-06	MDY (USA) with dot with single digits

Parameters:

dateStr - formatted source to parse. Examples that work are: "2006-01-31", "20060131", "01/31/2006", "01312006", "0131" (defaults to the current year), and many more.

Throws:

PlainDateException - if the passed string can not be interpreted or if it represents an invalid date like 13-99-2005.

createToday

public static PlainDate createToday(TimeZone tz)

Creates an instance for today in the specified time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the specified time zone.

createTodayLocal

public static PlainDate createTodayLocal()

Creates an instance for today in the local VM time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the local time zone.

createTodayUTC

public static PlainDate createTodayUTC()

Creates an instance for today in the UTC time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the UTC time zone.

createYesterday

public static PlainDate createYesterday(TimeZone tz)

Creates an instance for yesterday in the specified time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the specified time zone.

createYesterdayLocal

public static PlainDate createYesterdayLocal()

Creates an instance for yesterday in the local VM time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the local time zone.

createYesterdayUTC

public static PlainDate createYesterdayUTC()

Creates an instance for yesterday in the UTC time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the UTC time zone.

createTomorrow

public static PlainDate createTomorrow(TimeZone tz)

Creates an instance for tomorrow in the specified time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the specified time zone.

createTomorrowLocal

public static PlainDate createTomorrowLocal()

Creates an instance for tomorrow in the local VM time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the local time zone.

createTomorrowUTC

public static PlainDate createTomorrowUTC()

Creates an instance for tomorrow in the UTC time zone. The moment in time is retrieved from DateTools.getTime() and then the year, month, and day are derived using the UTC time zone.

getYear

public int getYear()

Returns the four-digit year as an int.

getMonth

public int getMonth()

Returns the month as a int in the range 1..12

getDay

public int getDay()

Returns the day as a int in the range 1..31 (as appropriate for the specific month).

getDayOfWeek

public DayOfWeek getDayOfWeek()

Returns the DayOfWeek for this date.

getYearStr

public String getYearStr()

Returns the year as a 4-digit string. For example: 1996, 2000, 2004.

getMonthStr

public String getMonthStr()

Returns the month as a 2-digit string. For example: 01, 09, 12.

getDayStr

public String getDayStr()

Returns the day as a 2-digit string. For example: 01, 05, 10, 29, 31.

formatYmdDash

public String formatYmdDash()

Returns this date in a yyyy-mm-dd format.

formatYmdSlash

public String formatYmdSlash()

Returns this date in a yyyy/mm/dd format.

formatYmdDot

public String formatYmdDot()

Returns this date in a yyyy.mm.dd format.

formatYmd

public String formatYmd()

Returns this date in a yyyymmdd format.

formatMdyDash

public String formatMdyDash()

Returns this date in a mm-dd-yyyy format.

formatMdySlash

public String formatMdySlash()

Returns this date in a mm/dd/yyyy format.

formatMdyDot

public String formatMdyDot()

Returns this date in a mm.dd.yyyy format.

formatMdy

public String formatMdy()

Returns this date in a mmddyyyy format.

toDateTime

public DateTime toDateTime(TimeZone tz)

Converts this PlainDate into a DateTime using noon for the time of day and using the specified timezone. This PlainDate's year, month, and day are combined with 12 for the hour of the day and a DateTime instance is created interpreting those values in the specified timezone tz.

Parameters:

tz - the timezone to use to determine the moment.

toDateTimeLocal

public DateTime toDateTimeLocal()

Converts this PlainDate into a DateTime using noon for the time of day and using the local Java VM's timezone. This PlainDate's year, month, and day are combined with 12 for the hour of the day and a DateTime instance is created interpreting those values in the local time zone.

toDateTimeUTC

public DateTime toDateTimeUTC()

Converts this PlainDate into a DateTime using noon for the time of day and using the UTC timezone. This PlainDate's year, month, and day are combined with 12 for the hour of the day and a DateTime instance is created interpreting those values in the UTC time zone.

getFirstDayOfCurrentMonth

public PlainDate getFirstDayOfCurrentMonth()

Returns a new PlainDate for the first day of the month for this instance's year and month.

getLastDayOfCurrentMonth

public PlainDate getLastDayOfCurrentMonth()

Returns a new PlainDate for the last day of the month for this instance's year and month.

addDays

public PlainDate addDays(int offset)

Returns a new PlainDate offset from this instance by the specified number of days. See DateTools.addDays(PlainDate, int) for more detail.

Parameters:

offset - the number of days to add (can be a negative number to go backwards in time).

addWeeks

public PlainDate addWeeks(int offset)

Returns a new PlainDate offset from this instance by the specified number of weeks. See DateTools.addWeeks(PlainDate, int) for more detail.

Parameters:

offset - the number of weeks to add (can be a negative number to go backwards in time).

addMonths

public PlainDate addMonths(int offset)

Returns a new PlainDate offset from this instance by the specified number of months. See DateTools.addMonths(PlainDate, int) for more detail.

Parameters:

offset - the number of months to add (can be a negative number to go backwards in time).

addYears

public PlainDate addYears(int offset)

Returns a new PlainDate offset from this instance by the specified number of years. See DateTools.addYears(PlainDate, int) for more detail.

Parameters:

offset - the number of years to add (can be a negative number to go backwards in time).

addDaysUntil

public PlainDate addDaysUntil(DayOfWeek targetDayOfWeek)

Adds days (as needed) to roll this PlainDate forward until the specified targetDayOfWeek is matched. The number of days added ranges from 0 up to a maximum of 6. If the day of the week for this PlainDate is already the specified target day of the week, then this PlainDate is simply returned (no change).

To find the first Monday in September 2007 (the answer is 2007-09-03):

 PlainDate firstMondayInSeptember =
     PlainDate.create("2007-09-01").addDaysUntil(DayOfWeek.MONDAY);
 

To find the first Monday in October 2007 (the starting date 2007-10-01 is actually the answer [no days need to be added]):

 PlainDate firstMondayInOctober =
     PlainDate.create("2007-10-01").addDaysUntil(DayOfWeek.MONDAY);
 

To find the first Wednesday in a month that an arbitrary date belongs to (in this case the month is June 2007, and we start from the 18th and go back to the first and then forward—if necessary—to find Wednesday. In this case, the answer is 2007-06-06):

 PlainDate randomDayInJune = PlainDate.create("2007-06-18");
 PlainDate firstWednesdayInJune =
     randomDayInJune.getFirstDayOfCurrentMonth().addDaysUntil(
         DayOfWeek.WEDNESDAY);
 

The next example takes an arbitrary date (in this case 2007-05-08) and locates all of the occurrences of a particular day of the week (in this case Thursday) in that date's month (May 2007). The resulting dates printed are the five Thursdays that occur in May 2007: 2007-05-03, 2007-05-10, 2007-05-17, 2007-05-24, and 2007-05-31.

 PlainDate startDate = PlainDate.create("2007-05-08");
 DayOfWeek targetDayOfWeek = DayOfWeek.THURSDAY;

 PlainDate currDate =
     startDate.getFirstDayOfCurrentMonth().addDaysUntil(
         targetDayOfWeek);

 while ( currDate.getMonth() == startDate.getMonth() ) {
     System.out.println("currDate=" + currDate);
     currDate = currDate.addDays(1).addDaysUntil(targetDayOfWeek);
 }
 

Parameters:

targetDayOfWeek - the desired day of the week

Returns:

a new PlainDate whose day of the week matches the specified target day of the week. If this PlainDate's day of the week was already a match for the target, then this instance is simply returned.

See Also:

subtractDaysUntil(DayOfWeek), DateTools.addDaysUntil(PlainDate, DayOfWeek)

subtractDaysUntil

public PlainDate subtractDaysUntil(DayOfWeek targetDayOfWeek)

Subtracts days (as needed) to roll this PlainDate backward until the specified targetDayOfWeek is matched. The number of days subtracted ranges from 0 up to a maximum of 6. If the day of the week for this PlainDate is already the specified target day of the week, then this PlainDate is simply returned (no change).

To find the last Friday in July 2007 (the answer is 2007-07-27):

 PlainDate randomDayInJuly = PlainDate.create("2007-07-04");
 PlainDate lastFridayInJuly =
     randomDayInJuly.getLastDayOfCurrentMonth().subtractDaysUntil(
         DayOfWeek.FRIDAY);
 

Parameters:

targetDayOfWeek - the desired day of the week

Returns:

a new PlainDate whose day of the week matches the specified target day of the week. If this PlainDate's day of the week was already a match for the target, then this instance is simply returned.

See Also:

addDaysUntil(DayOfWeek), DateTools.subtractDaysUntil(PlainDate, DayOfWeek)

getYearsBefore

public int getYearsBefore(PlainDate otherPlainDate)

Returns the integer number of years that this date is before the specified otherPlainDate. If this date is after the specified date, then a negative number is returned.

To figure out how old someone is from a date of birth, you can use code like this:

 PlainDate dateOfBirth = PlainDate.create("2001-06-15");
 int age = dateOfBirth.getYearsBefore(PlainDate.createTodayLocal());
 

Parameters:

otherPlainDate - the date to measure to

toString

public String toString()

Returns the date in the ISO format: yyyy-mm-dd.

Overrides:

toString in class Object

equals

public boolean equals(PlainDate other)

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(PlainDate otherPlainDate)
              throws IllegalArgumentException

Returns -1 if this instance's date comes before the passed date, 0 if they are the same, and -1 if the passed date comes after.

Specified by:

compareTo in interface Comparable<PlainDate>

Throws:

IllegalArgumentException - if null if passed.

before

public boolean before(PlainDate otherPlainDate)
               throws IllegalArgumentException

Returns true if the this instance's date comes before the date passed as a parameter. If they are equal, false is returned.

Throws:

IllegalArgumentException - if null if passed.

beforeOrEqualTo

public boolean beforeOrEqualTo(PlainDate otherPlainDate)
                        throws IllegalArgumentException

Returns true if the this instance's date comes before or is the same as the date passed as a parameter.

Throws:

IllegalArgumentException - if null if passed.

after

public boolean after(PlainDate otherPlainDate)
              throws IllegalArgumentException

Returns true if the this instance's date comes after the date passed as a parameter. If they are equal, false is returned.

Throws:

IllegalArgumentException - if null if passed.

afterOrEqualTo

public boolean afterOrEqualTo(PlainDate otherPlainDate)
                       throws IllegalArgumentException

Returns true if the this instance's date comes after or is the same as the date passed as a parameter.

Throws:

IllegalArgumentException - if null if passed.

clone

public Object clone()

Simply returns this instance as instances are immutable and our flyweight pattern keeps there from being more than one instance for the same year, month, and day.

Overrides:

clone in class Object