---

NSDate

Class at a Glance

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

Principal Attributes

• Seconds since absolute reference date (1 January 2001, GMT)

Commonly Used Methods

earlierDate

Compares the receiver to the argument and returns the earlier of the two.

isEqualToDate

Returns true 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

• timeIntervalSinceReferenceDate

Overview

NSDate objects represent a single point in time. 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.

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. Its subclass NSGregorianDate offers date objects that are suitable for representing dates according to western calendrical systems.

NSDate’s sole primitive method, 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.

Subclassing Notes

The major reason for subclassing NSDate is to create a class that expresses a calendrical system other than the western, Gregorian calendar (for which Cocoa provides the NSCalendarDate class). 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.

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. See the NSCalendarDate class for examples of such methods.

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

Tasks

Constructors

• NSDate

Creating an NSDate Instance

• distantFuture
• distantPast
• dateByAddingTimeInterval

Comparing Dates

• isEqualToDate
• earlierDate
• laterDate
• compare
• equals
• hashCode

Getting Time Intervals

• timeIntervalSinceDate
• timeIntervalSinceNow
• currentTimeIntervalSinceReferenceDate
• timeIntervalSinceReferenceDate

Representing Dates as Strings

• toString

Working with Milliseconds

• millisecondsToTimeInterval
• timeIntervalToMilliseconds

Static Methods

currentTimeIntervalSinceReferenceDate

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

public static double currentTimeIntervalSinceReferenceDate()

Discussion

.

See Also

• timeIntervalSinceReferenceDate
• timeIntervalSinceDate
• timeIntervalSinceNow

distantFuture

Creates and returns an object representing a date in the distant future (in terms of centuries).

public static Object distantFuture()

Discussion

You can pass this value when an NSDate is required to have the date argument essentially ignored. For example, the NSWindow method nextEventMatchingMask returns null 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.

See Also

• distantPast

distantPast

Creates and returns an object representing a date in the distant past (in terms of centuries).

public static Object distantPast()

Discussion

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

See Also

• distantFuture

millisecondsToTimeInterval

Converts a time span, milliseconds, measured in milliseconds, to a time interval, which is in seconds.

public static double millisecondsToTimeInterval(long milliseconds)

timeIntervalToMilliseconds

Converts a time interval, seconds, which is in seconds, to milliseconds.

public static long timeIntervalToMilliseconds(double seconds)

Instance Methods

compare

Compares the receiving date to anotherDate, using timeIntervalSinceDate, and returns a value of type int.

public int compare(NSDate anotherDate)

Discussion

If the two dates are exactly equal to each other, this method returns OrderedSame. If the receiving object in the comparison is more recent than anotherDate, the method returns OrderedDescending. If the receiving object is older, this method returns OrderedAscending.

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

See Also

• earlierDate
• laterDate

dateByAddingTimeInterval

Returns an NSDate object that is set to a specified number of seconds, seconds, relative to the receiver.

public NSDate dateByAddingTimeInterval(double seconds)

Discussion

Use a negative value for seconds to have the returned object specify a date before the receiver. The date returned might have a representation different from the receiver’s.

See Also

• timeIntervalSinceDate

earlierDate

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

public NSDate earlierDate(NSDate anotherDate)

See Also

• compare
• laterDate

equals

Returns true if anObject is an instance of NSDate and satisfies isEqualToDate.

public boolean equals(Object anObject)

Discussion

Returns false otherwise.

hashCode

Returns a hash value for the receiver.

public int hashCode()

Discussion

The hash value is the integer value of the time interval returned from timeIntervalSinceReferenceDate.

isEqualToDate

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 their date and time values differ.

public boolean isEqualToDate(NSDate anotherDate)

Discussion

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

See Also

• compare
• earlierDate
• laterDate

laterDate

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

public NSDate laterDate(NSDate anotherDate)

See Also

• compare
• earlierDate

timeIntervalSinceDate

Returns the interval between the receiver and anotherDate.

public double timeIntervalSinceDate(NSDate anotherDate)

Discussion

If the receiver is earlier than anotherDate, the return value is negative.

See Also

• timeIntervalSinceNow
• currentTimeIntervalSinceReferenceDate

timeIntervalSinceNow

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

public double timeIntervalSinceNow()

Discussion

If the receiver is earlier than the current date and time, the return value is negative.

See Also

• timeIntervalSinceDate
• currentTimeIntervalSinceReferenceDate

timeIntervalSinceReferenceDate

Returns the interval between the receiver and the system’s absolute reference date, 1 January 2001, GMT.

public double timeIntervalSinceReferenceDate()

Discussion

If the receiver is earlier than the absolute reference date, the return value is negative.

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

See Also

• timeIntervalSinceDate
• timeIntervalSinceNow
• currentTimeIntervalSinceReferenceDate

toString

Returns a string representation of the receiver.

public String toString()

Constants

NSDate provides the following constants as a convenience:

---