Provides an immutable list of languages/locales in priority order. The string format is based on the Accept-Language format (RFC 2616 Section 14.4), such as "af, en, fr;q=0.9". Syntactically it is slightly more lenient, in allowing extra whitespace between elements, extra commas, and more than 3 decimals (on input). The qvalues must be between 0 and 1.

In theory, Accept-Language indicates the relative 'quality' of each item, but in practice, all of the browsers just take an ordered list, like "en, fr, de", and synthesize arbitrary quality values that put these in the right order, like: "en, fr;q=0.7, de;q=0.3". The quality values in these de facto semantics thus have nothing to do with the relative qualities of the original. Accept-Language also doesn't specify the interpretation of multiple instances, eg what "en, fr, en;q=.5" means.

There are various ways to build a LocalePriorityList, such as using the following equivalent patterns:

list = LocalePriorityList.add("af, en, fr;q=0.9").build();

list2 = LocalePriorityList
 .add(ULocale.forString("af"))
 .add(ULocale.ENGLISH)
 .add(ULocale.FRENCH, 0.9d)
 .build();

When the list is built, the internal values are sorted in descending order by weight, and then by input order. That is, if two languages/locales have the same weight, the first one in the original order comes first. If exactly the same language tag appears multiple times, the last one wins.

There are two options when building. If preserveWeights are on, then "de;q=0.3, ja;q=0.3, en, fr;q=0.7, de " would result in the following:

 en;q=1.0
de;q=1.0
fr;q=0.7
ja;q=0.3

If it is off (the default), then all weights are reset to 1.0 after reordering. This is to match the effect of the Accept-Language semantics as used in browsers, and results in the following:

 en;q=1.0
de;q=1.0
fr;q=1.0
ja;q=1.0

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	LocalePriorityList.Builder Class used for building LocalePriorityLists.

Modifier and Type	Field and Description
private static final Double	D1
private final Map<ULocale, Double>	languagesAndWeights
private static final Pattern	languageSplitter
private static Comparator<Double>	myDescendingDouble
private static final Pattern	weightSplitter

Access	Constructor and Description
private	LocalePriorityList(final Map<ULocale, Double> languageToWeight)

Method Summary

Modifier and Type	Method and Description
public static LocalePriorityList.Builder	Returns: a new builder with these locales, for chaining add(ULocale... locales/languages to be added locales) Creates a Builder and adds locales, each with weight 1.0.
public static LocalePriorityList.Builder	Returns: a new builder with this locale, for chaining add(ULocale locale/language to be added locale, final double value from 0.0 to 1.0 weight) Creates a Builder and adds a locale with a specified weight.
public static LocalePriorityList.Builder	Returns: a new builder with these locales, for chaining add(LocalePriorityList list of locales with weights list) Creates a Builder and adds locales with weights.
public static LocalePriorityList.Builder	Returns: a new builder with these locales, for chaining add(String String in RFC 2616 format (leniently parsed) acceptLanguageString) Creates a Builder, parses the RFC 2616 string, and adds locales with weights accordingly.
public boolean	equals(final Object the reference object with which to compare. o) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this one.
public Set<ULocale>	Returns: the locales getULocales() Returns the locales as an immutable Set view.
public Double	Returns: weight getWeight(ULocale to get weight of locale) Returns the weight for a given language/locale, or null if there is none.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for the object.
public Iterator<ULocale>	iterator() Implements java.lang.Iterable.iterator. Returns an iterator over elements of type `T`.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

Field Detail

D1	back to summary
private static final Double D1

languagesAndWeights	back to summary
private final Map<ULocale, Double> languagesAndWeights

languageSplitter	back to summary
private static final Pattern languageSplitter

myDescendingDouble	back to summary
private static Comparator<Double> myDescendingDouble

weightSplitter	back to summary
private static final Pattern weightSplitter

Constructor Detail

LocalePriorityList	back to summary
private LocalePriorityList(final Map<ULocale, Double> languageToWeight)

Method Detail

add	back to summary
public static LocalePriorityList.Builder add(ULocale... locales) Creates a Builder and adds locales, each with weight 1.0. Parameters locales:ULocale[] locales/languages to be added Returns:LocalePriorityList.Builder a new builder with these locales, for chaining ICU Status Stable since ICU 4.4.

add

back to summary

public static LocalePriorityList.Builder add(ULocale... locales)

Creates a Builder and adds locales, each with weight 1.0.

Parameters

locales:ULocale[]: locales/languages to be added

Returns:LocalePriorityList.Builder

a new builder with these locales, for chaining

ICU Status

Stable since ICU 4.4.

add	back to summary
public static LocalePriorityList.Builder add(ULocale locale, final double weight) Creates a Builder and adds a locale with a specified weight. A zero or negative weight leads to removing the locale. A weight greater than 1 is pinned to 1. Parameters locale:ULocale locale/language to be added weight:double value from 0.0 to 1.0 Returns:LocalePriorityList.Builder a new builder with this locale, for chaining ICU Status Stable since ICU 4.4.

add

back to summary

public static LocalePriorityList.Builder add(ULocale locale, final double weight)

Creates a Builder and adds a locale with a specified weight. A zero or negative weight leads to removing the locale. A weight greater than 1 is pinned to 1.

Parameters

locale:ULocale: locale/language to be added
weight:double: value from 0.0 to 1.0

Returns:LocalePriorityList.Builder

a new builder with this locale, for chaining

ICU Status

Stable since ICU 4.4.

add	back to summary
public static LocalePriorityList.Builder add(LocalePriorityList list) Creates a Builder and adds locales with weights. Parameters list:LocalePriorityList list of locales with weights Returns:LocalePriorityList.Builder a new builder with these locales, for chaining ICU Status Stable since ICU 4.4.

add

back to summary

public static LocalePriorityList.Builder add(LocalePriorityList list)

Creates a Builder and adds locales with weights.

Parameters

list:LocalePriorityList: list of locales with weights

Returns:LocalePriorityList.Builder

a new builder with these locales, for chaining

ICU Status

Stable since ICU 4.4.

add	back to summary
public static LocalePriorityList.Builder add(String acceptLanguageString) Creates a Builder, parses the RFC 2616 string, and adds locales with weights accordingly. Parameters acceptLanguageString:String String in RFC 2616 format (leniently parsed) Returns:LocalePriorityList.Builder a new builder with these locales, for chaining ICU Status Stable since ICU 4.4.

add

back to summary

public static LocalePriorityList.Builder add(String acceptLanguageString)

Creates a Builder, parses the RFC 2616 string, and adds locales with weights accordingly.

Parameters

acceptLanguageString:String: String in RFC 2616 format (leniently parsed)

Returns:LocalePriorityList.Builder

a new builder with these locales, for chaining

ICU Status

Stable since ICU 4.4.

equals back to summary

equals	back to summary
public boolean equals(final Object o) Overrides java.lang.Object.equals. Doc from java.lang.Object.equals. Indicates whether some other object is "equal to" this one. The `equals` method implements an equivalence relation on non-null object references: It is reflexive: for any non-null reference value `x`, `x.equals(x)` should return `true`. It is symmetric: for any non-null reference values `x` and `y`, `x.equals(y)` should return `true` if and only if `y.equals(x)` returns `true`. It is transitive: for any non-null reference values `x`, `y`, and `z`, if `x.equals(y)` returns `true` and `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`. It is consistent: for any non-null reference values `x` and `y`, multiple invocations of `x.equals(y)` consistently return `true` or consistently return `false`, provided no information used in `equals` comparisons on the objects is modified. For any non-null reference value `x`, `x.equals(null)` should return `false`. An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes. Parameters o:Object the reference object with which to compare. Returns:boolean `true` if this object is the same as the obj argument; `false` otherwise. Annotations @Override ICU Status Stable since ICU 4.4.

public boolean equals(final Object o)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

It is reflexive: for any non-null reference value x, x.equals(x) should return true.
It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

Parameters

o:Object: the reference object with which to compare.

Returns:boolean

true if this object is the same as the obj argument; false otherwise.

Annotations

@Override

ICU Status

Stable since ICU 4.4.

getULocales	back to summary
public Set<ULocale> getULocales() Returns the locales as an immutable Set view. The set has the same iteration order as this object itself. Returns:Set<ULocale> the locales ICU Status Stable since ICU 65.

getULocales

back to summary

public Set<ULocale> getULocales()

Returns the locales as an immutable Set view. The set has the same iteration order as this object itself.

Returns:Set<ULocale>: the locales
ICU Status: Stable since ICU 65.

getWeight	back to summary
public Double getWeight(ULocale locale) Returns the weight for a given language/locale, or null if there is none. Note that the weights may be adjusted from those used to build the list. Parameters locale:ULocale to get weight of Returns:Double weight ICU Status Stable since ICU 4.4.

getWeight

back to summary

public Double getWeight(ULocale locale)

Returns the weight for a given language/locale, or null if there is none. Note that the weights may be adjusted from those used to build the list.

Parameters

locale:ULocale: to get weight of

Returns:Double

weight

ICU Status

Stable since ICU 4.4.

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Doc from java.lang.Object.hashCode. Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by `java.util.HashMap`. The general contract of `hashCode` is: Whenever it is invoked on the same object more than once during an execution of a Java application, the `hashCode` method must consistently return the same integer, provided no information used in `equals` comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables. Returns:int a hash code value for this object. Annotations @Override ICU Status Stable since ICU 4.4.

public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Returns:int

a hash code value for this object.

Annotations

@Override

ICU Status

Stable since ICU 4.4.

iterator back to summary

iterator	back to summary
public Iterator<ULocale> iterator() Implements java.lang.Iterable.iterator. Doc from java.lang.Iterable.iterator. Returns an iterator over elements of type `T`. Returns:Iterator<ULocale> an Iterator. Annotations @Override ICU Status Stable since ICU 4.4.

public Iterator<ULocale> iterator()

Implements java.lang.Iterable.iterator.

Doc from java.lang.Iterable.iterator.

Returns an iterator over elements of type T.

Returns:Iterator<ULocale>

an Iterator.

Annotations

@Override

ICU Status

Stable since ICU 4.4.

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Returns:String a string representation of the object. Annotations @Override ICU Status Stable since ICU 4.4.

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations

@Override

ICU Status

Stable since ICU 4.4.

com.ibm.icu.util back to summary

public Class LocalePriorityList.Builder

Class Inheritance

extends Object

java.lang.Object
com.ibm.icu.util.LocalePriorityList.Builder

Class used for building LocalePriorityLists.

ICU Status: Stable since ICU 4.4.

Field Summary

Modifier and Type	Field and Description
private LocalePriorityList	built The builder is reusable but rarely reused.
private boolean	hasWeights
private Map<ULocale, Double>	languageToWeight These store the input languages and weights, in chronological order, where later additions override previous ones.

Constructor Summary

Access	Constructor and Description
private	Builder() Private constructor, only used by LocalePriorityList
private	Builder(LocalePriorityList list)

Method Summary

Modifier and Type	Method and Description
public LocalePriorityList.Builder	Returns: this, for chaining add(final LocalePriorityList list of locales with weights list) Adds locales with weights.
public LocalePriorityList.Builder	Returns: this, for chaining add(final ULocale to add with weight 1.0 locale) Adds a locale with weight 1.0.
public LocalePriorityList.Builder	Returns: this, for chaining. add(ULocale... locales/languages to be added locales) Adds locales, each with weight 1.0.
public LocalePriorityList.Builder	Returns: this, for chaining. add(final ULocale language/locale to add locale, double value between 0.0 and 1.1 weight) Adds a locale with a specified weight.
public LocalePriorityList.Builder	Returns: this, for chaining. add(final String in RFC 2616 format (leniently parsed) acceptLanguageList) Parses the RFC 2616 string, and adds locales with weights accordingly.
public LocalePriorityList	Returns: A LocalePriorityList build() Creates a LocalePriorityList.
public LocalePriorityList	Returns: A LocalePriorityList build(boolean when true, each locale's given weight is preserved. preserveWeights) Creates a LocalePriorityList.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

built	back to summary
private LocalePriorityList built The builder is reusable but rarely reused. Avoid cloning the map when not needed. Exactly one of languageToWeight and built is null.

hasWeights	back to summary
private boolean hasWeights

languageToWeight	back to summary
private Map<ULocale, Double> languageToWeight These store the input languages and weights, in chronological order, where later additions override previous ones.

Constructor Detail

Builder	back to summary
private Builder() Private constructor, only used by LocalePriorityList

Builder	back to summary
private Builder(LocalePriorityList list)

Method Detail

add	back to summary
public LocalePriorityList.Builder add(final LocalePriorityList list) Adds locales with weights. Parameters list:LocalePriorityList list of locales with weights Returns:LocalePriorityList.Builder this, for chaining ICU Status Stable since ICU 4.4.

add

back to summary

public LocalePriorityList.Builder add(final LocalePriorityList list)

Adds locales with weights.

Parameters

list:LocalePriorityList: list of locales with weights

Returns:LocalePriorityList.Builder

this, for chaining

ICU Status

Stable since ICU 4.4.

add	back to summary
public LocalePriorityList.Builder add(final ULocale locale) Adds a locale with weight 1.0. Parameters locale:ULocale to add with weight 1.0 Returns:LocalePriorityList.Builder this, for chaining ICU Status Stable since ICU 4.4.

add

back to summary

public LocalePriorityList.Builder add(final ULocale locale)

Adds a locale with weight 1.0.

Parameters

locale:ULocale: to add with weight 1.0

Returns:LocalePriorityList.Builder

this, for chaining

ICU Status

Stable since ICU 4.4.

add	back to summary
public LocalePriorityList.Builder add(ULocale... locales) Adds locales, each with weight 1.0. Parameters locales:ULocale[] locales/languages to be added Returns:LocalePriorityList.Builder this, for chaining. ICU Status Stable since ICU 4.4.

add

back to summary

public LocalePriorityList.Builder add(ULocale... locales)

Adds locales, each with weight 1.0.

Parameters

locales:ULocale[]: locales/languages to be added

Returns:LocalePriorityList.Builder

this, for chaining.

ICU Status

Stable since ICU 4.4.

add	back to summary
public LocalePriorityList.Builder add(final ULocale locale, double weight) Adds a locale with a specified weight. Overrides any previous weight for the locale. A zero or negative weight leads to removing the locale. A weight greater than 1 is pinned to 1. Parameters locale:ULocale language/locale to add weight:double value between 0.0 and 1.1 Returns:LocalePriorityList.Builder this, for chaining. ICU Status Stable since ICU 4.4.

add

back to summary

public LocalePriorityList.Builder add(final ULocale locale, double weight)

Adds a locale with a specified weight. Overrides any previous weight for the locale. A zero or negative weight leads to removing the locale. A weight greater than 1 is pinned to 1.

Parameters

locale:ULocale: language/locale to add
weight:double: value between 0.0 and 1.1

Returns:LocalePriorityList.Builder

this, for chaining.

ICU Status

Stable since ICU 4.4.

add	back to summary
public LocalePriorityList.Builder add(final String acceptLanguageList) Parses the RFC 2616 string, and adds locales with weights accordingly. Parameters acceptLanguageList:String in RFC 2616 format (leniently parsed) Returns:LocalePriorityList.Builder this, for chaining. ICU Status Stable since ICU 4.4.

add

back to summary

public LocalePriorityList.Builder add(final String acceptLanguageList)

Parses the RFC 2616 string, and adds locales with weights accordingly.

Parameters

acceptLanguageList:String: in RFC 2616 format (leniently parsed)

Returns:LocalePriorityList.Builder

this, for chaining.

ICU Status

Stable since ICU 4.4.

build back to summary

build	back to summary
public LocalePriorityList build() Creates a LocalePriorityList. This is equivalent to `Builder.build(false)`. Returns:LocalePriorityList A LocalePriorityList ICU Status Stable since ICU 4.4.

public LocalePriorityList build()

Creates a LocalePriorityList. This is equivalent to Builder.build(false).

Returns:LocalePriorityList: A LocalePriorityList
ICU Status: Stable since ICU 4.4.

build	back to summary
public LocalePriorityList build(boolean preserveWeights) Creates a LocalePriorityList. Parameters preserveWeights:boolean when true, each locale's given weight is preserved. Returns:LocalePriorityList A LocalePriorityList ICU Status Stable since ICU 4.4.

build

back to summary

public LocalePriorityList build(boolean preserveWeights)

Creates a LocalePriorityList.

Parameters

preserveWeights:boolean: when true, each locale's given weight is preserved.

Returns:LocalePriorityList

A LocalePriorityList

ICU Status

Stable since ICU 4.4.