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

# Builder

*** ** * ** ***

```
class Builder
```

|---|---|
| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html) ||
| ↳ | [android.icu.util.ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#) |

`Builder` is used to build instances of `ULocale` from values configured by the setters. Unlike the `ULocale` constructors, the `Builder` checks if a value configured by a setter satisfies the syntax requirements defined by the `ULocale` class. A `ULocale` object created by a `Builder` is well-formed and can be transformed to a well-formed IETF BCP 47 language tag without losing information.

**Note:** The `ULocale` class does not provide any syntactic restrictions on variant, while BCP 47 requires each variant subtag to be 5 to 8 alphanumerics or a single numeric followed by 3 alphanumerics. The method `setVariant` throws `IllformedLocaleException` for a variant that does not satisfy this restriction. If it is necessary to support such a variant, use a ULocale constructor. However, keep in mind that a `ULocale` object created this way might lose the variant information when transformed to a BCP 47 language tag.

The following example shows how to create a `Locale` object with the `Builder`.

```kotlin
ULocale aLocale = new Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
  
```

Builders can be reused; `clear()` resets all fields to their default values.

## Summary

| Public constructors ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#Builder()()` Constructs an empty Builder. |

| Public methods ||
|---|---|
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#addUnicodeLocaleAttribute(kotlin.String)(attribute: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Adds a unicode locale attribute, if not already present, otherwise has no effect. |
| [ULocale](https://developer.android.com/reference/kotlin/android/icu/util/ULocale)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#build()()` Returns an instance of `ULocale` created from the fields set on this builder. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#clear()()` Resets the builder to its initial, empty state. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#clearExtensions()()` Resets the extensions to their initial, empty state. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#removeUnicodeLocaleAttribute(kotlin.String)(attribute: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Removes a unicode locale attribute, if present, otherwise has no effect. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setExtension(kotlin.Char,%20kotlin.String)(key: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-char/index.html, value: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Sets the extension for the given key. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setLanguage(kotlin.String)(language: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Sets the language. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setLanguageTag(kotlin.String)(languageTag: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Resets the Builder to match the provided IETF BCP 47 language tag. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setLocale(android.icu.util.ULocale)(locale: https://developer.android.com/reference/kotlin/android/icu/util/ULocale!)` Resets the `Builder` to match the provided `locale`. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setRegion(kotlin.String)(region: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Sets the region. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setScript(kotlin.String)(script: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Sets the script. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setUnicodeLocaleKeyword(kotlin.String,%20kotlin.String)(key: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!, type: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Sets the Unicode locale keyword type for the given key. |
| [ULocale.Builder](https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#)! | `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setVariant(kotlin.String)(variant: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html!)` Sets the variant. |

## Public constructors

### Builder

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

```
Builder()
```

Constructs an empty Builder. The default value of all fields, extensions, and private use information is the empty string.

## Public methods

### addUnicodeLocaleAttribute

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

```
fun addUnicodeLocaleAttribute(attribute: String!): ULocale.Builder!
```

Adds a unicode locale attribute, if not already present, otherwise has no effect. The attribute must not be null and must be well-formed or an exception is thrown.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `attribute` is ill-formed |
| `java.lang.NullPointerException` | if `attribute` is null |

**See Also**

- `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setExtension(kotlin.Char,%20kotlin.String)`

### build

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

```
fun build(): ULocale!
```

Returns an instance of `ULocale` created from the fields set on this builder.

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale!` | a new Locale |

### clear

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

```
fun clear(): ULocale.Builder!
```

Resets the builder to its initial, empty state.

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | this builder |

### clearExtensions

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

```
fun clearExtensions(): ULocale.Builder!
```

Resets the extensions to their initial, empty state. Language, script, region and variant are unchanged.

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | this builder |

**See Also**

- `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setExtension(kotlin.Char,%20kotlin.String)`

### removeUnicodeLocaleAttribute

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

```
fun removeUnicodeLocaleAttribute(attribute: String!): ULocale.Builder!
```

Removes a unicode locale attribute, if present, otherwise has no effect. The attribute must not be null and must be well-formed or an exception is thrown.

Attribute comparison for removal is case-insensitive.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `attribute` is ill-formed |
| `java.lang.NullPointerException` | if `attribute` is null |

**See Also**

- `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setExtension(kotlin.Char,%20kotlin.String)`

### setExtension

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

```
fun setExtension(
    key: Char, 
    value: String!
): ULocale.Builder!
```

Sets the extension for the given key. If the value is null or the empty string, the extension is removed. Otherwise, the extension must be well-formed or an exception is thrown.

**Note:** The key `https://developer.android.com/reference/kotlin/android/icu/util/ULocale#UNICODE_LOCALE_EXTENSION:kotlin.Char` ('u') is used for the Unicode locale extension. Setting a value for this key replaces any existing Unicode locale key/type pairs with those defined in the extension.

**Note:** The key `https://developer.android.com/reference/kotlin/android/icu/util/ULocale#PRIVATE_USE_EXTENSION:kotlin.Char` ('x') is used for the private use code. To be well-formed, the value for this key needs only to have subtags of one to eight alphanumeric characters, not two to eight as in the general case.

| Parameters ||
|---|---|
| `key` | [Char](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-char/index.html): the extension key |
| `value` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!: the extension value |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `key` is illegal or `value` is ill-formed |

**See Also**

- `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setUnicodeLocaleKeyword(kotlin.String,%20kotlin.String)`

### setLanguage

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

```
fun setLanguage(language: String!): ULocale.Builder!
```

Sets the language. If `language` is the empty string or null, the language in this `Builder` is removed. Otherwise, the language must be [well-formed](https://developer.android.com/reference/kotlin/android/icu/util/Locale#def_language) or an exception is thrown.

The typical language value is a two or three-letter language code as defined in ISO639.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `language` is ill-formed |

### setLanguageTag

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

```
fun setLanguageTag(languageTag: String!): ULocale.Builder!
```

Resets the Builder to match the provided IETF BCP 47 language tag. Discards the existing state. Null and the empty string cause the builder to be reset, like `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#clear()`. Legacy tags (see `https://developer.android.com/reference/kotlin/android/icu/util/ULocale#forLanguageTag(kotlin.String)`) are converted to their canonical form before being processed. Otherwise, the language tag must be well-formed (see `https://developer.android.com/reference/kotlin/android/icu/util/ULocale`) or an exception is thrown (unlike `ULocale.forLanguageTag`, which just discards ill-formed and following portions of the tag).

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `languageTag` is ill-formed |

**See Also**

- `https://developer.android.com/reference/kotlin/android/icu/util/ULocale#forLanguageTag(kotlin.String)`

### setLocale

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

```
fun setLocale(locale: ULocale!): ULocale.Builder!
```

Resets the `Builder` to match the provided `locale`. Existing state is discarded.

All fields of the locale must be well-formed, see `https://developer.android.com/reference/kotlin/java/util/Locale.html#`.

Locales with any ill-formed fields cause `IllformedLocaleException` to be thrown.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `locale` has any ill-formed fields. |
| `java.lang.NullPointerException` | if `locale` is null. |

### setRegion

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

```
fun setRegion(region: String!): ULocale.Builder!
```

Sets the region. If region is null or the empty string, the region in this `Builder` is removed. Otherwise, the region must be well-formed or an exception is thrown.

The typical region value is a two-letter ISO 3166 code or a three-digit UN M.49 area code.

The country value in the `Locale` created by the `Builder` is always normalized to upper case.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `region` is ill-formed |

### setScript

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

```
fun setScript(script: String!): ULocale.Builder!
```

Sets the script. If `script` is null or the empty string, the script in this `Builder` is removed. Otherwise, the script must be well-formed or an exception is thrown.

The typical script value is a four-letter script code as defined by ISO 15924.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `script` is ill-formed |

### setUnicodeLocaleKeyword

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

```
fun setUnicodeLocaleKeyword(
    key: String!, 
    type: String!
): ULocale.Builder!
```

Sets the Unicode locale keyword type for the given key. If the type is null, the Unicode keyword is removed. Otherwise, the key must be non-null and both key and type must be well-formed or an exception is thrown.

Keys and types are converted to lower case.

**Note** :Setting the 'u' extension via `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setExtension(kotlin.Char,%20kotlin.String)` replaces all Unicode locale keywords with those defined in the extension.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `key` or `type` is ill-formed |
| `java.lang.NullPointerException` | if `key` is null |

**See Also**

- `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#setExtension(kotlin.Char,%20kotlin.String)`

### setVariant

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

```
fun setVariant(variant: String!): ULocale.Builder!
```

Sets the variant. If variant is null or the empty string, the variant in this `Builder` is removed. Otherwise, it must consist of one or more well-formed subtags, or an exception is thrown.

**Note:** This method checks if `variant` satisfies the IETF BCP 47 variant subtag's syntax requirements, and normalizes the value to lowercase letters. However, the `ULocale` class does not impose any syntactic restriction on variant. To set such a variant, use a ULocale constructor.

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

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/icu/util/ULocale.Builder#!` | This builder. |

| Exceptions ||
|---|---|
| `android.icu.util.IllformedLocaleException` | if `variant` is ill-formed |