Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

# Builder

```
open class Builder
```

|---|---|
| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html) ||
| ↳ | [java.util.Calendar.Builder](https://developer.android.com/reference/kotlin/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](https://developer.android.com/reference/kotlin/java/util/Calendar#Epoch). The other is to set individual field parameters, such as `https://developer.android.com/reference/kotlin/java/util/Calendar#YEAR:kotlin.Int`, to their desired values. These two ways can't be mixed. Trying to set both the instant and individual fields will cause an `https://developer.android.com/reference/kotlin/java/lang/IllegalStateException.html#` 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 `https://developer.android.com/reference/kotlin/java/util/Calendar#YEAR:kotlin.Int` value isn't given for the Gregorian calendar, 1970 will be used. If there are any conflicts among field parameters, the [resolution rules](https://developer.android.com/reference/kotlin/java/util/Calendar#resolution) are applied. Therefore, the order of field setting matters.

In addition to the date-time parameters, the [locale](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setLocale(java.util.Locale)), [time zone](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setTimeZone(java.util.TimeZone)), [week definition](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setWeekDefinition(kotlin.Int,%20kotlin.Int)), and [leniency mode](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setLenient(kotlin.Boolean)) 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](https://developer.android.com/reference/kotlin/java/util/GregorianCalendar#iso8601_compatible_setting).

```kotlin
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 `https://developer.android.com/reference/kotlin/java/util/Calendar#ERA:kotlin.Int` is *Heisei* that started on that day.

```kotlin
Calendar cal = new Calendar.Builder().setCalendarType("japanese")
                         .setFields(YEAR, 1, DAY_OF_YEAR, 1).build();
```

## Summary

| Public constructors ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#Builder()()` Constructs a `Calendar.Builder`. |

| Public methods ||
|---|---|
| open [Calendar](https://developer.android.com/reference/kotlin/java/util/Calendar) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#build()()` Returns a `Calendar` built from the parameters set by the setter methods. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#set(kotlin.Int,%20kotlin.Int)(field: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, value: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the `field` parameter to the given `value`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setCalendarType(kotlin.String)(type: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)` Sets the calendar type parameter to the given `type`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setDate(kotlin.Int,%20kotlin.Int,%20kotlin.Int)(year: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, month: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, dayOfMonth: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the date field parameters to the values given by `year`, `month`, and `dayOfMonth`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setFields(kotlin.Int)(vararg fieldValuePairs: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets field parameters to their values given by `fieldValuePairs` that are pairs of a field and its value. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setInstant(java.util.Date)(instant: https://developer.android.com/reference/kotlin/java/util/Date)` Sets the instant parameter to the `instant` value given by a `https://developer.android.com/reference/kotlin/java/util/Date`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setInstant(kotlin.Long)(instant: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)` Sets the instant parameter to the given `instant` value that is a millisecond offset from [the Epoch](https://developer.android.com/reference/kotlin/java/util/Calendar#Epoch). |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setLenient(kotlin.Boolean)(lenient: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)` Sets the lenient mode parameter to the value given by `lenient`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setLocale(java.util.Locale)(locale: https://developer.android.com/reference/kotlin/java/util/Locale)` Sets the locale parameter to the given `locale`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setTimeOfDay(kotlin.Int,%20kotlin.Int,%20kotlin.Int)(hourOfDay: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, minute: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, second: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the time of day field parameters to the values given by `hourOfDay`, `minute`, and `second`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setTimeOfDay(kotlin.Int,%20kotlin.Int,%20kotlin.Int,%20kotlin.Int)(hourOfDay: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, minute: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, second: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, millis: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the time of day field parameters to the values given by `hourOfDay`, `minute`, `second`, and `millis`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setTimeZone(java.util.TimeZone)(zone: https://developer.android.com/reference/kotlin/java/util/TimeZone)` Sets the time zone parameter to the given `zone`. |
| open [Calendar.Builder](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setWeekDate(kotlin.Int,%20kotlin.Int,%20kotlin.Int)(weekYear: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, weekOfYear: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, dayOfWeek: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` 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](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#) | `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setWeekDefinition(kotlin.Int,%20kotlin.Int)(firstDayOfWeek: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html, minimalDaysInFirstWeek: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Sets the week definition parameters to the values given by `firstDayOfWeek` and `minimalDaysInFirstWeek` that are used to determine the [first week](https://developer.android.com/reference/kotlin/java/util/Calendar#first_week) of a year. |

## Public constructors

### Builder

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
Builder()
```

Constructs a `Calendar.Builder`.

## Public methods

### build

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun build(): Calendar
```

Returns a `Calendar` built from the parameters set by the setter methods. The calendar type given by the `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setCalendarType(kotlin.String)` method or the [locale](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setLocale(java.util.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](https://developer.android.com/reference/kotlin/java/util/GregorianCalendar#setGregorianChange(java.util.Date)) of a `https://developer.android.com/reference/kotlin/java/util/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](https://developer.android.com/reference/kotlin/java/util/GregorianCalendar#iso8601_compatible_setting). Note that the `https://developer.android.com/reference/kotlin/java/util/GregorianCalendar#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](https://developer.android.com/reference/kotlin/java/util/Locale#def_locale_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 ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/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. |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#getInstance(java.util.TimeZone,%20java.util.Locale)`
- `https://developer.android.com/reference/kotlin/java/util/Locale#getDefault(java.util.Locale.Category)`
- `https://developer.android.com/reference/kotlin/java/util/TimeZone#getDefault()`

### set

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun set(
    field: Int, 
    value: Int
): Calendar.Builder
```

Sets the `field` parameter to the given `value`. `field` is an index to the `https://developer.android.com/reference/kotlin/java/util/Calendar#fields:kotlin.IntArray`, such as `https://developer.android.com/reference/kotlin/java/util/Calendar#DAY_OF_MONTH:kotlin.Int`. 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](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): an index to the `Calendar` fields |
| `value` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the field value |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/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 `https://developer.android.com/reference/kotlin/java/lang/Integer.html#MAX_VALUE:kotlin.Int`) times. |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#set(kotlin.Int,%20kotlin.Int)`

### setCalendarType

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setLocale(java.util.Locale)).

In addition to the available calendar types returned by the `https://developer.android.com/reference/kotlin/java/util/Calendar#getAvailableCalendarTypes()` method, `"gregorian"` and `"iso8601"` as aliases of `"gregory"` can be used with this method.

| Parameters ||
|---|---|
| `type` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html): the calendar type |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` | if `type` is unknown |
| `java.lang.IllegalStateException` | if another calendar type has already been set |
| `java.lang.NullPointerException` | if `type` is `null` |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#getCalendarType()`
- `https://developer.android.com/reference/kotlin/java/util/Calendar#getAvailableCalendarTypes()`

### setDate

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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:

```kotlin
setFields(Calendar.YEAR, year,
              Calendar.MONTH, month,
              Calendar.DAY_OF_MONTH, dayOfMonth);
```

<br />

| Parameters ||
|---|---|
| `year` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#YEAR:kotlin.Int` value |
| `month` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#MONTH:kotlin.Int` value (the month numbering is *0-based*). |
| `dayOfMonth` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#DAY_OF_MONTH:kotlin.Int` value |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

### setFields

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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,

```kotlin
setFields(Calendar.YEAR, 2013,
              Calendar.MONTH, Calendar.DECEMBER,
              Calendar.DAY_OF_MONTH, 23);
```
is equivalent to the sequence of the following `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#set(kotlin.Int,%20kotlin.Int)` calls:

```kotlin
set(Calendar.YEAR, 2013)
    .set(Calendar.MONTH, Calendar.DECEMBER)
    .set(Calendar.DAY_OF_MONTH, 23);
```

<br />

| Parameters ||
|---|---|
| `fieldValuePairs` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): field-value pairs |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

| Exceptions ||
|---|---|
| `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 `https://developer.android.com/reference/kotlin/java/lang/Integer.html#MAX_VALUE:kotlin.Int`) times. |
| `java.lang.NullPointerException` | if `fieldValuePairs` is `null` |

### setInstant

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun setInstant(instant: Date): Calendar.Builder
```

Sets the instant parameter to the `instant` value given by a `https://developer.android.com/reference/kotlin/java/util/Date`. This method is equivalent to a call to `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setInstant(kotlin.Long)`.

| Parameters ||
|---|---|
| `instant` | [Date](https://developer.android.com/reference/kotlin/java/util/Date): a `Date` representing a millisecond offset from the Epoch |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

| Exceptions ||
|---|---|
| `java.lang.IllegalStateException` | if any of the field parameters have already been set |
| `java.lang.NullPointerException` | if `instant` is `null` |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#setTime(java.util.Date)`
- `https://developer.android.com/reference/kotlin/java/util/Calendar#setTimeInMillis(kotlin.Long)`
- `https://developer.android.com/reference/kotlin/java/util/Calendar#time:kotlin.Long`

### setInstant

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
open fun setInstant(instant: Long): Calendar.Builder
```

Sets the instant parameter to the given `instant` value that is a millisecond offset from [the Epoch](https://developer.android.com/reference/kotlin/java/util/Calendar#Epoch).

| Parameters ||
|---|---|
| `instant` | [Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html): a millisecond offset from the Epoch |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

| Exceptions ||
|---|---|
| `java.lang.IllegalStateException` | if any of the field parameters have already been set |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#setTime(java.util.Date)`
- `https://developer.android.com/reference/kotlin/java/util/Calendar#setTimeInMillis(kotlin.Long)`
- `https://developer.android.com/reference/kotlin/java/util/Calendar#time:kotlin.Long`

### setLenient

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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 `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#build()` method.

| Parameters ||
|---|---|
| `lenient` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html): `true` for lenient mode; `false` for non-lenient mode |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#setLenient(kotlin.Boolean)`

### setLocale

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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 [default](https://developer.android.com/reference/kotlin/java/util/Locale#getDefault(java.util.Locale.Category)) for `https://developer.android.com/reference/kotlin/java/util/Locale.Category` will be used.

If no calendar type is explicitly given by a call to the `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setCalendarType(kotlin.String)` 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 `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setWeekDefinition(kotlin.Int,%20kotlin.Int)` method, the `Locale`'s default values are used.

| Parameters ||
|---|---|
| `locale` | [Locale](https://developer.android.com/reference/kotlin/java/util/Locale): the `https://developer.android.com/reference/kotlin/java/util/Locale` |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

| Exceptions ||
|---|---|
| `java.lang.NullPointerException` | if `locale` is `null` |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#getInstance(java.util.Locale)`

### setTimeOfDay

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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:

```kotlin
setTimeOfDay(hourOfDay, minute, second, 0);
```

<br />

| Parameters ||
|---|---|
| `hourOfDay` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#HOUR_OF_DAY:kotlin.Int` value (24-hour clock) |
| `minute` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#MINUTE:kotlin.Int` value |
| `second` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#SECOND:kotlin.Int` value |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

### setTimeOfDay

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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:

```kotlin
setFields(Calendar.HOUR_OF_DAY, hourOfDay,
              Calendar.MINUTE, minute,
              Calendar.SECOND, second,
              Calendar.MILLISECOND, millis);
```

<br />

| Parameters ||
|---|---|
| `hourOfDay` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#HOUR_OF_DAY:kotlin.Int` value (24-hour clock) |
| `minute` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#MINUTE:kotlin.Int` value |
| `second` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#SECOND:kotlin.Int` value |
| `millis` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the `https://developer.android.com/reference/kotlin/java/util/Calendar#MILLISECOND:kotlin.Int` value |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

### setTimeZone

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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 [default](https://developer.android.com/reference/kotlin/java/util/TimeZone#getDefault()) will be used in the `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#build()` method.

| Parameters ||
|---|---|
| `zone` | [TimeZone](https://developer.android.com/reference/kotlin/java/util/TimeZone): the `https://developer.android.com/reference/kotlin/java/util/TimeZone` |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

| Exceptions ||
|---|---|
| `java.lang.NullPointerException` | if `zone` is `null` |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#setTimeZone(java.util.TimeZone)`

### setWeekDate

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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 `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#build()` method will throw an `https://developer.android.com/reference/kotlin/java/lang/IllegalArgumentException.html#`.

| Parameters ||
|---|---|
| `weekYear` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the week year |
| `weekOfYear` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the week number based on `weekYear` |
| `dayOfWeek` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the day of week value: one of the constants for the `https://developer.android.com/reference/kotlin/java/util/Calendar#DAY_OF_WEEK:kotlin.Int` field: `https://developer.android.com/reference/kotlin/java/util/Calendar#SUNDAY:kotlin.Int`, ..., `https://developer.android.com/reference/kotlin/java/util/Calendar#SATURDAY:kotlin.Int`. |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#setWeekDate(kotlin.Int,%20kotlin.Int,%20kotlin.Int)`
- `https://developer.android.com/reference/kotlin/java/util/Calendar#isWeekDateSupported()`

### setWeekDefinition

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
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](https://developer.android.com/reference/kotlin/java/util/Calendar#first_week) of a year. The parameters given by this method have precedence over the default values given by the [locale](https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#setLocale(java.util.Locale)).

| Parameters ||
|---|---|
| `firstDayOfWeek` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the first day of a week; one of `https://developer.android.com/reference/kotlin/java/util/Calendar#SUNDAY:kotlin.Int` to `https://developer.android.com/reference/kotlin/java/util/Calendar#SATURDAY:kotlin.Int` |
| `minimalDaysInFirstWeek` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the minimal number of days in the first week (1..7) |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/java/util/Calendar.Builder#` | this `Calendar.Builder` |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` | if `firstDayOfWeek` or `minimalDaysInFirstWeek` is invalid |

**See Also**

- `https://developer.android.com/reference/kotlin/java/util/Calendar#getFirstDayOfWeek()`
- `https://developer.android.com/reference/kotlin/java/util/Calendar#getMinimalDaysInFirstWeek()`