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.
Name | Description |
---|---|
|
Compares the time values (millisecond offsets from the Epoch) represented by two Calendar objects. |
|
Gets a Calendar set to the time of the given
Date using the default time zone and locale. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Returns the value of the Day of Month calendar
field. All calendar fields are normalized. |
|
Returns the first day of the week, for example, 1
(Sunday) in the U.S. or 2 (Monday) in
France. |
|
Returns the value of the Hour of Day calendar field.
All calendar fields are normalized. |
|
Gets a calendar using the default time zone and locale. The
returned is based on the current time in the default time
zone with the default locale. |
|
Returns the minimal days required in the first week of the year. |
|
Returns the value of the Minute calendar field. All
calendar fields are normalized. |
|
Returns the value of the Month calendar field. All
calendar fields are normalized. |
|
Returns the value of the Second calendar field. All
calendar fields are normalized. |
|
Returns the value of the Week of Year calendar
field. All calendar fields are normalized. |
|
Returns the number of weeks in the week year represented by this calendar. |
|
Returns the Week Year represented by this calendar.
|
|
Returns the value of the Year calendar field. All
calendar fields are normalized. |
|
Sets the value of the Day of Month calendar
field. |
|
Sets what the first day of the week is, for example, 1
(Sunday) in the U.S. or 2 (Monday) in
France. |
|
Sets the value of the Hour of Day calendar field.
|
|
Sets the locale with the given time locale value. |
|
Sets the minimal days required in the first week of the year. |
|
Sets the value of the Minute calendar field.
|
|
Sets the value of the Month calendar field.
|
|
Sets the value of the Second calendar field.
|
|
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. |
|
Sets the value of the Week of Year calendar
field. |
|
Sets the value of the Year calendar field.
|
|
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.
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.
- 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.
- 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 thanDay 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 thanHour
.