Important: The information in this document is obsolete and should not be used for new development.
Inherits from | |
Implements | |
Package | com.apple.cocoa.foundation |
Companion guides |
An NSDate object stores a date and time that can be compared to other dates and times.
Seconds since absolute reference date (1 January 2001, GMT)
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.
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.
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.
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.
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.
timeIntervalSinceDate
timeIntervalSinceNow
currentTimeIntervalSinceReferenceDate
timeIntervalSinceReferenceDate
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)
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
()
.
Creates and returns an object representing a date in the distant future (in terms of centuries).
public static Object distantFuture
()
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.
Creates and returns an object representing a date in the distant past (in terms of centuries).
public static Object distantPast
()
You can use this object in your code as a control date, a guaranteed temporal boundary.
Converts a time span, milliseconds, measured in milliseconds, to a time interval, which is in seconds.
public static double millisecondsToTimeInterval
(long milliseconds)
Converts a time interval, seconds, which is in seconds, to milliseconds.
public static long timeIntervalToMilliseconds
(double seconds)
Compares the receiving date to anotherDate, using timeIntervalSinceDate
, and returns a value of type int.
public int compare
(NSDate anotherDate)
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.
Returns an NSDate object that is set to a specified number of seconds, seconds, relative to the receiver.
public NSDate dateByAddingTimeInterval
(double seconds)
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.
Compares the receiver date to anotherDate, using timeIntervalSinceDate
, and returns the earlier of the two.
public NSDate earlierDate
(NSDate anotherDate)
Returns true
if anObject is an instance of NSDate and satisfies isEqualToDate
.
public boolean equals
(Object anObject)
Returns false
otherwise.
Returns a hash value for the receiver.
public int hashCode
()
The hash value is the integer value of the time interval returned from timeIntervalSinceReferenceDate
.
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)
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.
Compares the receiver to anotherDate, using timeIntervalSinceDate
, and returns the later of the two.
public NSDate laterDate
(NSDate anotherDate)
Returns the interval between the receiver and anotherDate.
public double timeIntervalSinceDate
(NSDate anotherDate)
If the receiver is earlier than anotherDate, the return value is negative.
Returns the interval between the receiver and the current date and time.
public double timeIntervalSinceNow
()
If the receiver is earlier than the current date and time, the return value is negative.
Returns the interval between the receiver and the system’s absolute reference date, 1 January 2001, GMT.
public double timeIntervalSinceReferenceDate
()
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.
Returns a string representation of the receiver.
public String toString
()
NSDate provides the following constants as a convenience:
Constant |
Type |
Description |
---|---|---|
NSDate |
Date object for 1 January 1970 |
|
double |
Seconds from 1 January 1970 to reference date, 1 January 2001 |
© 1997, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)