public
abstract
class
Calendar
extends Object
implements
Serializable,
Cloneable,
Comparable<Calendar>
The Calendar
class is an abstract class that provides methods
for converting between a specific instant in time and a set of calendar fields
such as YEAR
, MONTH
,
DAY_OF_MONTH
, HOUR
, and so on, and for
manipulating the calendar fields, such as getting the date of the next
week. 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 also provides additional fields and methods for
implementing a concrete calendar system outside the package. Those
fields and methods are defined as protected
.
Like other locale-sensitive classes, Calendar
provides a
class method, getInstance
, for getting a generally useful
object of this type. Calendar
‘s 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, Japanese-Traditional).
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 ==
for all calendars. Other values are defined by the
JANUARY
concrete subclass, such as ERA
. See individual field
documentation and subclass documentation for details.
The calendar field values can be set by calling the set
methods. Any field values set in a Calendar
will not be
interpreted until it needs to calculate its time value (milliseconds from
the Epoch) or values of the calendar fields. Calling the
get
, getTimeInMillis
, getTime
,
add
and roll
involves such calculation.
Calendar
has two modes for interpreting the calendar
fields, lenient and non-lenient. When a
Calendar
is in lenient mode, it accepts a wider range of
calendar field values than it produces. When a Calendar
recomputes calendar field values for return by get()
, all of
the calendar fields are normalized. For example, a lenient
GregorianCalendar
interprets MONTH == JANUARY
,
DAY_OF_MONTH == 32
as February 1.
When a Calendar
is in non-lenient mode, it throws an
exception if there is any inconsistency in its calendar fields. For
example, a GregorianCalendar
always produces
DAY_OF_MONTH
values between 1 and the length of the month. A
non-lenient GregorianCalendar
throws an exception upon
calculating its time or calendar field values if any out-of-range field
value has been set.
defines a locale-specific seven day week using two parameters: the first day of the week and the minimal days in first week (from 1 to 7). These numbers are taken from the locale resource data when ais 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 that 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.
When computing a date and time from the calendar fields, there may be insufficient information for the computation (such as only year and month with no day of month), or there may be inconsistent information (such as Tuesday, July 15, 1996 (Gregorian) — July 15, 1996 is actually a Monday).will resolve calendar field values to determine the date and time in the following way.
If there is any conflict in calendar field values,
Calendar
gives priorities 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, will be used.
:
If there are any calendar fields whose values haven’t been set in the selected
field combination, Calendar
uses their default values. The default
value of each field may vary by concrete calendar systems. For example, in
GregorianCalendar
, the default of a field is the same as that
of the start of the Epoch: i.e., YEAR = 1970
, MONTH =
,
JANUARYDAY_OF_MONTH = 1
, etc.
Note: There are certain possible ambiguities in
interpretation of certain singular times, which are resolved in the
following ways:
The date or time format strings are not part of the definition of a
calendar, as those must be modifiable or overridable by the user at
runtime. Use DateFormat
to format dates.
The calendar fields can be changed using three methods:, and
set(f, value)
changes calendar field
f
to value
. In addition, it sets an
internal member variable to indicate that calendar field f
has
been changed. Although calendar field f
is changed immediately,
the calendar’s time value in milliseconds is not recomputed until the next call to
get()
, getTime()
, getTimeInMillis()
,
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,
get(f)
will not necessarily return value
set by
the call to the set
method
after the calendar fields have been recomputed. The specifics are determined by
the concrete calendar class.
Example: Consider a GregorianCalendar
originally set to August 31, 1999. Calling set(Calendar.MONTH,
sets the date to September 31,
Calendar.SEPTEMBER)
1999. This is a temporary internal representation that resolves to
October 1, 1999 if getTime()
is then called. However, a
call to set(Calendar.DAY_OF_MONTH, 30)
before the call to
getTime()
sets the date to September 30, 1999, since
no recomputation occurs after set()
itself.
add(f, delta)
adds delta
to field f
. This is equivalent to calling set(f,
with two adjustments:
get(f) + delta)
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 f 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.
Add rule 1 . The value of field f after the call minus the value of field f before the call is delta , modulo any overflow that has occurred in field f . 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.
In addition, unlike set()
, add()
forces
an immediate recomputation of the calendar’s milliseconds and all
fields.
Example: Consider a GregorianCalendar
originally set to August 31, 1999. Calling add(Calendar.MONTH,
sets the calendar to September 30, 2000. Add rule
13)
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 in a
GregorianCalendar
, 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
GregorianCalendar
.
roll(f, delta)
adds
delta
to field f
without changing larger
fields. This is equivalent to calling add(f, 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 .
Example: See GregorianCalendar.roll(int, int)
.
Usage model. To motivate the behavior of
add()
and roll()
, consider a user interface
component with increment and decrement buttons for the month, day, and
year, and an underlying GregorianCalendar
. If the
interface reads January 31, 1999 and the user presses the month
increment button, what should it read? If the underlying
implementation uses set()
, it might read March 3, 1999. A
better result would be February 28, 1999. Furthermore, if the user
presses the month increment button again, it should read March 31,
1999, not March 28, 1999. By saving the original date and using either
add()
or roll()
, depending on whether larger
fields should be affected, the user interface can behave as most users
will intuitively expect.
Tóm Tắt
Nested classes
class
Calendar.Builder
Calendar.Builder
is used for creating a Calendar
from
various date-time parameters.
Constants
int
ALL_STYLES
A style specifier for getDisplayNames
indicating names in all styles, such as
“January” and “Jan”.
int
AM
Value of the AM_PM
field indicating the
period of the day from midnight to just before noon.
int
AM_PM
Field number for get
and set
indicating
whether the HOUR
is before or after noon.
int
APRIL
Value of the MONTH
field indicating the
fourth month of the year in the Gregorian and Julian calendars.
int
AUGUST
Value of the MONTH
field indicating the
eighth month of the year in the Gregorian and Julian calendars.
int
DATE
Field number for get
and set
indicating the
day of the month.
int
DAY_OF_MONTH
Field number for get
and set
indicating the
day of the month.
int
DAY_OF_WEEK
Field number for get
and set
indicating the day
of the week.
int
DAY_OF_WEEK_IN_MONTH
Field number for get
and set
indicating the
ordinal number of the day of the week within the current month.
int
DAY_OF_YEAR
Field number for get
and set
indicating the day
number within the current year.
int
DECEMBER
Value of the MONTH
field indicating the
twelfth month of the year in the Gregorian and Julian calendars.
int
DST_OFFSET
Field number for get
and set
indicating the
daylight saving offset in milliseconds.
int
ERA
Field number for get
and set
indicating the
era, e.g., AD or BC in the Julian calendar.
int
FEBRUARY
Value of the MONTH
field indicating the
second month of the year in the Gregorian and Julian calendars.
int
FIELD_COUNT
The number of distinct fields recognized by get
and set
.
int
FRIDAY
Value of the DAY_OF_WEEK
field indicating
Friday.
int
HOUR
Field number for get
and set
indicating the
hour of the morning or afternoon.
int
HOUR_OF_DAY
Field number for get
and set
indicating the
hour of the day.
int
JANUARY
Value of the MONTH
field indicating the
first month of the year in the Gregorian and Julian calendars.
int
JULY
Value of the MONTH
field indicating the
seventh month of the year in the Gregorian and Julian calendars.
int
JUNE
Value of the MONTH
field indicating the
sixth month of the year in the Gregorian and Julian calendars.
int
LONG
A style specifier for getDisplayName
and getDisplayNames
equivalent to LONG_FORMAT
.
int
LONG_FORMAT
A style specifier for getDisplayName
and getDisplayNames
indicating a long name used for format.
int
LONG_STANDALONE
A style specifier for getDisplayName
and getDisplayNames
indicating a long name used independently,
such as a month name as calendar headers.
int
MARCH
Value of the MONTH
field indicating the
third month of the year in the Gregorian and Julian calendars.
int
MAY
Value of the MONTH
field indicating the
fifth month of the year in the Gregorian and Julian calendars.
int
MILLISECOND
Field number for get
and set
indicating the
millisecond within the second.
int
MINUTE
Field number for get
and set
indicating the
minute within the hour.
int
MONDAY
Value of the DAY_OF_WEEK
field indicating
Monday.
int
MONTH
Field number for get
and set
indicating the
month.
int
NARROW_FORMAT
A style specifier for getDisplayName
and getDisplayNames
indicating a narrow name used for format.
int
NARROW_STANDALONE
A style specifier for getDisplayName
and getDisplayNames
indicating a narrow name independently.
int
NOVEMBER
Value of the MONTH
field indicating the
eleventh month of the year in the Gregorian and Julian calendars.
int
OCTOBER
Value of the MONTH
field indicating the
tenth month of the year in the Gregorian and Julian calendars.
int
PM
Value of the AM_PM
field indicating the
period of the day from noon to just before midnight.
int
SATURDAY
Value of the DAY_OF_WEEK
field indicating
Saturday.
int
SECOND
Field number for get
and set
indicating the
second within the minute.
int
SEPTEMBER
Value of the MONTH
field indicating the
ninth month of the year in the Gregorian and Julian calendars.
int
SHORT
A style specifier for getDisplayName
and getDisplayNames
equivalent to SHORT_FORMAT
.
int
SHORT_FORMAT
A style specifier for getDisplayName
and getDisplayNames
indicating a short name used for format.
int
SHORT_STANDALONE
A style specifier for getDisplayName
and getDisplayNames
indicating a short name used independently,
such as a month abbreviation as calendar headers.
int
SUNDAY
Value of the DAY_OF_WEEK
field indicating
Sunday.
int
THURSDAY
Value of the DAY_OF_WEEK
field indicating
Thursday.
int
TUESDAY
Value of the DAY_OF_WEEK
field indicating
Tuesday.
int
UNDECIMBER
Value of the MONTH
field indicating the
thirteenth month of the year.
int
WEDNESDAY
Value of the DAY_OF_WEEK
field indicating
Wednesday.
int
WEEK_OF_MONTH
Field number for get
and set
indicating the
week number within the current month.
int
WEEK_OF_YEAR
Field number for get
and set
indicating the
week number within the current year.
int
YEAR
Field number for get
and set
indicating the
year.
int
ZONE_OFFSET
Field number for get
and set
indicating the raw offset from GMT in milliseconds.
Fields
protected
boolean
areFieldsSet
True if fields[]
are in sync with the currently set time.
protected
int[]
fields
The calendar field values for the currently set time for this calendar.
protected
boolean[]
isSet
The flags which tell if a specified calendar field for the calendar is set.
protected
boolean
isTimeSet
True if then the value of time
is valid.
protected
long
time
The currently set time for this calendar, expressed in milliseconds after
January 1, 1970, 0:00:00 GMT.
Protected constructors
Calendar()
Constructs a Calendar with the default time zone
and the default FORMAT
locale.
Calendar(TimeZone zone, Locale aLocale)
Constructs a calendar with the specified time zone and locale.
Public methods
abstract
void
add(int field, int amount)
Adds or subtracts the specified amount of time to the given calendar field,
based on the calendar’s rules.
boolean
after(Object when)
Returns whether this Calendar
represents a time
after the time represented by the specified
Object
.
boolean
before(Object when)
Returns whether this Calendar
represents a time
before the time represented by the specified
Object
.
final
void
clear()
Sets all the calendar field values and the time value
(millisecond offset from the Epoch) of
this Calendar
undefined.
final
void
clear(int field)
Sets the given calendar field value and the time value
(millisecond offset from the Epoch) of
this Calendar
undefined.
Object
clone()
Creates and returns a copy of this object.
int
compareTo(Calendar anotherCalendar)
Compares the time values (millisecond offsets from the Epoch) represented by two
Calendar
objects.
boolean
equals(Object obj)
Compares this Calendar
to the specified
Object
.
int
get(int field)
Returns the value of the given calendar field.
int
getActualMaximum(int field)
Returns the maximum value that the specified calendar field
could have, given the time value of this
Calendar
.
int
getActualMinimum(int field)
Returns the minimum value that the specified calendar field
could have, given the time value of this Calendar
.
static
Set<String>
getAvailableCalendarTypes()
Returns an unmodifiable Set
containing all calendar types
supported by Calendar
in the runtime environment.
static
Locale[]
getAvailableLocales()
Returns an array of all locales for which the getInstance
methods of this class can return localized instances.
String
getCalendarType()
Returns the calendar type of this Calendar
.
String
getDisplayName(int field, int style, Locale locale)
Returns the string representation of the calendar
field
value in the given style
and
locale
.
Map<String, Integer>
getDisplayNames(int field, int style, Locale locale)
Returns a Map
containing all names of the calendar
field
in the given style
and
locale
and their corresponding field values.
int
getFirstDayOfWeek()
Gets what the first day of the week is; e.g., SUNDAY
in the U.S.,
MONDAY
in France.
abstract
int
getGreatestMinimum(int field)
Returns the highest minimum value for the given calendar field
of this Calendar
instance.
static
Calendar
getInstance()
Gets a calendar using the default time zone and locale.
static
Calendar
getInstance(Locale aLocale)
Gets a calendar using the default time zone and specified locale.
static
Calendar
getInstance(TimeZone zone, Locale aLocale)
Gets a calendar with the specified time zone and locale.
static
Calendar
getInstance(TimeZone zone)
Gets a calendar using the specified time zone and default locale.
abstract
int
getLeastMaximum(int field)
Returns the lowest maximum value for the given calendar field
of this Calendar
instance.
abstract
int
getMaximum(int field)
Returns the maximum value for the given calendar field of this
Calendar
instance.
int
getMinimalDaysInFirstWeek()
Gets what the minimal days required in the first week of the year are;
e.g., if the first week is defined as one that contains the first day
of the first month of a year, this method returns 1.
abstract
int
getMinimum(int field)
Returns the minimum value for the given calendar field of this
Calendar
instance.
final
Date
getTime()
Returns a Date
object representing this
Calendar
‘s time value (millisecond offset from the Epoch”).
long
getTimeInMillis()
Returns this Calendar’s time value in milliseconds.
TimeZone
getTimeZone()
Gets the time zone.
int
getWeekYear()
Returns the week year represented by this Calendar
.
int
getWeeksInWeekYear()
Returns the number of weeks in the week year represented by this
Calendar
.
int
hashCode()
Returns a hash code for this calendar.
boolean
isLenient()
Tells whether date/time interpretation is to be lenient.
final
boolean
isSet(int field)
Determines if the given calendar field has a value set,
including cases that the value has been set by internal fields
calculations triggered by a get
method call.
boolean
isWeekDateSupported()
Returns whether this Calendar
supports week dates.
abstract
void
roll(int field, boolean up)
Adds or subtracts (up/down) a single unit of time on the given time
field without changing larger fields.
void
roll(int field, int amount)
Adds the specified (signed) amount to the specified calendar field
without changing larger fields.
final
void
set(int year, int month, int date, int hourOfDay, int minute, int second)
Sets the values for the fields YEAR
, MONTH
,
DAY_OF_MONTH
, HOUR_OF_DAY
, MINUTE
, and
SECOND
.
final
void
set(int year, int month, int date, int hourOfDay, int minute)
Sets the values for the calendar fields YEAR
,
MONTH
, DAY_OF_MONTH
,
HOUR_OF_DAY
, and MINUTE
.
void
set(int field, int value)
Sets the given calendar field to the given value.
final
void
set(int year, int month, int date)
Sets the values for the calendar fields YEAR
,
MONTH
, and DAY_OF_MONTH
.
void
setFirstDayOfWeek(int value)
Sets what the first day of the week is; e.g., SUNDAY
in the U.S.,
MONDAY
in France.
void
setLenient(boolean lenient)
Specifies whether or not date/time interpretation is to be lenient.
void
setMinimalDaysInFirstWeek(int value)
Sets what the minimal days required in the first week of the year are;
For example, if the first week is defined as one that contains the first
day of the first month of a year, call this method with value 1.
final
void
setTime(Date date)
Sets this Calendar’s time with the given Date
.
void
setTimeInMillis(long millis)
Sets this Calendar’s current time from the given long value.
void
setTimeZone(TimeZone value)
Sets the time zone with the given time zone value.
void
setWeekDate(int weekYear, int weekOfYear, int dayOfWeek)
Sets the date of this Calendar
with the the given date
specifiers – week year, week of year, and day of week.
final
Instant
toInstant()
Converts this object to an Instant
.
String
toString()
Return a string representation of this calendar.
Protected methods
void
complete()
Fills in any unset fields in the calendar fields.
abstract
void
computeFields()
Converts the current millisecond time value time
to calendar field values in fields[]
.
abstract
void
computeTime()
Converts the current calendar field values in fields[]
to the millisecond time value
time
.
final
int
internalGet(int field)
Returns the value of the given calendar field.
Inherited methods
From class
Object
clone()
Creates and returns a copy of this object.
boolean
equals(Object obj)
Indicates whether some other object is “equal to” this one.
void
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
final
Class<?>
getClass()
Returns the runtime class of this Object
.
int
hashCode()
Returns a hash code value for the object.
final
void
notify()
Wakes up a single thread that is waiting on this object’s
monitor.
final
void
notifyAll()
Wakes up all threads that are waiting on this object’s monitor.
String
toString()
Returns a string representation of the object.
final
void
wait(long timeout, int nanos)
Causes the current thread to wait until another thread invokes the
notify()
method or the
notifyAll()
method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.
final
void
wait(long timeout)
Causes the current thread to wait until either another thread invokes the
notify()
method or the
notifyAll()
method for this object, or a
specified amount of time has elapsed.
final
void
wait()
Causes the current thread to wait until another thread invokes the
notify()
method or the
notifyAll()
method for this object.
From interface
abstract
int
compareTo(Calendar o)
Compares this object with the specified object for order.
Constants
AM
Added in API level 1
public static final int AM
Value of the AM_PM
field indicating the
period of the day from midnight to just before noon.
Constant Value:
0
(0x00000000)
AM_PM
Added in API level 1
public static final int AM_PM
Field number for get
and set
indicating
whether the HOUR
is before or after noon.
E.g., at 10:04:15.250 PM the AM_PM
is PM
.
See also:
AM
PM
HOUR
Constant Value:
9
(0x00000009)
APRIL
Added in API level 1
public static final int APRIL
Value of the MONTH
field indicating the
fourth month of the year in the Gregorian and Julian calendars.
Constant Value:
3
(0x00000003)
AUGUST
Added in API level 1
public static final int AUGUST
Value of the MONTH
field indicating the
eighth month of the year in the Gregorian and Julian calendars.
Constant Value:
7
(0x00000007)
Added in API level 1
public static final int DATE
Field number for get
and set
indicating the
day of the month. This is a synonym for DAY_OF_MONTH
.
The first day of the month has value 1.
See also:
DAY_OF_MONTH
Constant Value:
5
(0x00000005)
DAY_OF_MONTH
Added in API level 1
public static final int DAY_OF_MONTH
Field number for get
and set
indicating the
day of the month. This is a synonym for DATE
.
The first day of the month has value 1.
See also:
DATE
Constant Value:
5
(0x00000005)
DAY_OF_WEEK
Added in API level 1
public static final int DAY_OF_WEEK
Field number for get
and set
indicating the day
of the week. This field takes values SUNDAY
,
MONDAY
, TUESDAY
, WEDNESDAY
,
THURSDAY
, FRIDAY
, and SATURDAY
.
See also:
SUNDAY
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
Constant Value:
7
(0x00000007)
DAY_OF_WEEK_IN_MONTH
Added in API level 1
public static final int DAY_OF_WEEK_IN_MONTH
Field number for get
and set
indicating the
ordinal number of the day of the week within the current month. Together
with the DAY_OF_WEEK
field, this uniquely specifies a day
within a month. Unlike WEEK_OF_MONTH
and
WEEK_OF_YEAR
, this field’s value does not depend on
getFirstDayOfWeek()
or
getMinimalDaysInFirstWeek()
. DAY_OF_MONTH 1
through 7
always correspond to DAY_OF_WEEK_IN_MONTH
;
18
through 14
correspond to
DAY_OF_WEEK_IN_MONTH 2
, and so on.
DAY_OF_WEEK_IN_MONTH 0
indicates the week before
DAY_OF_WEEK_IN_MONTH 1
. Negative values count back from the
end of the month, so the last Sunday of a month is specified as
DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1
. Because
negative values count backward they will usually be aligned differently
within the month than positive values. For example, if a month has 31
days, DAY_OF_WEEK_IN_MONTH -1
will overlap
DAY_OF_WEEK_IN_MONTH 5
and the end of 4
.
See also:
DAY_OF_WEEK
WEEK_OF_MONTH
Constant Value:
8
(0x00000008)
DAY_OF_YEAR
Added in API level 1
public static final int DAY_OF_YEAR
Field number for get
and set
indicating the day
number within the current year. The first day of the year has value 1.
Constant Value:
6
(0x00000006)
DECEMBER
Added in API level 1
public static final int DECEMBER
Value of the MONTH
field indicating the
twelfth month of the year in the Gregorian and Julian calendars.
Constant Value:
11
(0x0000000b)
DST_OFFSET
Added in API level 1
public static final int DST_OFFSET
Field number for get
and set
indicating the
daylight saving offset in milliseconds.
This field reflects the correct daylight saving offset value of
the time zone of this Calendar
if the
TimeZone
implementation subclass supports
historical Daylight Saving Time schedule changes.
Constant Value:
16
(0x00000010)
ERA
Added in API level 1
public static final int ERA
Field number for get
and set
indicating the
era, e.g., AD or BC in the Julian calendar. This is a calendar-specific
value; see subclass documentation.
See also:
GregorianCalendar.AD
GregorianCalendar.BC
Constant Value:
0
(0x00000000)
FEBRUARY
Added in API level 1
public static final int FEBRUARY
Value of the MONTH
field indicating the
second month of the year in the Gregorian and Julian calendars.
Constant Value:
1
(0x00000001)
FIELD_COUNT
Added in API level 1
public static final int FIELD_COUNT
The number of distinct fields recognized by get
and set
.
Field numbers range from 0..FIELD_COUNT-1
.
Constant Value:
17
(0x00000011)
FRIDAY
Added in API level 1
public static final int FRIDAY
Value of the DAY_OF_WEEK
field indicating
Friday.
Constant Value:
6
(0x00000006)
HOUR
Added in API level 1
public static final int HOUR
Field number for get
and set
indicating the
hour of the morning or afternoon. HOUR
is used for the
12-hour clock (0 – 11). Noon and midnight are represented by 0, not by 12.
E.g., at 10:04:15.250 PM the HOUR
is 10.
See also:
AM_PM
HOUR_OF_DAY
Constant Value:
10
(0x0000000a)
HOUR_OF_DAY
Added in API level 1
public static final int HOUR_OF_DAY
Field number for get
and set
indicating the
hour of the day. HOUR_OF_DAY
is used for the 24-hour clock.
E.g., at 10:04:15.250 PM the HOUR_OF_DAY
is 22.
See also:
HOUR
Constant Value:
11
(0x0000000b)
JANUARY
Added in API level 1
public static final int JANUARY
Value of the MONTH
field indicating the
first month of the year in the Gregorian and Julian calendars.
Constant Value:
0
(0x00000000)
JULY
Added in API level 1
public static final int JULY
Value of the MONTH
field indicating the
seventh month of the year in the Gregorian and Julian calendars.
Constant Value:
6
(0x00000006)
JUNE
Added in API level 1
public static final int JUNE
Value of the MONTH
field indicating the
sixth month of the year in the Gregorian and Julian calendars.
Constant Value:
5
(0x00000005)
LONG
Added in API level 9
public static final int LONG
A style specifier for getDisplayName
and getDisplayNames
equivalent to LONG_FORMAT
.
See also:
LONG_STANDALONE
SHORT
Constant Value:
2
(0x00000002)
LONG_FORMAT
Added in API level 26
public static final int LONG_FORMAT
A style specifier for getDisplayName
and getDisplayNames
indicating a long name used for format.
See also:
LONG_STANDALONE
SHORT_FORMAT
SHORT_STANDALONE
Constant Value:
2
(0x00000002)
LONG_STANDALONE
Added in API level 26
public static final int LONG_STANDALONE
A style specifier for getDisplayName
and getDisplayNames
indicating a long name used independently,
such as a month name as calendar headers.
See also:
LONG_FORMAT
SHORT_FORMAT
SHORT_STANDALONE
Constant Value:
32770
(0x00008002)
MARCH
Added in API level 1
public static final int MARCH
Value of the MONTH
field indicating the
third month of the year in the Gregorian and Julian calendars.
Constant Value:
2
(0x00000002)
MAY
Added in API level 1
public static final int MAY
Value of the MONTH
field indicating the
fifth month of the year in the Gregorian and Julian calendars.
Constant Value:
4
(0x00000004)
MILLISECOND
Added in API level 1
public static final int MILLISECOND
Field number for get
and set
indicating the
millisecond within the second.
E.g., at 10:04:15.250 PM the MILLISECOND
is 250.
Constant Value:
14
(0x0000000e)
MINUTE
Added in API level 1
public static final int MINUTE
Field number for get
and set
indicating the
minute within the hour.
E.g., at 10:04:15.250 PM the MINUTE
is 4.
Constant Value:
12
(0x0000000c)
MONDAY
Added in API level 1
public static final int MONDAY
Value of the DAY_OF_WEEK
field indicating
Monday.
Constant Value:
2
(0x00000002)
MONTH
Added in API level 1
public static final int MONTH
Field number for get
and set
indicating the
month. This is a calendar-specific value. The first month of
the year in the Gregorian and Julian calendars is
JANUARY
which is 0; the last depends on the number
of months in a year.
See also:
JANUARY
FEBRUARY
MARCH
APRIL
MAY
JUNE
JULY
AUGUST
SEPTEMBER
OCTOBER
NOVEMBER
DECEMBER
UNDECIMBER
Constant Value:
2
(0x00000002)
NARROW_FORMAT
Added in API level 26
public static final int NARROW_FORMAT
A style specifier for getDisplayName
and getDisplayNames
indicating a narrow name used for format. Narrow names
are typically single character strings, such as “M” for Monday.
See also:
NARROW_STANDALONE
SHORT_FORMAT
LONG_FORMAT
Constant Value:
4
(0x00000004)
NARROW_STANDALONE
Added in API level 26
public static final int NARROW_STANDALONE
A style specifier for getDisplayName
and getDisplayNames
indicating a narrow name independently. Narrow names
are typically single character strings, such as “M” for Monday.
See also:
NARROW_FORMAT
SHORT_STANDALONE
LONG_STANDALONE
Constant Value:
32772
(0x00008004)
NOVEMBER
Added in API level 1
public static final int NOVEMBER
Value of the MONTH
field indicating the
eleventh month of the year in the Gregorian and Julian calendars.
Constant Value:
10
(0x0000000a)
OCTOBER
Added in API level 1
public static final int OCTOBER
Value of the MONTH
field indicating the
tenth month of the year in the Gregorian and Julian calendars.
Constant Value:
9
(0x00000009)
PM
Added in API level 1
public static final int PM
Value of the AM_PM
field indicating the
period of the day from noon to just before midnight.
Constant Value:
1
(0x00000001)
SATURDAY
Added in API level 1
public static final int SATURDAY
Value of the DAY_OF_WEEK
field indicating
Saturday.
Constant Value:
7
(0x00000007)
SECOND
Added in API level 1
public static final int SECOND
Field number for get
and set
indicating the
second within the minute.
E.g., at 10:04:15.250 PM the SECOND
is 15.
Constant Value:
13
(0x0000000d)
SEPTEMBER
Added in API level 1
public static final int SEPTEMBER
Value of the MONTH
field indicating the
ninth month of the year in the Gregorian and Julian calendars.
Constant Value:
8
(0x00000008)
SHORT
Added in API level 9
public static final int SHORT
A style specifier for getDisplayName
and getDisplayNames
equivalent to SHORT_FORMAT
.
See also:
SHORT_STANDALONE
LONG
Constant Value:
1
(0x00000001)
SHORT_FORMAT
Added in API level 26
public static final int SHORT_FORMAT
A style specifier for getDisplayName
and getDisplayNames
indicating a short name used for format.
See also:
SHORT_STANDALONE
LONG_FORMAT
LONG_STANDALONE
Constant Value:
1
(0x00000001)
SHORT_STANDALONE
Added in API level 26
public static final int SHORT_STANDALONE
A style specifier for getDisplayName
and getDisplayNames
indicating a short name used independently,
such as a month abbreviation as calendar headers.
See also:
SHORT_FORMAT
LONG_FORMAT
LONG_STANDALONE
Constant Value:
32769
(0x00008001)
SUNDAY
Added in API level 1
public static final int SUNDAY
Value of the DAY_OF_WEEK
field indicating
Sunday.
Constant Value:
1
(0x00000001)
THURSDAY
Added in API level 1
public static final int THURSDAY
Value of the DAY_OF_WEEK
field indicating
Thursday.
Constant Value:
5
(0x00000005)
TUESDAY
Added in API level 1
public static final int TUESDAY
Value of the DAY_OF_WEEK
field indicating
Tuesday.
Constant Value:
3
(0x00000003)
UNDECIMBER
Added in API level 1
public static final int UNDECIMBER
Value of the MONTH
field indicating the
thirteenth month of the year. Although GregorianCalendar
does not use this value, lunar calendars do.
Constant Value:
12
(0x0000000c)
WEDNESDAY
Added in API level 1
public static final int WEDNESDAY
Value of the DAY_OF_WEEK
field indicating
Wednesday.
Constant Value:
4
(0x00000004)
WEEK_OF_MONTH
Added in API level 1
public static final int WEEK_OF_MONTH
Field number for get
and set
indicating the
week number within the current month. The first week of the month, as
defined by getFirstDayOfWeek()
and
getMinimalDaysInFirstWeek()
, has value 1. Subclasses define
the value of WEEK_OF_MONTH
for days before the first week of
the month.
See also:
getFirstDayOfWeek()
getMinimalDaysInFirstWeek()
Constant Value:
4
(0x00000004)
WEEK_OF_YEAR
Added in API level 1
public static final int WEEK_OF_YEAR
Field number for get
and set
indicating the
week number within the current year. The first week of the year, as
defined by getFirstDayOfWeek()
and
getMinimalDaysInFirstWeek()
, has value 1. Subclasses define
the value of WEEK_OF_YEAR
for days before the first week of
the year.
See also:
getFirstDayOfWeek()
getMinimalDaysInFirstWeek()
Constant Value:
3
(0x00000003)
YEAR
Added in API level 1
public static final int YEAR
Field number for get
and set
indicating the
year. This is a calendar-specific value; see subclass documentation.
Constant Value:
1
(0x00000001)
ZONE_OFFSET
Added in API level 1
public static final int ZONE_OFFSET
Field number for get
and set
indicating the raw offset from GMT in milliseconds.
This field reflects the correct GMT offset value of the time
zone of this Calendar
if the
TimeZone
implementation subclass supports
historical GMT offset changes.
Constant Value:
15
(0x0000000f)
Fields
areFieldsSet
Added in API level 1
protected boolean areFieldsSet
True if fields[]
are in sync with the currently set time.
If false, then the next attempt to get the value of a field will
force a recomputation of all fields from the current value of
time
.
fields
Added in API level 1
protected int[] fields
The calendar field values for the currently set time for this calendar.
This is an array of FIELD_COUNT
integers, with index values
ERA
through DST_OFFSET
.
isSet
Added in API level 1
protected boolean[] isSet
The flags which tell if a specified calendar field for the calendar is set.
A new object has no fields set. After the first call to a method
which generates the fields, they all remain set after that.
This is an array of FIELD_COUNT
booleans, with index values
ERA
through DST_OFFSET
.
isTimeSet
Added in API level 1
protected boolean isTimeSet
True if then the value of time
is valid.
The time is made invalid by a change to an item of field[]
.
See also:
time
time
Added in API level 1
protected long time
The currently set time for this calendar, expressed in milliseconds after
January 1, 1970, 0:00:00 GMT.
See also:
isTimeSet
Protected constructors
Calendar
Added in API level 1
protected Calendar ()
Constructs a Calendar with the default time zone
and the default FORMAT
locale.
See also:
TimeZone.getDefault()
Calendar
Added in API level 1
protected Calendar (TimeZone zone, Locale aLocale)
Constructs a calendar with the specified time zone and locale.
Parameters
zone
TimeZone
: the time zone to use
aLocale
Locale
: the locale for the week data
Public methods
add
Added in API level 1
public abstract void add (int field, int amount)
Adds or subtracts the specified amount of time to the given calendar field,
based on the calendar’s rules. For example, to subtract 5 days from
the current time of the calendar, you can achieve it by calling:
add(Calendar.DAY_OF_MONTH, -5)
.
Parameters
field
int
: the calendar field.
amount
int
: the amount of date or time to be added to the field.
See also:
roll(int, int)
set(int, int)
after
Added in API level 1
public boolean after (Object when)
Returns whether this Calendar
represents a time
after the time represented by the specified
Object
. This method is equivalent to:
compareTo(when) > 0
if and only if when
is a Calendar
instance. Otherwise, the method returns false
.
Parameters
when
Object
: the Object
to be compared
Returns
boolean
true
if the time of this Calendar
is
after the time represented by when
; false
otherwise.
See also:
compareTo(Calendar)
if and only ifis ainstance. Otherwise, the method returns
before
Added in API level 1
public boolean before (Object when)
Returns whether this Calendar
represents a time
before the time represented by the specified
Object
. This method is equivalent to:
compareTo(when) < 0
if and only if when
is a Calendar
instance. Otherwise, the method returns false
.
Parameters
when
Object
: the Object
to be compared
Returns
boolean
true
if the time of this
Calendar
is before the time represented by
when
; false
otherwise.
See also:
compareTo(Calendar)
if and only ifis ainstance. Otherwise, the method returns
clear
Added in API level 1
public final void clear ()
Sets all the calendar field values and the time value
(millisecond offset from the Epoch) of
this Calendar
undefined. This means that isSet()
will return false
for all the
calendar fields, and the date and time calculations will treat
the fields as if they had never been set. A
Calendar
implementation class may use its specific
default field values for date/time calculations. For example,
GregorianCalendar
uses 1970 if the
YEAR
field value is undefined.
See also:
clear(int)
clone
Added in API level 1
public Object clone ()
Creates and returns a copy of this object.
Returns
Object
a copy of this object.
compareTo
Added in API level 1
public int compareTo (Calendar anotherCalendar)
Compares the time values (millisecond offsets from the Epoch) represented by two
Calendar
objects.
Parameters
anotherCalendar
Calendar
: the Calendar
to be compared.
Returns
int
the value 0
if the time represented by the argument
is equal to the time represented by this Calendar
; a value
less than 0
if the time of this Calendar
is
before the time represented by the argument; and a value greater than
0
if the time of this Calendar
is after the
time represented by the argument.
Throws
NullPointerException
if the specified Calendar
is
null
.
IllegalArgumentException
if the time value of the
specified Calendar
object can’t be obtained due to
any invalid calendar values.
equals
Added in API level 1
public boolean equals (Object obj)
Compares this Calendar
to the specified
Object
. The result is true
if and only if
the argument is a Calendar
object of the same calendar
system that represents the same time value (millisecond offset from the
Epoch) under the same
Calendar
parameters as this object.
The Calendar
parameters are the values represented
by the isLenient
, getFirstDayOfWeek
,
getMinimalDaysInFirstWeek
and getTimeZone
methods. If there is any difference in those parameters
between the two Calendar
s, this method returns
false
.
Use the compareTo
method to
compare only the time values.
Parameters
obj
Object
: the object to compare with.
Returns
boolean
true
if this object is equal to obj
;
false
otherwise.
get
Added in API level 1
public int get (int field)
Returns the value of the given calendar field. In lenient mode,
all calendar fields are normalized. In non-lenient mode, all
calendar fields are validated and this method throws an
exception if any calendar fields have out-of-range values. The
normalization and validation are handled by the
complete()
method, which process is calendar
system dependent.
Parameters
field
int
: the given calendar field.
Returns
int
the value for the given calendar field.
Throws
ArrayIndexOutOfBoundsException
if the specified field is out of range
(field < 0 || field >= FIELD_COUNT
).
See also:
set(int, int)
complete()
getActualMaximum
Added in API level 1
public int getActualMaximum (int field)
Returns the maximum value that the specified calendar field
could have, given the time value of this
Calendar
. For example, the actual maximum value of
the MONTH
field is 12 in some years, and 13 in
other years in the Hebrew calendar system.
The default implementation of this method uses an iterative
algorithm to determine the actual maximum value for the
calendar field. Subclasses should, if possible, override this
with a more efficient implementation.
Parameters
field
int
: the calendar field
Returns
int
the maximum of the given calendar field for the time
value of this Calendar
See also:
getMinimum(int)
getMaximum(int)
getGreatestMinimum(int)
getLeastMaximum(int)
getActualMinimum(int)
getActualMinimum
Added in API level 1
public int getActualMinimum (int field)
Returns the minimum value that the specified calendar field
could have, given the time value of this Calendar
.
The default implementation of this method uses an iterative
algorithm to determine the actual minimum value for the
calendar field. Subclasses should, if possible, override this
with a more efficient implementation – in many cases, they can
simply return getMinimum()
.
Parameters
field
int
: the calendar field
Returns
int
the minimum of the given calendar field for the time
value of this Calendar
See also:
getMinimum(int)
getMaximum(int)
getGreatestMinimum(int)
getLeastMaximum(int)
getActualMaximum(int)
getAvailableCalendarTypes
Added in API level 26
public static Set<String> getAvailableCalendarTypes ()
Returns an unmodifiable Set
containing all calendar types
supported by Calendar
in the runtime environment. The available
calendar types can be used for the Unicode locale extensions.
The Set
returned contains at least "gregory"
. The
calendar types don’t include aliases, such as "gregorian"
for
"gregory"
.
Returns
Set<String>
an unmodifiable Set
containing all available calendar types
See also:
getCalendarType()
Calendar.Builder.setCalendarType(String)
Locale.getUnicodeLocaleType(String)
getAvailableLocales
Added in API level 1
public static Locale[] getAvailableLocales ()
Returns an array of all locales for which the getInstance
methods of this class can return localized instances.
The array returned must contain at least a Locale
instance equal to Locale.US
.
Returns
Locale[]
An array of locales for which localized
Calendar
instances are available.
getCalendarType
Added in API level 26
public String getCalendarType ()
Returns the calendar type of this Calendar
. Calendar types are
defined by the Unicode Locale Data Markup Language (LDML)
specification.
The default implementation of this method returns the class name of
this Calendar
instance. Any subclasses that implement
LDML-defined calendar systems should override this method to return
appropriate calendar types.
Returns
String
the LDML-defined calendar type or the class name of this
Calendar
instance
See also:
- Locale extensions
Locale.Builder.setLocale(Locale)
Locale.Builder.setUnicodeLocaleKeyword(String, String)
getDisplayName
Added in API level 9
public String getDisplayName (int field, int style, Locale locale)
Returns the string representation of the calendar
field
value in the given style
and
locale
. If no string representation is
applicable, null
is returned. This method calls
get(field)
to get the calendar
field
value if the string representation is
applicable to the given calendar field
.
For example, if this Calendar
is a
GregorianCalendar
and its date is 2005-01-01, then
the string representation of the MONTH
field would be
“January” in the long style in an English locale or “Jan” in
the short style. However, no string representation would be
available for the DAY_OF_MONTH
field, and this method
would return null
.
The default implementation supports the calendar fields for
which a DateFormatSymbols
has names in the given
locale
.
Parameters
field
int
: the calendar field for which the string representation
is returned
style
int
: the style applied to the string representation; one of SHORT_FORMAT
(SHORT
), SHORT_STANDALONE
,
LONG_FORMAT
(LONG
), LONG_STANDALONE
,
NARROW_FORMAT
, or NARROW_STANDALONE
.
locale
Locale
: the locale for the string representation
(any calendar types specified by locale
are ignored)
Returns
String
the string representation of the given
field
in the given style
, or
null
if no string representation is
applicable.
Throws
IllegalArgumentException
if field
or style
is invalid,
or if this Calendar
is non-lenient and any
of the calendar fields have invalid values
NullPointerException
if locale
is null
getDisplayNames
Added in API level 9
public Map<String, Integer> getDisplayNames (int field, int style, Locale locale)
Returns a Map
containing all names of the calendar
field
in the given style
and
locale
and their corresponding field values. For
example, if this Calendar
is a GregorianCalendar
, the returned map would contain “Jan” to
JANUARY
, “Feb” to FEBRUARY
, and so on, in the
short style in an English locale.
Narrow names may not be unique due to use of single characters,
such as “S” for Sunday and Saturday. In that case narrow names are not
included in the returned Map
.
The values of other calendar fields may be taken into
account to determine a set of display names. For example, if
this Calendar
is a lunisolar calendar system and
the year value given by the YEAR
field has a leap
month, this method would return month names containing the leap
month name, and month names are mapped to their values specific
for the year.
The default implementation supports display names contained in
a DateFormatSymbols
. For example, if field
is MONTH
and style
is ALL_STYLES
, this method returns a Map
containing
all strings returned by DateFormatSymbols#getShortMonths()
and DateFormatSymbols#getMonths()
.
Parameters
field
int
: the calendar field for which the display names are returned
style
int
: the style applied to the string representation; one of SHORT_FORMAT
(SHORT
), SHORT_STANDALONE
,
LONG_FORMAT
(LONG
), LONG_STANDALONE
,
NARROW_FORMAT
, or NARROW_STANDALONE
locale
Locale
: the locale for the display names
Returns
Map<String, Integer>
a Map
containing all display names in
style
and locale
and their
field values, or null
if no display names
are defined for field
Throws
IllegalArgumentException
if field
or style
is invalid,
or if this Calendar
is non-lenient and any
of the calendar fields have invalid values
NullPointerException
if locale
is null
getFirstDayOfWeek
Added in API level 1
public int getFirstDayOfWeek ()
Gets what the first day of the week is; e.g., SUNDAY
in the U.S.,
MONDAY
in France.
Returns
int
the first day of the week.
See also:
setFirstDayOfWeek(int)
getMinimalDaysInFirstWeek()
getGreatestMinimum
Added in API level 1
public abstract int getGreatestMinimum (int field)
Returns the highest minimum value for the given calendar field
of this Calendar
instance. The highest minimum
value is defined as the largest value returned by getActualMinimum(int)
for any possible time value. The
greatest minimum value depends on calendar system specific
parameters of the instance.
Parameters
field
int
: the calendar field.
Returns
int
the highest minimum value for the given calendar field.
See also:
getMinimum(int)
getMaximum(int)
getLeastMaximum(int)
getActualMinimum(int)
getActualMaximum(int)
getInstance
Added in API level 1
public static 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
FORMAT
locale.
Returns
Calendar
a Calendar.
getInstance
Added in API level 1
public static Calendar getInstance (Locale aLocale)
Gets a calendar using the default time zone and specified locale.
The Calendar
returned is based on the current time
in the default time zone with the given locale.
Parameters
aLocale
Locale
: the locale for the week data
Returns
Calendar
a Calendar.
getInstance
Added in API level 1
public static Calendar getInstance (TimeZone zone, Locale aLocale)
Gets a calendar with the specified time zone and locale.
The Calendar
returned is based on the current time
in the given time zone with the given locale.
Parameters
zone
TimeZone
: the time zone to use
aLocale
Locale
: the locale for the week data
Returns
Calendar
a Calendar.
getInstance
Added in API level 1
public static Calendar getInstance (TimeZone zone)
Gets a calendar using the specified time zone and default locale.
The Calendar
returned is based on the current time
in the given time zone with the default
FORMAT
locale.
Parameters
zone
TimeZone
: the time zone to use
Returns
Calendar
a Calendar.
getLeastMaximum
Added in API level 1
public abstract int getLeastMaximum (int field)
Returns the lowest maximum value for the given calendar field
of this Calendar
instance. The lowest maximum
value is defined as the smallest value returned by getActualMaximum(int)
for any possible time value. The least
maximum value depends on calendar system specific parameters of
the instance. For example, a Calendar
for the
Gregorian calendar system returns 28 for the
DAY_OF_MONTH
field, because the 28th is the last
day of the shortest month of this calendar, February in a
common year.
Parameters
field
int
: the calendar field.
Returns
int
the lowest maximum value for the given calendar field.
See also:
getMinimum(int)
getMaximum(int)
getGreatestMinimum(int)
getActualMinimum(int)
getActualMaximum(int)
getMaximum
Added in API level 1
public abstract int getMaximum (int field)
Returns the maximum value for the given calendar field of this
Calendar
instance. The maximum value is defined as
the largest value returned by the get
method
for any possible time value. The maximum value depends on
calendar system specific parameters of the instance.
Parameters
field
int
: the calendar field.
Returns
int
the maximum value for the given calendar field.
See also:
getMinimum(int)
getGreatestMinimum(int)
getLeastMaximum(int)
getActualMinimum(int)
getActualMaximum(int)
getMinimalDaysInFirstWeek
Added in API level 1
public int getMinimalDaysInFirstWeek ()
Gets what the minimal days required in the first week of the year are;
e.g., if the first week is defined as one that contains the first day
of the first month of a year, this method returns 1. If
the minimal days required must be a full week, this method
returns 7.
Returns
int
the minimal days required in the first week of the year.
See also:
setMinimalDaysInFirstWeek(int)
getMinimum
Added in API level 1
public abstract int getMinimum (int field)
Returns the minimum value for the given calendar field of this
Calendar
instance. The minimum value is defined as
the smallest value returned by the get
method
for any possible time value. The minimum value depends on
calendar system specific parameters of the instance.
Parameters
field
int
: the calendar field.
Returns
int
the minimum value for the given calendar field.
See also:
getMaximum(int)
getGreatestMinimum(int)
getLeastMaximum(int)
getActualMinimum(int)
getActualMaximum(int)
getTime
Added in API level 1
public final Date getTime ()
Returns a Date
object representing this
Calendar
‘s time value (millisecond offset from the Epoch”).
Returns
Date
a Date
representing the time value.
See also:
setTime(Date)
getTimeInMillis()
getTimeInMillis
Added in API level 1
public long getTimeInMillis ()
Returns this Calendar’s time value in milliseconds.
Returns
long
the current time as UTC milliseconds from the epoch.
See also:
getTime()
setTimeInMillis(long)
getTimeZone
Added in API level 1
public TimeZone getTimeZone ()
Gets the time zone.
Returns
TimeZone
the time zone object associated with this calendar.
getWeekYear
Added in API level 24
public int getWeekYear ()
Returns the week year represented by this Calendar
. The
week year is in sync with the week cycle. The first day of the first week is the first
day of the week year.
The default implementation of this method throws an
UnsupportedOperationException
.
Returns
int
the week year of this Calendar
Throws
UnsupportedOperationException
if any week year numbering isn’t supported
in this Calendar
.
See also:
isWeekDateSupported()
getFirstDayOfWeek()
getMinimalDaysInFirstWeek()
getWeeksInWeekYear
Added in API level 24
public int getWeeksInWeekYear ()
Returns the number of weeks in the week year represented by this
Calendar
.
The default implementation of this method throws an
UnsupportedOperationException
.
Returns
int
the number of weeks in the week year.
Throws
UnsupportedOperationException
if any week year numbering isn’t supported in this
Calendar
.
See also:
WEEK_OF_YEAR
isWeekDateSupported()
getWeekYear()
getActualMaximum(int)
hashCode
Added in API level 1
public int hashCode ()
Returns a hash code for this calendar.
Returns
int
a hash code value for this object.
isLenient
Added in API level 1
public boolean isLenient ()
Tells whether date/time interpretation is to be lenient.
Returns
boolean
true
if the interpretation mode of this calendar is lenient;
false
otherwise.
See also:
setLenient(boolean)
isSet
Added in API level 1
public final boolean isSet (int field)
Determines if the given calendar field has a value set,
including cases that the value has been set by internal fields
calculations triggered by a get
method call.
Parameters
field
int
: the calendar field to test
Returns
boolean
true
if the given calendar field has a value set;
false
otherwise.
Added in API level 24
public boolean isWeekDateSupported ()
Returns whether this Calendar
supports week dates.
The default implementation of this method returns false
.
Returns
boolean
true
if this Calendar
supports week dates;
false
otherwise.
See also:
getWeekYear()
setWeekDate(int, int, int)
getWeeksInWeekYear()
roll
Added in API level 1
public abstract void roll (int field, boolean up)
Adds or subtracts (up/down) a single unit of time on the given time
field without changing larger fields. For example, to roll the current
date up by one day, you can achieve it by calling:
roll(Calendar.DATE, true).
When rolling on the year or Calendar.YEAR field, it will roll the year
value in the range between 1 and the value returned by calling
getMaximum(Calendar.YEAR)
.
When rolling on the month or Calendar.MONTH field, other fields like
date might conflict and, need to be changed. For instance,
rolling the month on the date 01/31/96 will result in 02/29/96.
When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will
roll the hour value in the range between 0 and 23, which is zero-based.
Parameters
field
int
: the time field.
up
boolean
: indicates if the value of the specified time field is to be
rolled up or rolled down. Use true if rolling up, false otherwise.
See also:
add(int, int)
set(int, int)
roll
Added in API level 1
public void roll (int field, int amount)
Adds the specified (signed) amount to the specified calendar field
without changing larger fields. A negative amount means to roll
down.
NOTE: This default implementation on Calendar
just repeatedly calls the
version of roll()
that rolls by one unit. This may not
always do the right thing. For example, if the DAY_OF_MONTH
field is 31,
rolling through February will leave it set to 28. The GregorianCalendar
version of this function takes care of this problem. Other subclasses
should also provide overrides of this function that do the right thing.
Parameters
field
int
: the calendar field.
amount
int
: the signed amount to add to the calendar field
.
See also:
roll(int, boolean)
add(int, int)
set(int, int)
set
Added in API level 1
public final void set (int year, int month, int date, int hourOfDay, int minute, int second)
Sets the values for the fields YEAR
, MONTH
,
DAY_OF_MONTH
, HOUR_OF_DAY
, MINUTE
, and
SECOND
.
Previous values of other fields are retained. If this is not desired,
call clear()
first.
Parameters
year
int
: the value used to set the YEAR
calendar field.
month
int
: the value used to set the MONTH
calendar field.
Month value is 0-based. e.g., 0 for January.
date
int
: the value used to set the DAY_OF_MONTH
calendar field.
hourOfDay
int
: the value used to set the HOUR_OF_DAY
calendar field.
minute
int
: the value used to set the MINUTE
calendar field.
second
int
: the value used to set the SECOND
calendar field.
See also:
set(int, int)
set(int, int, int)
set(int, int, int, int, int)
set
Added in API level 1
public final void set (int year, int month, int date, int hourOfDay, int minute)
Sets the values for the calendar fields YEAR
,
MONTH
, DAY_OF_MONTH
,
HOUR_OF_DAY
, and MINUTE
.
Previous values of other fields are retained. If this is not desired,
call clear()
first.
Parameters
year
int
: the value used to set the YEAR
calendar field.
month
int
: the value used to set the MONTH
calendar field.
Month value is 0-based. e.g., 0 for January.
date
int
: the value used to set the DAY_OF_MONTH
calendar field.
hourOfDay
int
: the value used to set the HOUR_OF_DAY
calendar field.
minute
int
: the value used to set the MINUTE
calendar field.
See also:
set(int, int)
set(int, int, int)
set(int, int, int, int, int, int)
setFirstDayOfWeek
Added in API level 1
public void setFirstDayOfWeek (int value)
Sets what the first day of the week is; e.g., SUNDAY
in the U.S.,
MONDAY
in France.
Parameters
value
int
: the given first day of the week.
See also:
getFirstDayOfWeek()
getMinimalDaysInFirstWeek()
setLenient
Added in API level 1
public void setLenient (boolean lenient)
Specifies whether or not date/time interpretation is to be lenient. With
lenient interpretation, a date such as “February 942, 1996” will be
treated as being equivalent to the 941st day after February 1, 1996.
With strict (non-lenient) interpretation, such dates will cause an exception to be
thrown. The default is lenient.
Parameters
lenient
boolean
: true
if the lenient mode is to be turned
on; false
if it is to be turned off.
See also:
isLenient()
DateFormat.setLenient(boolean)
setMinimalDaysInFirstWeek
Added in API level 1
public void setMinimalDaysInFirstWeek (int value)
Sets what the minimal days required in the first week of the year are;
For example, if the first week is defined as one that contains the first
day of the first month of a year, call this method with value 1. If it
must be a full week, use value 7.
Parameters
value
int
: the given minimal days required in the first week
of the year.
See also:
getMinimalDaysInFirstWeek()
Added in API level 1
public final void setTime (Date date)
Sets this Calendar’s time with the given Date
.
Note: Calling setTime()
with
Date(Long.MAX_VALUE)
or Date(Long.MIN_VALUE)
may yield incorrect field values from get()
.
Parameters
date
Date
: the given Date.
See also:
getTime()
setTimeInMillis(long)
setTimeInMillis
Added in API level 1
public void setTimeInMillis (long millis)
Sets this Calendar’s current time from the given long value.
Parameters
millis
long
: the new time in UTC milliseconds from the epoch.
See also:
setTime(Date)
getTimeInMillis()
setTimeZone
Added in API level 1
public void setTimeZone (TimeZone value)
Sets the time zone with the given time zone value.
Parameters
value
TimeZone
: the given time zone.
Added in API level 24
public void setWeekDate (int weekYear, int weekOfYear, int dayOfWeek)
Sets the date of this Calendar
with the the given date
specifiers – week year, week of year, and day of week.
Unlike the set
method, all of the calendar fields
and time
values are calculated upon return.
If weekOfYear
is out of the valid week-of-year range
in weekYear
, the weekYear
and weekOfYear
values are adjusted in lenient mode, or an IllegalArgumentException
is thrown in non-lenient mode.
The default implementation of this method throws an
UnsupportedOperationException
.
Parameters
weekYear
int
: the week year
weekOfYear
int
: the week number based on weekYear
dayOfWeek
int
: the day of week value: one of the constants
for the DAY_OF_WEEK
field: SUNDAY
, …, SATURDAY
.
Throws
IllegalArgumentException
if any of the given date specifiers is invalid
or any of the calendar fields are inconsistent
with the given date specifiers in non-lenient mode
UnsupportedOperationException
if any week year numbering isn’t supported in this
Calendar
.
See also:
isWeekDateSupported()
getFirstDayOfWeek()
getMinimalDaysInFirstWeek()
toInstant
Added in API level 26
public final Instant toInstant ()
Converts this object to an Instant
.
The conversion creates an Instant
that represents the
same point on the time-line as this Calendar
.
Returns
Instant
the instant representing the same point on the time-line
toString
Added in API level 1
public String toString ()
Return a string representation of this calendar. This method
is intended to be used only for debugging purposes, and the
format of the returned string may vary between implementations.
The returned string may be empty but may not be null
.
Returns
String
a string representation of this calendar.
Protected methods
complete
Added in API level 1
protected void complete ()
Fills in any unset fields in the calendar fields. First, the computeTime()
method is called if the time value (millisecond offset
from the Epoch) has not been calculated from
calendar field values. Then, the computeFields()
method is
called to calculate all calendar field values.
computeFields
Added in API level 1
protected abstract void computeFields ()
Converts the current millisecond time value time
to calendar field values in fields[]
.
This allows you to sync up the calendar field values with
a new time that is set for the calendar. The time is not
recomputed first; to recompute the time, then the fields, call the
complete()
method.
See also:
computeTime()
computeTime
Added in API level 1
protected abstract void computeTime ()
Converts the current calendar field values in fields[]
to the millisecond time value
time
.
See also:
complete()
computeFields()
internalGet
Added in API level 1
protected final int internalGet (int field)
Returns the value of the given calendar field. This method does
not involve normalization or validation of the field value.
Parameters
field
int
: the given calendar field.
Returns
int
the value for the given calendar field.
See also:
get(int)
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2021-02-18 UTC.
[{
“type”: “thumb-down”,
“id”: “missingTheInformationINeed”,
“label”:”Missing the information I need”
},{
“type”: “thumb-down”,
“id”: “tooComplicatedTooManySteps”,
“label”:”Too complicated / too many steps”
},{
“type”: “thumb-down”,
“id”: “outOfDate”,
“label”:”Out of date”
},{
“type”: “thumb-down”,
“id”: “samplesCodeIssue”,
“label”:”Samples / code issue”
},{
“type”: “thumb-down”,
“id”: “otherDown”,
“label”:”Other”
}]
[{
“type”: “thumb-up”,
“id”: “easyToUnderstand”,
“label”:”Easy to understand”
},{
“type”: “thumb-up”,
“id”: “solvedMyProblem”,
“label”:”Solved my problem”
},{
“type”: “thumb-up”,
“id”: “otherUp”,
“label”:”Other”
}]