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.
Return an NSCalendarDate generated from the supplied
description using the format
specified for parsing that string. Calls
-initWithString:calendarFormat:
to create the date.
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.
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.
Returns a description of the receiver using its
normal format but with the specified
locale dictionary. Calls
-descriptionWithCalendarFormat:locale:
to do this.
Initializes an NSCalendarDate using the
specified description and
format string interpreted in the default
locale. Calls
-initWithString:calendarFormat: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).
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.
Sets the format string associated with the
receiver. Providing a nil
argument sets the default calendar
format. See
-descriptionWithCalendarFormat:locale:
for details.
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.
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.