Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.0 and later. |
Declared in | NSCalendarDate.h NSDate.h |
Companion guides | |
Related sample code |
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.
NSDate
provides several methods to interpret and to create string representations of dates (for example, dateWithNaturalLanguageString:locale: and descriptionWithLocale:). In general, on Mac OS X v10.4 and later you should use an instance of NSDateFormatter
to parse and generate strings using the methods dateFromString:
and stringFromDate:
—see NSDateFormatter on Mac OS X 10.4 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, CFDate Reference. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSDate *
parameter, you can pass a CFDateRef
, and in a function where you see a CFDateRef
parameter, you can pass an NSDate
instance (you cast one type to the other to suppress compiler warnings). See Interchangeable Data Types for more information on toll-free bridging.
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.
If you want to subclass NSDate
to obtain behavior different than that provided by the private or public subclasses, you must do these things:
Declare a suitable instance variable to hold the date and time value (relative to an absolute reference date).
Override the timeIntervalSinceReferenceDate
instance method to provide the correct date and time value based on your instance variable.
Override initWithTimeIntervalSinceReferenceDate:
, the designated initializer method.
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.
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.
+ date
+ dateWithNaturalLanguageString:
+ dateWithNaturalLanguageString:locale:
+ dateWithString:
+ dateWithTimeIntervalSinceNow:
+ dateWithTimeIntervalSinceReferenceDate:
+ dateWithTimeIntervalSince1970:
– init
– initWithString:
– initWithTimeIntervalSinceNow:
– initWithTimeInterval:sinceDate:
– initWithTimeIntervalSinceReferenceDate:
– timeIntervalSinceDate:
– timeIntervalSinceNow
+ timeIntervalSinceReferenceDate
– timeIntervalSinceReferenceDate
– timeIntervalSince1970
Creates and returns a new date set to the current date and time.
+ (id)date
A new date object set to the current date and time.
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]; |
NSDate.h
Creates and returns an NSDate
object set to the date and time specified by a given string.
+ (id)dateWithNaturalLanguageString:(NSString *)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.”
A new NSDate
object set to the current date and time specified by string.
This method supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged.
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.)
NSCalendarDate.h
Creates and returns an NSDate
object set to the date and time specified by a given string.
+ (id)dateWithNaturalLanguageString:(NSString *)string locale:(id)localeDictionary
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.”
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.
A new NSDate
object set to the date and time specified by string as interpreted according to localeDictionary.
This method supports only a limited set of colloquial phrases, primarily in English. It may give unexpected results, and its use is strongly discouraged.
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
NSCalendarDate.h
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
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.
An NSDate
object with a date and time value specified by aString.
NSCalendarDate.h
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
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.
An NSDate
object set to seconds seconds from the reference date.
This method is useful for creating NSDate
objects from time_t values returned by BSD system functions.
NSDate.h
Creates and returns an NSDate
object set to a given number of seconds from the current date and time.
+ (id)dateWithTimeIntervalSinceNow:(NSTimeInterval)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.
An NSDate
object set to seconds seconds from the current date and time.
NSDate.h
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
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.
An NSDate
object set to seconds seconds from the absolute reference date.
NSDate.h
Creates and returns an NSDate
object representing a date in the distant future.
+ (id)distantFuture
An NSDate
object representing a date in the distant future (in terms of centuries).
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]; |
NSDate.h
Creates and returns an NSDate
object representing a date in the distant past.
+ (id)distantPast
An NSDate
object representing a date in the distant past (in terms of centuries).
You can use this object as a control date, a guaranteed temporal boundary.
NSDate.h
Returns the interval between the first instant of 1 January 2001, GMT and the current date and time.
+ (NSTimeInterval)timeIntervalSinceReferenceDate
The interval between the system’s absolute reference date (the first instant of 1 January 2001, GMT) and the current date and time.
This method is the primitive method for NSDate
. If you subclass NSDate
, you must override this method with your own implementation for it.
– timeIntervalSinceReferenceDate
– timeIntervalSinceDate:
– timeIntervalSince1970
– timeIntervalSinceNow
NSDate.h
Returns a new NSDate
object that is set to a given number of seconds relative to the receiver.
- (id)addTimeInterval:(NSTimeInterval)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.
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.
NSDate.h
Returns an NSComparisonResult value that indicates the temporal ordering of the receiver and another given date.
- (NSComparisonResult)compare:(NSDate *)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 Mac OS X.
If:
The receiver and anotherDate are exactly equal to each other, NSOrderedSame
The receiver is later in time than anotherDate, NSOrderedDescending
The receiver is earlier in time than anotherDate, NSOrderedAscending
.
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.
– earlierDate:
– isEqual:
(NSObject
protocol)– laterDate:
NSDate.h
Converts the receiver to an NSCalendarDate
object with a given format string and time zone.
- (NSCalendarDate *)dateWithCalendarFormat:(NSString *)formatString timeZone:(NSTimeZone *)timeZone
The format for the returned string (see Converting Dates to Strings 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
.)
The time zone for the new calendar date. Pass nil
to use the default time zone—specific to the current locale.
A new NSCalendarDate
object bound to formatString and the time zone timeZone.
– description
– descriptionWithCalendarFormat:timeZone:locale:
– descriptionWithLocale:
dateWithString:calendarFormat:
(NSCalendarDate
)NSCalendarDate.h
Returns a string representation of the receiver.
- (NSString *)description
A string representation of the receiver 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
”).
NSDate.h
Returns a string representation of the receiver, formatted as specified by given conversion specifiers.
- (NSString *)descriptionWithCalendarFormat:(NSString *)formatString timeZone:(NSTimeZone *)aTimeZone locale:(id)localeDictionary
The format for the returned string (see Converting Dates to Strings 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
.)
The time zone in which to represent the receiver. Pass nil
to use the default time zone—specific to the current locale.
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.
A string representation of the receiver, formatted as specified by the given conversion specifiers.
There are several problems with the implementation of this method that cannot be fixed for compatibility reasons. To format a date correctly, you should consider using a date formatter object instead (see NSDateFormatter
and Data Formatting Programming Guide for Cocoa).
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]); |
– description
descriptionWithCalendarFormat:locale:
(NSCalendarDate
)– descriptionWithLocale:
NSCalendarDate.h
Returns a string representation of the receiver using the given locale.
- (NSString *)descriptionWithLocale:(id)locale
An NSLocale
object.
If you pass nil
, NSDate
formats the date in the same way as the description
method.
On Mac OS X v10.4 and earlier, this parameter was an NSDictionary
object. If you pass in an NSDictionary
object on Mac OS X v10.5, NSDate
uses the default user locale—the same as if you passed in [NSLocale currentLocale].
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
”)
On Mac 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].
NSCalendarDate.h
Returns the earlier of the receiver and another given date.
- (NSDate *)earlierDate:(NSDate *)anotherDate
The date with which to compare the receiver.
The earlier of the receiver and anotherDate, determined using timeIntervalSinceDate:
. If the receiver and anotherDate represent the same date, returns the receiver.
– compare:
– isEqual:
(NSObject
protocol)– laterDate:
NSDate.h
Returns an NSDate
object initialized to the current date and time.
- (id)init
An NSDate
object initialized to the current date and time.
This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:
.
NSDate.h
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
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.
An NSDate
object initialized with a date and time value specified by aString.
This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:
.
NSCalendarDate.h
Returns an NSDate
object initialized relative to another given date by a given number of seconds.
- (id)initWithTimeInterval:(NSTimeInterval)seconds sinceDate:(NSDate *)refDate
The number of seconds to add to refDate. A negative value means the receiver will be earlier than refDate.
The reference date.
An NSDate
object initialized relative to refDate by seconds seconds.
This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:
.
NSDate.h
Returns an NSDate
object initialized relative to the current date and time by a given number of seconds.
- (id)initWithTimeIntervalSinceNow:(NSTimeInterval)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.
An NSDate
object initialized relative to the current date and time by seconds seconds.
This method uses the designated initializer, initWithTimeIntervalSinceReferenceDate:
.
NSDate.h
Returns an NSDate
object initialized relative the first instant of 1 January 2001, GMT by a given number of seconds.
- (id)initWithTimeIntervalSinceReferenceDate:(NSTimeInterval)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.
An NSDate
object initialized relative to the absolute reference date by seconds seconds.
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.
NSDate.h
Returns a Boolean value that indicates whether a given object is an NSDate
object and exactly equal the receiver.
- (BOOL)isEqualToDate:(NSDate *)anotherDate
The date to compare with the receiver.
YES
if the anotherDate is an NSDate
object and is exactly equal to the receiver, otherwise NO
.
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.
– compare:
– earlierDate:
– isEqual:
(NSObject
protocol)– laterDate:
NSDate.h
Returns the later of the receiver and another given date.
- (NSDate *)laterDate:(NSDate *)anotherDate
The date with which to compare the receiver.
The later of the receiver and anotherDate, determined using timeIntervalSinceDate:
. If the receiver and anotherDate represent the same date, returns the receiver.
– compare:
– earlierDate:
– isEqual:
(NSObject
protocol)NSDate.h
Returns the interval between the receiver and the first instant of 1 January 1970, GMT.
- (NSTimeInterval)timeIntervalSince1970
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.
– timeIntervalSinceDate:
– timeIntervalSinceNow
– timeIntervalSinceReferenceDate
+ timeIntervalSinceReferenceDate
NSDate.h
Returns the interval between the receiver and another given date.
- (NSTimeInterval)timeIntervalSinceDate:(NSDate *)anotherDate
The date with which to compare the receiver.
The interval between the receiver and anotherDate. If the receiver is earlier than anotherDate, the return value is negative.
NSDate.h
Returns the interval between the receiver and the current date and time.
- (NSTimeInterval)timeIntervalSinceNow
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.
NSDate.h
Returns the interval between the receiver and the first instant of 1 January 2001, GMT.
- (NSTimeInterval)timeIntervalSinceReferenceDate
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.
NSDate.h
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
NSTimeIntervalSince1970
The number of seconds from 1 January 1970 to the reference date, 1 January 2001.
Available in Mac OS X v10.0 and later.
Declared in NSDate.h
.
1 January 1970 is the epoch (or starting point) for Unix time.
NSDate.h
© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)