Mac Developer Library

Developer

Foundation Framework Reference NSDate Class Reference

Options
Deployment Target:

On This Page
Language:

NSDate

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

Inheritance


Import Statement


import Foundation @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Creates and returns a new date set to the current date and time.

    Declaration

    Objective-C

    + (instancetype)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];

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    class func dateWithNaturalLanguageString(_ string: String) -> AnyObject?

    Objective-C

    + (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.)

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    class func dateWithNaturalLanguageString(_ string: String, locale localeDictionary: AnyObject?) -> AnyObject?

    Objective-C

    + (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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

  • 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).

    Declaration

    Swift

    class func dateWithString(_ aString: String) -> AnyObject

    Objective-C

    + (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).

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    + (instancetype)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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • init() init Designated Initializer

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

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Return Value

    An NSDate object initialized to the current date and time.

    Discussion

    This method is a designated initializer for NSDate.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    convenience init?(string description: String)

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    convenience init(timeIntervalSinceNow seconds: NSTimeInterval)

    Objective-C

    - (instancetype)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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    convenience init(timeInterval seconds: NSTimeInterval, sinceDate refDate: NSDate)

    Objective-C

    - (instancetype)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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init(timeIntervalSinceReferenceDate seconds: NSTimeInterval)

    Objective-C

    - (instancetype)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 a 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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    convenience init(timeIntervalSince1970 seconds: NSTimeInterval)

    Objective-C

    - (instancetype)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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    class func distantFuture() -> AnyObject

    Objective-C

    + (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];

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    + distantPast

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

    Declaration

    Swift

    class func distantPast() -> AnyObject

    Objective-C

    + (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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    + distantFuture

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

    Declaration

    Swift

    func isEqualToDate(_ anotherDate: NSDate) -> Bool

    Objective-C

    - (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 NOfalse.

    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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the earlier of the receiver and another given date.

    Declaration

    Swift

    func earlierDate(_ anotherDate: NSDate) -> NSDate

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – compare:
    isEqual: (NSObject protocol)
    – laterDate:

  • Returns the later of the receiver and another given date.

    Declaration

    Swift

    func laterDate(_ anotherDate: NSDate) -> NSDate

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – compare:
    – earlierDate:
    isEqual: (NSObject protocol)

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

    Declaration

    Swift

    func compare(_ anotherDate: NSDate) -> NSComparisonResult

    Objective-C

    - (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:

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

    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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    – earlierDate:
    isEqual: (NSObject protocol)
    – laterDate:

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

    Declaration

    Swift

    func dateByAddingTimeInterval(_ seconds: NSTimeInterval) -> Self!

    Objective-C

    - (instancetype)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.

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.6 and later.

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

    Deprecation Statement

    This method has been replaced by dateByAddingTimeInterval:.

    Declaration

    Objective-C

    - (id)addTimeInterval:(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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • A string representation of the date object. (read-only)

    Declaration

    Swift

    var description: String { get }

    Objective-C

    @property(readonly, copy) NSString *description

    Discussion

    The representation is useful for debugging only.

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func descriptionWithCalendarFormat(_ formatString: String?, timeZone aTimeZone: NSTimeZone?, locale localeDictionary: AnyObject?) -> String?

    Objective-C

    - (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]);

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    func descriptionWithLocale(_ locale: AnyObject?) -> String?

    Objective-C

    - (NSString *)descriptionWithLocale:(id)locale

    Parameters

    locale

    An NSLocale object.

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

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Converts the receiver to an NSCalendarDate object with a given format string and time zone.

    Deprecation Statement

    Use the NSDate methods to set the individual date values.

    Declaration

    Swift

    func dateWithCalendarFormat(_ formatString: String?, timeZone timeZone: NSTimeZone?) -> NSCalendarDate

    Objective-C

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.10.

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

    Declaration

    Swift

    var NSTimeIntervalSince1970: Double { get }

    Objective-C

    #define NSTimeIntervalSince1970 978307200.0

    Constants

    • NSTimeIntervalSince1970

      NSTimeIntervalSince1970

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

      Available in OS X v10.0 and later.

    Discussion

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

    Import Statement

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

    Import Statement

    import Foundation

    Availability

    Available in OS X v10.6 and later.