Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.


Inherits From: NSObject

Conforms To: NSCoding, NSCopying NSObject (NSObject)

Declared In: Foundation/NSDate.h

Class Description

NSDate is an abstract class that provides behavior for creating dates, comparing dates, representing dates, computing time intervals, and similar functionality. It presents a programmatic interface through which suitable date objects are requested and returned. NSDate objects 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 NSCalendarDate 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 typed as NSTimeInterval (a double) and expressed as seconds. The NSTimeInterval type makes possible a wide and fine-grained range of date and time values, giving accuracy within milliseconds for dates 10,000 years apart.

NSDate and its subclasses compute time as seconds relative to an absolute reference date. This reference date is the first instant of January 1, 2001. NSDate converts all date and time representations to and from NSTimeInterval 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.

Note: Conventional UNIX systems implement time according to the Network Time Protocol (NTP) standard, which is based on Coordinated Universal Time. The private implementation of NSDate follows the NTP standard. However, this standard doesn't account for leap seconds and therefore isn't synchronized with International Atomic Time (the most accurate).

Like various other Foundation classes, NSDate lets you 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.

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

Using NSDate

The date objects dispensed by NSDate give you a diverse range of date and time functionality. To obtain dates, send one of the date... messages to the NSDate class object. One of the most useful is date itself, which returns a date object representing the current date and time. You can get new date objects with date and time values adjusted from existing date objects by sending addTimeInterval:.

You can obtain relative date information by sending the timeInterval... messges to a date object. For instance, timeIntervalSinceNow gives you the time, in seconds, between the current time and the receiving date object. Compare dates with the isEqual:, compare:, laterDate:, and earlierDate: methods and use the description method to obtain a string object that represents the date in a standard international format.

Creating an NSDate Object

Converting to an NSCalendar Object

Representing Dates

Adding and Getting Intervals

Comparing Dates