LanguageRange
class LanguageRange
kotlin.Any | |
↳ | java.util.Locale.LanguageRange |
This class expresses a Language Range defined in RFC 4647 Matching of Language Tags. A language range is an identifier which is used to select language tag(s) meeting specific requirements by using the mechanisms described in Locale Matching. 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 as follows:
basic-language-range = (1*8ALPHA *("-" 1*8alphanum)) / "*" extended-language-range = (1*8ALPHA / "*") *("-" (1*8alphanum / "*")) alphanum = ALPHA / DIGIT
"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.
Summary
Constants | |
---|---|
static Double |
A constant holding the maximum value of weight, 1. |
static Double |
A constant holding the minimum value of weight, 0. |
Public constructors | |
---|---|
LanguageRange(range: String) Constructs a |
|
LanguageRange(range: String, weight: Double) Constructs a |
Public methods | |
---|---|
Boolean |
Compares this object to the specified object. |
String |
getRange() Returns the language range of this |
Double |
Returns the weight of this |
Int |
hashCode() Returns a hash code value for the object. |
static MutableList<Locale.LanguageRange!> |
mapEquivalents(priorityList: MutableList<Locale.LanguageRange!>, map: MutableMap<String!, MutableList<String!>!>) Generates a new customized Language Priority List using the given |
static MutableList<Locale.LanguageRange!> |
Parses the given |
static MutableList<Locale.LanguageRange!> |
parse(ranges: String, map: MutableMap<String!, MutableList<String!>!>) Parses the given |
String |
toString() Returns an informative string representation of this |
Constants
MAX_WEIGHT
static val MAX_WEIGHT: Double
A constant holding the maximum value of weight, 1.0, which indicates that the language range is a good fit for the user.
Value: 1.0
MIN_WEIGHT
static val MIN_WEIGHT: Double
A constant holding the minimum value of weight, 0.0, which indicates that the language range is not a good fit for the user.
Value: 0.0
Public constructors
LanguageRange
LanguageRange(range: String)
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)
.
Parameters | |
---|---|
range |
String: a language range |
Exceptions | |
---|---|
java.lang.NullPointerException |
if the given range is null |
java.lang.IllegalArgumentException |
if the given range does not comply with the syntax of the language range mentioned in RFC 4647 |
LanguageRange
LanguageRange(
range: String,
weight: Double)
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.
Parameters | |
---|---|
range |
String: a language range |
weight |
Double: a weight value between MIN_WEIGHT and MAX_WEIGHT |
Exceptions | |
---|---|
java.lang.NullPointerException |
if the given range is null |
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 |
Public methods
equals
fun equals(other: Any?): Boolean
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.
Parameters | |
---|---|
obj |
the object to compare with |
Return | |
---|---|
Boolean |
true if this object's range and weight are the same as the obj 's; false otherwise. |
getRange
fun getRange(): String
Returns the language range of this LanguageRange
.
Return | |
---|---|
String |
the language range. |
getWeight
fun getWeight(): Double
Returns the weight of this LanguageRange
.
Return | |
---|---|
Double |
the weight value. |
hashCode
fun hashCode(): Int
Returns a hash code value for the object.
Return | |
---|---|
Int |
a hash code value for this object. |
mapEquivalents
static fun mapEquivalents(
priorityList: MutableList<Locale.LanguageRange!>,
map: MutableMap<String!, MutableList<String!>!>
): MutableList<Locale.LanguageRange!>
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: <b>Key</b><b>Value</b>"zh" (Chinese) "zh", "zh-Hans"(Simplified Chinese) "zh-HK" (Chinese, Hong Kong) "zh-HK" "zh-TW" (Chinese, Taiwan) "zh-TW"
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"
.
Parameters | |
---|---|
priorityList |
MutableList<Locale.LanguageRange!>: user's Language Priority List |
map |
MutableMap<String!, MutableList<String!>!>: a map containing information to customize language ranges |
Return | |
---|---|
MutableList<Locale.LanguageRange!> |
a new Language Priority List with customization. The list is modifiable. |
Exceptions | |
---|---|
java.lang.NullPointerException |
if priorityList is null |
See Also
parse
static fun parse(ranges: String): MutableList<Locale.LanguageRange!>
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)
";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:
<b>Range</b><b>Weight</b>"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
"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).
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 |
Return | |
---|---|
MutableList<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. |
Exceptions | |
---|---|
java.lang.NullPointerException |
if ranges is null |
java.lang.IllegalArgumentException |
if a language range or a weight found in the given ranges is ill-formed |
parse
static fun parse(
ranges: String,
map: MutableMap<String!, MutableList<String!>!>
): MutableList<Locale.LanguageRange!>
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)
.
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 |
map |
MutableMap<String!, MutableList<String!>!>: a map containing information to customize language ranges |
Return | |
---|---|
MutableList<Locale.LanguageRange!> |
a Language Priority List with customization. The list is modifiable. |
Exceptions | |
---|---|
java.lang.NullPointerException |
if ranges is null |
java.lang.IllegalArgumentException |
if a language range or a weight found in the given ranges is ill-formed |
See Also
toString
fun toString(): String
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.
Return | |
---|---|
String |
a string representation of this LanguageRange object. |