- Inherits from:
- NSDate : NSObject
- Conforms to:
- NSCoding
- (NSDate)
- NSCopying (NSDate)
- NSObject (NSObject)
Declared in:
- Foundation/NSCalendarDate.h
NSCalendarDate is a public subclass of NSDate that represents concrete date objects and performs date computations based on the Gregorian calendar. These objects associate a time interval with a time zone and are especially suited for representing and manipulating dates according to western calendrical systems.
An NSCalendarDate object stores a date as the number of seconds relative to the absolute reference date (the first instance of 1 January 2001, GMT). Use the associated time zone to change how the NSCalendarDate object prints its time interval. The time zone does not change how the time interval is stored. Because the value is stored independent of the time zone, you can accurately compare NSCalendarDates with any other NSDate objects or use them to create other NSDate objects. It also means that you can track a date across different time zones; that is, you can create a new NSCalendarDate object with a different time zone to see how the particular date is represented in that time zone.
NSCalendarDate provides both class and instance methods for creating objects. Some of these methods allow you to initialize NSCalendarDate objects from strings while others create objects from sets of integers corresponding the standard time values (months, hours, seconds, and so on).
To retrieve conventional elements of an NSCalendarDate object, use the ...Of... methods. For example, dayOfWeek returns a number that indicates the day of the week (0 is Sunday). The monthOfYear method returns a number between 1 and 12 that indicates the month.
Each NSCalendarDate object has a calendar format associated with it. This format is a string that contains date-conversion specifiers that are very similar to those used in the standard C library function strftime(). NSCalendarDate interprets dates that are represented as strings conforming to this format. You can set the default format for an NSCalendarDate object at initialization time or using the setCalendarFormat: method. Several methods allow you to specify formats other than the one bound to the object.
The date conversion specifiers cover a range of date conventions:
Conversion Specifier | Description |
%% | a '%' character |
%a | abbreviated weekday name |
%A | full weekday name |
%b | abbreviated month name |
%B | full month name |
%c | shorthand for %X %x, the locale format for date and time |
%d | day of the month as a decimal number (01-31) |
%e | same as %d but does not print the leading 0 for days 1 through 9 |
%F | milliseconds as a decimal number (000-999) |
%H | hour based on a 24-hour clock as a decimal number (00-23) |
%I | hour based on a 12-hour clock as a decimal number (01-12) |
%j | day of the year as a decimal number (001-366) |
%m | month as a decimal number (01-12) |
%M | minute as a decimal number (00-59) |
%p | AM/PM designation for the locale |
%S | second as a decimal number (00-59) |
%w | weekday as a decimal number (0-6), where Sunday is 0 |
%x | date using the date representation for the locale |
%X | time using the time representation for the locale |
%y | year without century (00-99) |
%Y | year with century (such as 1990) |
%Z | time zone name (such as Pacific Daylight Time) |
%z | time zone offset in hours and minutes from GMT (HHMM) |
NSCalendarDate provides several description... methods for representing dates as strings. These methods- description, descriptionWithLocale:, descriptionWithCalendarFormat:, and descriptionWithCalendarFormat:locale:-take an implicit or explicit calendar format. The user's locale information affects the returned string. NSCalendarDate accesses the locale information as an NSDictionary. If you use descriptionWithLocale: or descriptionWithCalendarFormat:locale:, you can specify a different locale dictionary. The following keys in the locale dictionary affect NSCalendarDates:
Locale Key | Description |
NSTimeDateFormatString |
Specifies how dates with times are printed, affecting strings that use the format specifiers %c, %X, or %x. The default is to use abbreviated months and days with a 24 hour clock, as in "Sun Jan 01 23:00:00 +6 2001". |
NSAMPMDesignation |
Specifies how the morning and afternoon designations are printed, affecting strings that use the %p format specifier. The default is AM and PM. |
NSMonthNameArray |
Specifies the names for the months, affecting strings that use the %B format specifier. |
NSShortMonthNameArray |
Specifies the abbreviations for the months, affecting strings that use the %b format specifier. |
NSWeekDayNameArray |
Specifies the names for the days of the week, affecting strings that use the %A format specifier. |
NSShortWeekDayNameArray |
Specifies the abbreviations for the days of the week, affecting strings that use the %a format specifier. |
If you subclass NSCalendarDate and override description, you should also override descriptionWithLocale:. NSString's stringWithFormat: method uses descriptionWithLocale: instead of description when you use the %@ conversion specifier to print an NSCalendarDate. That is, this message:
[NSString stringWithFormat:@"The current date and time are %@", [MyNSCalendarDateSubclass date]]
will invoke descriptionWithLocale:.
- Creating an NSCalendarDate instance
- + calendarDate
- + dateWithString:calendarFormat:
- + dateWithString:calendarFormat:locale:
- + dateWithYear:month:day:hour:minute:second:timeZone:
- - initWithString:
- - initWithString:calendarFormat:
- - initWithString:calendarFormat:locale:
- - initWithYear:month:day:hour:minute:second:timeZone:
- Retrieving date elements
- - dayOfCommonEra
- - dayOfMonth
- - dayOfWeek
- - dayOfYear
- - hourOfDay
- - minuteOfHour
- - monthOfYear
- - secondOfMinute
- - yearOfCommonEra
- Adjusting a date
- - dateByAddingYears:months:days:hours:minutes:seconds:
- Computing date intervals
- - years:months:days:hours:minutes:seconds:sinceDate:
- Representing dates as NSStrings
- - description
- - descriptionWithCalendarFormat:
- - descriptionWithCalendarFormat:locale:
- - descriptionWithLocale:
- Getting and setting calendar formats
- - setCalendarFormat:
- - calendarFormat
- Getting and setting the time zone
- - setTimeZone:
- - timeZone
+ (id)calendarDate
Creates and returns a calendar date initialized to the current date and time.
See Also: + date (NSDate)
+ (id)dateWithString:(NSString
*)description
calendarFormat:(NSString *)format
Creates and returns a calendar date initialized with the date specified in the string description. NSCalendarDate uses format both to interpret the description string and as the default calendar format for this new object. format consists of conversion specifiers similar to those used in strftime(). See "The Calendar Format" in NSDateFormatter's Class Description for more information. If description does not match format exactly, this method returns nil.
For example, let's say your company's convention for dates on correspondence takes the form "Friday, 1 July 1994, 11:45 AM." To get an calendar date with a temporal value corresponding to this string, you would use this statement:
NSCalendarDate *today = [NSCalendarDate dateWithString:@"Friday, 1 July 1994, 11:45 AM" calendarFormat:@"%A, %d %B %Y, %I:%M %p"];
If you include a time zone in the description argument, this method verifies it and can substitute an alternative time zone. If the method does supply a new time zone, it applies the difference in offsets-from-GMT values between the substituted and the original time zone to the calendar date being created.
See Also: + dateWithString:calendarFormat:locale:, - calendarFormat, - initWithString:calendarFormat:
+ (id)dateWithString:(NSString
*)description
calendarFormat:(NSString *)format
locale:(NSDictionary *)locale
Creates and returns a calendar date initialized with the date specified in the string description. NSCalendarDate uses format both to interpret the description string and as the default calendar format for this new object. format consists of conversion specifiers similar to those used in strftime(). The keys and values that represent the locale data in locale are used when parsing the string. If description does not match format exactly, this method returns nil.
See "NSString Representations for NSCalendarDates" in the Class Description for a list of the appropriate locale dictionary keys. See "The Calendar Format" in NSDateFormatter's Class Description for a list of the date conversion specifiers.
See Also: + dateWithString:calendarFormat:, - calendarFormat, - initWithString:calendarFormat:locale:
+ (id)dateWithYear:(int)year
month:(unsigned)month
day:(unsigned)day
hour:(unsigned)hour
minute:(unsigned)minute
second:(unsigned)second
timeZone:(NSTimeZone *)aTimeZone
Creates and returns a calendar date initialized with the specified values for year, month, day, hour, minute, and second and the NSTimeZone object, aTimeZone. The year value must include the century (for example, 1995 instead of 95). The other values are the standard ones: 1 through 12 for months, 1 through 31 for days, 0 through 23 for hours and 0 through 59 for both minutes and seconds.
The following code fragment shows a calendar date created with a date on 4 July 1994, 9 PM, Eastern Standard Time ( timeZoneWithName: returns the NSTimeZone object that represents the time zone with the specified name).
NSCalendarDate *fireworks = [NSCalendarDate dateWithYear:1994 month:7 day:4 hour:21 minute:0 second:0 timeZone:[NSTimeZone timeZoneWithName:@"EST"]];
See Also: - initWithYear:month:day:hour:minute:second:timeZone:
- (NSString *)calendarFormat
Returns the receiver's default calendar format (used when the format is unspecified). You can set this format when you create the calendar date using one of the class methods dateWithString:calendarFormat: or dateWithString:calendarFormat:locale:, or you can change the format using the instance method setCalendarFormat:. If you do not specify a default calendar format, NSCalendarDate substitutes its own default: an international format of "%Y-%m-%d %H:%M:%S %z" (for example, 1994-01-14 16:45:12 +0900). See "The Calendar Format" in NSDateFormatter's Class Description for more information on what a calendar format contains.
See Also: - descriptionWithLocale:
- (NSCalendarDate *)dateByAddingYears:(int)year
months:(int)month
days:(int)day
hours:(int)hour
minutes:(int)minute
seconds:(int)second
Returns a calendar date that is updated with the year, month, day, hour, minute, and second offsets specified as arguments. The offsets can be positive (future) or negative (past). This method preserves "clock time" across changes in Daylight Savings Time zones and leap years. For example, adding one month to a calendar date with a time of 12 noon correctly maintains time at 12 noon.
The following code fragment shows a calendar date created with a date a week later than an existing calendar date.
NSCalendarDate *now = [NSCalendarDate calendarDate]; NSCalendarDate *nextWeek = [now dateByAddingYears:0 months:0 days:7 hours:0 minutes:0 seconds:0];
See Also: - years:months:days:hours:minutes:seconds:sinceDate:
- (int)dayOfCommonEra
Returns the number of days since the beginning of the Common Era. The base year of the Common Era is 1 C.E. (which is the same as 1 A.D.).
See Also: - dayOfMonth, - dayOfWeek, - dayOfYear, - hourOfDay, - minuteOfHour, - monthOfYear, - secondOfMinute, - yearOfCommonEra
- (int)dayOfMonth
Returns a number that indicates the day of the month (1 through 31) of the receiver.
See Also: - dayOfCommonEra, - dayOfWeek, - dayOfYear, - hourOfDay, - minuteOfHour, - monthOfYear, - secondOfMinute, - yearOfCommonEra
- (int)dayOfWeek
Returns a number that indicates the day of the week (0 through 6) of the receiver; 0 indicates Sunday.
See Also: - dayOfCommonEra, - dayOfMonth, - dayOfYear, - hourOfDay, - minuteOfHour, - monthOfYear, - secondOfMinute, - yearOfCommonEra
- (int)dayOfYear
Returns a number that indicates the day of the year (1 through 366) of the receiver.
See Also: - dayOfCommonEra, - dayOfMonth, - dayOfWeek, - hourOfDay, - minuteOfHour, - monthOfYear, - secondOfMinute, - yearOfCommonEra
- (NSString *)description
Returns a string representation of the receiver. The string is formatted as specified by the receiver's default calendar format. You can find out what the default calendar format is using the method calendarFormat.
Because NSCalendarDate implements descriptionWithLocale:, descriptionWithLocale: is used to print the date when you use the %@ conversion specifier. That is, the following statement invokes descriptionWithLocale:, not description.
NSLog(@"The current date and time is %@", [NSCalendarDate date]);
See Also: - descriptionWithCalendarFormat:, - descriptionWithCalendarFormat:locale:, - descriptionWithLocale:, - setCalendarFormat:
- (NSString *)descriptionWithCalendarFormat:(NSString
*)format
Returns a string representation of the receiver. The string is formatted as specified by the conversion specifiers in the calendar format string format. The conversion specifiers cover a range of date conventions. See "The Calendar Format" in NSDateFormatter's Class Description for a listing of these specifiers.
This example displays the current date formatted as "Tues 3/1/94 3:30 PM" in a text field:
NSCalendarDate *now = [NSCalendarDate calendarDate]; NSString *datestr = [now descriptionWithCalendarFormat:@"%a %m/%d/%y %I:%M %p"]; [dateField setStringValue:datestr];
See Also: - description, - descriptionWithCalendarFormat:locale:, - descriptionWithLocale:
- (NSString *)descriptionWithCalendarFormat:(NSString
*)format
locale:(NSDictionary *)locale
Returns a string representation of the receiver. The string is formatted according to the conversion specifiers in format and represented according to the locale information in locale. See "NSString Representations for NSCalendarDates" in the Class Description for a list of the appropriate locale dictionary keys. See "The Calendar Format" in NSDateFormatter's Class Description for a list of the date conversion specifiers.
See Also: - description, - descriptionWithCalendarFormat:, - descriptionWithLocale:
- (NSString *)descriptionWithLocale:(NSDictionary
*)locale
Returns a string representation of the receiver. The string is formatted as specified by the receiver's default calendar format and represented according to the locale information in locale. You can find out what the default calendar format is using the method calendarFormat. See "NSString Representations for NSCalendarDates" in the Class Description for a list of the locale dictionary keys that affect calendar formats.
This method is used to print the NSCalendarDate when the %@ conversion specifier is used. That is, this statement invokes descriptionWithLocale:.
NSLog(@"The current date and time is %@", [NSCalendarDate date]);
See Also: - description, - descriptionWithCalendarFormat:, - descriptionWithCalendarFormat:locale:, - setCalendarFormat:
- (int)hourOfDay
Returns the hour value (0 through 23) of the receiver. On Daylight Savings "fall back" days, a value of 1 is returned for two consecutive hours, but with a different time zone (the first in daylight savings time and the second in standard time).
See Also: - dayOfCommonEra, - dayOfMonth, - dayOfWeek, - dayOfYear, - minuteOfHour, - monthOfYear, - secondOfMinute, - yearOfCommonEra
- (id)initWithString:(NSString
*)description
Returns a calendar date initialized with the date specified as a string in description. The description string must conform to the default calendar format "%Y-%m-%d %H:%M:%S %z" (for example, 1994-01-14 16:45:12 +0900). If description does not match this format exactly, this method returns nil. See "The Calendar Format" in NSDateFormatter's Class Description for a discussion of date conversion specifiers.
- (id)initWithString:(NSString
*)description
calendarFormat:(NSString *)format
Returns a calendar date initialized with the date specified as a string in description. This method uses format both to interpret the description string and as the default calendar format for this object. format consists of conversion specifiers similar to those used in strftime(). See "The Calendar Format" in NSDateFormatter's Class Description for a listing of these specifiers. If description does not match format exactly, this method returns nil.
For example, let's assume you want to initialize a calendar date object with a string obtained from a text field. This date string takes the form "03.21.94 22:00 PST":
NSCalendarDate *newDate = [[[NSCalendarDate alloc] initWithString:[dateField stringValue] calendarFormat:@"%m.%d.%y %H:%M %Z"] autorelease];
See Also: + dateWithString:calendarFormat:, - calendarFormat
- (id)initWithString:(NSString
*)description
calendarFormat:(NSString *)format
locale:(NSDictionary *)locale
Returns a calendar date initialized with the date specified in the string description. NSCalendarDate uses format both to interpret the description string and as the default calendar format for this object. format consists of conversion specifiers similar to those used in strftime(). The keys and values that represent the locale data from locale are used when parsing the string. See "NSString Representations for NSCalendarDates" in the Class Description for a list of the appropriate locale dictionary keys. See "The Calendar Format" in NSDateFormatter's Class Description for a list of the date conversion specifiers.
If you specify a locale dictionary that has a month name array with more than 12 elements or a day name array with more than 7 arguments, initWithString:calendarFormat:locale: returns nil.
See Also: + dateWithString:calendarFormat:locale:, - calendarFormat
- (id)initWithYear:(int)year
month:(unsigned)month
day:(unsigned)day
hour:(unsigned)hour
minute:(unsigned)minute
second:(unsigned)second
timeZone:(NSTimeZone *)aTimeZone
Returns a calendar date initialized with the specified values for year, month, day, hour, minute, and second and the NSTimeZone object, aTimeZone. The year value must include the century (for example, 1995 instead of 95). The other values are the standard ones: 1 through 12 for months, 1 through 31 for days, 0 through 23 for hours and 0 through 59 for both minutes and seconds.
The following code fragment shows a calendar date created with a date on 4 July 1994, 9 PM, Eastern Standard Time (timeZoneWithName: returns the NSTimeZone object that represents the time zone with the specified name).
NSCalendarDate *fireworks = [[[NSCalendarDate alloc] initWithYear:1994 month:7 day:4 hour:21 minute:0 second:0 timeZone:[NSTimeZone timeZoneWithName:@"EST"]] autorelease];
See Also: + dateWithYear:month:day:hour:minute:second:timeZone:
- (int)minuteOfHour
Returns the minutes value (0 through 59) of the receiver.
See Also: - dayOfCommonEra, - dayOfMonth, - dayOfWeek, - dayOfYear, - hourOfDay, , - monthOfYear, - secondOfMinute, - yearOfCommonEra
- (int)monthOfYear
Returns a number that indicates the month of the year (1 through 12) of the receiver.
See Also: - dayOfCommonEra, - dayOfMonth, - dayOfWeek, - dayOfYear, - hourOfDay, , - minuteOfHour, - secondOfMinute, - yearOfCommonEra
- (int)secondOfMinute
Returns the seconds value (0 through 59) of the receiver.
See Also: - dayOfCommonEra, - dayOfMonth, - dayOfWeek, - dayOfYear, - hourOfDay, , - minuteOfHour, - monthOfYear, - yearOfCommonEra
- (void)setCalendarFormat:(NSString
*)format
Sets the default calendar format for the receiver. A calendar format is a string formatted with date-conversion specifiers. If you do not specify a calendar format for an object, NSCalendarDate substitutes its own default. This is the international format of "%Y-%m-%d %H:%M:%S %z" (for example, 1994-01-14 16:45:12 +0900). See "The Calendar Format" in NSDateFormatter's Class Description for a list of the date conversion specifiers
See Also: - calendarFormat, - description, - descriptionWithLocale:
- (void)setTimeZone:(NSTimeZone
*)aTimeZone
Sets the time zone for the receiver. If you do not specify a time zone for an object at initialization time, NSCalendarDate uses the default time zone for the locale. Use this method to set it to another time zone.
See Also: - timeZone
- (NSTimeZone *)timeZone
Returns the time zone object associated with the receiver. You can set the time zone when you create the calendar date using the class methods dateWithString:calendarFormat: or dateWithString:calendarFormat:locale: by including the time zone in the description and format arguments. Or you can explicitly set the time zone to an NSTimeZone object using dateWithYear:month:day:hour:minute:second:timeZone:. If you do not specify a time zone for an object at initialization time, NSCalendarDate uses the default time zone for the locale.
See Also: - setTimeZone:
- (int)yearOfCommonEra
Returns a number that indicates the year, including the century, of the receiver (for example, 1995). The base year of the Common Era is 1 C.E. (which is the same as 1 A.D).
See Also: - dayOfCommonEra, - dayOfMonth, - dayOfWeek, - dayOfYear, - hourOfDay, , - minuteOfHour, - monthOfYear, - secondOfMinute
- (void)years:(int
*)yearsPointer
months:(int *)monthsPointer
days:(int *)daysPointer
hours:(int *)hoursPointer
minutes:(int *)minutesPointer
seconds:(int *)secondsPointer
sinceDate:(NSCalendarDate *)date
Computes the calendrical time difference between the receiver and date and returns it in yearsPointer, monthsPointer, daysPointer, hoursPointer, minutesPointer, and secondsPointer. You can choose any representation you wish for the time difference by passing null for the arguments you want to ignore. For example, the following code fragment computes the difference in months, days, and years between two dates:
NSCalendarDate *momsBDay = [NSCalendarDate dateWithYear:1936 month:1 day:8 hour:7 minute:30 second:0 timeZone:[NSTimeZone timeZoneWithName:@"EST"]]; NSCalendarDate *dateOfBirth = [NSCalendarDate dateWithYear:1965 month:12 day:7 hour:17 minute:25 second:0 timeZone:[NSTimeZone timeZoneWithName:@"EST"]]; int years, months, days; [dateOfBirth years:&years months:&months days:&days hours:null minutes:nullseconds:null sinceDate:momsBDay];
This message returns 29 years, 10 months, and 29 days. If you want to express the years in terms of months, you pass null for the years argument:
[dateOfBirth years:null months:&months days:&days hours:null minutes:null seconds:null sinceDate:momsBDay];
This message returns 358 months and 29 days.
See Also: - dateByAddingYears:months:days:hours:minutes:seconds: