< Previous PageNext Page > Hide TOC

Dates

This article describes the classes you use to represent dates in Cocoa, and the relationships between them.

Contents:

Dates
Creating Date Objects
Basic Date Calculations

Dates

Cocoa gives you two ways to represent dates and times.

• A date object is useful for representing a date users don’t see. It has methods for creating dates, comparing dates, and computing intervals. This is implemented by NSDate.

• A Gregorian date object, a special type of date object, is useful for representing dates users do see. It adds methods for converting dates to strings, converting strings to dates, and retrieving elements from dates (such as hours, minutes, and the day of the week). This is implemented by NSCalendarDate in Objective-C and by com.apple.cocoa.foundation.NSGregorianDate in Java.

All kinds of date objects are immutable since they represent a invariant point in time.

Like various other Foundation classes, NSDate enables you to obtain operating-system functionality (dates and times) without depending on operating-system internals. It also provides a basis for the NSRunLoop and NSTimer classes, which use concrete date objects to implement local event loops and timers.

“Date” as used here implies clock time as well. Dates store their times as the number of seconds relative to an absolute reference time: the first instant of 1 January, 2001, Greenwich Mean Time (GMT). Dates before then are stored as negative numbers; dates after then are stored as positive numbers. The standard unit of time for date objects is a value typed as double in Java and NSTimeInterval in Objective-C and is expressed as seconds. These types makes possible a wide and fine-grained range of date and time values, giving precision within milliseconds for dates 10,000 years apart.

NSDate and its subclasses compute time as seconds relative to the absolute reference date. The sole primitive method of NSDate, timeIntervalSinceReferenceDate, provides the basis for all the other methods in the NSDate interface. NSDate converts all date and time representations to and from NSTimeInterval values that are relative to the 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.

You can use the time zone associated with a date to change how the date prints its time interval. The time zone does not change how the time interval is stored. Because the value is stored independent of the time zone, you can accurately compare Gregorian dates with any other date objects or use them to create other date objects. It also means that you can track a date across different time zones; that is, you can create a new Gregorian date with a different time zone to see how the particular date is represented in that time zone.

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

Creating Date Objects

If you want to store the current time, use the date class method currentTimeIntervalSinceReferenceDate to create the date object. If you want to store some time other than the current time, use one of the Java constructors or Objective-C dateWithTimeInterval... methods.

The constructors or dateWithTimeInterval... methods create 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.

The Objective-C code fragment below defines two date objects. tomorrow is exactly 24 hours from the current date and time, and yesterday is exactly 24 hours earlier than the current date and time.

NSTimeInterval secondsPerDay = 24 * 60 * 60;

NSDate *tomorrow = [NSDate

            dateWithTimeIntervalSinceNow:secondsPerDay];

NSDate *yesterday = [NSDate

            dateWithTimeIntervalSinceNow:-secondsPerDay];

To get new date objects with date-and-time values adjusted from existing date objects, use addTimeInterval:.

NSTimeInterval secondsPerDay = 24 * 60 * 60;

NSDate *today = [NSDate date];

NSDate *tomorrow, yesterday;

tomorrow = [today addTimeInterval:secondsPerDay];

yesterday = [today addTimeInterval:-secondsPerDay];

Basic Date Calculations

To compare dates, use the isEqualToDate:, 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 a Gregorian date instead (NSCalendarDate in Objective-C, NSGregorianDate in Java). The following Objective-C code shows how to use timeIntervalSinceDate: to see if two dates are within one minute (60 seconds) of each other.

if (fabs([date2 timeIntervalSinceDate:date1]) < 60) ...

To obtain the difference between a date object and another point in time, you can 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 retrieve conventional elements of an Gregorian date, use the …Of… methods. For example, dayOfWeek returns a number that indicates the day of the week (0 is Sunday). The monthOfYear method returns a number between 1 and 12 that indicates the month. If you are using Mac OS X v10.4 or later, you can use a calendar object for more complicated calculations to determine, for example, how many weeks or months there are between two dates—see “Calendars.”

< Previous PageNext Page > Hide TOC