Up

# NSDate class reference

### Authors

Jeremy Bettis (`jeremy@hksys.com`)
Scott Christley (`scottc@net-community.com`)
Richard Frith-Macdonald (`richard@brainstorm.co.uk`)

Version: 34117

Date: 2011-11-04 04:38:16 -0600 (Fri, 04 Nov 2011)

Copyright: (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc.

# Software documentation for the NSDate class

## NSDate : NSObject

> Declared in:
>   Foundation/NSDate.h

> Conforms to:
>   NSCoding
>   NSCopying

Availability: OpenStep
An `NSDate` object encapsulates a constant date/time to a high resolution represented by the `NSTimeInterval` typedef. `NSDate` has methods relating to times and time differences in the abstract, but not calendar dates or time zones. These features are added in the NSCalendarDate subclass. The NSTimeZone class handles time zone information.
Method summary

- +date
- +dateWithNaturalLanguageString:
- +dateWithNaturalLanguageString:locale:
- +dateWithString:
- +dateWithTimeIntervalSince1970:
- +dateWithTimeIntervalSinceNow:
- +dateWithTimeIntervalSinceReferenceDate:
- +distantFuture
- +distantPast
- +timeIntervalSinceReferenceDate
- -addTimeInterval:
- -compare:
- -dateWithCalendarFormat:timeZone:
- -description
- -descriptionWithCalendarFormat:timeZone:locale:
- -descriptionWithLocale:
- -earlierDate:
- -initWithString:
- -initWithTimeInterval:sinceDate:
- -initWithTimeIntervalSince1970:
- -initWithTimeIntervalSinceNow:
- -initWithTimeIntervalSinceReferenceDate:
- -isEqualToDate:
- -laterDate:
- -timeIntervalSince1970
- -timeIntervalSinceDate:
- -timeIntervalSinceNow
- -timeIntervalSinceReferenceDate

### date

+ (id) date;
Availability: OpenStep
Returns an autoreleased instance representing the current date/time.

### dateWithNaturalLanguageString:

+ (id) dateWithNaturalLanguageString: (NSString*)string;
Availability: MacOS-X 10.0.0
Returns an autoreleased instance representing the date and time given by string. The value of string may be a 'natural' specification as specified by the preferences in the user defaults database, allowing phrases like 'last tuesday'

### dateWithNaturalLanguageString: locale:

+ (id) dateWithNaturalLanguageString: (NSString*)string locale: (NSDictionary*)locale;
Availability: MacOS-X 10.0.0

Returns an autoreleased instance representing the date and time given by string. The value of string may be a 'natural' specification as specified by the preferences in the user defaults database, allowing phrases like 'last tuesday'

The locale contains keys such as -

NSDateTimeOrdering
  Controls the use of ambiguous numbers. This is done as a sequence of the letters D(ay), M(onth), Y(ear), and H(our). YMDH means that the first number encountered is assumed to be a year, the second a month, the third a day, and the last an hour.
NSEarlierTimeDesignations
  An array of strings for times in the past.
  Defaults are ago, last, past, prior
NSHourNameDesignations
  An array of arrays of strings identifying the time of day. Each array has an hour as its first value, and one or more words as subsequent values.
  Defaults are: (0, midnight), (10, morning), (12, noon, lunch), (14, afternoon), (19, dinner).
NSLaterTimeDesignations
  An array of strings for times in the future.
  Default is next
NSNextDayDesignations
  The day after today. Default is tomorrow.
NSNextNextDayDesignations
  The day after tomorrow. Default is nextday.
NSPriorDayDesignations
  The day before today. Default is yesterday.
NSThisDayDesignations
  Identifies the current day. Default is today.
NSYearMonthWeekDesignations
  An array giving the word for year, month, and week.
  Defaults are year, month and week.

### dateWithString:

+ (id) dateWithString: (NSString*)description;
Availability: OpenStep
Returns an autoreleased instance with the date and time value given by the string using the ISO standard format YYYY-MM-DD HH:MM:SS +/-HHHMM (all the fields of which must be present).

### dateWithTimeIntervalSince1970:

+ (id) dateWithTimeIntervalSince1970: (NSTimeInterval)seconds;
Availability: OpenStep
Returns an autoreleased instance with the offset from the unix system reference date of 1 January 1970, GMT.

### dateWithTimeIntervalSinceNow:

+ (id) dateWithTimeIntervalSinceNow: (NSTimeInterval)seconds;
Availability: OpenStep
Returns an autoreleased instance with the offset from the current date/time given by seconds (which may be fractional).

### dateWithTimeIntervalSinceReferenceDate:

+ (id) dateWithTimeIntervalSinceReferenceDate: (NSTimeInterval)seconds;
Availability: OpenStep
Returns an autoreleased instance with the offset from the OpenStep reference date of 1 January 2001, GMT.

### distantFuture

+ (id) distantFuture;
Availability: OpenStep
Returns an autoreleased instance with th date/time set in the far future.

### distantPast

+ (id) distantPast;
Availability: OpenStep
Returns an autoreleased instance with th date/time set in the far past.

### timeIntervalSinceReferenceDate

+ (NSTimeInterval) timeIntervalSinceReferenceDate;
Availability: OpenStep
Returns the time interval between the current date and the reference date (1 January 2001, GMT).

### addTimeInterval:

- (id) addTimeInterval: (NSTimeInterval)seconds;
Availability: OpenStep
Returns an autoreleased NSDate instance whose value if offset from that of the receiver by seconds.

### compare:

- (NSComparisonResult) compare: (NSDate*)otherDate;
Availability: OpenStep
Returns NSOrderedDescending if the receiver is later than otherDate, Returns NSOrderedAscending if the receiver is earlier than otherDate, Otherwise, returns NSOrderedSame.

### dateWithCalendarFormat: timeZone:

- (NSCalendarDate*) dateWithCalendarFormat: (NSString*)formatString timeZone: (NSTimeZone*)timeZone;
Availability: OpenStep
Returns an autoreleased instance of the NSCalendarDate class whose date/time value is the same as that of the receiver, and which uses the formatString and timeZone specified.

### description

- (NSString*) description;
Availability: OpenStep
Returns a string representation of the receiver formatted according to the default format string, time zone, and locale.

### descriptionWithCalendarFormat: timeZone: locale:

- (NSString*) descriptionWithCalendarFormat: (NSString*)format timeZone: (NSTimeZone*)aTimeZone locale: (NSDictionary*)l;
Availability: OpenStep
Returns a string representation of the receiver formatted according to the specified format string, time zone, and locale.

### descriptionWithLocale:

- (NSString*) descriptionWithLocale: (id)locale;
Availability: OpenStep
Returns a string representation of the receiver formatted according to the default format string and time zone, but using the given locale.

### earlierDate:

- (NSDate*) earlierDate: (NSDate*)otherDate;
Availability: OpenStep
Returns the earlier of the receiver and otherDate.
If the two represent identical date/time values, returns the receiver.

### initWithString:

- (id) initWithString: (NSString*)description;
Availability: OpenStep
Returns an instance with the date and time value given by the string using the ISO standard format YYYY-MM-DD HH:MM:SS +/-HHHMM (all the fields of which must be present).

### initWithTimeInterval: sinceDate:

- (id) initWithTimeInterval: (NSTimeInterval)secsToBeAdded sinceDate: (NSDate*)anotherDate;
Availability: OpenStep
Returns an instance with the given offset from anotherDate.

### initWithTimeIntervalSince1970:

- (id) initWithTimeIntervalSince1970: (NSTimeInterval)seconds;
Availability: MacOS-X 10.0.0
Returns an instance with the offset from the unix system reference date of 1 January 1970, GMT.

### initWithTimeIntervalSinceNow:

- (id) initWithTimeIntervalSinceNow: (NSTimeInterval)secsToBeAdded;
Availability: OpenStep
Returns an instance with the offset from the current date/time.

### initWithTimeIntervalSinceReferenceDate:

- (id) initWithTimeIntervalSinceReferenceDate: (NSTimeInterval)secs;
Availability: OpenStep
This is a designated initialiser for the class.
Returns an instance with the given offset from the OpenStep reference date of 1 January 2001, GMT.

### isEqualToDate:

- (BOOL) isEqualToDate: (NSDate*)other;
Availability: OpenStep
Returns whether the receiver is exactly equal to other, to the limit of the NSTimeInterval precision.
This is the behavior of the current MacOS-X system, not that of the OpenStep specification (which counted two dates within a second of each other as being equal).
The old behavior meant that two dates equal to a third date were not necessarily equal to each other (confusing), and meant that there was no reasonable way to use a date as a dictionary key or store dates in a set.

### laterDate:

- (NSDate*) laterDate: (NSDate*)otherDate;
Availability: OpenStep
Returns the earlier of the receiver and otherDate.
If the two represent identical date/time values, returns the receiver.

### timeIntervalSince1970

- (NSTimeInterval) timeIntervalSince1970;
Availability: OpenStep
Returns the time interval between the receivers value and the unix system reference date of 1 January 1970, GMT.

### timeIntervalSinceDate:

- (NSTimeInterval) timeIntervalSinceDate: (NSDate*)otherDate;
Availability: OpenStep
Returns the time interval between the receivers value and that of the otherDate argument. If otherDate is earlier than the receiver, the returned value will be positive, if it is later it will be negative.
For current (2011) OSX compatibility, this method returns NaN if otherDate is `nil`... do not write code depending on that behavior.

### timeIntervalSinceNow

- (NSTimeInterval) timeIntervalSinceNow;
Availability: OpenStep
Returns the time interval between the receivers value and the current date/time. If the receiver represents a date/time in the past this will be negative, if it is in the future the returned value will be positive.

### timeIntervalSinceReferenceDate

- (NSTimeInterval) timeIntervalSinceReferenceDate;
Availability: OpenStep
Returns the time interval between the receivers value and the OpenStep reference date of 1 Jan 2001 GMT.

Up