Class next.util.Date

CLASS DESCRIPTION

Extends:
next.util.NextObject

Implements:
next/util/Coding

Date objects represent a single point in time. The Date class declares the programmatic interface for specific and relative time values.

Date is an abstract class that provides behavior for creating dates, comparing dates, representing dates, computing intervals, and similar functionality. It presents a programmatic interface through which suitable date objects are requested and returned. Date objects returned from Date are lightweight and immutable since they represent a invariant point in time. This class is designed to provide the foundation for arbitrary calendrical representations. Its subclass CalendarDate offers date objects that are suitable for representing dates according to western calendrical systems.

"Date" as used above implies clock time as well. The standard unit of time for date objects is a value expressed as seconds. This type makes possible a wide and fine-grained range of date and time values, giving accuracy within milliseconds for dates 10,000 years apart.

Date and its subclasses compute time as seconds relative to an absolute reference date. This reference date is the first instant of 1 January, 2001, Greenwich Mean Time (GMT). Date converts all date and time representations to and from values that are relative to this absolute reference date. A positive interval relative to a date represents a point in the future, a negative interval represents a time in the past.

Conventional UNIX systems implement time according to the Network Time Protocol (NTP) standard, which is based on Coordinated Universal Time. The current private implementations of Date follow the NTP standard. However, they do not account for leap seconds and therefore are not synchronized with International Atomic Time (the most accurate).

Like various other next.util classes, Date enables you to obtain operating-system functionality (dates and times) without depending on operating-system internals.

Date's sole primitive method, timeIntervalSinceReferenceDate, provides the basis for all the other methods in the Date interface. It returns a time value relative to an absolute reference date.

Creating Date Objects

Use a date object to store a point in time. If you want to store the current time, use the Date constructor to create the date object. If you want to store some time other than the current time, Create a Date object and then use one of the timeInterval... methods.

The timeInterval... methods set date objects relative to a particular time, which the method name describes. You specify (in seconds) how much more recent or how much more in the past you want your date object to be. To specify a date that occurs earlier than the method's reference date, use a negative number of seconds.

CalendarDate

next.util provides, for your convenience, a public concrete subclass of Date that satisfies many requirements for dates and times. This subclass, CalendarDate, enables you to represent dates as arbitrary strings, to create new date objects from string representations, to extract date and time elements from date objects, and to do other calendar-related functions.

Comparing Date Objects

To obtain the difference between a date object and another point in time, send a timeInterval... message to the date object. For instance, timeIntervalSinceNow gives you the time, in seconds, between the current time and the receiving date object.

To compare dates, use the compare, laterDate, and earlierDate methods. These methods perform exact comparisons, which means they will detect subsecond differences between dates. You might want to compare dates with a less fine granularity. For example, you might want to consider two dates equal if they are within a minute of each other. If this is the case, use timeIntervalSinceDate to compare the two dates or use CalendarDate objects instead. Subclassing Date If you want to subclass Date to obtain behavior different than that provided by the CalendarDate subclass, you must do these things:

Your subclass may use a different reference date than the absolute reference date used by Date (the first instance of 1 January 2001 GMT). If it does, it must still use the absolute reference date in its implementation of timeIntervalSinceReferenceDate. That is, the reference date referred to in the title of this method is the absolute reference date. If you do not use the absolute reference date in this method, comparisons between Date objects of your subclass and Date objects of a private subclass will not work.

CONSTRUCTORS

Date

public Date()

Creates and returns a Date set to the current date and time.


METHODS

compare

public int compare(next.util.Date aDate)

Compares the receiving date to aDate, using timeIntervalSinceDate, and returns an integer indicating the result. If the two dates are exactly equal to each other, this method returns 0. If the receiving object in the comparison is more recent than aDate, the method returns 1. If it is older, it returns -1.

This method detects subsecond differences between dates. If you want to compare dates with a less fine granularity, use timeIntervalSinceDate to compare the two dates or use CalendarDate objects instead.


dateWithNaturalLanguageString

public static java.lang.Object dateWithNaturalLanguageString(java.lang.String aString)

Creates and returns a Date set to the date and time specified by aString. The argument aString can be a colloquial specification of a date, such as "last Tuesday at dinner," "3pm December 31, 1995," "12/31/95," or "31/12/95." In parsing aString, this method uses the date and time preferences stored in the user's defaults database. In addition to the locale keys listed in the class description, these keys are used when parsing natural language strings:

NSDateTimeOrdering
Determines how to use ambiguous numbers. Specify this value as a permutation of the letters M (month), D (day), Y (year), and H (hour). For example, MDYH treats "2/3/95 10" as the 3rd day of February 1995 at 10:00am, whereas DMYH treats the same value as the 2nd day of March 1995 at 10:00am.
If fewer numbers are specified than are needed, the numbers are prioritized to satisfy day first, then the month, and then the year. For example, if you supply only the value 12, it means the 12th day of this month in this year because the day must be specified. If you supply "2 12" it means either February 12 or December 2, depending on if the ordering is "MDYH" or "DMYH."
NSEarlierTimeDesignations
An array of strings that denote a time in the past. These are adjectives that modify values from NSYearMonthWeekDesignations. The defaults are "prior," "last," "past," and "ago."
NSHourNameDesignations
Strings that identify the time of day. These strings should be bound to an hour. The default is this array of arrays: (0, midnight), (12, noon, lunch), (10, morning), (14, afternoon), (19, dinner).
NSLaterTimeDesignations
An array of strings that denote a time in the future. This is an adjective that modifies a value from NSYearMonthWeekDesignations. The default is "next."
NSNextDayDesignations
A string that identifies the day after today. The default is "tomorrow."
NSNextNextDayDesignations
A string that identifies the day after tomorrow. The default is "nextday".
NSPriorDayDesignations
A string that identifies the day before today. The default is "yesterday."
NSThisDayDesignations
A string that identifies what this day is called. The default is "today."
NSYearMonthWeekDesignations
An array of strings that specify the word for year, month, and week in the current locale. The defaults are "year," "month," and "week."


distantFuture

public static java.lang.Object distantFuture()

Creates and returns a Date that represents a date in the distant future (in terms of centuries).

You can pass this value where a Date is required to have the date argument essentially ignored.


distantPast

public static java.lang.Object distantPast()

Creates and returns a Date that represents a date in the distant past (in terms of centuries). You can use this object in your code as a control date, a guaranteed temporal boundary.


earlierDate

public next.util.Date earlierDate(next.util.Date aDate)

Compares the receiver date to aDate, using timeIntervalSinceDate, and returns the earlier of the two.


encodeWithCoder

public void encodeWithCoder(next.util.Coder aCoder)

Encodes the receiver using aCoder. See the Coding interface description for more information.


laterDate

public next.util.Date laterDate(next.util.Date aDate)

Compares the receiver to aDate, using timeIntervalSinceDate, and returns the later of the two.


timeInterval

public double timeInterval()

Returns the interval between the receiver and the system's absolute reference date, 1 January 2001, GMT. If the receiver is earlier than the absolute reference date, the return value is negative.

This is the primitive method for Date. If you subclass Date, you must override this method with your own implementation for it.


timeIntervalSince1970

public double timeIntervalSince1970()

Returns the interval between the receiver and the reference date used by UNIX systems, 1 January 1970. If the receiver is earlier than 1 January 1970, the return value is negative.


timeIntervalSinceDate

public double timeIntervalSinceDate(next.util.Date aDate)

Returns the interval between the receiver and aDate. If the return value is a negative number, aDate is earlier than the receiver.


timeIntervalSinceNow

public double timeIntervalSinceNow()

Returns the interval between the receiver and the current date and time. If the receiver is earlier than the current date and time, the return value is negative.


timeIntervalSinceReferenceDate

public static double timeIntervalSinceReferenceDate()

Returns the interval between the receiver and the system's absolute reference date, 1 January 2001, GMT. If the receiver is earlier than the absolute reference date, the return value is negative.