NSDate Class Reference

Inherits from
NSObject
Conforms to
NSCopying
NSSecureCoding
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSCalendarDate.h
NSDate.h
Companion guides
Date and Time Programming Guide
Property List Programming Guide
Related sample code

Overview

NSDate objects represent a single point in time. NSDate is a class cluster; its 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 instances not 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. Generally, you instantiate a suitable date object by invoking one of the date... class methods.

NSDate is an abstract class that provides behavior for creating dates, comparing dates, representing dates, computing intervals, and similar functionality. NSDate 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 an invariant point in time. This class is designed to provide the foundation for arbitrary calendrical representations.

The sole primitive method of NSDate, timeIntervalSinceReferenceDate, provides the basis for all the other methods in the NSDate interface. This method returns a time value relative to an absolute reference date—the first instant of 1 January 2001, GMT.

To parse strings containing dates and to generate string representations of a date, you should use an instance of NSDateFormatter using the methods dateFromString: and stringFromDate: respectively—see “Date Formatters” for more details.

NSDate models the change from the Julian to the Gregorian calendar in October 1582, and calendrical calculations performed in conjunction with NSCalendar take this transition into account. Note, however, that some locales adopted the Gregorian calendar at other times; for example, Great Britain didn't switch over until September 1752.

NSDate is “toll-free bridged” with its Cocoa Foundation counterpart, CFDateRef. See “Toll-Free Bridging” for more information on toll-free bridging.

Subclassing Notes

The major reason for subclassing NSDate is to create a class with convenience methods for working with a particular calendrical system. But you could also require a custom NSDate class for other reasons, such as to get a date and time value that provides a finer temporal granularity.

Methods to Override

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

If you are creating a subclass that represents a calendrical system, you must also define methods that partition past and future periods into the units of this calendar.

Because the NSDate class adopts the NSCopying and NSCoding protocols, your subclass must also implement all of the methods in these protocols.

Special Considerations

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

Tasks

Creating and Initializing Date Objects

Getting Temporal Boundaries

Comparing Dates

Getting Time Intervals

Adding a Time Interval

Representing Dates as Strings

Converting to an NSCalendarDate Object

Class Methods

date

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

+ (id)date
Return Value

A new date object set to the current date and time.

Discussion

This method uses the default initializer method for the class, init.

The following code sample shows how to use date to get the current date:

NSDate *today = [NSDate date];
Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSDate.h

dateWithNaturalLanguageString:

Creates and returns an NSDate object set to the date and time specified by a given string.

+ (id)dateWithNaturalLanguageString:(NSString *)string
Parameters
string

A string that contains a colloquial specification of a date, such as “last Tuesday at dinner,” “3pm December 31, 2001,” “12/31/01,” or “31/12/01.”

Return Value

A new NSDate object set to the current date and time specified by string.

Discussion

This method supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged. To create a date object from a string, you should use a date formatter object instead (see NSDateFormatter and Data Formatting Guide).

In parsing the string, this method uses the date and time preferences stored in the user’s defaults database. (See dateWithNaturalLanguageString:locale: for a list of the specific items used.)

Availability
  • Available in OS X v10.0 and later.
Declared In
NSCalendarDate.h

dateWithNaturalLanguageString:locale:

Creates and returns an NSDate object set to the date and time specified by a given string.

+ (id)dateWithNaturalLanguageString:(NSString *)string locale:(id)localeDictionary
Parameters
string

A string that contains a colloquial specification of a date, such as “last Tuesday at dinner,” “3pm December 31, 2001,” “12/31/01,” or “31/12/01.”

localeDictionary

An NSDictionary object containing locale data. To use the user's preferences, you can use [[NSUserDefaults standardUserDefaults] dictionaryRepresentation].

If you pass nil or an instance of NSLocale, NSDate uses the system default locale—this is not the same as the current user's locale.

Return Value

A new NSDate object set to the date and time specified by string as interpreted according to localeDictionary.

Discussion

This method supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged. To create a date object from a string, you should use a date formatter object instead (see NSDateFormatter and Data Formatting Guide).

The keys and values that represent the locale data from localeDictionary are used when parsing the string. In addition to the locale keys listed in the class description, these keys are used when parsing natural language strings:

  • NSDateTimeOrdering

  • NSEarlierTimeDesignations

  • NSHourNameDesignations

  • NSLaterTimeDesignations

  • NSNextDayDesignations

  • NSNextNextDayDesignations

  • NSPriorDayDesignations

  • NSThisDayDesignations

  • NSYearMonthWeekDesignations

Availability
  • Available in OS X v10.0 and later.
Declared In
NSCalendarDate.h

dateWithString:

Creates and returns an NSDate object with a date and time value specified by a given string in the international string representation format (YYYY-MM-DD HH:MM:SS ±HHMM).

+ (id)dateWithString:(NSString *)aString
Parameters
aString

A string that specifies a date and time value in the international string representation format—YYYY-MM-DD HH:MM:SS ±HHMM, where ±HHMM is a time zone offset in hours and minutes from GMT (for example, “2001-03-24 10:45:32 +0600”).

You must specify all fields of the format string, including the time zone offset, which must have a plus or minus sign prefix.

Return Value

An NSDate object with a date and time value specified by aString.

Discussion

To create a date object from a string, you should typically use a date formatter object instead (see NSDateFormatter and Data Formatting Guide).

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSCalendarDate.h

dateWithTimeInterval:sinceDate:

Creates and returns an NSDate object set to a given number of seconds from the specified date.

+ (id)dateWithTimeInterval:(NSTimeInterval)seconds sinceDate:(NSDate *)date
Parameters
seconds

The number of seconds to add to date. Use a negative argument to specify a date and time before date.

date

The date.

Return Value

An NSDate object set to seconds seconds from date.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSDate.h

dateWithTimeIntervalSince1970:

Creates and returns an NSDate object set to the given number of seconds from the first instant of 1 January 1970, GMT.

+ (id)dateWithTimeIntervalSince1970:(NSTimeInterval)seconds
Parameters
seconds

The number of seconds from the reference date, 1 January 1970, GMT, for the new date. Use a negative argument to specify a date before this date.

Return Value

An NSDate object set to seconds seconds from the reference date.

Discussion

This method is useful for creating NSDate objects from time_t values returned by BSD system functions.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

dateWithTimeIntervalSinceNow:

Creates and returns an NSDate object set to a given number of seconds from the current date and time.

+ (id)dateWithTimeIntervalSinceNow:(NSTimeInterval)seconds
Parameters
seconds

The number of seconds from the current date and time for the new date. Use a negative value to specify a date before the current date.

Return Value

An NSDate object set to seconds seconds from the current date and time.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

dateWithTimeIntervalSinceReferenceDate:

Creates and returns an NSDate object set to a given number of seconds from the first instant of 1 January 2001, GMT.

+ (id)dateWithTimeIntervalSinceReferenceDate:(NSTimeInterval)seconds
Parameters
seconds

The number of seconds from the absolute reference date (the first instant of 1 January 2001, GMT) for the new date. Use a negative argument to specify a date and time before the reference date.

Return Value

An NSDate object set to seconds seconds from the absolute reference date.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

distantFuture

Creates and returns an NSDate object representing a date in the distant future.

+ (id)distantFuture
Return Value

An NSDate object representing a date in the distant future (in terms of centuries).

Discussion

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

myEvent = [myWindow nextEventMatchingMask:myEventMask
    untilDate:[NSDate distantFuture]
    inMode:NSDefaultRunLoopMode
    dequeue:YES];
Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

distantPast

Creates and returns an NSDate object representing a date in the distant past.

+ (id)distantPast
Return Value

An NSDate object representing a date in the distant past (in terms of centuries).

Discussion

You can use this object as a control date, a guaranteed temporal boundary.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

timeIntervalSinceReferenceDate

Returns the interval between the first instant of 1 January 2001, GMT and the current date and time.

+ (NSTimeInterval)timeIntervalSinceReferenceDate
Return Value

The interval between the system’s absolute reference date (the first instant of 1 January 2001, GMT) and the current date and time.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

Instance Methods

compare:

Returns an NSComparisonResult value that indicates the temporal ordering of the receiver and another given date.

- (NSComparisonResult)compare:(NSDate *)anotherDate
Parameters
anotherDate

The date with which to compare the receiver.

This value must not be nil. If the value is nil, the behavior is undefined and may change in future versions of OS X.

Return Value

If:

Discussion

This method detects sub-second differences between dates. If you want to compare dates with a less fine granularity, use timeIntervalSinceDate: to compare the two dates.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

dateByAddingTimeInterval:

Returns a new NSDate object that is set to a given number of seconds relative to the receiver.

- (id)dateByAddingTimeInterval:(NSTimeInterval)seconds
Parameters
seconds

The number of seconds to add to the receiver. Use a negative value for seconds to have the returned object specify a date before the receiver.

Return Value

A new NSDate object that is set to seconds seconds relative to the receiver. The date returned might have a representation different from the receiver’s.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSDate.h

dateWithCalendarFormat:timeZone:

Converts the receiver to an NSCalendarDate object with a given format string and time zone. (Deprecated. Use the NSDate methods to set the individual date values.)

- (NSCalendarDate *)dateWithCalendarFormat:(NSString *)formatString timeZone:(NSTimeZone *)timeZone
Parameters
formatString

The format for the returned string (see “Date and Number Formatters on OS X v10.0 to 10.3” for a discussion of how to create the format string). Pass nil to use the default format string, “%Y-%m-%d %H:%M:%S %z” (this conforms to the international format YYYY-MM-DD HH:MM:SS ±HHMM.)

timeZone

The time zone for the new calendar date. Pass nil to use the default time zone—specific to the current locale.

Return Value

A new NSCalendarDate object bound to formatString and the time zone timeZone.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSCalendarDate.h

description

Returns a string representation of the receiver.

- (NSString *)description
Return Value

A string representation of the receiver.

Discussion

The representation is useful for debugging only.

There are a number of options to aquire a formated string for a date including: date formatters (see NSDateFormatter and Data Formatting Guide), and the NSDate methods descriptionWithLocale:, dateWithCalendarFormat:timeZone:, and descriptionWithCalendarFormat:timeZone:locale:

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

descriptionWithCalendarFormat:timeZone:locale:

Returns a string representation of the receiver, formatted as specified by given conversion specifiers.

- (NSString *)descriptionWithCalendarFormat:(NSString *)formatString timeZone:(NSTimeZone *)aTimeZone locale:(id)localeDictionary
Parameters
formatString

The format for the returned string (see “Date and Number Formatters on OS X v10.0 to 10.3” for a discussion of how to create the format string). Pass nil to use the default format string, “%Y-%m-%d %H:%M:%S %z” (this conforms to the international format YYYY-MM-DD HH:MM:SS ±HHMM.)

aTimeZone

The time zone in which to represent the receiver. Pass nil to use the default time zone—specific to the current locale.

localeDictionary

An NSDictionary object containing locale data. To use the user's preferences, you can use [[NSUserDefaults standardUserDefaults] dictionaryRepresentation].

If you pass nil or an instance of NSLocale, NSDate uses the system default locale—this is not the same as the current user's locale.

Return Value

A string representation of the receiver, formatted as specified by the given conversion specifiers.

Discussion

There are several problems with the implementation of this method that cannot be fixed for compatibility reasons. To format a date, you should use a date formatter object instead (see NSDateFormatter and Data Formatting Guide).

You could use this method to print the current time as follows:

sprintf(aString, "The current time is %s\n", [[[NSDate  date]
    descriptionWithCalendarFormat:@"%H:%M:%S %Z" timeZone:nil
    locale:[[NSUserDefaults standardUserDefaults] dictionaryRepresentation]]
        UTF8String]);
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSCalendarDate.h

descriptionWithLocale:

Returns a string representation of the receiver using the given locale.

- (NSString *)descriptionWithLocale:(id)locale
Parameters
locale

An NSLocale object.

If you pass nil, NSDate formats the date in the same way as the description method.

On OS X v10.4 and earlier, this parameter was an NSDictionary object. If you pass in an NSDictionary object on OS X v10.5, NSDate uses the default user locale—the same as if you passed in [NSLocale currentLocale].

Return Value

A string representation of the receiver, using the given locale, or if the locale argument is nil, in the international format YYYY-MM-DD HH:MM:SS ±HHMM, where ±HHMM represents the time zone offset in hours and minutes from GMT (for example, “2001-03-24 10:45:32 +0600”)

Special Considerations

On OS X v10.4 and earlier, localeDictionary is an NSDictionary object containing locale data. To use the user's preferences, you can use [[NSUserDefaults standardUserDefaults] dictionaryRepresentation].

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDate.h

earlierDate:

Returns the earlier of the receiver and another given date.

- (NSDate *)earlierDate:(NSDate *)anotherDate
Parameters
anotherDate

The date with which to compare the receiver.

Return Value

The earlier of the receiver and anotherDate, determined using timeIntervalSinceDate:. If the receiver and anotherDate represent the same date, returns the receiver.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

init

Returns an NSDate object initialized to the current date and time.

- (id)init
Return Value

An NSDate object initialized to the current date and time.

Discussion

This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

initWithString:

Returns an NSDate object initialized with a date and time value specified by a given string in the international string representation format.

- (id)initWithString:(NSString *)description
Parameters
description

A string that specifies a date and time value in the international string representation format—YYYY-MM-DD HH:MM:SS ±HHMM, where ±HHMM is a time zone offset in hours and minutes from GMT (for example, “2001-03-24 10:45:32 +0600”).

You must specify all fields of the format string, including the time zone offset, which must have a plus or minus sign prefix.

Return Value

An NSDate object initialized with a date and time value specified by aString.

Discussion

This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSCalendarDate.h

initWithTimeInterval:sinceDate:

Returns an NSDate object initialized relative to another given date by a given number of seconds.

- (id)initWithTimeInterval:(NSTimeInterval)seconds sinceDate:(NSDate *)refDate
Parameters
seconds

The number of seconds to add to refDate. A negative value means the receiver will be earlier than refDate.

refDate

The reference date.

Return Value

An NSDate object initialized relative to refDate by seconds seconds.

Discussion

This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDate.h

initWithTimeIntervalSince1970:

Returns an NSDate object set to the given number of seconds from the first instant of 1 January 1970, GMT.

- (id)initWithTimeIntervalSince1970:(NSTimeInterval)seconds
Parameters
seconds

The number of seconds from the reference date, 1 January 1970, GMT, for the new date. Use a negative argument to specify a date before this date.

Return Value

An NSDate object set to seconds seconds from the reference date.

Discussion

This method is useful for creating NSDate objects from time_t values returned by BSD system functions.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSDate.h

initWithTimeIntervalSinceNow:

Returns an NSDate object initialized relative to the current date and time by a given number of seconds.

- (id)initWithTimeIntervalSinceNow:(NSTimeInterval)seconds
Parameters
seconds

The number of seconds from relative to the current date and time to which the receiver should be initialized. A negative value means the returned object will represent a date in the past.

Return Value

An NSDate object initialized relative to the current date and time by seconds seconds.

Discussion

This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

initWithTimeIntervalSinceReferenceDate:

Returns an NSDate object initialized relative the first instant of 1 January 2001, GMT by a given number of seconds.

- (id)initWithTimeIntervalSinceReferenceDate:(NSTimeInterval)seconds
Parameters
seconds

The number of seconds to add to the reference date (the first instant of 1 January 2001, GMT). A negative value means the receiver will be earlier than the reference date.

Return Value

An NSDate object initialized relative to the absolute reference date by seconds seconds.

Discussion

This method is the designated initializer for the NSDate class and is declared primarily for the use of subclasses of NSDate. When you subclass NSDate to create a concrete date class, you must override this method.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

isEqualToDate:

Returns a Boolean value that indicates whether a given object is an NSDate object and exactly equal the receiver.

- (BOOL)isEqualToDate:(NSDate *)anotherDate
Parameters
anotherDate

The date to compare with the receiver.

Return Value

YES if the anotherDate is an NSDate object and is exactly equal to the receiver, otherwise NO.

Discussion

This method detects sub-second differences between dates. If you want to compare dates with a less fine granularity, use timeIntervalSinceDate: to compare the two dates.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

laterDate:

Returns the later of the receiver and another given date.

- (NSDate *)laterDate:(NSDate *)anotherDate
Parameters
anotherDate

The date with which to compare the receiver.

Return Value

The later of the receiver and anotherDate, determined using timeIntervalSinceDate:. If the receiver and anotherDate represent the same date, returns the receiver.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

timeIntervalSince1970

Returns the interval between the receiver and the first instant of 1 January 1970, GMT.

- (NSTimeInterval)timeIntervalSince1970
Return Value

The interval between the receiver and the reference date, 1 January 1970, GMT. If the receiver is earlier than the reference date, the value is negative.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

timeIntervalSinceDate:

Returns the interval between the receiver and another given date.

- (NSTimeInterval)timeIntervalSinceDate:(NSDate *)anotherDate
Parameters
anotherDate

The date with which to compare the receiver.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

timeIntervalSinceNow

Returns the interval between the receiver and the current date and time.

- (NSTimeInterval)timeIntervalSinceNow
Return Value

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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDate.h

timeIntervalSinceReferenceDate

Returns the interval between the receiver and the first instant of 1 January 2001, GMT.

- (NSTimeInterval)timeIntervalSinceReferenceDate
Return Value

The interval between the receiver and the system’s absolute reference date (the first instant of 1 January 2001, GMT). If the receiver is earlier than the reference date, the value is negative.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSDate.h

Constants

NSTimeIntervalSince1970

NSDate provides a constant that specifies the number of seconds from 1 January 1970 to the reference date, 1 January 2001.

#define NSTimeIntervalSince1970  978307200.0
Constants
NSTimeIntervalSince1970

The number of seconds from 1 January 1970 to the reference date, 1 January 2001.

Available in OS X v10.0 and later.

Declared in NSDate.h.

Discussion

1 January 1970 is the epoch (or starting point) for Unix time.

Declared In
NSDate.h

Notifications

NSSystemClockDidChangeNotification

Posted whenever the system clock is changed. This can be initiated by a call to settimeofday() or the user changing values in the Date and Time Preference panel. The notification object is null. This notification does not contain a userInfo dictionary.
Availability
Declared In
NSDate.h


© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)

Did this document help you? Yes It's good, but... Not helpful...