Class next.util.CalendarDate
CLASS DESCRIPTION
- Extends:
- next.util.Date
CalendarDate creates concrete date objects for western calendars. These objects have time zones and calendar formats as attributes and are especially suited for representing and manipulating dates according to western calendrical systems.
CalendarDate objects can adjust their visible representations to reflect their associated time zones. Because of this, you can track a CalendarDate object across different time zones; that is, you can change a Calendar Date's time zone to see how the particular date is represented in that time zone.
CalendarDate provides a number of constructors for creating objects. Some of these methods allow you to initialize CalendarDate objects from strings while others create objects from sets of integers corresponding the standard time values (months, hours, seconds, and so on).
To retrieve conventional elements of a CalendarDate object, use the ...Of... methods. For example, dayOfWeek returns a number that indicates the day of the week (0 is Sunday). The monthOfYear method returns a number between 1 and 12 that indicates the month.
CalendarDate performs date computations based on western calendrical systems, primarily the Gregorian. (The algorithms are derived from public domain software described in "Calendrical Calculations," a two-part series by Nachum Dershowitz and Edward M Reingold in Software - Practice and Experience).
The Calendar Format
Each CalendarDate object has a calendar format associated with it. This format is a string that contains date-conversion specifiers that are very similar to those used in the standard C library function strftime(). CalendarDate interprets dates that are represented as strings conforming to this format. You can set the default format for a CalendarDate object at initialization time or using the setCalendarFormat method.
The date conversion specifiers cover a range of date conventions:
- %%
- a '%' character
- %a
- abbreviated weekday name
- %A
- full weekday name
- %b
- abbreviated month name
- %B
- ull month name
- %c
- shorthand for %X %x, the locale format for date and time
- %d
- day of the month as a decimal number (01-31)
- %F
- milliseconds as a decimal number (000-999)
- %H
- hour based on a 24-hour clock as a decimal number (00-23)
- %I
- hour based on a 12-hour clock as a decimal number (01-12)
- %j
- day of the year as a decimal number (001-366)
- %m
- month as a decimal number (01-12)
- %M
- minute as a decimal number (00-59)
- %p
- AM/PM designation for the locale
- %S
- second as a decimal number (00-59)
- %w
- weekday as a decimal number (0-6), where Sunday is 0
- %x
- date using the date representation for the locale
- %X
- time using the time representation for the locale
- %y
- year without century (00-99)
- %Y
- year with century (such as 1990)
- %Z
- time zone abbreviation (such as PDT)
- %z
- time zone offset in hours and minutes from GMT (HHMM)
String Representations for CalendarDates
CalendarDate provides the toString method for representing dates as strings. This method takes an explicit calendar format. The user's locale information affects the returned string. CalendarDate accesses the locale information as an ImmutableHashtable. The following keys in the locale dictionary affect CalendarDates:
- NSTimeDateFormatString
- Specifies how dates with times are printed, affecting strings that use the format specifiers %c, %X, or %x. The default is to use abbreviated months and days with a 24 hour clock, as in "Sun Jan 01 23:00:00 +6 2001".
- NSAMPMDesignation
- Specifies how the morning and afternoon designations are printed, affecting strings that use the %p format specifier. The default is AM and PM.
- NSMonthNameArray
- Specifies the names for the months, affecting strings that use the %B format specifier.
- NSShortMonthNameArray
- Specifies the abbreviations for the months, affecting strings that use the %b format specifier.
- NSWeekDayNameArray
- Specifies the names for the days of the week, affecting strings that use the %A format specifier.
- NSShortWeekDayNameArray
- Specifies the abbreviations for the days of the week, affecting strings that use the %a format specifier.
Time Zones
Time zones represent geopolitical regions, and represent a temporal offset, either plus or minus, from Greenwich Mean Time (GMT) and an abbreviation (such as "PST").
The system supplies many choices for time zones. The system stores time zone information in the directory NextLibrary/Frameworks/Foundation.framework/Resources/TimeZoneInfo on Windows platforms. The files in this directory store time zone information. For example, the geopolitical regions US/Pacific and Canada/Pacific are both in the same longitudinal area and both use the abbreviation "PST."
The RegionsDictionary file in the time zone information directory supplies these methods with the information necessary to make such choices.
setDefaultTimeZone permits you to set the default time zone for your locale. You can access this default time zone at any time with the defaultTimeZone method.
Unless you specify otherwise, objects returned from CalendarDate are bound to the default time zone for the current locale.