Up
Authors
- Scott Christley (
scottc@net-community.com
)
-
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Date: 2006-08-15 02:01:14 -0600 (Tue, 15 Aug 2006)
Copyright: (C) 1996, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
- 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
+ (id)
calendarDate;
Availability: OpenStep
Return an NSCalendarDate for the current date and time using the default timezone.
+ (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.
+ (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.
+ (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;
Availability: OpenStep
- (
NSCalendarDate*)
addYear: (int)year
month: (int)month
day: (int)day
hour: (int)hour
minute: (int)minute
second: (int)second;
Availability: OpenStep
- (
NSString*)
calendarFormat;
Availability: OpenStep
- (int)
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.
- (int)
dayOfMonth;
Availability: OpenStep
Return the month (1 to 31) of the receiving date.
- (int)
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
- (int)
dayOfYear;
Availability: OpenStep
Return the day of the year (1 to 366) of the receiving date.
- (
NSString*)
description;
Availability: OpenStep
- (
NSString*)
descriptionWithCalendarFormat: (
NSString*)format;
Availability: OpenStep
- (
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 decimal number (leading zero)
-
%e day of month as decimal number (leading space)
-
%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
-
%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
- (int)
hourOfDay;
Availability: OpenStep
Return the hour of the day (0 to 23) of the receiving date.
- (id)
initWithString: (
NSString*)description;
Availability: OpenStep
- (id)
initWithString: (
NSString*)description
calendarFormat: (
NSString*)format;
Availability: OpenStep
- (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
.
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 decimal number
-
%e same as %d without leading zero (you get a leading space instead)
-
%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
-
%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.
- (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;
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.
- (int)
minuteOfHour;
Availability: OpenStep
Return the minute of the hour (0 to 59) of the receiving date.
- (int)
monthOfYear;
Availability: OpenStep
Return the month of the year (1 to 12) of the receiving date.
- (int)
secondOfMinute;
Availability: OpenStep
Return the second of the minute (0 to 59) of the receiving date.
- (void)
setCalendarFormat: (
NSString*)format;
Availability: OpenStep
- (void)
setTimeZone: (
NSTimeZone*)aTimeZone;
Availability: OpenStep
Sets the time zone associated with the receiver.
Providing a nil
argument sets the local time zone.
- (
NSTimeZone*)
timeZone;
Availability: MacOS-X 10.0.0
Returns the time zone associated with the receiver.
- (
NSTimeZoneDetail*)
timeZoneDetail;
Availability: OpenStep removed at OPENSTEP 4.0.0
Returns the time zone detail associated with the receiver.
- (int)
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
@protected NSString* _calendar_format;
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.
@protected NSTimeInterval _seconds_since_ref;
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.
@protected NSTimeZone* _time_zone;
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.
- Declared in:
- Foundation/NSCalendarDate.h
Availability: Base 0.0.0
Method summary
- (int)
weekOfYear;
Availability: Base 0.0.0
The ISO standard week of the year is based on the first week of the year being that week (starting on monday) for which the thursday is on or after the first of january.
This has the effect that, if january first is a friday, saturday or sunday, the days of that week (up to and including the sunday) are considered to be in week 53 of the preceding year. Similarly if the last day of the year is a monday tuesday or wednesday, these days are part of week 1 of the next year.
- Declared in:
- Foundation/NSCalendarDate.h
Availability: Base 0.0.0
Routines for manipulating Gregorian dates.
Method summary
- (int)
absoluteGregorianDay: (int)day
month: (int)month
year: (int)year;
Availability: Base 0.0.0
Returns the number of days since the start of the era for the specified day, month, and year.
- (void)
gregorianDateFromAbsolute: (int)d
day: (int*)day
month: (int*)month
year: (int*)year;
Availability: Base 0.0.0
Given a day number since the start of the era, returns the date as a day, month, and year.
- (int)
lastDayOfGregorianMonth: (int)month
year: (int)year;
Availability: Base 0.0.0
Returns the number of the last day of the month in the specified year.
- Declared in:
- Foundation/NSCalendarDate.h
Availability: OpenStep removed at OPENSTEP 4.0.0
Methods present in OpenStep but later removed from MacOS-X.
Method summary
- (
NSCalendarDate*)
dateByAddingYears: (int)years
months: (int)months
days: (int)days
hours: (int)hours
minutes: (int)minutes
seconds: (int)seconds;
Availability: OpenStep removed at OPENSTEP 4.0.0
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.
- (void)
years: (int*)years
months: (int*)months
days: (int*)days
hours: (int*)hours
minutes: (int*)minutes
seconds: (int*)seconds
sinceDate: (
NSDate*)date;
Availability: OpenStep removed at OPENSTEP 4.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