Класс ChoiceFormat

java.text.ChoiceFormat

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

public class ChoiceFormat extends NumberFormat

ChoiceFormat — конкретный подкласс NumberFormat, позволяющий связать формат с диапазоном чисел. Обычно он используется в MessageFormat для обработки форм множественного числа. Выбор задаётся возрастающим списком чисел типа double, где каждый элемент определяет полуоткрытый интервал до следующего элемента:

X matches j if and only if limit[j] ≤ X < limit[j+1]

Если соответствие не найдено, используется первый или последний индекс — в зависимости от того, слишком мало или слишком велико число (X). Если массив пределов не упорядочен по возрастанию, результаты форматирования будут неверными. ChoiceFormat также принимает \u221E как эквивалент infinity(INF).

Примечание: ChoiceFormat отличается от других классов Format тем, что объект ChoiceFormat создаётся конструктором (а не фабричным методом в стиле getInstance). Фабричные методы не нужны, поскольку ChoiceFormat не требует сложной настройки для заданной локали. Фактически ChoiceFormat не реализует поведение, специфичное для локали.

Шаблоны

Шаблон ChoiceFormat имеет следующий синтаксис:

Pattern:

SubPattern *("|" SubPattern)

SubPattern:

Limit Relation Format
_{Примечание: предел-интервал каждого последующего SubPattern должен возрастать}

Limit:

Number / "∞" / "-∞"

Number:

["-"] *(Digit) 1*(Decimal / Digit) *(Digit) [Exponent]

Decimal:

1*(Digit ".") / 1*("." Digit)

Digit:

0 - 9

Exponent:

*(Digit) Digit ExponentSymbol Digit *(Digit)

ExponentSymbol:

"e" / "E"

Relation:

"#" / "<" / "≤"

Format:

Любые символы, кроме специального символа шаблона '|'

Примечание: отношение ≤ не эквивалентно <=

Чтобы использовать зарезервированный специальный символ шаблона внутри шаблона Format, его необходимо заключить в одинарные кавычки. Например, new ChoiceFormat("1#'|'foo'|'").format(1) возвращает "|foo|". Чтобы получить одинарную кавычку как обычный символ, используйте две одинарные кавычки подряд. Например, new ChoiceFormat("1# ''one'' ").format(1) возвращает " 'one' ".

Информация об использовании

ChoiceFormat можно создать, используя массив форматов и массив пределов либо строковый шаблон. При создании с массивами форматов и пределов их длины должны совпадать. Например:

limits = {1,2,3,4,5,6,7}
formats = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}
limits = {0, 1, ChoiceFormat.nextDouble(1)}
formats = {"no files", "one file", "many files"}
(nextDouble можно использовать, чтобы получить следующее большее число типа double и сформировать полуоткрытый интервал.)

Ниже приведён пример создания ChoiceFormat с массивами для форматирования и анализа значений:

double[] limits = {1,2,3,4,5,6,7};
String[] dayOfWeekNames = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"};
ChoiceFormat form = new ChoiceFormat(limits, dayOfWeekNames);
ParsePosition status = new ParsePosition(0);
for (double i = 0.0; i <= 8.0; ++i) {
    status.setIndex(0);
    System.out.println(i + " -> " + form.format(i) + " -> "
                             + form.parse(form.format(i),status));
}

Ниже приведён пример создания ChoiceFormat со строковым шаблоном:

ChoiceFormat fmt = new ChoiceFormat(
     "-1#is negative| 0#is zero or fraction | 1#is one |1.0<is 1+ |2#is two |2<is more than 2.");

System.out.println(fmt.format(Double.NEGATIVE_INFINITY)); // outputs "is negative"
System.out.println(fmt.format(-1.0)); // outputs "is negative"
System.out.println(fmt.format(0)); // outputs "is zero or fraction"
System.out.println(fmt.format(0.9)); // outputs "is zero or fraction"
System.out.println(fmt.format(1)); // outputs "is one"
System.out.println(fmt.format(1.5)); // outputs "is 1+"
System.out.println(fmt.format(2)); // outputs "is two"
System.out.println(fmt.format(2.1)); // outputs "is more than 2."
System.out.println(fmt.format(Double.NaN)); // outputs "is negative"
System.out.println(fmt.format(Double.POSITIVE_INFINITY)); // outputs "is more than 2."

Для более сложных шаблонов ChoiceFormat можно использовать вместе с MessageFormat, чтобы получать корректные формы единственного и множественного числа:

MessageFormat msgFmt = new MessageFormat("The disk \"{0}\" contains {1}.");
double[] fileLimits = {0,1,2};
String[] filePart = {"no files","one file","{1,number} files"};
ChoiceFormat fileChoices = new ChoiceFormat(fileLimits, filePart);
msgFmt.setFormatByArgumentIndex(1, fileChoices);
Object[] args = {"MyDisk", 1273};
System.out.println(msgFmt.format(args));

Результат для различных значений fileCount:

The disk "MyDisk" contains no files.
The disk "MyDisk" contains one file.
The disk "MyDisk" contains 1,273 files.

См. MessageFormat, где приведены замечания по использованию шаблонов MessageFormat внутри шаблона ChoiceFormat.

Синхронизация

Объекты ChoiceFormat не синхронизированы. Рекомендуется создавать отдельный экземпляр формата для каждого потока. Если несколько потоков одновременно обращаются к формату, синхронизацию необходимо обеспечить извне.

Примечание к API:

Подкласс может выполнять более последовательную проверку шаблонов, выбрасывая IllegalArgumentException во всех случаях некорректных данных. Поведение этой реализации при некорректных шаблонах описано в Implementation Note.

Этот класс наследует методы экземпляра от NumberFormat, но не использует их; подкласс может переопределить такие методы и выбрасывать UnsupportedOperationException.

Примечание по реализации:

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


NumberFormatException

выбрасывается, если limit не удаётся разобрать как числовое значение, а IllegalArgumentException выбрасывается, если отсутствует SubPattern или интервалы не расположены в порядке возрастания. Отбрасывание некорректной части может привести к созданию ChoiceFormat с пустыми limits и formats.

Начиная с версии:

1.1

См. также:

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

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

NumberFormat.Field, NumberFormat.Style

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

Поля, объявленные в классе NumberFormat

FRACTION_FIELD, INTEGER_FIELD

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

Конструктор	Описание
`ChoiceFormat(double[] limits, String[] formats)`	Создаёт объект с пределами и соответствующими форматами.
`ChoiceFormat(String newPattern)`	Создаёт ChoiceFormat с пределами и соответствующими форматами на основе шаблона.

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

Модификатор и тип	Метод	Описание
`void`	`applyPattern(String newPattern)`	Применяет указанный шаблон к этому объекту ChoiceFormat.
`Object`	`clone()`	Переопределяет Cloneable
`boolean`	`equals(Object obj)`	Сравнивает указанный объект с этим `ChoiceFormat` на равенство.
`StringBuffer`	`format(double number, StringBuffer toAppendTo, FieldPosition status)`	Возвращает шаблон с отформатированным числом double.
`StringBuffer`	`format(long number, StringBuffer toAppendTo, FieldPosition status)`	Специализация метода format.
`Object[]`	`getFormats()`	Возвращает форматы этого объекта ChoiceFormat.
`double[]`	`getLimits()`	Возвращает пределы этого объекта ChoiceFormat.
`int`	`hashCode()`	Возвращает хеш-код этого `ChoiceFormat`.
`boolean`	`isStrict()`	Возвращает `true`, если этот формат будет строго анализировать числа; в противном случае возвращает `false`.
`static final double`	`nextDouble(double d)`	Находит наименьшее число double, большее `d`.
`static double`	`nextDouble(double d, boolean positive)`	Находит наименьшее число double, большее `d` (если `positive` равно `true`), или наибольшее число double, меньшее `d` (если `positive` равно `false`).
`Number`	`parse(String text, ParsePosition status)`	Анализирует входной текст, начиная с индекса, заданного параметром `ParsePosition`, как `Double`.
`static final double`	`previousDouble(double d)`	Находит наибольшее число double, меньшее `d`.
`void`	`setChoices(double[] limits, String[] formats)`	Задаёт варианты, используемые при форматировании.
`void`	`setStrict(boolean strict)`	Изменяет степень строгости при анализе.
`String`	`toPattern()`	Возвращает шаблон `string`, представляющий `limits` и `formats` этого объекта ChoiceFormat.
`String`	`toString()`	Возвращает строку, идентифицирующую этот `ChoiceFormat`, для отладки.

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

format, format, format, getAvailableLocales, getCompactNumberInstance, getCompactNumberInstance, getCurrency, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getMaximumFractionDigits, getMaximumIntegerDigits, getMinimumFractionDigits, getMinimumIntegerDigits, getNumberInstance, getNumberInstance, getPercentInstance, getPercentInstance, getRoundingMode, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setCurrency, setGroupingUsed, setMaximumFractionDigits, setMaximumIntegerDigits, setMinimumFractionDigits, setMinimumIntegerDigits, setParseIntegerOnly, setRoundingMode

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

format, formatToCharacterIterator, parseObject

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

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

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

ChoiceFormat

public ChoiceFormat(String newPattern)

Создаёт ChoiceFormat с пределами и соответствующими форматами на основе шаблона. Синтаксис шаблона ChoiceFormat и замечания об ошибках описаны в разделе «Шаблоны». В отличие от ChoiceFormat(double[], String[]), этот конструктор выбрасывает IllegalArgumentException, если limits расположены не в порядке возрастания.

Параметры:

newPattern — новая строка шаблона

Выбрасывает:

NullPointerException — если newPattern равно null

IllegalArgumentException — если newPattern нарушает синтаксис шаблона

См. также:

ChoiceFormat

public ChoiceFormat(double[] limits, String[] formats)

Создаёт объект с пределами и соответствующими форматами.

Параметры:

limits — пределы в порядке возрастания

formats — соответствующие строки форматов

Выбрасывает:

NullPointerException — если limits или formats равно null

IllegalArgumentException — если длины limits и formats не совпадают

См. также:

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

applyPattern

public void applyPattern(String newPattern)

Применяет указанный шаблон к этому объекту ChoiceFormat. Синтаксис шаблона ChoiceFormat и замечания об ошибках описаны в разделе «Шаблоны». В отличие от setChoices(double[], String[]), этот метод выбрасывает IllegalArgumentException, если limits расположены не в порядке возрастания.

Параметры:

newPattern — строка шаблона

Выбрасывает:

NullPointerException — если newPattern равно null

IllegalArgumentException — если newPattern нарушает синтаксис шаблона

См. также:

toPattern

public String toPattern()

Возвращает шаблон string, представляющий limits и formats этого объекта ChoiceFormat. Не гарантируется, что возвращённый string совпадает с исходным string, переданным в applyPattern(String) или ChoiceFormat(String).

Возвращает:

шаблон string, представляющий limits и formats этого объекта ChoiceFormat

См. также:

setChoices

public void setChoices(double[] limits, String[] formats)

Задаёт варианты, используемые при форматировании.

Параметры:: limits — содержит верхнее значение, которое требуется анализировать с помощью этого формата; значения должны быть отсортированы по возрастанию. При форматировании X выбирается вариант i, для которого limit[i] ≤ X < limit[i+1]. Если массив пределов не упорядочен по возрастанию, результаты форматирования будут неверными.; formats — форматы, используемые для каждого предела.
Выбрасывает:: NullPointerException — если limits или formats равно null; IllegalArgumentException — если длины limits и formats не совпадают

getLimits

public double[] getLimits()

Возвращает пределы этого объекта ChoiceFormat.

Возвращает:: пределы этого объекта ChoiceFormat

getFormats

public Object[] getFormats()

Возвращает форматы этого объекта ChoiceFormat.

Возвращает:: форматы этого объекта ChoiceFormat

format

public StringBuffer format(long number, StringBuffer toAppendTo, FieldPosition status)

Специализация метода format. Фактически этот метод вызывает format(double, StringBuffer, FieldPosition). Таким образом, поддерживаемый диапазон значений long совпадает только с диапазоном, представимым типом double. На практике это никогда не будет ограничением.

Определено в:

format в классе NumberFormat

Параметры:

number — число для форматирования и подстановки.

toAppendTo — буфер, в который добавляется текст.

status — игнорируется; полезные сведения о состоянии не возвращаются.

Возвращает:

отформатированный StringBuffer

Выбрасывает:

ArrayIndexOutOfBoundsException — если limits или formats этого объекта ChoiceFormat пусты

NullPointerException — если toAppendTo равно null

См. также:

format

public StringBuffer format(double number, StringBuffer toAppendTo, FieldPosition status)

Возвращает шаблон с отформатированным числом double.

Определено в:

format в классе NumberFormat

Параметры:

number — число для форматирования и подстановки.

toAppendTo — буфер, в который добавляется текст.

status — игнорируется; полезные сведения о состоянии не возвращаются.

Возвращает:

отформатированный StringBuffer

Выбрасывает:

ArrayIndexOutOfBoundsException — если limits или formats этого объекта ChoiceFormat пусты

NullPointerException — если toAppendTo равно null

См. также:

parse

public Number parse(String text, ParsePosition status)

Анализирует входной текст, начиная с индекса, заданного параметром ParsePosition, как Double. Возвращаемое значение — это limit, соответствующее format, которое является самой длинной подстрокой входного текста. Сопоставление выполняется в порядке возрастания; если текст одинаково хорошо соответствует нескольким format, возвращается первое совпавшее limit. Если совпадений нет, возвращается Double.NaN.

Например:

var fmt = new ChoiceFormat("0#foo|1#bar|2#baz");
fmt.parse("baz", new ParsePosition(0)); // returns 2.0
fmt.parse("quux", new ParsePosition(0)); // returns NaN

Определено в:

parse в классе NumberFormat

Параметры:

text — исходный текст.

status — входной и выходной параметр. При входе поле status.index указывает на первый символ исходного текста, который необходимо анализировать. При выходе, если ошибки не произошло, status.index устанавливается в позицию первого необработанного символа исходного текста. При выходе, если произошла ошибка, status.index не изменяется, а status.errorIndex устанавливается в позицию первого символа, вызвавшего сбой анализа.

Возвращает:

Объект Number, представляющий limit, соответствующее разобранному format, или Double.NaN, если анализ завершился неудачно.

Выбрасывает:

NullPointerException — если status равно null или если text равно null и список строк выбора не пуст.

См. также:

isStrict

public boolean isStrict()

Описание скопировано из класса: NumberFormat

Возвращает true, если этот формат будет строго анализировать числа; в противном случае возвращает false.

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

isStrict в классе NumberFormat

Возвращает:

true, если этот формат будет строго анализировать числа; в противном случае возвращает false

Начиная с версии:

См. также:

setStrict

public void setStrict(boolean strict)

Описание скопировано из класса: NumberFormat

Изменяет степень строгости при анализе. Анализ может быть строгим или нестрогим; по умолчанию он нестрогий.

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

setStrict в классе NumberFormat

Параметры:

strict — true, если анализ должен выполняться строго; в противном случае — false

Начиная с версии:

См. также:

nextDouble

public static final double nextDouble(double d)

Находит наименьшее число double, большее d. Если NaN, возвращает то же значение.

Используется для создания полуоткрытых интервалов.

Примечание по реализации:

Эквивалентно вызову Math.nextUp(d)

Параметры:

d — опорное значение

Возвращает:

наименьшее значение double, большее d

См. также:

nextDouble

public static double nextDouble(double d, boolean positive)

Находит наименьшее число double, большее d (если positive равно true), или наибольшее число double, меньшее d (если positive равно false). Если NaN, возвращает то же значение.

Примечание по реализации:: Эквивалентно вызову positive ? Math.nextUp(d) : Math.nextDown(d)
Параметры:: d — опорное значение; positive — true, если требуется наименьшее число double; в противном случае — false
Возвращает:: наименьшее или наибольшее значение double

previousDouble

public static final double previousDouble(double d)

Находит наибольшее число double, меньшее d. Если NaN, возвращает то же значение.

Примечание по реализации:

Эквивалентно вызову Math.nextDown(d)

Параметры:

d — опорное значение

Возвращает:

наибольшее значение double, меньшее d

См. также:

clone

public Object clone()

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

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

clone в классе NumberFormat

Возвращает:

копию этого экземпляра.

См. также:

hashCode

public int hashCode()

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

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

hashCode в классе NumberFormat

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

Этот метод вычисляет значение хеш-кода на основе значений, возвращаемых методами getFormats() и getLimits().

Возвращает:

хеш-код этого ChoiceFormat

См. также:

toString

public String toString()

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

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

equals

public boolean equals(Object obj)

Сравнивает указанный объект с этим ChoiceFormat на равенство. Возвращает true, если объект также является ChoiceFormat и оба формата форматируют любое значение одинаково.

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

equals в классе NumberFormat

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

Этот метод проверяет равенство, определяя идентичность класса на основе getClass(), а не instanceof. Поэтому в методах equals подклассов экземпляр этого класса не должен считаться равным экземпляру подкласса.

Параметры:

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

Возвращает:

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

См. также:

© 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/ChoiceFormat.html