# NSCalendarDate class reference

scottc@net-community.com
rfm@gnu.org
Generated at 2025-09-10 09:16:48 +0000
1996, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
Software documentation for the NSCalendarDate class
Foundation/NSCalendarDate.h
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.
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.
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.
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.
calendarDate
Return an NSCalendarDate for the current date and time using the default timezone.
dateWithString:
description
calendarFormat:
format
Return an NSCalendarDate generated from the supplied description using the format specified for parsing that string.
Calls -initWithString:calendarFormat: to create the date.
dateWithString:
description
calendarFormat:
format
locale:
dictionary
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:
year
month:
month
day:
day
hour:
hour
minute:
minute
second:
second
timeZone:
aTimeZone
Creates and returns an NSCalendarDate from the specified values by calling -initWithYear:month:day:hour:minute:second:timeZone:
addYear:
year
month:
month
day:
day
hour:
hour
minute:
minute
second:
second

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
Returns the format string associated with the receiver.
See -descriptionWithCalendarFormat:locale: for details.
dayOfCommonEra
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
Return the month (1 to 31) of the receiving date.
dayOfWeek
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
Return the day of the year (1 to 366) of the receiving date.
description
Calls -descriptionWithCalendarFormat:locale: passing the receiver's calendar format and a `nil` locale.
descriptionWithCalendarFormat:
format
Returns a string representation of the receiver using the specified format string.
Calls -descriptionWithCalendarFormat:locale: with a `nil` locale.
descriptionWithCalendarFormat:
format
locale:
locale
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:
locale
Returns a description of the receiver using its normal format but with the specified locale dictionary.
Calls -descriptionWithCalendarFormat:locale: to do this.
hourOfDay
Return the hour of the day (0 to 23) of the receiving date.
initWithString:
description
Initializes an NSCalendarDate using the specified description and the default calendar format and locale.
Calls -initWithString:calendarFormat:locale:
initWithString:
description
calendarFormat:
format
Initializes an NSCalendarDate using the specified description and format string interpreted in the default locale.
Calls -initWithString:calendarFormat:locale:
initWithString:
description
calendarFormat:
fmt
locale:
locale
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:
year
month:
month
day:
day
hour:
hour
minute:
minute
second:
second
timeZone:
aTimeZone
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
Return the minute of the hour (0 to 59) of the receiving date.
monthOfYear
Return the month of the year (1 to 12) of the receiving date.
secondOfMinute
Return the second of the minute (0 to 59) of the receiving date.
setCalendarFormat:
format
Sets the format string associated with the receiver.
Providing a `nil` argument sets the default calendar format.
See -descriptionWithCalendarFormat:locale: for details.
setTimeZone:
aTimeZone
Sets the time zone associated with the receiver.
Providing a `nil` argument sets the local time zone.
timeZone
Returns the time zone associated with the receiver.
timeZoneDetail
Returns the time zone detail associated with the receiver.
yearOfCommonEra
Return the year of the 'common' era of the receiving date. The era starts at 1 A.D.
Software documentation for the NSCalendarDate(GregorianDate) category
Foundation/NSCalendarDate.h
Routines for manipulating Gregorian dates.
absoluteGregorianDay:
day
month:
month
year:
year
Returns the number of days since the start of the era for the specified day, month, and year.
gregorianDateFromAbsolute:
d
day:
day
month:
month
year:
year
Given a day number since the start of the era, returns the date as a day, month, and year.
lastDayOfGregorianMonth:
month
year:
year
Returns the number of the last day of the month in the specified year.
Software documentation for the NSCalendarDate(OPENSTEP) category
Foundation/NSCalendarDate.h
Methods present in OpenStep but later removed from MacOS-X.
dateByAddingYears:
years
months:
months
days:
days
hours:
hours
minutes:
minutes
seconds:
seconds
Description forthcoming.
years:
years
months:
months
days:
days
hours:
hours
minutes:
minutes
seconds:
seconds
sinceDate:
date
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.