Builder
open class Builder
kotlin.Any | |
↳ | java.util.Calendar.Builder |
Calendar.Builder
is used for creating a Calendar
from various date-time parameters.
There are two ways to set a Calendar
to a date-time value. One is to set the instant parameter to a millisecond offset from the Epoch. The other is to set individual field parameters, such as YEAR
, to their desired values. These two ways can't be mixed. Trying to set both the instant and individual fields will cause an IllegalStateException
to be thrown. However, it is permitted to override previous values of the instant or field parameters.
If no enough field parameters are given for determining date and/or time, calendar specific default values are used when building a Calendar
. For example, if the YEAR
value isn't given for the Gregorian calendar, 1970 will be used. If there are any conflicts among field parameters, the resolution rules are applied. Therefore, the order of field setting matters.
In addition to the date-time parameters, the locale, time zone, week definition, and leniency mode parameters can be set.
Examples
The following are sample usages. Sample code assumes that the Calendar
constants are statically imported.
The following code produces a Calendar
with date 2012-12-31 (Gregorian) because Monday is the first day of a week with the ISO 8601 compatible week parameters.
Calendar cal = new Calendar.Builder().setCalendarType("iso8601") .setWeekDate(2013, 1, MONDAY).build();
The following code produces a Japanese Calendar
with date 1989-01-08 (Gregorian), assuming that the default ERA
is Heisei that started on that day.
Calendar cal = new Calendar.Builder().setCalendarType("japanese") .setFields(YEAR, 1, DAY_OF_YEAR, 1).build();
Summary
Public constructors | |
---|---|
Builder() Constructs a |
Public methods | |
---|---|
open Calendar |
build() Returns a |
open Calendar.Builder |
Sets the |
open Calendar.Builder |
setCalendarType(type: String) Sets the calendar type parameter to the given |
open Calendar.Builder |
Sets the date field parameters to the values given by |
open Calendar.Builder |
Sets field parameters to their values given by |
open Calendar.Builder |
setInstant(instant: Long) Sets the instant parameter to the given |
open Calendar.Builder |
setInstant(instant: Date) Sets the instant parameter to the |
open Calendar.Builder |
setLenient(lenient: Boolean) Sets the lenient mode parameter to the value given by |
open Calendar.Builder |
Sets the locale parameter to the given |
open Calendar.Builder |
setTimeOfDay(hourOfDay: Int, minute: Int, second: Int) Sets the time of day field parameters to the values given by |
open Calendar.Builder |
setTimeOfDay(hourOfDay: Int, minute: Int, second: Int, millis: Int) Sets the time of day field parameters to the values given by |
open Calendar.Builder |
setTimeZone(zone: TimeZone) Sets the time zone parameter to the given |
open Calendar.Builder |
setWeekDate(weekYear: Int, weekOfYear: Int, dayOfWeek: Int) Sets the week-based date parameters to the values with the given date specifiers - week year, week of year, and day of week. |
open Calendar.Builder |
setWeekDefinition(firstDayOfWeek: Int, minimalDaysInFirstWeek: Int) Sets the week definition parameters to the values given by |
Public constructors
Public methods
build
open fun build(): Calendar
Returns a Calendar
built from the parameters set by the setter methods. The calendar type given by the setCalendarType
method or the locale is used to determine what Calendar
to be created. If no explicit calendar type is given, the locale's default calendar is created.
If the calendar type is "iso8601"
, the Gregorian change date of a GregorianCalendar
is set to Date(Long.MIN_VALUE)
to be the proleptic Gregorian calendar. Its week definition parameters are also set to be compatible with the ISO 8601 standard. Note that the getCalendarType
method of a GregorianCalendar
created with "iso8601"
returns "gregory"
.
The default values are used for locale and time zone if these parameters haven't been given explicitly.
Since Android 13, if the locale contains the time zone with "tz" Unicode extension, and time zone hasn't been given explicitly, time zone in the locale is used.
Any out of range field values are either normalized in lenient mode or detected as an invalid value in non-lenient mode.
Return | |
---|---|
Calendar |
a Calendar built with parameters of this Calendar.Builder |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the calendar type is unknown, or if any invalid field values are given in non-lenient mode, or if a week date is given for the calendar type that doesn't support week dates. |
set
open fun set(
field: Int,
value: Int
): Calendar.Builder
Sets the field
parameter to the given value
. field
is an index to the Calendar#fields
, such as DAY_OF_MONTH
. Field value validation is not performed in this method. Any out of range values are either normalized in lenient mode or detected as an invalid value in non-lenient mode when building a Calendar
.
Parameters | |
---|---|
field |
Int: an index to the Calendar fields |
value |
Int: the field value |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if field is invalid |
java.lang.IllegalStateException |
if the instant value has already been set, or if fields have been set too many (approximately Integer#MAX_VALUE ) times. |
See Also
setCalendarType
open fun setCalendarType(type: String): Calendar.Builder
Sets the calendar type parameter to the given type
. The calendar type given by this method has precedence over any explicit or implicit calendar type given by the locale.
In addition to the available calendar types returned by the Calendar.getAvailableCalendarTypes
method, "gregorian"
and "iso8601"
as aliases of "gregory"
can be used with this method.
Parameters | |
---|---|
type |
String: the calendar type |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.NullPointerException |
if type is null |
java.lang.IllegalArgumentException |
if type is unknown |
java.lang.IllegalStateException |
if another calendar type has already been set |
setDate
open fun setDate(
year: Int,
month: Int,
dayOfMonth: Int
): Calendar.Builder
Sets the date field parameters to the values given by year
, month
, and dayOfMonth
. This method is equivalent to a call to:
setFields(Calendar.YEAR, year, Calendar.MONTH, month, Calendar.DAY_OF_MONTH, dayOfMonth);
Parameters | |
---|---|
year |
Int: the YEAR value |
month |
Int: the MONTH value (the month numbering is 0-based). |
dayOfMonth |
Int: the DAY_OF_MONTH value |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
setFields
open fun setFields(vararg fieldValuePairs: Int): Calendar.Builder
Sets field parameters to their values given by fieldValuePairs
that are pairs of a field and its value. For example,
setFields(Calendar.YEAR, 2013, Calendar.MONTH, Calendar.DECEMBER, Calendar.DAY_OF_MONTH, 23);
set
calls:
set(Calendar.YEAR, 2013) .set(Calendar.MONTH, Calendar.DECEMBER) .set(Calendar.DAY_OF_MONTH, 23);
Parameters | |
---|---|
fieldValuePairs |
Int: field-value pairs |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.NullPointerException |
if fieldValuePairs is null |
java.lang.IllegalArgumentException |
if any of fields are invalid, or if fieldValuePairs.length is an odd number. |
java.lang.IllegalStateException |
if the instant value has been set, or if fields have been set too many (approximately Integer#MAX_VALUE ) times. |
setInstant
open fun setInstant(instant: Long): Calendar.Builder
Sets the instant parameter to the given instant
value that is a millisecond offset from the Epoch.
Parameters | |
---|---|
instant |
Long: a millisecond offset from the Epoch |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.IllegalStateException |
if any of the field parameters have already been set |
setInstant
open fun setInstant(instant: Date): Calendar.Builder
Sets the instant parameter to the instant
value given by a Date
. This method is equivalent to a call to setInstant(instant.getTime())
.
Parameters | |
---|---|
instant |
Date: a Date representing a millisecond offset from the Epoch |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.NullPointerException |
if instant is null |
java.lang.IllegalStateException |
if any of the field parameters have already been set |
setLenient
open fun setLenient(lenient: Boolean): Calendar.Builder
Sets the lenient mode parameter to the value given by lenient
. If no lenient parameter is given to this Calendar.Builder
, lenient mode will be used in the build
method.
Parameters | |
---|---|
lenient |
Boolean: true for lenient mode; false for non-lenient mode |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
setLocale
open fun setLocale(locale: Locale): Calendar.Builder
Sets the locale parameter to the given locale
. If no locale is given to this Calendar.Builder
, the java.util.Locale#getDefault(java.util.Locale.Category)} for Locale.Category#FORMAT
will be used.
If no calendar type is explicitly given by a call to the setCalendarType
method, the Locale
value is used to determine what type of Calendar
to be built.
If no week definition parameters are explicitly given by a call to the setWeekDefinition
method, the Locale
's default values are used.
Parameters | |
---|---|
locale |
Locale: the Locale |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.NullPointerException |
if locale is null |
setTimeOfDay
open fun setTimeOfDay(
hourOfDay: Int,
minute: Int,
second: Int
): Calendar.Builder
Sets the time of day field parameters to the values given by hourOfDay
, minute
, and second
. This method is equivalent to a call to:
setTimeOfDay(hourOfDay, minute, second, 0);
Parameters | |
---|---|
hourOfDay |
Int: the HOUR_OF_DAY value (24-hour clock) |
minute |
Int: the MINUTE value |
second |
Int: the SECOND value |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
setTimeOfDay
open fun setTimeOfDay(
hourOfDay: Int,
minute: Int,
second: Int,
millis: Int
): Calendar.Builder
Sets the time of day field parameters to the values given by hourOfDay
, minute
, second
, and millis
. This method is equivalent to a call to:
setFields(Calendar.HOUR_OF_DAY, hourOfDay, Calendar.MINUTE, minute, Calendar.SECOND, second, Calendar.MILLISECOND, millis);
Parameters | |
---|---|
hourOfDay |
Int: the HOUR_OF_DAY value (24-hour clock) |
minute |
Int: the MINUTE value |
second |
Int: the SECOND value |
millis |
Int: the MILLISECOND value |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
setTimeZone
open fun setTimeZone(zone: TimeZone): Calendar.Builder
Sets the time zone parameter to the given zone
. If no time zone parameter is given to this Calendar.Builder
, the java.util.TimeZone#getDefault()} will be used in the build
method.
Parameters | |
---|---|
zone |
TimeZone: the TimeZone |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.NullPointerException |
if zone is null |
setWeekDate
open fun setWeekDate(
weekYear: Int,
weekOfYear: Int,
dayOfWeek: Int
): Calendar.Builder
Sets the week-based date parameters to the values with the given date specifiers - week year, week of year, and day of week.
If the specified calendar doesn't support week dates, the build
method will throw an IllegalArgumentException
.
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 . |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
setWeekDefinition
open fun setWeekDefinition(
firstDayOfWeek: Int,
minimalDaysInFirstWeek: Int
): Calendar.Builder
Sets the week definition parameters to the values given by firstDayOfWeek
and minimalDaysInFirstWeek
that are used to determine the first week of a year. The parameters given by this method have precedence over the default values given by the locale.
Parameters | |
---|---|
firstDayOfWeek |
Int: the first day of a week; one of Calendar#SUNDAY to Calendar#SATURDAY |
minimalDaysInFirstWeek |
Int: the minimal number of days in the first week (1..7) |
Return | |
---|---|
Calendar.Builder |
this Calendar.Builder |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if firstDayOfWeek or minimalDaysInFirstWeek is invalid |