Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 methodsÐdescription, 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 SoftwareÐPractice 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.)

Retrieving Date Elements

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

Providing Adjusted Dates 

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

Getting String Descriptions of Dates 

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

Getting and Setting Calendar Formats 

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

Getting and Setting Time Zones 

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