Up

NSCalendarDate class reference

Authors

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

Version: 1.96

Date: 2004/05/13 09:38:03

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(GSCategories) category
  3. Software documentation for the NSCalendarDate(GregorianDate) category
  4. Software documentation for the NSCalendarDate(OPENSTEP) category

Software documentation for the NSCalendarDate class

NSCalendarDate : NSDate

Declared in:
Foundation/NSCalendarDate.h
Standards:

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 for NSCalendarDate Class

_calendar_format

@private NSString* _calendar_format;

Description forthcoming.


_seconds_since_ref

@private NSTimeInterval _seconds_since_ref;

Description forthcoming.


_time_zone

@private NSTimeZone* _time_zone;

Description forthcoming.





Method summary

calendarDate 

+ (id) calendarDate;

Return an NSCalendarDate for the current date and time using the default timezone.


dateWithString: calendarFormat: 

+ (id) dateWithString: (NSString*)description calendarFormat: (NSString*)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: calendarFormat: locale: 

+ (id) dateWithString: (NSString*)description calendarFormat: (NSString*)format locale: (NSDictionary*)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: month: day: hour: minute: second: timeZone: 

+ (id) dateWithYear: (int)year month: (unsigned int)month day: (unsigned int)day hour: (unsigned int)hour minute: (unsigned int)minute second: (unsigned int)second timeZone: (NSTimeZone*)aTimeZone;

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: (int)year month: (int)month day: (int)day hour: (int)hour minute: (int)minute second: (int)second;

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;

Returns the format string associated with the receiver.
See -descriptionWithCalendarFormat:locale: for details.


dayOfCommonEra 

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

- (int) dayOfMonth;

Return the month (1 to 31) of the receiving date.


dayOfWeek 

- (int) dayOfWeek;

Return the day of the week (0 to 6) of the receiving date.


dayOfYear 

- (int) dayOfYear;

Return the day of the year (1 to 366) of the receiving date.


description 

- (NSString*) description;

Calls -descriptionWithCalendarFormat:locale: passing the receviers calendar format and a nil locale.


descriptionWithCalendarFormat: 

- (NSString*) descriptionWithCalendarFormat: (NSString*)format;

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;

Returns a string representation of the receiver using the specified format string and locale dictionary.
Format specifiers are -


descriptionWithLocale: 

- (NSString*) descriptionWithLocale: (NSDictionary*)locale;

Returns a description of the receiver using its normal format but with the specified locale dictionary.
Calls -descriptionWithCalendarFormat:locale: to do this.


hourOfDay 

- (int) hourOfDay;

Return the hour of the day (0 to 23) of the receiving date.


initWithString: 

- (id) initWithString: (NSString*)description;

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;

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;

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.
Format specifiers are -

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.


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

- (id) initWithYear: (int)year month: (unsigned int)month day: (unsigned int)day hour: (unsigned int)hour minute: (unsigned int)minute second: (unsigned int)second timeZone: (NSTimeZone*)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 ...


minuteOfHour 

- (int) minuteOfHour;

Return the minute of the hour (0 to 59) of the receiving date.


monthOfYear 

- (int) monthOfYear;

Return the month of the year (1 to 12) of the receiving date.


secondOfMinute 

- (int) secondOfMinute;

Return the second of the minute (0 to 59) of the receiving date.


setCalendarFormat: 

- (void) setCalendarFormat: (NSString*)format;

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;

Sets the time zone associated with the receiver.
Providing a nil argument sets the local time zone.


timeZone 

- (NSTimeZone*) timeZone;

Returns the time zone associated with the receiver.


timeZoneDetail 

- (NSTimeZoneDetail*) timeZoneDetail;

Returns the time zone detail associated with the receiver.


yearOfCommonEra 

- (int) yearOfCommonEra;

Return the year of the 'common' era of the receiving date. The era starts at 1 A.D.


Software documentation for the NSCalendarDate(GSCategories) category

NSCalendarDate(GSCategories)

Declared in:
Foundation/NSCalendarDate.h
Standards:

Description forthcoming.

Method summary

weekOfYear 

- (int) weekOfYear;

Description forthcoming.


Software documentation for the NSCalendarDate(GregorianDate) category

NSCalendarDate(GregorianDate)

Declared in:
Foundation/NSCalendarDate.h
Standards:

Routines for manipulating Gregorian dates

Method summary

absoluteGregorianDay: month: year: 

- (int) absoluteGregorianDay: (int)day month: (int)month year: (int)year;

Returns the number of days since the start of the era for the specified day, month, and year.


gregorianDateFromAbsolute: day: month: year: 

- (void) gregorianDateFromAbsolute: (int)d day: (int*)day month: (int*)month year: (int*)year;

Given a day number since the start of the era, returns the date as a day, month, and year.


lastDayOfGregorianMonth: year: 

- (int) lastDayOfGregorianMonth: (int)month year: (int)year;

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

Methods present in OpenStep but later removed from MacOS-X

Method summary

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

- (NSCalendarDate*) dateByAddingYears: (int)years months: (int)months days: (int)days hours: (int)hours minutes: (int)minutes seconds: (int)seconds;

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.


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

- (void) years: (int*)years months: (int*)months days: (int*)days hours: (int*)hours minutes: (int*)minutes seconds: (int*)seconds sinceDate: (NSDate*)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.



Up