The Calendar Class

The Calendar class provides methods for converting between a specific date and a set of calendar fields such as Year, Month, Day of Month, or Hour. It also allows for manipulating the calendar fields, for example, getting the date of the next week.

Methods

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

Table 1. Class Methods (Static Member Methods)
Name Description
Numeric compareTo(Calendar other)
Compares the time values (millisecond offsets from the Epoch) represented by two Calendar objects.
Calendar fromDate(Date date [, String timeZone [, String locale] ])
Gets a Calendar set to the time of the given Date using the default time zone and locale.
Numeric getActualDayOfMonthMaximum()
Returns the maximum value that the Day of Month field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualDayOfMonthMinimum()
Returns the minimum value that the Day of Month field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualHourOfDayMaximum()
Returns the maximum value that the Hour of Day field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualHourOfDayMinimum()
Returns the minimum value that the Hour of Day field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualMinuteMaximum()
Returns the maximum value that the Minute field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualMinuteMinimum()
Returns the minimum value that the Minute field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualMonthMaximum()
Returns the maximum value that the Month field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualMonthMinimum()
Returns the minimum value that the Month field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualSecondMaximum()
Returns the maximum value that the Second field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualSecondMinimum()
Returns the minimum value that the Second field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualWeekOfYearMaximum()
Returns the maximum value that the Week of Year field could have, taking into consideration the given time value and the current values of the getFIrstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualWeekOfYearMinimum()
Returns the minimum value that the Week of Year field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualYearMaximum()
Returns the maximum value that the Year field could have, taking into consideration the given time value and the current values of the getFirstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getActualYearMinimum()
Returns the minimum value that the Year field could have, taking into consideration the given time value and the current values of the getFIrstDayOfWeek(), getMinimalDaysInFirstWeek(), and setTimeZone() methods.
Numeric getDayOfMonth()
Returns the value of the Day of Month calendar field. All calendar fields are normalized.
Numeric getFirstDayOfWeek()
Returns the first day of the week, for example, 1 (Sunday) in the U.S. or 2 (Monday) in France.
Numeric getHourOfDay()
Returns the value of the Hour of Day calendar field. All calendar fields are normalized.
Calendar getInstance()
Gets a calendar using the default time zone and locale. The Calendar returned is based on the current time in the default time zone with the default locale.
Numeric getMinimalDaysInFirstWeek()
Returns the minimal days required in the first week of the year.
Numeric getMinute()
Returns the value of the Minute calendar field. All calendar fields are normalized.
Numeric getMonth()
Returns the value of the Month calendar field. All calendar fields are normalized.
Numeric getSecond()
Returns the value of the Second calendar field. All calendar fields are normalized.
Numeric getWeekOfYear()
Returns the value of the Week of Year calendar field. All calendar fields are normalized.
Numeric getWeeksInWeekYear()
Returns the number of weeks in the week year represented by this calendar.
Numeric getWeekYear()
Returns the Week Year represented by this calendar.
Numeric getYear()
Returns the value of the Year calendar field. All calendar fields are normalized.
Calendar setDayOfMonth(Numeric value)
Sets the value of the Day of Month calendar field.
Calendar setFirstDayOfWeek(Numeric value)
Sets what the first day of the week is, for example, 1 (Sunday) in the U.S. or 2 (Monday) in France.
Calendar setHourOfDay(Numeric value)
Sets the value of the Hour of Day calendar field.
Calendar setLocale(String locale)
Sets the locale with the given time locale value.
Calendar setMinimalDaysInFirstWeek(Numeric value)
Sets the minimal days required in the first week of the year.
Calendar setMinute(Numeric value)
Sets the value of the Minute calendar field.
Calendar setMonth(Numeric value)
Sets the value of the Month calendar field.
Calendar setSecond(Numeric value)
Sets the value of the Second calendar field.
Calendar setTimeZone(String timeZone)
Sets the time zone with the given time zone value. A time zone ID can be a value from the below list or a custom time zone ID as explained below.
Calendar setWeekOfYear(Numeric value)
Sets the value of the Week of Year calendar field.
Calendar setYear(Numeric value)
Sets the value of the Year calendar field.
Date toDate()
Returns a Date object representing this Calendar's time value (millisecond offset from the Epoch).

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.

Note: The normalized numbering returned by get() may be different. For example, a specific Calendar subclass may designate the week before week 1 of a year as week n of the previous year.

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.

Note: There are possible ambiguities in interpretation of singular times, which are resolved in the following ways:
  1. 23:59 is the last minute of the day and 00:00 is the first minute of the next day. Therefore, 23:59 on Dec 31, 1999 < 00:00 on Jan 1, 2000 < 00:01 on Jan 1, 2000.
  2. Although historically not precise, midnight also belongs to "am", and noon belongs to "pm". Therefore, on the same day, 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm

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.