Added in [API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Ctors](https://developer.android.com/reference/android/icu/util/ULocale.Builder#pubctors) \| [Methods](https://developer.android.com/reference/android/icu/util/ULocale.Builder#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/icu/util/ULocale.Builder#inhmethods)

# ULocale.Builder

*** ** * ** ***


`
public
static
final

class
ULocale.Builder
`


`

extends https://developer.android.com/reference/java/lang/Object


`

`


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.icu.util.ULocale.Builder |

<br />

*** ** * ** ***

`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`.
>
> ```
>     ULocale aLocale = new Builder().setLanguage("sr").setScript("Latn").setRegion("RS").build();
> ```

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

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

## Summary

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

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

| ### Inherited methods |
|---|---|
| From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class<?>` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | ||

## Public constructors

### Builder

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

```
public Builder ()
```

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

<br />

## Public methods

### addUnicodeLocaleAttribute

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

```
public ULocale.Builder addUnicodeLocaleAttribute (String attribute)
```

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.

<br />

| Parameters ||
|---|---|
| `attribute` | `String`: the attribute <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/IllformedLocaleException` | if `attribute` is ill-formed |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `attribute` is null |

**See also:**

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

### build

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

```
public ULocale build ()
```

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

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale` | a new Locale <br /> |

### clear

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

```
public ULocale.Builder clear ()
```

Resets the builder to its initial, empty state.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | this builder <br /> |

### clearExtensions

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

```
public ULocale.Builder clearExtensions ()
```

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

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | this builder <br /> |

**See also:**

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

### removeUnicodeLocaleAttribute

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

```
public ULocale.Builder removeUnicodeLocaleAttribute (String attribute)
```

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.

<br />

| Parameters ||
|---|---|
| `attribute` | `String`: the attribute <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/IllformedLocaleException` | if `attribute` is ill-formed |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `attribute` is null |

**See also:**

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

### setExtension

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

```
public ULocale.Builder setExtension (char key, 
                String value)
```

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/android/icu/util/ULocale#UNICODE_LOCALE_EXTENSION` ('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/android/icu/util/ULocale#PRIVATE_USE_EXTENSION` ('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.

<br />

| Parameters ||
|---|---|
| `key` | `char`: the extension key <br /> |
| `value` | `String`: the extension value <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/IllformedLocaleException` | if `key` is illegal or `value` is ill-formed |

**See also:**

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

### setLanguage

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

```
public ULocale.Builder setLanguage (String language)
```

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/android/icu/util/Locale.html#def_language)
or an exception is thrown.

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

<br />

| Parameters ||
|---|---|
| `language` | `String`: the language <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/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#ApiLevels)

```
public ULocale.Builder setLanguageTag (String languageTag)
```

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/android/icu/util/ULocale.Builder#clear()`. Legacy tags (see `https://developer.android.com/reference/android/icu/util/ULocale#forLanguageTag(java.lang.String)`) are converted to their canonical
form before being processed. Otherwise, the language tag
must be well-formed (see `https://developer.android.com/reference/android/icu/util/ULocale`) or an exception is
thrown (unlike `ULocale.forLanguageTag`, which
just discards ill-formed and following portions of the
tag).

<br />

| Parameters ||
|---|---|
| `languageTag` | `String`: the language tag <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/IllformedLocaleException` | if `languageTag` is ill-formed |

**See also:**

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

### setLocale

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

```
public ULocale.Builder setLocale (ULocale locale)
```

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/java/util/Locale`.

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

<br />

| Parameters ||
|---|---|
| `locale` | `ULocale`: the locale <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/IllformedLocaleException` | if `locale` has any ill-formed fields. |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `locale` is null. |

### setRegion

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

```
public ULocale.Builder setRegion (String region)
```

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.

<br />

| Parameters ||
|---|---|
| `region` | `String`: the region <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/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#ApiLevels)

```
public ULocale.Builder setScript (String script)
```

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.

<br />

| Parameters ||
|---|---|
| `script` | `String`: the script <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/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#ApiLevels)

```
public ULocale.Builder setUnicodeLocaleKeyword (String key, 
                String type)
```

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/android/icu/util/ULocale.Builder#setExtension(char,%20java.lang.String)`
replaces all Unicode locale keywords with those defined in the
extension.

<br />

| Parameters ||
|---|---|
| `key` | `String`: the Unicode locale key <br /> |
| `type` | `String`: the Unicode locale type <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/IllformedLocaleException` | if `key` or `type` is ill-formed |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `key` is null |

**See also:**

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

### setVariant

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

```
public ULocale.Builder setVariant (String variant)
```

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.

<br />

| Parameters ||
|---|---|
| `variant` | `String`: the variant <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/ULocale.Builder` | This builder. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/IllformedLocaleException` | if `variant` is ill-formed |