Класс ListFormat

java.lang.Object

java.text.Format

java.text.ListFormat

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

public final class ListFormat extends Format

ListFormat форматирует или разбирает список строк в зависимости от локали. Используйте ListFormat для построения списка строк, отображаемых для конечных пользователей. Например, отобразить список из 3 дней недели, например, "Понедельник", "Среда", "Пятница" как "Понедельник, среда и пятница" в формате включительно. Этот класс предоставляет функциональность, определённую в спецификации LDML Консорциума Юникода для шаблонов списков.

Предоставляются три типа форматирования: 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 и Baz", как показано ниже:

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

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

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

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

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

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

С:

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

См. также:

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

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

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

Format.Field

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

Модификатор и тип	Метод	Описание
`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`, для отладки.

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

clone, format, formatToCharacterIterator, parseObject

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

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

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

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.

Массив шаблонов должен содержать пять строковых шаблонов, каждый из которых соответствует шаблону LDML Unicode, т.е., «начало», «середина», «конец», шаблоны для двух элементов и трех элементов в этом порядке. Каждый шаблон содержит заглушки "{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 стилю на английском языке США:

Стандартные/Полные шаблоны на английском языке США
Вид шаблона	Строка шаблона
начало	"{0}, {1}"
середина	"{0}, {1}"
конец	"{0}, и {1}"
два	"{0} и {1}"
три	""

Вот форматированные строки с указанным массивом шаблонов.

Примеры форматирования
Список входных строк	Отформатированная строка
"Foo", "Bar", "Baz", "Qux"	"Foo, Bar, Baz, и Qux"
"Foo", "Bar", "Baz"	"Foo, Bar, и Baz"
"Foo", "Bar"	"Foo и 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 - список входных строк для форматирования. В этом списке должно быть как минимум одна строка, в противном случае генерируется IllegalArgumentException.
Возвращает:: строку, состоящую из входных строк, соединенных шаблонами этого ListFormat
Исключения:: IllegalArgumentException - если длина input равна нулю.; NullPointerException - если input равен null.

format

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

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

Задано в:: format в классе Format
Примечание API:: Форматирование строки из чрезмерно длинного списка или массива может превысить лимит памяти или размера строки.
Параметры:: obj - объект для форматирования. Должен быть списком или массивом объектов.; toAppendTo - место, куда должен быть добавлен текст; pos - Игнорируется. Не используется в ListFormat. Может быть null
Возвращает:: переданный буфер строк, с добавленным отформатированным текстом
Исключения:: 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) для получения дополнительной информации о разборе списков.

Specified by:: parseObject в классе Format
Parameters:: source - Строка, часть которой должна быть обработана.; parsePos - Объект ParsePosition с информацией об индексе и индексе ошибки, как описано выше.
Returns:: Список строк, разобранных из source. В случае ошибки возвращает null.
Throws:: NullPointerException - если source или parsePos равны null.; IndexOutOfBoundsException - если начальный индекс, заданный parsePos, находится вне source.

equals

public boolean equals(Object obj)

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

Overrides:

equals в классе Object

Parameters:

obj - объект, подлежащий сравнению на равенство.

Returns:

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

See Also:

toString

public String toString()

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

Overrides:: toString в классе Object
Returns:: строку, идентифицирующую этот 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.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/text/ListFormat.html