Up

# NSCalendarDate class reference

### Authors

Scott Christley (`scottc@net-community.com`)
Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 34363

Date: 2011-12-29 11:28:27 -0700 (Thu, 29 Dec 2011)

Copyright: (C) 1996, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSCalendarDate class
2. Software documentation for the NSCalendarDate(GregorianDate) category
3. Software documentation for the NSCalendarDate(OPENSTEP) category

# Software documentation for the NSCalendarDate class

## NSCalendarDate : NSDate

> Declared in:
>   Foundation/NSCalendarDate.h

Availability: OpenStep
An NSDate subclass which understands about timezones and provides methods for dealing with date and time information by calendar and with hours minutes and seconds.

Instance Variables
Method summary

- -absoluteGregorianDay:month:year:
- -gregorianDateFromAbsolute:day:month:year:
- -lastDayOfGregorianMonth:year:
- -dateByAddingYears:months:days:hours:minutes:seconds:
- -years:months:days:hours:minutes:seconds:sinceDate:
- +calendarDate
- +dateWithString:calendarFormat:
- +dateWithString:calendarFormat:locale:
- +dateWithYear:month:day:hour:minute:second:timeZone:
- -addYear:month:day:hour:minute:second:
- -calendarFormat
- -dayOfCommonEra
- -dayOfMonth
- -dayOfWeek
- -dayOfYear
- -description
- -descriptionWithCalendarFormat:
- -descriptionWithCalendarFormat:locale:
- -descriptionWithLocale:
- -hourOfDay
- -initWithString:
- -initWithString:calendarFormat:
- -initWithString:calendarFormat:locale:
- -initWithYear:month:day:hour:minute:second:timeZone:
- -minuteOfHour
- -monthOfYear
- -secondOfMinute
- -setCalendarFormat:
- -setTimeZone:
- -timeZone
- -timeZoneDetail
- -yearOfCommonEra

### calendarDate

+ (id) calendarDate;
Availability: OpenStep
Return an NSCalendarDate for the current date and time using the default timezone.

### dateWithString: calendarFormat:

+ (id) dateWithString: (NSString*)description calendarFormat: (NSString*)format;
Availability: OpenStep
Return an NSCalendarDate generated from the supplied description using the format specified for parsing that string.
Calls -initWithString:calendarFormat: to create the date.

### dateWithString: calendarFormat: locale:

+ (id) dateWithString: (NSString*)description calendarFormat: (NSString*)format locale: (NSDictionary*)dictionary;
Availability: OpenStep
Return an NSCalendarDate generated from the supplied description using the format specified for parsing that string and interpreting it according to the dictionary specified.
Calls -initWithString:calendarFormat:locale: to create the date.

### dateWithYear: month: day: hour: minute: second: timeZone:

+ (id) dateWithYear: (NSInteger)year month: (NSUInteger)month day: (NSUInteger)day hour: (NSUInteger)hour minute: (NSUInteger)minute second: (NSUInteger)second timeZone: (NSTimeZone*)aTimeZone;
Availability: OpenStep
Creates and returns an NSCalendarDate from the specified values by calling -initWithYear:month:day:hour:minute:second:timeZone:

### addYear: month: day: hour: minute: second:

- (NSCalendarDate*) addYear: (NSInteger)year month: (NSInteger)month day: (NSInteger)day hour: (NSInteger)hour minute: (NSInteger)minute second: (NSInteger)second;
Availability: OpenStep

Returns a calendar date formed by adding the specified offsets to the receiver. The offsets are added in order, years, then months, then days, then hours then minutes then seconds, so if you add 1 month and forty days to 20th September, the result will be 9th November.

This method understands leap years and tries to adjust for daylight savings time changes so that it preserves expected clock time.

The returned date has the calendar format and timezone of the receiver.

This method exists solely for conformance to the OpenStep spec. Its use is deprecated... it simply calls -dateByAddingYears:months:days:hours:minutes:seconds:

### calendarFormat

- (NSString*) calendarFormat;
Availability: OpenStep
Returns the format string associated with the receiver.
See -descriptionWithCalendarFormat:locale: for details.

### dayOfCommonEra

- (NSInteger) dayOfCommonEra;
Availability: OpenStep
Return the day number (ie number of days since the start of) in the 'common' era of the receiving date. The era starts at 1 A.D.

### dayOfMonth

- (NSInteger) dayOfMonth;
Availability: OpenStep
Return the month (1 to 31) of the receiving date.

### dayOfWeek

- (NSInteger) dayOfWeek;
Availability: OpenStep
Return the day of the week (0 to 6) of the receiving date.

- 0 is sunday
- 1 is monday
- 2 is tuesday
- 3 is wednesday
- 4 is thursday
- 5 is friday
- 6 is saturday

### dayOfYear

- (NSInteger) dayOfYear;
Availability: OpenStep
Return the day of the year (1 to 366) of the receiving date.

### description

- (NSString*) description;
Availability: OpenStep
Calls -descriptionWithCalendarFormat:locale: passing the receiver's calendar format and a `nil` locale.

### descriptionWithCalendarFormat:

- (NSString*) descriptionWithCalendarFormat: (NSString*)format;
Availability: OpenStep
Returns a string representation of the receiver using the specified format string.
Calls -descriptionWithCalendarFormat:locale: with a `nil` locale.

### descriptionWithCalendarFormat: locale:

- (NSString*) descriptionWithCalendarFormat: (NSString*)format locale: (NSDictionary*)locale;
Availability: OpenStep
Returns a string representation of the receiver using the specified format string and locale dictionary.
Format specifiers are -

- %a abbreviated weekday name according to locale
- %A full weekday name according to locale
- %b abbreviated month name according to locale
- %c this is the same as %X %x
- %B full month name according to locale
- %d day of month as two digit decimal number (leading zero)
- %e day of month as decimal number (without leading zero)
- %F milliseconds (000 to 999)
- %H hour as a decimal number using 24-hour clock
- %I hour as a decimal number using 12-hour clock
- %j day of year as a decimal number
- %k same as %H with leading space instead of zero
- %m month as decimal number
- %M minute as decimal number
- %p 'am' or 'pm'
- %S second as decimal number
- %U week of the current year as decimal number (Sunday first day)
- %W week of the current year as decimal number (Monday first day)
- %w day of the week as decimal number (Sunday = 0)
- %x date formatted according to the locale
- %X time formatted according to the locale
- %y year as a decimal number without century (minimum 0)
- %Y year as a decimal number with century, minimum 0, maximum 9999
- %z time zone offset (HHMM)
- %Z time zone
- %% literal % character

NB. If GSMacOSCompatible is set to `YES`, the %k specifier is not recognized.

### descriptionWithLocale:

- (NSString*) descriptionWithLocale: (id)locale;
Availability: OpenStep
Returns a description of the receiver using its normal format but with the specified locale dictionary.
Calls -descriptionWithCalendarFormat:locale: to do this.

### hourOfDay

- (NSInteger) hourOfDay;
Availability: OpenStep
Return the hour of the day (0 to 23) of the receiving date.

### initWithString:

- (id) initWithString: (NSString*)description;
Availability: OpenStep
Initializes an NSCalendarDate using the specified description and the default calendar format and locale.
Calls -initWithString:calendarFormat:locale:

### initWithString: calendarFormat:

- (id) initWithString: (NSString*)description calendarFormat: (NSString*)format;
Availability: OpenStep
Initializes an NSCalendarDate using the specified description and format string interpreted in the default locale.
Calls -initWithString:calendarFormat:locale:

### initWithString: calendarFormat: locale:

- (id) initWithString: (NSString*)description calendarFormat: (NSString*)fmt locale: (NSDictionary*)locale;
Availability: OpenStep
Initializes an NSCalendarDate using the specified description and format string interpreted in the given locale.
If description does not match fmt exactly, this method returns `nil`.
Excess characters in the description (after the format is matched) are ignored.
Format specifiers are -

- %% literal % character
- %a abbreviated weekday name according to locale
- %A full weekday name according to locale
- %b abbreviated month name according to locale
- %B full month name according to locale
- %c same as '%X %x'
- %d day of month as a two digit decimal number
- %e same as %d without leading zero
- %F milliseconds as a decimal number
- %H hour as a decimal number using 24-hour clock
- %I hour as a decimal number using 12-hour clock
- %j day of year as a decimal number
- %k same as %H without leading zero (leading space is used instead)
- %m month as decimal number
- %M minute as decimal number
- %p 'am' or 'pm'
- %S second as decimal number
- %U week of the current year as decimal number (Sunday first day)
- %W week of the current year as decimal number (Monday first day)
- %w day of the week as decimal number (Sunday = 0)
- %x date with date representation for locale
- %X time with time representation for locale
- %y year as a decimal number without century
- %Y year as a decimal number with century
- %z time zone offset in hours and minutes from GMT (HHMM)
- %Z time zone abbreviation

If no year is specified in the format, the current year is assumed.
If no month is specified in the format, January is assumed.
If no day is specified in the format, 1 is assumed.
If no hour is specified in the format, 0 is assumed.
If no minute is specified in the format, 0 is assumed.
If no second is specified in the format, 0 is assumed.
If no millisecond is specified in the format, 0 is assumed.
If no timezone is specified in the format, the local timezone is assumed.

If GSMacOSXCompatible is `YES`, the %k specifier is not recognized.

NB. Where the format calls for a numeric value and the string contains fewer digits than expected, the value will be accepted and left padded with zeros to the expected size.
For instance, the '%z' format implies four digits (two for the hour offset and two for the digit offset) and if the string contains '01' it will be treated as '0001' ie. a timezone offset of 1 minute.
Similarly, the '%F' format implies three digits, so a value of '1' would be treated as '001' or 1 millisecond, not a tenth of a second (as you might assume as '%F' is usually used after a decimal separator).

### initWithYear: month: day: hour: minute: second: timeZone:

- (id) initWithYear: (NSInteger)year month: (NSUInteger)month day: (NSUInteger)day hour: (NSUInteger)hour minute: (NSUInteger)minute second: (NSUInteger)second timeZone: (NSTimeZone*)aTimeZone;
Availability: OpenStep
Returns an NSCalendarDate instance with the given year, month, day, hour, minute, and second, using aTimeZone.
The year includes the century (ie you can't just say '02' when you mean '2002').
The month is in the range 1 to 12,
The day is in the range 1 to 31,
The hour is in the range 0 to 23,
The minute is in the range 0 to 59,
The second is in the range 0 to 59.
If aTimeZone is `nil`, the [NSTimeZone +localTimeZone] value is used.

GNUstep checks the validity of the method arguments, and unless the base library was built with 'warn=no' it generates a warning for bad values. It tries to use those bad values to generate a date anyway though, rather than failing (this also appears to be the behavior of MacOS-X).

The algorithm GNUstep uses to create the date is this ...

- Convert the broken out date values into a time interval since the reference date, as if those values represent a GMT date/time.
- Ask the time zone for the offset from GMT at the resulting date, and apply that offset to the time interval... so get the value for the specified timezone.
- Ask the time zone for the offset from GMT at the new date... in case the new date is in a different daylight savings time band from the original date. If this offset differs from the previous one, apply the difference so that the result is corrected for daylight savings. This is the final result used.
- After establishing the time interval we will use and completing initialisation, we ask the time zone for the offset from GMT again. If it is not the same as the last time, then the time specified by the broken out date does not really exist... since it's in the period lost by the transition to daylight savings. The resulting date is therefore not the date that was actually asked for, but is the best approximation we can do. If the base library was not built with 'warn=no' then a warning message is logged for this condition.

### minuteOfHour

- (NSInteger) minuteOfHour;
Availability: OpenStep
Return the minute of the hour (0 to 59) of the receiving date.

### monthOfYear

- (NSInteger) monthOfYear;
Availability: OpenStep
Return the month of the year (1 to 12) of the receiving date.

### secondOfMinute

- (NSInteger) secondOfMinute;
Availability: OpenStep
Return the second of the minute (0 to 59) of the receiving date.

### setCalendarFormat:

- (void) setCalendarFormat: (NSString*)format;
Availability: OpenStep
Sets the format string associated with the receiver.
Providing a `nil` argument sets the default calendar format.
See -descriptionWithCalendarFormat:locale: for details.

### setTimeZone:

- (void) setTimeZone: (NSTimeZone*)aTimeZone;
Availability: OpenStep
Sets the time zone associated with the receiver.
Providing a `nil` argument sets the local time zone.

### timeZone

- (NSTimeZone*) timeZone;
Availability: MacOS-X 10.0.0
Returns the time zone associated with the receiver.

### timeZoneDetail

- (NSTimeZoneDetail*) timeZoneDetail;
Availability: OPENSTEP 4.0.0 removed at MacOS-X 10.0.0
Returns the time zone detail associated with the receiver.

### yearOfCommonEra

- (NSInteger) yearOfCommonEra;
Availability: OpenStep
Return the year of the 'common' era of the receiving date. The era starts at 1 A.D.

## Instance Variables for NSCalendarDate Class

### _calendar_format

@protected NSString* _calendar_format;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _seconds_since_ref

@protected NSTimeInterval _seconds_since_ref;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _time_zone

@protected NSTimeZone* _time_zone;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSCalendarDate(GregorianDate) category

## NSCalendarDate(GregorianDate)

> Declared in:
>   Foundation/NSCalendarDate.h

Availability: Not in OpenStep/MacOS-X
Routines for manipulating Gregorian dates.
Method summary

- -absoluteGregorianDay:month:year:
- -gregorianDateFromAbsolute:day:month:year:
- -lastDayOfGregorianMonth:year:

### absoluteGregorianDay: month: year:

- (NSInteger) absoluteGregorianDay: (NSInteger)day month: (NSInteger)month year: (NSInteger)year;
Availability: Not in OpenStep/MacOS-X
Returns the number of days since the start of the era for the specified day, month, and year.

### gregorianDateFromAbsolute: day: month: year:

- (void) gregorianDateFromAbsolute: (NSInteger)d day: (NSInteger*)day month: (NSInteger*)month year: (NSInteger*)year;
Availability: Not in OpenStep/MacOS-X
Given a day number since the start of the era, returns the date as a day, month, and year.

### lastDayOfGregorianMonth: year:

- (NSInteger) lastDayOfGregorianMonth: (NSInteger)month year: (NSInteger)year;
Availability: Not in OpenStep/MacOS-X
Returns the number of the last day of the month in the specified year.

# Software documentation for the NSCalendarDate(OPENSTEP) category

## NSCalendarDate(OPENSTEP)

> Declared in:
>   Foundation/NSCalendarDate.h

Availability: OPENSTEP 4.0.0 removed at MacOS-X 10.0.0
Methods present in OpenStep but later removed from MacOS-X.
Method summary

- -dateByAddingYears:months:days:hours:minutes:seconds:
- -years:months:days:hours:minutes:seconds:sinceDate:

### dateByAddingYears: months: days: hours: minutes: seconds:

- (NSCalendarDate*) dateByAddingYears: (NSInteger)years months: (NSInteger)months days: (NSInteger)days hours: (NSInteger)hours minutes: (NSInteger)minutes seconds: (NSInteger)seconds;
Availability: OPENSTEP 4.0.0 removed at MacOS-X 10.0.0
Description forthcoming.

### years: months: days: hours: minutes: seconds: sinceDate:

- (void) years: (NSInteger*)years months: (NSInteger*)months days: (NSInteger*)days hours: (NSInteger*)hours minutes: (NSInteger*)minutes seconds: (NSInteger*)seconds sinceDate: (NSDate*)date;
Availability: OPENSTEP 4.0.0 removed at MacOS-X 10.0.0
Returns the number of years, months, days, hours, minutes, and seconds between the receiver and the given date.
If date is in the future of the receiver, the returned values will be negative (or zero), otherwise they are all positive.
If any of the pointers to return value in is null, the corresponding value will not be returned, and other return values will be adjusted accordingly. eg. If a difference of 1 hour was to be returned but hours is null, then the value returned in minutes will be increased by 60.

Up