NSCalendarDate

Inherits From: NSDate : NSObject

Conforms To: NSCoding, NSCopying (NSDate) NSObject (NSObject)

Declared In: Foundation/NSDate.h

Class Description

NSCalendarDate is a public subclass of NSDate that defines concrete date objects. These objects have time zones and format strings bound to them and are especially suited for representing and manipulating dates according to western calendrical systems.

By drawing on the behavior of the NSTimeZone class, NSCalendarDate objects adjust their visible representations to reflect their associated time zones. Because of this, you can track an NSCalendarDate object across different time zones. You can also present date information from time-zone viewpoints other than the one for the current locale.

Each NSCalendarDate object also has a calendar format string bound to it. This format string contains date-conversion specifiers that are very similar to those used in the standard C library function strftime(). By reference to this format string, NSCalendarDate can interpret dates that are represented as strings conforming to the format. Several methods allow you to specify formats other than the one bound to the object, and setCalendarFormat: lets you change the default format string for an NSCalendarDate object.

NSCalendarDate provides both class and instance methods for obtaining initialized objects. Some of these methods allow you to initialize date objects from strings while others initialize objects from sets of integers corresponding the standard time values (months, hours, seconds, etc.). As always, you are responsible for deallocating any objects obtained through an alloc... or copy... method.

To retrieve conventional elements of a date, use the methods of the form dayOfWeek, monthOfYear, and so on. For example, dayOfWeek returns a number that indicates the day of the week (0 is Sunday). The monthOfYear method returns a number from 1 to 12 that indicates the month.

NSCalendarDate provides several methods for representing dates as strings. These methodsdescription, descriptionWithLocale:, descriptionWithCalendarFormat:, and descriptionWithCalendarFormat:timeZone:take an implicit or explicit format string.

NSCalendarDate performs date computations based on western calendar systems, primarily the Gregorian. (The algorithms are derived from public domain software described in Calendrical Calculations, a two-part series by Nachum Dershowitz and Edward M. Reingold in SoftwarePractice and Experience).

General Exceptions

NSCalendarDate will raise NSInvalidArgumentException in the general case where numeric character strings to specify years, months, days, and so on, are not valid numbers.

Getting and Initializing an NSCalendar Date

• + (NSCalendarDate *)calendarDate Returns an NSCalendarDate initialized to the current date and time.
• + (NSCalendarDate *)dateWithString:(NSString *)description calendarFormat:(NSString *)format Returns an NSCalendarDate object initialized with the date specified in description and interpreted according the the conversion specifiers in format. Raises NSInvalidArgumentException if the description and format do not correspond exactly.
• + (NSCalendarDate *)dateWithString:(NSString *)description calendarFormat:(NSString *)format Returns an NSCalendarDate object initialized with the date locale:(NSDictionary *)dictionary date specified in description and interpreted according the the conversion specifiers in format. String components of the date are fetched from the locale dictionary. Raises NSInvalidArgumentException if the description and format do not correspond exactly.
• + (NSCalendarDate *)dateWithYear:(int)year Returns an NSCalendarDate object initialized with integers month:(unsigned int)month that specify a year (which must include the day:(unsigned int)day century), month, day, hour, minute, and second. Also hour:(unsigned int)hour include a time-zone object or time-zone detail object minute:(unsigned int)minute (aTimeZone) to have the date adjusted to a particular second:(unsigned int)second locale. If you specify nil for a time zone, timeZone:(NSTimeZone *)aTimeZone NSInvalidArgumentException is raised. (See "Retrieving Date Elements," below, for the proper ranges of the date and time integers.)
• - (id)initWithString:(NSString *)description Initializes and returns an NSCalendarDate object specified by description in the international format for date representation (YYYY-MM-DD HH:MM:SS - HHMM, where - HHMM is an offset from GMT).
• - (id)initWithString:(NSString *)description Initializes and returns an NSCalendarDate object specified calendarFormat:(NSString *)format as a string object in description and interpreted according to the extended strftime() date-conversion specifiers in format. Raises NSInvalidArgumentException if the description and format do not correspond exactly.
• - (id)initWithString:(NSString *)description Initializes and returns an NSCalendarDate object specified calendarFormat:(NSString *)format as a string object in description and interpreted locale:(NSDictionary *)dictionary according to the extended strftime date-conversion specifiers in format. String components of the date are fetched from the locale dictionary. Raises an NSInvalidArgumentException if the description and format do not correspond exactly.
• - (id)initWithYear:(int)year Returns an NSCalendarDate object initialized with integers month:(unsigned int)month that specify a year (which must include the day:(unsigned int)day century), month, day, hour, minute, and second. Also hour:(unsigned int)hour include a time-zone object (aTimeZone) to have the minute:(unsigned int)minute date adjusted for a particular locale. Raises an second:(unsigned int)second NSInvalidArgumentException if you specify nil for a timeZone:(NSTimeZone *)aTimeZone time zone. (See "RetrievingDate Elements," below, for the proper ranges of the date and time integers.)

• - (int)dayOfCommonEra Returns the number of days since the beginning of the Common Era.
• - (int)dayOfMonth Returns the day of the month (1 through 31) of the NSCalendarDate object.
• - (int)dayOfWeek Returns a number indicating the day of the week (0 [Sun] through 6 [Sat]) of the NSCalendarDate object.
• - (int)dayOfYear Returns a number indicating the day of the year (1 through 366) of the NSCalendarDate object.
• - (int)hourOfDay Returns a number indicating the hour of the day (0 through 23) of the NSCalendarDate object.
• - (int)minuteOfHour Returns a number indicating the minute of the hour (0 through 59) of the NSCalendarDate object.
• - (int)monthOfYear Returns a number indicating the month of the year (1 through 12) of the NSCalendarDate object.
• - (int)secondOfMinute Returns a number indicating the second of the minute (0 through 59) of the NSCalendarDate object.
• - (int)yearOfCommonEra Returns a number indicating the year, including the century, of the NSCalendarDate object.

• - (NSCalendarDate *)addYear:(int)year Returns an NSCalendarDate objects with the year, month, month:(int)month day, hour, minute, and second offsets specified as day:(int)day arguments and the correct time-zone detail object for hour:(int)hour the computed date. These offsets are relative to the minute:(int)minute object and can be positive or negative. This method second:(int)second preserves clock time during transitions to and from Daylight Savings Time and on leap years.

• - (NSString *)description Returns a string description of the receiver's date using the default format string (%Y-%m-%d %H:%M:%S %z) and the locale and time-zone information associated with the receiver.
• - (NSString *)descriptionWithCalendarFormat:(NSString *)format Returns a string description of the receiver's date that is formatted according to the conversion specifiers in format and using the locale and time-zone detail information associated with the receiver.
• - (NSString *)descriptionWithCalendarFormat:(NSString *)format locale:(NSDictionary *)locale Returns a string description of the receiver's date that is formatted according to the conversion specifiers in format, represented according to the locale information in locale, and adjusted according to the time-zone detail information associated with the receiver.
• - (NSString *)descriptionWithLocale:(NSDictionary *)locale Returns a string description of the receiver's date using the default format string (%Y-%m-%d %H:%M:%S %z), with information localized according to the locale information in locale, and using the time zone information associated with the receiver.

• - (NSString *)calendarFormat Returns the calendar format (a string of date-conversion specifiers) for the receiving object. The default calendar format is %Y-%m-%d %H:%M:%S %z.
• - (void)setCalendarFormat:(NSString *)format Sets the calendar format for the receiving object to format.

• - (void)setTimeZone:(NSTimeZone *)aTimeZone Sets the time-zone object associated with the NSCalendarDate object to aTimeZone.
• - (NSTimeZoneDetail *)timeZoneDetail Returns the NSTimeZoneDetail object associated with the receiver.