Developer Documentation
PATH  Mac OS X Documentation > Foundation Reference: Java


[Previous] [Class List] [Next]

NSDate


Inherits from: NSObject
Package: com.apple.yellow.foundation

Class at a Glance


An NSDate object stores a date and time that can be compared to other dates and times.

Principal Attributes


Commonly Used Methods



earlierDate Compares the receiver to the argument and returns the earlier of the two.
isEqualToDate Returns YES if the receiver and the argument are equal.
laterDate Compares the receiver to the argument and returns the later of the two.
timeIntervalSinceNow Returns the number of seconds difference between the receiver and the current date and time.

Primitive Methods



currentTimeIntervalSinceReferenceDate




Class Description


NSDate objects represent a single point in time. The NSDate cluster's single public superclass, NSDate, declares the programmatic interface for specific and relative time values.

The objects you create using NSDate are referred to as date objects. They are immutable objects. Because of the nature of class clusters, objects returned by the NSDate class are not instances of that abstract class but of one of its private subclasses. Although a date object's class is private, its interface is public, as declared by the abstract superclass, NSDate. (See the "Class Clusters" programming topic for more information on class clusters and creating subclasses within a cluster.)

Generally, you instantiate a suitable date object by invoking one of the date... class methods.

The date classes adopt the NSCopying and NSCoding protocols.

NSDate 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 NSDate 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 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 1 January, 2001, Greenwich Mean Time (GMT). 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.


Rhapsody and supported UNIX systems implement 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).

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.

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.

Creating NSDate Objects

Use a date object to store a point in time. If you want to store the current time, use the date class method to create the date object. If you want to store some time other than the current time, use one of the dateWithTimeInterval... methods.

The 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.

NSCalendarDate

The NSDate class cluster provides, for your convenience, a public concrete subclass of NSDate that satisfies many requirements for dates and times. This subclass, NSCalendarDate, 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. You can create an NSCalendarDate out of your NSDate using the dateWithCalendarFormat:timeZone: method.

Comparing NSDate 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 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 NSCalendarDate objects instead.

NSString Representations for NSDates

To represent your date object as an NSString, use the description... methods. The simplest method, description, prints out the date in the format YYYY-MM-DD HH:MM:SS ±HHMM, where ±HHMM represents the time zone offset in hours and minutes from GMT. (Adding the offset to the specific time yields the equivalent GMT.) To have a specific locale dictionary affect the representation of your NSDate, use descriptionWithLocale: instead of description. The following keys in the locale dictionary affect NSDates:


Key Description
NSTimeDateFormatString Specifies how dates with times are printed. The default is to use abbreviated months and days with a 24 hour clock, as in "Sun Jan 01 23:00:00 +6 2001."
NSAMPMDesignation Specifies how the morning and afternoon designations are printed. The default is AM and PM.
NSMonthNameArray Specifies the names for the months.
NSShortMonthNameArray Specifies the abbreviations for the months.
NSWeekDayNameArray Specifies the names for the days of the week.
NSShortWeekDayNameArray Specifies the abbreviations for the days of the week.

Subclassing NSDate

If you want to subclass NSDate to obtain behavior different than that provided by the private subclasses, you must do these things:

Your subclass may use a different reference date than the absolute reference date used by NSDate (the first instance of 1 January 2001 GMT). If it does, it must still use the absolute reference date in its implementations of the methods currentTimeIntervalSinceReferenceDate and initWithTimeIntervalSinceReferenceDate:. That is, the reference date referred to in the titles of these methods is the absolute reference date. If you do not use the absolute reference date in these methods, comparisons between NSDate objects of your subclass and NSDate objects of a private subclass will not work.


Adopted Protocols


NSCopying
- copyWithZone:
NSCoding
- encodeWithCoder:
- initWithCoder:

Method Types


Creating an NSDate instance
date
dateWithTimeIntervalSinceNow:
dateWithString:
dateWithNaturalLanguageString:
dateWithNaturalLanguageString:locale:
dateWithTimeIntervalSinceReferenceDate:
dateWithTimeIntervalSince1970:
distantFuture
distantPast
initWithTimeIntervalSinceNow:
initWithString:
initWithTimeInterval:sinceDate:
init
initWithTimeIntervalSinceReferenceDate:
addTimeInterval:
Comparing dates
isEqualToDate
earlierDate
laterDate
compare
Getting time intervals
timeIntervalSinceDate
timeIntervalSinceNow
currentTimeIntervalSinceReferenceDate
timeIntervalSinceReferenceDate
timeIntervalSince1970
Representing dates as NSStrings
description
descriptionWithLocale:
descriptionWithCalendarFormat:timeZone:locale:
Converting to an NSCalendarDate object
dateWithCalendarFormat:timeZone:

Constructors


NSDate

public NSDate()

public NSDate(double aDouble)

public NSDate(double aDouble, NSDate aNSDate)

Static Methods



currentTimeIntervalSinceReferenceDate

public static double currentTimeIntervalSinceReferenceDate()

Returns the interval between the system's absolute reference date (the first instance of 1 January 2001, GMT) and the current date and time. Currently, this value is a negative number.

See Also: timeIntervalSince1970timeIntervalSinceReferenceDate, timeIntervalSinceDate, timeIntervalSinceNow



distantFuture

public static NSDate distantFuture()

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

You can pass this value where an NSDate is required to have the date argument essentially ignored. For example, the NSWindow method nextEventMatchingMask:untilDate:inMode:dequeue: returns null if an event specified in the event mask does not happen before the specified date. You can use the object returned by distantF uture as the date argument to wait indefinitely for the event to occur.

myEvent = [myWindow nextEventMatchingMask:myEventMask 
	untilDate:[NSDate distantFuture] 
	inMode:NSDefaultRunLoopMode 
	dequeue:YES];

See Also: distantPast



distantPast

public static NSDate distantPast()

Creates and returns an NSDate 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.

See Also: distantFuture



millisecondsToTimeInterval

public static double millisecondsToTimeInterval(long aLong)



timeIntervalToMilliseconds

public static long timeIntervalToMilliseconds(double aDouble)




Instance Methods



compare

public int compare(NSDate anotherDate)

Compares the receiving date to anotherDate, using timeIntervalSinceDate:, and returns a value of type NSComparisonResult. If the two dates are exactly equal to each other, this method returns NSOrderedSame. If the receiving object in the comparison is more recent than anotherDate, the method returns NSOrderedDescending. If it is older, it returns NSOrderedAscending.

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 NSCalendarDate objects instead.

See Also: earlierDate, - isEqual: (NSObject protocol), laterDate



dateByAddingTimeInterval

public NSDate dateByAddingTimeInterval(double aDouble)



earlierDate

public NSDate earlierDate(NSDate anotherDate)

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

See Also: compare, - isEqual: (NSObject protocol), laterDate



equals

public boolean equals(Object anObject)



hashCode

public int hashCode()



isEqualToDate

public boolean isEqualToDate(NSDate anotherDate)

Returns true if the two objects compared are NSDate objects and are exactly equal to each other, false if one of the objects is not of the NSDate class or if their date and time values differ. This method detects subsecond differences between dates. If you want to compare dates with a less fine granularity, either use timeIntervalSinceDate to compare the two dates or use NSCalendarDate objects instead.

See Also: compare, earlierDate, - isEqual: (NSObject protocol), laterDate



laterDate

public NSDate laterDate(NSDate anotherDate)

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

See Also: compare, earlierDate, - isEqual: (NSObject protocol)



timeIntervalSinceDate

public double timeIntervalSinceDate(NSDate anotherDate)

Returns the interval between the receiver and anotherDate. If the receiver is earlier than anotherDate, the return value is negative.

See Also: timeIntervalSince1970timeIntervalSinceNow, currentTimeIntervalSinceReferenceDate



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.

See Also: timeIntervalSince1970timeIntervalSinceDate, currentTimeIntervalSinceReferenceDate



timeIntervalSinceReferenceDate

public 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.

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

See Also: timeIntervalSince1970timeIntervalSinceDate, timeIntervalSinceNow, currentTimeIntervalSinceReferenceDate



toString

public String toString()




[Previous] [Next]