Класс ListFormat

java.lang.Object

java.text.Format

java.text.ListFormat

Все реализуемые интерфейсы:: Serializable, Cloneable

public final class ListFormat extends Format

ListFormat форматирует или анализирует список строк с учетом локали. Используйте ListFormat для создания списка строк, отображаемого конечным пользователям. Например, список из 3 дней недели, например «Monday», «Wednesday», «Friday», отображается как «Monday, Wednesday, and Friday» для включительного типа списка. Этот класс предоставляет функциональность, определенную в спецификации LDML Консорциума Unicode для шаблонов списков.

Предусмотрено три типа форматирования: STANDARD, OR и UNIT, определяющие знаки препинания между строками и, если применимо, соединительные слова. Кроме того, для каждого типа предусмотрено три стиля форматирования: FULL, SHORT и NARROW, которые подходят для строк с разной степенью сокращения. Ниже приведен пример форматирования списка строк "Foo", "Bar", "Baz" на американском английском с типом STANDARD и стилем FULL:

ListFormat.getInstance(Locale.US, ListFormat.Type.STANDARD, ListFormat.Style.FULL)
    .format(List.of("Foo", "Bar", "Baz"))

В результате получится объединенная строка списка «Foo, Bar, and Baz», как показано ниже:

Примеры форматирования
	FULL	SHORT	NARROW
STANDARD	Foo, Bar, and Baz	Foo, Bar, & Baz	Foo, Bar, Baz
OR	Foo, Bar, or Baz	Foo, Bar, or Baz	Foo, Bar, or Baz
UNIT	Foo, Bar, Baz	Foo, Bar, Baz	Foo Bar Baz

Примечание: эти примеры взяты из CLDR; другие поставщики данных локали могут выдавать иные результаты.

Кроме того, независимые от локали, типа и/или стиля экземпляры можно создать с помощью getInstance(String[]). Массив строк, передаваемый методу, задает шаблоны разделителей для начальной, промежуточной и конечной частей форматируемой строки, а также дополнительные специализированные шаблоны для двух или трех элементов. Дополнительные сведения см. в описании метода.

При разборе, если во входной строке обнаруживается неоднозначность, например последовательности-разделители, результат после форматирования с теми же параметрами может не совпасть с исходной строкой. Например, список строк из двух элементов «a, b,» и «c» будет отформатирован как «a, b, and c», но может быть разобран как три элемента: «a», «b», «c».

Требования к реализации:

Этот класс неизменяемый и потокобезопасный

С момента выпуска:

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

См. также:

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static enum`	`ListFormat.Style`	Стиль ListFormat — `FULL`, `SHORT` и `NARROW`.
`static enum`	`ListFormat.Type`	Тип ListFormat — `STANDARD`, `OR` и `UNIT`.

Вложенные классы и интерфейсы, объявленные в классе Format

Format.Field

Модификатор и тип	Класс	Описание
`static class`	`Format.Field`	Определяет константы, используемые в качестве ключей атрибутов в `AttributedCharacterIterator`, возвращаемом методом `Format.formatToCharacterIterator`, и в качестве идентификаторов полей в `FieldPosition`.

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

Модификатор и тип	Метод	Описание
`boolean`	`equals(Object obj)`	Сравнивает указанный объект с этим `ListFormat` на равенство.
`StringBuffer`	`format(Object obj, StringBuffer toAppendTo, FieldPosition pos)`	Форматирует объект и добавляет полученный текст в заданный буфер строк.
`String`	`format(List<String> input)`	Возвращает строку, состоящую из входных строк, объединенных с использованием шаблонов этого `ListFormat`.
`static Locale[]`	`getAvailableLocales()`	Возвращает список доступных локалей, поддерживающих ListFormat.
`static ListFormat`	`getInstance()`	Возвращает объект ListFormat для локали по умолчанию `FORMAT Locale`, типа `STANDARD` и стиля `FULL`.
`static ListFormat`	`getInstance(String[] patterns)`	Возвращает объект ListFormat для указанных шаблонов.
`static ListFormat`	`getInstance(Locale locale, ListFormat.Type type, ListFormat.Style style)`	Возвращает объект ListFormat для указанной `Locale`, `Type` и `Style`.
`Locale`	`getLocale()`	Возвращает `Locale` этого ListFormat.
`String[]`	`getPatterns()`	Возвращает шаблоны, используемые в этом ListFormat.
`List<String>`	`parse(String source)`	Возвращает разобранный список строк из строки `source`.
`Object`	`parseObject(String source, ParsePosition parsePos)`	Разбирает текст из строки и создает список строк.
`String`	`toString()`	Возвращает строку, идентифицирующую этот `ListFormat`, для отладки.

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

clone, format, formatToCharacterIterator, parseObject

Модификатор и тип	Метод	Описание
`Object`	`clone()`	Создает и возвращает копию этого объекта.
`final String`	`format(Object obj)`	Форматирует объект, создавая строку.
`AttributedCharacterIterator`	`formatToCharacterIterator(Object obj)`	Форматирует объект, создавая `AttributedCharacterIterator`.
`Object`	`parseObject(String source)`	Разбирает текст с начала заданной строки и создает объект.

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

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Модификатор и тип	Метод	Описание
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API подлежит удалению в будущей версии. Финализация устарела и подлежит удалению в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ожидать пробуждения, обычно в результате вызова notify или interrupt, либо до истечения заданного промежутка реального времени.

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

getAvailableLocales

public static Locale[] getAvailableLocales()

Возвращает список доступных локалей, поддерживающих ListFormat.

Возвращает:: доступные локали, поддерживающие ListFormat

getInstance

public static ListFormat getInstance()

Возвращает объект ListFormat для локали по умолчанию FORMAT Locale, типа STANDARD и стиля FULL.

Возвращает:: объект ListFormat для локали по умолчанию FORMAT Locale, типа STANDARD и стиля FULL

getInstance

public static ListFormat getInstance(Locale locale, ListFormat.Type type, ListFormat.Style style)

Возвращает объект ListFormat для указанной Locale, Type и Style.

Параметры:: locale — используемая Locale, не null; type — тип ListFormat. Одно из значений: STANDARD, OR или UNIT, не null; style — стиль ListFormat. Одно из значений: FULL, SHORT или NARROW, не null
Возвращает:: объект ListFormat для указанной Locale, Type и Style
Вызывает исключение:: NullPointerException — если какой-либо аргумент равен null

getInstance

public static ListFormat getInstance(String[] patterns)

Возвращает объект ListFormat для указанных шаблонов.

Эта фабрика возвращает экземпляр, основанный на массиве настроенных шаблонов, вместо того чтобы позволять среде выполнения выбирать подходящие шаблоны для Locale, Type или Style.

Массив шаблонов должен содержать пять шаблонов String, каждый из которых соответствует listPatternPart Unicode LDML, то есть шаблонам для «start», «middle», «end», двух и трех элементов в указанном порядке. Каждый шаблон содержит заполнители «{0}» и «{1}» (а для шаблона трех элементов — также «{2}»), которые при форматировании заменяются переданными входными строками. Если длина массива шаблонов не равна 5, выбрасывается IllegalArgumentException.

Сначала каждая строка шаблона разбирается следующим образом. Литералы в скобках, например «start_before», являются необязательными:

start := (start_before){0}start_between{1}
middle := {0}middle_between{1}
end := {0}end_between{1}(end_after)
two := (two_before){0}two_between{1}(two_after)
three := (three_before){0}three_between1{1}three_between2{2}(three_after)

Если шаблон для двух или трех элементов пуст, вместо него используется соответственно "(start_before){0}end_between{1}(end_after)", "(start_before){0}start_between{1}end_between{2}(end_after)". Если не удается разобрать какой-либо шаблон для начала, середины, конца, двух или трех элементов, выбрасывается IllegalArgumentException.

При форматировании входной список строк из n элементов подставляется в указанные выше заполнители в зависимости от количества элементов:

n = 1: {0}
n = 2: parsed pattern for "two"
n = 3: parsed pattern for "three"
n > 3: (start_before){0}start_between{1}middle_between{2} ... middle_between{m}end_between{n}(end_after)

В качестве примера в следующей таблице показан массив шаблонов, эквивалентный типу STANDARD и стилю FULL в американском английском:

Шаблоны Standard/Full для американского английского
Тип шаблона	Строка шаблона
start	"{0}, {1}"
middle	"{0}, {1}"
end	"{0}, and {1}"
two	"{0} and {1}"
three	""

Ниже приведены строки, полученные при форматировании с указанным выше массивом шаблонов.

Примеры форматирования
Входной список строк	Отформатированная строка
"Foo", "Bar", "Baz", "Qux"	"Foo, Bar, Baz, and Qux"
"Foo", "Bar", "Baz"	"Foo, Bar, and Baz"
"Foo", "Bar"	"Foo and Bar"
"Foo"	"Foo"

Параметры:: patterns — массив шаблонов, не null
Возвращает:: объект ListFormat для указанных шаблонов
Вызывает исключение:: IllegalArgumentException — если длина массива patterns не равна 5 или не удается разобрать какой-либо из шаблонов start, middle, end, two или three.; NullPointerException — если patterns равен null.

getLocale

public Locale getLocale()

Возвращает Locale этого ListFormat. locale задается методом getInstance(Locale, Type, Style) или getInstance(String[]).

Возвращает:: Locale этого ListFormat

getPatterns

public String[] getPatterns()

Возвращает шаблоны, используемые в этом ListFormat. patterns задаются методом getInstance(Locale, Type, Style) или getInstance(String[]).

Возвращает:: шаблоны, используемые в этом ListFormat

format

public String format(List<String> input)

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

Примечание к API:: Форматирование строки из чрезмерно длинного списка может превысить ограничения памяти или размера строки.
Параметры:: input — список входных строк для форматирования. В списке должен быть хотя бы один элемент String, иначе выбрасывается IllegalArgumentException.
Возвращает:: строку, состоящую из входных строк, объединенных с использованием шаблонов этого ListFormat
Вызывает исключение:: IllegalArgumentException — если длина input равна нулю.; NullPointerException — если input равен null.

format

public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos)

Форматирует объект и добавляет полученный текст в заданный буфер строк. Объект должен быть списком List или массивом объектов Object.

Определено в:: format в классе Format
Примечание к API:: Форматирование строки из чрезмерно длинного списка или массива может превысить ограничения памяти или размера строки.
Параметры:: obj — форматируемый объект. Должен быть списком List или массивом объектов Object.; toAppendTo — буфер, в который добавляется текст; pos — игнорируется. Не используется в ListFormat. Может быть null
Возвращает:: переданный буфер строк toAppendTo с добавленным отформатированным текстом
Вызывает исключение:: NullPointerException — если obj или toAppendTo равен null; IllegalArgumentException — если obj не является ни List, ни массивом Object, либо его длина равна нулю.

parse

public List<String> parse(String source) throws ParseException

Возвращает разобранный список строк из строки source. Обратите внимание, что format(List) и этот метод не гарантируют обратное преобразование, если входные строки содержат неоднозначные разделители. Например, список строк из двух элементов "a, b,", "c" будет отформатирован как "a, b, and c", но может быть разобран как три элемента "a", "b", "c".

Параметры:: source — разбираемая строка, не null.
Возвращает:: разобранный список строк из строки source
Вызывает исключение:: ParseException — если разбор не удался; NullPointerException — если исходное значение равно null

parseObject

public Object parseObject(String source, ParsePosition parsePos)

Разбирает текст из строки и создает список строк.

Метод пытается разобрать текст, начиная с индекса, заданного параметром parsePos. Если разбор выполнен успешно, индекс parsePos обновляется до позиции после последнего использованного символа (при разборе не обязательно используются все символы до конца строки), а разобранный объект возвращается. Обновленный parsePos можно использовать, чтобы указать начальную позицию при следующем вызове для разбора дополнительного текста. При возникновении ошибки индекс parsePos не изменяется, индекс ошибки parsePos устанавливается в позицию символа, на котором произошла ошибка, и возвращается null. Дополнительные сведения о разборе списков см. в методе parse(String).

Определено в:: parseObject в классе Format
Параметры:: source — строка, часть которой необходимо разобрать.; parsePos — объект ParsePosition с информацией об индексе и индексе ошибки, как описано выше.
Возвращает:: Список строк, разобранный из source. В случае ошибки возвращает null.
Вызывает исключение:: NullPointerException — если source или parsePos равен null.; IndexOutOfBoundsException — если начальный индекс, заданный параметром parsePos, выходит за пределы source.

equals

public boolean equals(Object obj)

Сравнивает указанный объект с этим ListFormat на равенство. Возвращает true, если указанный объект также является ListFormat и locale и patterns, возвращенные методами getLocale() и getPatterns() соответственно, равны.

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

equals в классе Object

Параметры:

obj — объект, с которым выполняется сравнение на равенство.

Возвращает:

true, если указанный объект равен этому ListFormat

См. также:

toString

public String toString()

Возвращает строку, идентифицирующую этот ListFormat, для отладки.

Переопределяет:: toString в классе Object
Возвращает:: строку, идентифицирующую этот ListFormat, для отладки

© 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.