Класс 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[]). Массив String, передаваемый методу, задает разделительные шаблоны для начальной, средней и конечной частей форматируемой строки, а также необязательные специальные шаблоны для двух или трех элементов. Подробнее см. описание метода.

При разборе неоднозначной входной строки, например содержащей разделительные последовательности, результат при форматировании с теми же настройками может отличаться от исходной строки. Например, список из двух элементов 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

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

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

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.

Массив шаблонов должен содержать пять шаблонов String, каждый из которых соответствует шаблонам Unicode LDML listPatternPart, то есть шаблонам «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 для американского английского:

Стандартные шаблоны полного формата для американского английского
Тип шаблона	Строка шаблона
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)

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

Определено в:: format в классе Format
Примечание API:: Форматирование строки из слишком длинного списка или массива может превысить доступный объем памяти или максимальный размер строки.
Параметры:: obj — форматируемый объект. Должен быть списком или массивом 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) и этот метод не гарантируют обратное преобразование, если входные строки содержат неоднозначные разделители. Например, список String из двух элементов "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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/text/ListFormat.html