# Locale.Builder

public static final class **Locale.Builder** extends [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)  
`Builder` is used to build instances of `Locale`
from values configured by the setters. Unlike the `Locale`
constructors, the `Builder` checks if a value configured by a
setter satisfies the syntax requirements defined by the `Locale`
class. A `Locale` 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 `Locale` 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
Locale constructor. However, keep in mind that a `Locale`
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`.
>
> ```
>      Locale 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://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#forLanguageTag(java.lang.String)`

### Public Constructor Summary

|---|---|
|   | [Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#Builder())() Constructs an empty Builder. |

### Public Method Summary

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

### Inherited Method Summary

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notify())() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| final void | [notifyAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notifyAll())() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

## Public Constructors

#### public
**Builder**
()

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

## Public Methods

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**addUnicodeLocaleAttribute**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#def_locale_extension) or an exception
is thrown.

##### Parameters

| attribute | the attribute |
|---|---|

##### Returns

- This builder.

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `attribute` is null |
| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `attribute` is ill-formed |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#setExtension(char,%20java.lang.String)`

#### public [Locale](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html)
**build**
()

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

This applies the conversions listed in `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#forLanguageTag(java.lang.String)`
when constructing a Locale. (Grandfathered tags are handled in
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#setLanguageTag(java.lang.String)`.)

##### Returns

- A Locale.

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**clear**
()

Resets the builder to its initial, empty state.

##### Returns

- This builder.

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**clearExtensions**
()

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

##### Returns

- This builder.

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#setExtension(char,%20java.lang.String)`

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**removeUnicodeLocaleAttribute**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) attribute)

Removes a unicode locale attribute, if present, otherwise has no
effect. The attribute must not be null and must be [well-formed](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#def_locale_extension) or an exception
is thrown.

Attribute comparision for removal is case-insensitive.

##### Parameters

| attribute | the attribute |
|---|---|

##### Returns

- This builder.

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `attribute` is null |
| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `attribute` is ill-formed |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#setExtension(char,%20java.lang.String)`

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setExtension**
(char key, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#def_extensions) or an exception
is thrown.

**Note:** The key `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#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://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#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.

##### Parameters

| key | the extension key |
| value | the extension value |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `key` is illegal or `value` is ill-formed |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#setUnicodeLocaleKeyword(java.lang.String,%20java.lang.String)`

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setLanguage**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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://developers.google.com/j2objc/javadoc/jre/reference/java/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.

##### Parameters

| language | the language |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `language` is ill-formed |
|---|---|

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setLanguageTag**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#clear()`. Grandfathered tags (see `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#forLanguageTag(java.lang.String)`) are converted to their canonical
form before being processed. Otherwise, the language tag
must be well-formed (see `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html`) or an exception is
thrown (unlike `Locale.forLanguageTag`, which
just discards ill-formed and following portions of the
tag).

##### Parameters

| languageTag | the language tag |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `languageTag` is ill-formed |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#forLanguageTag(java.lang.String)`

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setLocale**
([Locale](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html) locale)

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

All fields of the locale must be well-formed, see `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html`.

Locales with any ill-formed fields cause
`IllformedLocaleException` to be thrown, except for the
following three cases which are accepted for compatibility
reasons:

- Locale("ja", "JP", "JP") is treated as "ja-JP-u-ca-japanese"
- Locale("th", "TH", "TH") is treated as "th-TH-u-nu-thai"
- Locale("no", "NO", "NY") is treated as "nn-NO"

<br />

##### Parameters

| locale | the locale |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `locale` has any ill-formed fields. |
| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `locale` is null. |
|---|---|

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setRegion**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#def_region) 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 | the region |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `region` is ill-formed |
|---|---|

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setScript**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#def_script) or an
exception is thrown.

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

##### Parameters

| script | the script |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `script` is ill-formed |
|---|---|

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setUnicodeLocaleKeyword**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) key, [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#def_locale_extension) or an exception
is thrown.

Keys and types are converted to lower case.

**Note** :Setting the 'u' extension via `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#setExtension(char,%20java.lang.String)`
replaces all Unicode locale keywords with those defined in the
extension.

##### Parameters

| key | the Unicode locale key |
| type | the Unicode locale type |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `key` or `type` is ill-formed |
| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if `key` is null |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html#setExtension(char,%20java.lang.String)`

#### public [Locale.Builder](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.Builder.html)
**setVariant**
([String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) 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](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Locale.html#def_variant)
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 `Locale` class does not impose any syntactic
restriction on variant, and the variant value in
`Locale` is case sensitive. To set such a variant,
use a Locale constructor.

##### Parameters

| variant | the variant |
|---|---|

##### Returns

- This builder.

##### Throws

| [IllformedLocaleException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/IllformedLocaleException.html) | if `variant` is ill-formed |
|---|---|