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.


CONSTRUCTORS

CalendarDate

CalendarDate(int year, int month, int day, int hour, int minute, int second, java.lang.String timeZone)

Returns a newly allocated an initialized CalendarDate object. The object is initialized with the specified values for year, month, day, hour, minute, and second and the named time zone. The year value must include the century (for example, 1995 instead of 95). The other values are the standard ones: 1 through 12 for months, 1 through 31 for days, 0 through 23 for hours and 0 through 59 for both minutes and seconds.

CalendarDate(java.lang.String description)

Returns a newly allocated an initialized CalendarDate object, initialized with the date specified as a string in description. This method uses "%Y-%m-%d %H:%M:%S %z" both to interpret the description string and as the default calendar format for this object. If description does not match format exactly, this method returns nil.

CalendarDate(java.lang.String description, java.lang.String format)

Returns a newly allocated an initialized CalendarDate object, initialized with the date specified as a string in description. This method uses format both to interpret the description string and as the default calendar format for this object. format consists of conversion specifiers similar to those used in strftime(). See the class description for a listing of these specifiers. If description does not match format exactly, this method returns nil.

CalendarDate(java.util.Date aDate)

Returns a newly allocated an initialized CalendarDate object, initialized to the date and time specified by aDate. The time zone of the newly-initialized object is that which can be obtained from the defaultTimeZone method.

CalendarDate(next.util.CalendarDate aCalendarDate, int year, int month, int day, int hour, int minute, int second)

Returns a newly allocated an initialized CalendarDate object. The object is initialized with the specified values for year, month, day, hour, minute, and second. The year value must include the century (for example, 1995 instead of 95). The other values are the standard ones: 1 through 12 for months, 1 through 31 for days, 0 through 23 for hours and 0 through 59 for both minutes and seconds.


CalendarDate

public CalendarDate()
public CalendarDate(double offset)

Returns a newly allocated and initialized CalendarDate object set to the current date and time. If offset is supplied, the new object is initialized to the current date and time plus the supplied offset.


METHODS

calendarFormat

public java.lang.String calendarFormat()

Returns the receiver's default calendar format (used when the format is unspecified). You can set this format when you create the CalendarDate, or you can change the format using the instance method setCalendarFormat. If you do not specify a default calendar format, CalendarDate substitutes its own default: an international format of "%Y-%m-%d %H:%M:%S %z" (for example, 1994-01-14 16:45:12 +0900). See the class description for a discussion of date conversion specifiers.


dayOfCommonEra

public int dayOfCommonEra()

Returns the number of days since the beginning of the Common Era. The base year of the Common Era is 1 A.C.E. (which is the same as 1 A.D.).


dayOfMonth

public int dayOfMonth()

Returns a number that indicates the day of the month (1 through 31) of the receiver.


dayOfWeek

public int dayOfWeek()

Returns a number that indicates the day of the week (0 through 6) of the receiver; 0 indicates Sunday.


dayOfYear

public int dayOfYear()

Returns a number that indicates the day of the year (1 through 366) of the receiver.


defaultTimeZone

public static java.lang.String defaultTimeZone()

Returns the default time zone, set for the current locale.


hourOfDay

public int hourOfDay()

Returns the hour value (0 through 23) of the receiver. On Daylight Savings "fall back" days, a value of 1 is returned for two consecutive hours, but with a different time zone (the first in daylight savings time and the second in standard time).


minuteOfHour

public int minuteOfHour()

Returns the minutes value (0 through 59) of the receiver.


monthOfYear

public int monthOfYear()

Returns a number that indicates the month of the year (1 through 12) of the receiver.


secondOfMinute

public int secondOfMinute()

Returns the seconds value (0 through 59) of the receiver.


setCalendarFormat

public void setCalendarFormat(java.lang.String format)

Sets the default calendar format for the receiver. A calendar format is a string formatted with date-conversion specifiers listed in the class description. If you do not specify a calendar format for an object, CalendarDate substitutes its own default. This is the international format of "%Y-%m-%d %H:%M:%S %z" (for example, 1994-01-14 16:45:12 +0900).


setDefaultTimeZone

public static void setDefaultTimeZone(java.lang.String aString)

Sets the time zone appropriate for the current locale. There can be only one default time zone, so by setting a new default time zone, you lose the previous one.


setTimeZone

public void setTimeZone(java.lang.String aString)

Sets the time zone for the receiver. If you do not specify a time zone for an object at initialization time, CalendarDate uses the default time zone for the locale. Use this method to set it to another time zone.


timeZone

public java.lang.String timeZone()

Returns the time zone that is associated with the receiver. You can set the time zone when you create the CalendarDate. Or you can explicitly set the time zone to an NSTimeZone object using setTimeZone. If you do not specify a time zone for an object at initialization time, CalendarDate uses the default time zone for the locale.


toString

public java.lang.String toString(java.lang.String format)

Returns a string representation of the receiver. The string is formatted as specified by the conversion specifiers in the calendar format string format. The conversion specifiers cover a range of date conventions. See the class description for a listing of these specifiers.


yearOfCommonEra

public int yearOfCommonEra()

Returns a number that indicates the year, including the century, of the receiver (for example, 1995). The base year of the Common Era is 1 A.C.E. (which is the same as 1 A.D).