Up

NSCalendarDate class reference

Authors

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

Version: 36751

Date: 2013-06-24 17:48:22 +0100 (Mon, 24 Jun 2013)

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

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: 

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

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