Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Constants](https://developer.android.com/reference/java/util/Locale.LanguageRange#constants) \| [Ctors](https://developer.android.com/reference/java/util/Locale.LanguageRange#pubctors) \| [Methods](https://developer.android.com/reference/java/util/Locale.LanguageRange#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/java/util/Locale.LanguageRange#inhmethods)

# Locale.LanguageRange


`
public
static
final

class
Locale.LanguageRange
`


`

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


`

`


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | java.util.Locale.LanguageRange |

<br />

*** ** * ** ***

This class expresses a *Language Range* defined in
[RFC 4647 Matching of
Language Tags](https://tools.ietf.org/html/rfc4647). A language range is an identifier which is used to
select language tag(s) meeting specific requirements by using the
mechanisms described in [ERROR(Locale
Matching/java.util.Locale##LocaleMatching Locale
Matching)](https://developer.android.com/). A list which represents a user's preferences and consists
of language ranges is called a *Language Priority List*.

There are two types of language ranges: basic and extended. In RFC
4647, the syntax of language ranges is expressed in
[ABNF](https://tools.ietf.org/html/rfc4234) as follows:
>
> ```
>     basic-language-range    = (1*8ALPHA *("-" 1*8alphanum)) / "*"
>     extended-language-range = (1*8ALPHA / "*")
>                               *("-" (1*8alphanum / "*"))
>     alphanum                = ALPHA / DIGIT
> ```
For example, `"en"` (English), `"ja-JP"` (Japanese, Japan), `"*"` (special language range which matches any language tag) are basic language ranges, whereas `"*-CH"` (any languages, Switzerland), `"es-*"` (Spanish, any regions), and `"zh-Hant-*"` (Traditional Chinese, any regions) are extended language ranges.

<br />

**See also:**

- `https://developer.android.com/reference/java/util/Locale#filter(java.util.List<java.util.Locale.LanguageRange>,%20java.util.Collection<java.util.Locale>)`
- `https://developer.android.com/reference/java/util/Locale#filterTags(java.util.List<java.util.Locale.LanguageRange>,%20java.util.Collection<java.lang.String>)`
- `https://developer.android.com/reference/java/util/Locale#lookup(java.util.List<java.util.Locale.LanguageRange>,%20java.util.Collection<java.util.Locale>)`
- `https://developer.android.com/reference/java/util/Locale#lookupTag(java.util.List<java.util.Locale.LanguageRange>,%20java.util.Collection<java.lang.String>)`

## Summary

| ### Constants ||
|---|---|
| `double` | `https://developer.android.com/reference/java/util/Locale.LanguageRange#MAX_WEIGHT` A constant holding the maximum value of weight, 1.0, which indicates that the language range is a good fit for the user. |
| `double` | `https://developer.android.com/reference/java/util/Locale.LanguageRange#MIN_WEIGHT` A constant holding the minimum value of weight, 0.0, which indicates that the language range is not a good fit for the user. |

| ### Public constructors ||
|---|---|
| ` https://developer.android.com/reference/java/util/Locale.LanguageRange#LanguageRange(java.lang.String)(https://developer.android.com/reference/java/lang/String range) ` Constructs a `LanguageRange` using the given `range`. |
| ` https://developer.android.com/reference/java/util/Locale.LanguageRange#LanguageRange(java.lang.String,%20double)(https://developer.android.com/reference/java/lang/String range, double weight) ` Constructs a `LanguageRange` using the given `range` and `weight`. |

| ### Public methods ||
|---|---|
| ` boolean` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Compares this object to the specified object. |
| ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#getRange()() ` Returns the language range of this `LanguageRange`. |
| ` double` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#getWeight()() ` Returns the weight of this `LanguageRange`. |
| ` int` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#hashCode()() ` |
| ` static https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/util/Locale.LanguageRange>` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#mapEquivalents(java.util.List<java.util.Locale.LanguageRange>,%20java.util.Map<java.lang.String,java.util.List<java.lang.String>>)(https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/util/Locale.LanguageRange> priorityList, https://developer.android.com/reference/java/util/Map<https://developer.android.com/reference/java/lang/String, https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/lang/String>> map) ` Generates a new customized Language Priority List using the given `priorityList` and `map`. |
| ` static https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/util/Locale.LanguageRange>` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#parse(java.lang.String)(https://developer.android.com/reference/java/lang/String ranges) ` Parses the given `ranges` to generate a Language Priority List. |
| ` static https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/util/Locale.LanguageRange>` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#parse(java.lang.String,%20java.util.Map<java.lang.String,java.util.List<java.lang.String>>)(https://developer.android.com/reference/java/lang/String ranges, https://developer.android.com/reference/java/util/Map<https://developer.android.com/reference/java/lang/String, https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/lang/String>> map) ` Parses the given `ranges` to generate a Language Priority List, and then customizes the list using the given `map`. |
| ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/util/Locale.LanguageRange#toString()() ` Returns an informative string representation of this `LanguageRange` object, consisting of language range and weight if the range is weighted and the weight is less than the max weight. |

| ### 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*. | ||

## Constants

### MAX_WEIGHT

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

```
public static final double MAX_WEIGHT
```

A constant holding the maximum value of weight, 1.0, which indicates
that the language range is a good fit for the user.

<br />

Constant Value:

1.0


### MIN_WEIGHT

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

```
public static final double MIN_WEIGHT
```

A constant holding the minimum value of weight, 0.0, which indicates
that the language range is not a good fit for the user.

<br />

Constant Value:

0.0


## Public constructors

### LanguageRange

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

```
public LanguageRange (String range)
```

Constructs a `LanguageRange` using the given `range`.
Note that no validation is done against the IANA Language Subtag
Registry at time of construction.

This is equivalent to `LanguageRange(range, MAX_WEIGHT)`.

<br />

| Parameters ||
|---|---|
| `range` | `String`: a language range <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the given `range` does not comply with the syntax of the language range mentioned in RFC 4647 |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the given `range` is `null` |

### LanguageRange

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

```
public LanguageRange (String range, 
                double weight)
```

Constructs a `LanguageRange` using the given `range` and
`weight`. Note that no validation is done against the IANA
Language Subtag Registry at time of construction.

<br />

| Parameters ||
|---|---|
| `range` | `String`: a language range <br /> |
| `weight` | `double`: a weight value between `MIN_WEIGHT` and `MAX_WEIGHT` <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if the given `range` does not comply with the syntax of the language range mentioned in RFC 4647 or if the given `weight` is less than `MIN_WEIGHT` or greater than `MAX_WEIGHT` |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the given `range` is `null` |

## Public methods

### equals

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

```
public boolean equals (Object obj)
```

Compares this object to the specified object. The result is true if
and only if the argument is not `null` and is a
`LanguageRange` object that contains the same `range`
and `weight` values as this object.

<br />

| Parameters ||
|---|---|
| `obj` | `Object`: the object to compare with <br /> |

| Returns ||
|---|---|
| `boolean` | `true` if this object's `range` and `weight` are the same as the `obj`'s; `false` otherwise. <br /> |

### getRange

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

```
public String getRange ()
```

Returns the language range of this `LanguageRange`.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/String` | the language range. <br /> |

### getWeight

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

```
public double getWeight ()
```

Returns the weight of this `LanguageRange`.

<br />

| Returns ||
|---|---|
| `double` | the weight value. <br /> |

### hashCode

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

```
public int hashCode ()
```

<br />

<br />

| Returns ||
|---|---|
| `int` | a hash code value for this object <br /> |

### mapEquivalents

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

```
public static List<Locale.LanguageRange> mapEquivalents (List<Locale.LanguageRange> priorityList, 
                Map<String, List<String>> map)
```

Generates a new customized Language Priority List using the given
`priorityList` and `map`. If the given `map` is
empty, this method returns a copy of the given `priorityList`.

In the map, a key represents a language range whereas a value is
a list of equivalents of it. `'*'` cannot be used in the map.
Each equivalent language range has the same weight value as its
original language range.

```
 An example of map:
   Key                            Value
     "zh" (Chinese)                 "zh",
                                    "zh-Hans"(Simplified Chinese)
     "zh-HK" (Chinese, Hong Kong)   "zh-HK"
     "zh-TW" (Chinese, Taiwan)      "zh-TW"
```
The customization is performed after modification using the IANA Language Subtag Registry.

For example, if a user's Language Priority List consists of five
language ranges (`"zh"`, `"zh-CN"`, `"en"`,
`"zh-TW"`, and `"zh-HK"`), the newly generated Language
Priority List which is customized using the above map example will
consists of `"zh"`, `"zh-Hans"`, `"zh-CN"`,
`"zh-Hans-CN"`, `"en"`, `"zh-TW"`, and
`"zh-HK"`.

`"zh-HK"` and `"zh-TW"` aren't converted to
`"zh-Hans-HK"` nor `"zh-Hans-TW"` even if they are
included in the Language Priority List. In this example, mapping
is used to clearly distinguish Simplified Chinese and Traditional
Chinese.

If the `"zh"`-to-`"zh"` mapping isn't included in the
map, a simple replacement will be performed and the customized list
won't include `"zh"` and `"zh-CN"`.

<br />

| Parameters ||
|---|---|
| `priorityList` | `List`: user's Language Priority List <br /> |
| `map` | `Map`: a map containing information to customize language ranges <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/util/Locale.LanguageRange>` | a new Language Priority List with customization. The list is modifiable. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `priorityList` is `null` |

**See also:**

- `https://developer.android.com/reference/java/util/Locale.LanguageRange#parse(java.lang.String,%20java.util.Map<java.lang.String,java.util.List<java.lang.String>>)`

### parse

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

```
public static List<Locale.LanguageRange> parse (String ranges)
```

Parses the given `ranges` to generate a Language Priority List.

This method performs a syntactic check for each language range in
the given `ranges` but doesn't do validation using the IANA
Language Subtag Registry.

The `ranges` to be given can take one of the following
forms:

```
  "Accept-Language: ja,en;q=0.4"  (weighted list with Accept-Language prefix)
  "ja,en;q=0.4"                   (weighted list)
  "ja,en"                         (prioritized list)
```
In a weighted list, each language range is given a weight value. The weight value is identical to the "quality value" in [RFC 2616](https://tools.ietf.org/html/rfc2616), and it expresses how much the user prefers the language. A weight value is specified after a corresponding language range followed by `";q="`, and the default weight value is `MAX_WEIGHT` when it is omitted.

Unlike a weighted list, language ranges in a prioritized list
are sorted in the descending order based on its priority. The first
language range has the highest priority and meets the user's
preference most.

In either case, language ranges are sorted in descending order in
the Language Priority List based on priority or weight. If a
language range appears in the given `ranges` more than once,
only the first one is included on the Language Priority List.

The returned list consists of language ranges from the given
`ranges` and their equivalents found in the IANA Language
Subtag Registry. For example, if the given `ranges` is
`"Accept-Language: iw,en-us;q=0.7,en;q=0.3"`, the elements in
the list to be returned are:

```
 Range                                   Weight
   "iw" (older tag for Hebrew)             1.0
   "he" (new preferred code for Hebrew)    1.0
   "en-us" (English, United States)        0.7
   "en" (English)                          0.3
```
Two language ranges, `"iw"` and `"he"`, have the same highest priority in the list. By adding `"he"` to the user's Language Priority List, locale-matching method can find Hebrew as a matching locale (or language tag) even if the application or system offers only `"he"` as a supported locale (or language tag).

<br />

<br />

| Parameters ||
|---|---|
| `ranges` | `String`: a list of comma-separated language ranges or a list of language ranges in the form of the "Accept-Language" header defined in [RFC 2616](https://tools.ietf.org/html/rfc2616) <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/util/Locale.LanguageRange>` | a Language Priority List consisting of language ranges included in the given `ranges` and their equivalent language ranges if available. The list is modifiable. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if a language range or a weight found in the given `ranges` is ill-formed |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `ranges` is null |

### parse

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

```
public static List<Locale.LanguageRange> parse (String ranges, 
                Map<String, List<String>> map)
```

Parses the given `ranges` to generate a Language Priority
List, and then customizes the list using the given `map`.
This method is equivalent to
`mapEquivalents(parse(ranges), map)`.

<br />

| Parameters ||
|---|---|
| `ranges` | `String`: a list of comma-separated language ranges or a list of language ranges in the form of the "Accept-Language" header defined in [RFC 2616](https://tools.ietf.org/html/rfc2616) <br /> |
| `map` | `Map`: a map containing information to customize language ranges <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/List<https://developer.android.com/reference/java/util/Locale.LanguageRange>` | a Language Priority List with customization. The list is modifiable. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | if a language range or a weight found in the given `ranges` is ill-formed |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `ranges` is null |

**See also:**

- `https://developer.android.com/reference/java/util/Locale.LanguageRange#parse(java.lang.String)`
- `https://developer.android.com/reference/java/util/Locale.LanguageRange#mapEquivalents(java.util.List<java.util.Locale.LanguageRange>,%20java.util.Map<java.lang.String,java.util.List<java.lang.String>>)`

### toString

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

```
public String toString ()
```

Returns an informative string representation of this `LanguageRange`
object, consisting of language range and weight if the range is
weighted and the weight is less than the max weight.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/String` | a string representation of this `LanguageRange` object. <br /> |