Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSDate

Inherits from
Implements
Package
com.apple.cocoa.foundation
Companion guides

Class at a Glance

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

Principal Attributes

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

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:

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

Creating an NSDate Instance

Comparing Dates

Getting Time Intervals

Representing Dates as Strings

Working with Milliseconds

Constructors

NSDate

Creates an NSDate set to the current date and time.

public NSDate()

Creates an NSDate relative to the absolute reference date (the first instant of 1 January 2001, GMT) by the specified number of seconds (plus or minus).

public NSDate(double seconds)

Creates an NSDate relative to refDate by a specified number of seconds (plus or minus).

public NSDate(double seconds, NSDate refDate)

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

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

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

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

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

earlierDate

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

public NSDate earlierDate(NSDate anotherDate)

See Also

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

laterDate

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

public NSDate laterDate(NSDate anotherDate)

See Also

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

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

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

toString

Returns a string representation of the receiver.

public String toString()

Constants

NSDate provides the following constants as a convenience:

Constant

Type

Description

DateFor1970

NSDate

Date object for 1 January 1970

TimeIntervalSince1970

double

Seconds from 1 January 1970 to reference date, 1 January 2001



Next Page > Hide TOC


© 1997, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.