The Calendar Class

Methods

Class methods are static methods that do not require an object. The method name is prefixed by the class name.

Numeric compareTo(Calendar other)

Calendar fromDate(Date date [, String timeZone [, String locale] ])

Numeric getActualDayOfMonthMaximum()

Numeric getActualDayOfMonthMinimum()

Numeric getActualHourOfDayMaximum()

Numeric getActualHourOfDayMinimum()

Numeric getActualMinuteMaximum()

Numeric getActualMinuteMinimum()

Numeric getActualMonthMaximum()

Numeric getActualMonthMinimum()

Numeric getActualSecondMaximum()

Numeric getActualSecondMinimum()

Numeric getActualWeekOfYearMaximum()

Numeric getActualWeekOfYearMinimum()

Numeric getActualYearMaximum()

Numeric getActualYearMinimum()

Numeric getDayOfMonth()

Numeric getFirstDayOfWeek()

Numeric getHourOfDay()

Calendar getInstance()

Numeric getMinimalDaysInFirstWeek()

Numeric getMinute()

Numeric getMonth()

Numeric getSecond()

Numeric getWeekOfYear()

Numeric getWeeksInWeekYear()

Numeric getWeekYear()

Numeric getYear()

Calendar setDayOfMonth(Numeric value)

Calendar setFirstDayOfWeek(Numeric value)

Calendar setHourOfDay(Numeric value)

Calendar setLocale(String locale)

Calendar setMinimalDaysInFirstWeek(Numeric value)

Calendar setMinute(Numeric value)

Calendar setMonth(Numeric value)

Calendar setSecond(Numeric value)

Calendar setTimeZone(String timeZone)

Calendar setWeekOfYear(Numeric value)

Calendar setYear(Numeric value)

Date toDate()

Usage

With RTL classes, it is not possible to create and subclass objects. The new keyword is not supported.

An instant in time can be represented by a millisecond value that is an offset from the Epoch,January 1, 1970 00:00:00.000 GMT Gregorian. The class represents a Gregorian calendar.

Like other locale-sensitive classes, Calendar provides a class method, getInstance(), for getting a generally useful object of this type. The getInstance() method returns a Calendar object whose calendar fields have been initialized with the current date and time.

A Calendar object can produce all the calendar field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian). Calendar defines the range of values returned by certain calendar fields, as well as their meaning. For example, the first month of the calendar system has value Month == 0.

Any field values set in a Calendar are not interpreted until it needs to calculate its time value (milliseconds from the Epoch) or values of the calendar fields. Calling get, getTime, add and roll involves such calculation.

First week

Calendar defines a locale-specific seven-day week using two parameters:

• The first day of the week
• The minimal days in the first week (from 1 to 7)

These numbers are taken from the locale resource data when a Calendar is constructed. They may also be specified explicitly through the methods for setting their values.

When setting or getting the Week of Month or Week of year fields, Calendar must determine the first week of the month or year as a reference point. The first week of a month or year is defined as the earliest seven day period beginning on getFirstDayOfWeek() and containing at least getMinimalDaysInFirstWeek() days of that month or year. Weeks numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow it.

Resolving fields

When computing a date and time from the calendar fields, there may be insufficient information for the computation (such as only year and month but no day of month), or there may be inconsistent information (such as "Tuesday, July 15, 1996" where July 15, 1996 is actually a Monday). Calendar resolves calendar field values to determine the date and time in the following way:

If there is any conflict in calendar field values, Calendar gives priority to calendar fields that have been set more recently. The following are the default combinations of the calendar fields. The most recent combination, as determined by the most recently set single field, is used.

For the date fields:

Year + Month + Day of Month 
Year + Month + Week of Month + Day of Week 
Year + Month + Day of Week in Month + Day of Week 
Year + Day of Year 
Year + Day of Week + Day of Year

For the time of day fields:

Hour of Day 
AM PM + Hour

If there are any calendar fields whose values haven't been set in the selected field combination, Calendar uses their default values. For example, the default of a field is the same as that of the start of the Epoch: Year = 1970, Month = 0, Day of Month = 1, etc.

Changing field values

The calendar fields can be changed using three methods: set(), add(), and roll().

setX(value) changes calendar field X to value. In addition, it sets an internal member variable to indicate that calendar field X has been changed. Although calendar field X is changed immediately, the calendar's time value in milliseconds is not recomputed until the next call to get(), getTime(), add() or roll() is made. Thus, multiple calls to set() do not trigger multiple, unnecessary computations. As a result of changing a calendar field using set(), other calendar fields may also change, depending on the calendar field, the calendar field value, and the calendar system. In addition, getX() does not necessarily return value set by the call to the setX method after the calendar fields have been recomputed.

For example, a Calendar is originally set to August 31, 1999. Calling setMonth( 8) sets the date to September 31, 1999. This is a temporary internal representation that resolves to October 1, 1999 if getTime() is then called. However, a call to setDayOfMonth(30) before the call to getTime() sets the date to September 30, 1999, since no recomputation occurs after setMonth() itself.

addX(delta) adds delta to field X. This is equivalent to calling setX(getX() + delta) with two adjustments:

• Add rule 1. The value of field X after the call minus the value of field X before the call is delta, modulo any overflow that has occurred in field X. Overflow occurs when a field value exceeds its range and, as a result, the next larger field is incremented or decremented and the field value is adjusted back into its range.
• Add rule 2. If a smaller field is expected to be invariant, but it is impossible for it to be equal to its prior value because of changes in its minimum or maximum after field X is changed or other constraints, such as time zone offset changes, then its value is adjusted to be as close as possible to its expected value. A smaller field represents a smaller unit of time. Hour is a smaller field than Day of Month. No adjustment is made to smaller fields that are not expected to be invariant. The calendar system determines what fields are expected to be invariant.

Unlike set(), add() forces an immediate recomputation of the calendar's milliseconds and all fields.

For example, a Calendar is originally set to August 31, 1999. Calling addMonth(13) sets the calendar to September 31, 2000. Add rule 1 sets the Month field to September, since adding 13 months to August gives September of the next year. Since Day of Month cannot be 31 in September, add rule 2 sets the Day of Month to 30, the closest possible value. Although it is a smaller field, Day of Week is not adjusted by rule 2, since it is expected to change when the month changes in a Calendar.

rollX(delta) adds delta to field X without changing larger fields. This is equivalent to calling addX(delta) with the following adjustment:

• Roll rule. Larger fields are unchanged after the call. A larger field represents a larger unit of time. Day of Month is a larger field than Hour.