Класс Locale.LanguageRange

java.lang.Object

java.util.Locale.LanguageRange

Внешний класс:: Locale

public static final class Locale.LanguageRange extends Object

Этот класс представляет языковой диапазон, определённый в документе RFC 4647 Matching of Language Tags. Языковой диапазон — это идентификатор, используемый для выбора языковых тегов, соответствующих определённым требованиям, с помощью механизмов, описанных в разделе Сопоставление локалей. Список, представляющий предпочтения пользователя и состоящий из языковых диапазонов, называется списком приоритетов языков.

Существует два типа языковых диапазонов: базовые и расширенные. В RFC 4647 синтаксис языковых диапазонов выражен в ABNF следующим образом:

    basic-language-range    = (1*8ALPHA *("-" 1*8alphanum)) / "*"
    extended-language-range = (1*8ALPHA / "*")
                              *("-" (1*8alphanum / "*"))
    alphanum                = ALPHA / DIGIT

Например, "en" (английский), "ja-JP" (японский, Япония), "*" (специальный языковой диапазон, соответствующий любому языковому тегу) являются базовыми языковыми диапазонами, тогда как "*-CH" (любой язык, Швейцария), "es-*" (испанский, любой регион) и "zh-Hant-*" (традиционный китайский, любой регион) являются расширенными языковыми диапазонами.

С версии:

1.8

Внешние спецификации

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final double`	`MAX_WEIGHT`	Константа, содержащая максимальное значение веса — 1.0, указывающее, что языковой диапазон хорошо подходит пользователю.
`static final double`	`MIN_WEIGHT`	Константа, содержащая минимальное значение веса — 0.0, указывающее, что языковой диапазон не подходит пользователю.

Краткое описание конструкторов

Конструктор	Описание
`LanguageRange(String range)`	Создаёт `LanguageRange` с использованием заданного `range`.
`LanguageRange(String range, double weight)`	Создаёт `LanguageRange` с использованием заданных `range` и `weight`.

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`equals(Object obj)`	Сравнивает этот объект с указанным объектом.
`String`	`getRange()`	Возвращает языковой диапазон этого `LanguageRange`.
`double`	`getWeight()`	Возвращает вес этого `LanguageRange`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`static List<Locale.LanguageRange>`	`mapEquivalents(List<Locale.LanguageRange> priorityList, Map<String, List<String>> map)`	Создаёт новый настроенный список приоритетов языков с использованием заданных `priorityList` и `map`.
`static List<Locale.LanguageRange>`	`parse(String ranges)`	Разбирает заданный `ranges` для создания списка приоритетов языков.
`static List<Locale.LanguageRange>`	`parse(String ranges, Map<String, List<String>> map)`	Разбирает заданный `ranges` для создания списка приоритетов языков, а затем настраивает список с использованием заданного `map`.
`String`	`toString()`	Возвращает информативное строковое представление этого объекта `LanguageRange`, состоящее из языкового диапазона и веса, если для диапазона задан вес и он меньше максимального.

Методы, объявленные в классе Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Подробное описание полей

MAX_WEIGHT

public static final double MAX_WEIGHT

Константа, содержащая максимальное значение веса — 1.0, указывающее, что языковой диапазон хорошо подходит пользователю.

См. также:

MIN_WEIGHT

public static final double MIN_WEIGHT

Константа, содержащая минимальное значение веса — 0.0, указывающее, что языковой диапазон не подходит пользователю.

См. также:

Подробное описание конструкторов

LanguageRange

public LanguageRange(String range)

Создаёт LanguageRange с использованием заданного range. Обратите внимание: при создании проверка по реестру языковых подстановок IANA не выполняется.

Это эквивалентно LanguageRange(range, MAX_WEIGHT).

Параметры:: range — языковой диапазон
Исключения:: NullPointerException — если заданный range равен null; IllegalArgumentException — если заданный range не соответствует синтаксису языкового диапазона, указанному в RFC 4647

LanguageRange

public LanguageRange(String range, double weight)

Создаёт LanguageRange с использованием заданных range и weight. Обратите внимание: при создании проверка по реестру языковых подстановок IANA не выполняется.

Параметры:: range — языковой диапазон; weight — значение веса от MIN_WEIGHT до MAX_WEIGHT
Исключения:: NullPointerException — если заданный range равен null; IllegalArgumentException — если заданный range не соответствует синтаксису языкового диапазона, указанному в RFC 4647, либо если заданный weight меньше MIN_WEIGHT или больше MAX_WEIGHT

Подробное описание методов

getRange

public String getRange()

Возвращает языковой диапазон этого LanguageRange.

Возвращает:: языковой диапазон.

getWeight

public double getWeight()

Возвращает вес этого LanguageRange.

Возвращает:: значение веса.

parse

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

Разбирает заданный ranges для создания списка приоритетов языков.

Этот метод выполняет синтаксическую проверку каждого языкового диапазона в заданном ranges, но не проверяет их с использованием реестра языковых подстановок IANA.

Задаваемый ranges может иметь один из следующих форматов:

  "Accept-Language: ja,en;q=0.4"  (weighted list with Accept-Language prefix)
  "ja,en;q=0.4"                   (weighted list)
  "ja,en"                         (prioritized list)

В списке с весами каждому языковому диапазону присваивается значение веса. Значение веса совпадает со значением «quality» из RFC 2616 и выражает предпочтение пользователя для данного языка. Значение веса указывается после соответствующего языкового диапазона, за которым следует ";q="; если оно не указано, используется значение веса по умолчанию MAX_WEIGHT.

В отличие от списка с весами, языковые диапазоны в списке с приоритетами сортируются по убыванию приоритета. Первый языковой диапазон имеет наивысший приоритет и в наибольшей степени соответствует предпочтениям пользователя.

В обоих случаях языковые диапазоны в списке приоритетов языков сортируются по убыванию приоритета или веса. Если языковой диапазон встречается в заданном ranges более одного раза, в список приоритетов языков включается только первое вхождение.

Возвращаемый список состоит из языковых диапазонов из заданного ranges и их эквивалентов, найденных в реестре языковых подстановок IANA. Например, если заданный ranges — это "Accept-Language: iw,en-us;q=0.7,en;q=0.3", возвращаемый список будет содержать следующие элементы:

 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

Два языковых диапазона, "iw" и "he", имеют в списке одинаковый наивысший приоритет. Добавив "he" в список приоритетов языков пользователя, метод сопоставления локалей сможет найти иврит как соответствующую локаль (или языковой тег), даже если приложение или система предлагает в качестве поддерживаемой локали (или языкового тега) только "he".

Параметры:

ranges — список языковых диапазонов, разделённых запятыми, или список языковых диапазонов в формате заголовка «Accept-Language», определённого в RFC 2616

Возвращает:

список приоритетов языков, состоящий из языковых диапазонов, входящих в заданный ranges, и их эквивалентных языковых диапазонов, если они доступны. Список можно изменять.

Исключения:

NullPointerException — если ranges равен null

IllegalArgumentException — если языковой диапазон или вес, найденный в заданном ranges, имеет неверный формат

Внешние спецификации

parse

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

Разбирает заданный ranges для создания списка приоритетов языков, а затем настраивает список с использованием заданного map. Этот метод эквивалентен mapEquivalents(parse(ranges), map).

Параметры:

map — карта, содержащая сведения для настройки языковых диапазонов

Возвращает:

настроенный список приоритетов языков. Список можно изменять.

Исключения:

NullPointerException — если ranges равен null

IllegalArgumentException — если языковой диапазон или вес, найденный в заданном ranges, имеет неверный формат

Внешние спецификации

См. также:

mapEquivalents

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

Создаёт новый настроенный список приоритетов языков с использованием заданных priorityList и map. Если заданный map пуст, этот метод возвращает копию заданного priorityList.

В карте ключ представляет языковой диапазон, а значение — список его эквивалентов. '*' нельзя использовать в карте. Каждый эквивалентный языковой диапазон имеет то же значение веса, что и исходный языковой диапазон.

 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"

Настройка выполняется после изменения с использованием реестра языковых подстановок IANA.

Например, если список приоритетов языков пользователя состоит из пяти языковых диапазонов ("zh", "zh-CN", "en", "zh-TW" и "zh-HK"), вновь созданный список приоритетов языков, настроенный с использованием приведённого выше примера карты, будет состоять из "zh", "zh-Hans", "zh-CN", "zh-Hans-CN", "en", "zh-TW" и "zh-HK".

"zh-HK" и "zh-TW" не преобразуются в "zh-Hans-HK" или "zh-Hans-TW", даже если они включены в список приоритетов языков. В этом примере сопоставление используется для явного различения упрощённого и традиционного китайского.

Если сопоставление "zh"-"zh" не включено в карту, будет выполнена простая замена, и настроенный список не будет содержать "zh" и "zh-CN".

Параметры:

priorityList — список приоритетов языков пользователя

map — карта, содержащая сведения для настройки языковых диапазонов

Возвращает:

новый настроенный список приоритетов языков. Список можно изменять.

Исключения:

NullPointerException — если priorityList равен null

См. также:

hashCode

public int hashCode()

Возвращает хеш-код этого объекта.

Переопределяет:

hashCode в классе Object

Возвращает:

хеш-код этого объекта

См. также:

equals

public boolean equals(Object obj)

Сравнивает этот объект с указанным объектом. Результат равен true тогда и только тогда, когда аргумент не является null и является объектом LanguageRange, содержащим те же значения range и weight, что и этот объект.

Переопределяет:

equals в классе Object

Параметры:

obj — объект для сравнения

Возвращает:

true, если значения range и weight этого объекта совпадают со значениями объекта obj; в противном случае — false.

См. также:

toString

public String toString()

Возвращает информативное строковое представление этого объекта LanguageRange, состоящее из языкового диапазона и веса, если для диапазона задан вес и он меньше максимального.

Переопределяет:: toString в классе Object
Возвращает:: строковое представление этого объекта LanguageRange.

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Locale.LanguageRange.html