Class

NSDate

NSDate objects encapsulate a single point in time, independent of any particular calendrical system or time zone. Date objects are immutable, representing an invariant time interval relative to an absolute reference date (00:00:00 UTC on 1 January 2001).

Overview

The NSDate class provides methods for comparing dates, calculating the time interval between two dates, and creating a new date from a time interval relative to another date. NSDate objects can be used in conjunction with DateFormatter objects to create localized representations of dates and times, as well as with NSCalendar objects to perform calendar arithmetic.

NSDate is “toll-free bridged” with its Core Foundation counterpart, CFDate. 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:

  • 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 init(timeIntervalSinceReferenceDate:), one of the designated initializer methods.

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 (00:00:00 UTC on 1 January 2001). If it does, it must still use the absolute reference date in its implementations of the methods timeIntervalSinceReferenceDate and init(timeIntervalSinceReferenceDate:). 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.

Symbols

Creating and Initializing Date Objects

class func date(withNaturalLanguageString: String)

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

Deprecated
class func date(withNaturalLanguageString: String, locale: Any?)

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

Deprecated
class func date(with: String)

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

Deprecated
init()

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

init?(string: String)

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

Deprecated
init(timeIntervalSinceNow: TimeInterval)

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

init(timeInterval: TimeInterval, since: Date)

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

init(timeIntervalSinceReferenceDate: TimeInterval)

Returns an NSDate object initialized relative to 00:00:00 UTC on 1 January 2001 by a given number of seconds.

init(timeIntervalSince1970: TimeInterval)

Returns an NSDate object initialized relative to 00:00:00 UTC on 1 January 1970 by a given number of seconds.

Comparing Dates

func isEqual(to: Date)

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

func earlierDate(Date)

Returns the earlier of the receiver and another given date.

func laterDate(Date)

Returns the later of the receiver and another given date.

func compare(Date)

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

Getting Time Intervals

func timeIntervalSince(Date)

Returns the interval between the receiver and another given date.

var timeIntervalSinceNow: TimeInterval

The time interval between the date object and the current date and time.

class var timeIntervalSinceReferenceDate: TimeInterval
var timeIntervalSinceReferenceDate: TimeInterval

Returns the interval between the date object and 00:00:00 UTC on 1 January 2001.

var timeIntervalSince1970: TimeInterval

The interval between the date object and 00:00:00 UTC on 1 January 1970.

Adding a Time Interval

func addingTimeInterval(TimeInterval)

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

Representing Dates as Strings

var description: String

A string representation of the date object.

func description(withCalendarFormat: String?, timeZone: TimeZone?, locale: Any?)

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

Deprecated
func description(with: Any?)

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

Converting to an NSCalendarDate Object

func date(withCalendarFormat: String?, timeZone: TimeZone?)

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

Deprecated

Constants

NSTimeIntervalSince1970

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

Notifications

static let NSSystemClockDidChange: NSNotification.Name

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.