Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.


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

Retrieving Date Elements

Providing Adjusted Dates

Getting String Descriptions of Dates

Getting and Setting Calendar Formats

Getting and Setting Time Zones