Класс ChoiceFormat

java.text.ChoiceFormat

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

public class ChoiceFormat extends NumberFormat

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

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

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

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

Шаблоны

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

Шаблон:

Подшаблон *("|" Подшаблон)

Подшаблон:

Граница Отношение Формат
_{Примечание: Каждый дополнительный подшаблон должен иметь интервал Граница-Отношение по возрастанию}

Граница:

Число / "∞" / "-∞"

Число:

["-"] *(Цифра) 1*(Десятичная / Цифра) *(Цифра) [Показатель]

Десятичная:

1*(Цифра ".") / 1*("." Цифра)

Цифра:

0 - 9

Показатель:

*(Цифра) Цифра СимволПоказателя Цифра *(Цифра)

СимволПоказателя:

"e" / "E"

Отношение:

"#" / "<" / "≤"

Формат:

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

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

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

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

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

limits = {1,2,3,4,5,6,7}
formats = {"Вс","Пн","Вт","Ср","Чт","Пт","Сб"}
limits = {0, 1, ChoiceFormat.nextDouble(1)}
formats = {"нет файлов", "один файл", "много файлов"}
(nextDouble может использоваться для получения следующего большего числа с двойной точностью, чтобы создать полуоткрытый интервал.)

Ниже приведен пример создания 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.

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

Форматы Choice не синхронизированы. Рекомендуется создавать отдельные экземпляры формата для каждого потока. Если к формату одновременно обращаются несколько потоков, он должен быть внешне синхронизирован.

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

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

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

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

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


 NumberFormatException

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

С тех пор:

1.1

См. также:

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

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

NumberFormat.Field, NumberFormat.Style

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

Поля, объявленные в классе java.text.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)`	Возвращает шаблон с отформатированным числом с плавающей точкой.
`StringBuffer`	`format(long number, StringBuffer toAppendTo, FieldPosition status)`	Специализация форматирования.
`Object[]`	`getFormats()`	Возвращает форматы этого ChoiceFormat.
`double[]`	`getLimits()`	Возвращает границы этого ChoiceFormat.
`int`	`hashCode()`	Возвращает хэш-код для этого `ChoiceFormat`.
`boolean`	`isStrict()`	Возвращает `true`, если этот формат будет анализировать числа строго; `false` в противном случае.
`static final double`	`nextDouble(double d)`	Поиск наименьшего числа с плавающей точкой, большего чем `d`.
`static double`	`nextDouble(double d, boolean positive)`	Поиск наименьшего числа с плавающей точкой, большего чем `d` (если `positive` равно `true`), или наибольшего числа с плавающей точкой, меньшего чем `d` (если `positive` равно `false`).
`Number`	`parse(String text, ParsePosition status)`	Разбор числа из входного текста.
`static final double`	`previousDouble(double d)`	Поиск наибольшего числа с плавающей точкой, меньшего чем `d`.
`void`	`setChoices(double[] limits, String[] formats)`	Установить используемые варианты для форматирования.
`void`	`setStrict(boolean strict)`	Изменение значения толерантности для разбора.
`String`	`toPattern()`	Возвращает шаблон `string`, который представляет `limits` и `formats` этого объекта ChoiceFormat.
`String`	`toString()`	Возвращает строку, идентифицирующую этот `ChoiceFormat`, для отладки.

Методы, объявленные в классе java.text.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

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

format, formatToCharacterIterator, parseObject

Методы, объявленные в классе java.lang.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, который представляет пределы и форматы этого объекта ChoiceFormat. Возвращаемый шаблон не гарантируется как идентичный входному string, переданному в applyPattern(String) или ChoiceFormat(String).

Возвращает:

шаблон string, который представляет пределы и форматы этого объекта ChoiceFormat

См. также:

setChoices

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

Устанавливает используемые значения для форматирования.

Параметры:: limits - содержит верхнее значение, которое нужно разобрать с этим форматом и должно быть отсортировано по возрастанию. При форматировании X, выбор будет i, где limit[i] ≤ X < limit[i+1]. Если массив limit не отсортирован по возрастанию, результаты форматирования будут некорректными.; 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(double, StringBuffer, FieldPosition). Таким образом, диапазон длин целых чисел, которые поддерживаются, равен диапазону, который может быть сохранён типом 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)

Разбирает число из входного текста.

Задано в:

parse в классе NumberFormat

Параметры:

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

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

Возвращает:

Число, представляющее значение разобранного числа.

Исключения:

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

См. также:

isStrict

public boolean isStrict()

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

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

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

isStrict в классе NumberFormat

Возвращает:

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

С:

См. также:

setStrict

public void setStrict(boolean strict)

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

Изменение значения leniency для разбора. Разбор может быть строгим или мягким, по умолчанию он мягкий.

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

setStrict в классе NumberFormat

Параметры:

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

С:

См. также:

nextDouble

public static final double nextDouble(double d)

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

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

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

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

Параметры:

d - значение ссылки

Возвращает:

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

См. также:

END_OF_DOCUMENT_MARKER

nextDouble

public static double nextDouble(double d, boolean positive)

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

Implementation Note:: Это эквивалентно вызову positive ? Math.nextUp(d) : Math.nextDown(d)
Parameters:: d - значение для сравнения; positive - true, если нужно наименьшее double; false в противном случае
Returns:: наименьшее или наибольшее значение double

previousDouble

public static final double previousDouble(double d)

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

Implementation Note:

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

Parameters:

d - значение для сравнения

Returns:

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

See Also:

clone

public Object clone()

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

Overrides:

clone в классе NumberFormat

Returns:

клонированный экземпляр.

See Also:

hashCode

public int hashCode()

Возвращает код хэширования для этого ChoiceFormat.

Overrides:

hashCode в классе NumberFormat

Implementation Requirements:

Этот метод рассчитывает значение хэша, используя значения, возвращаемые getFormats() и getLimits().

Returns:

код хэширования для этого ChoiceFormat

See Also:

toString

public String toString()

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

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

equals

public boolean equals(Object obj)

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

Overrides:

equals в классе NumberFormat

Implementation Requirements:

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

Parameters:

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

Returns:

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

See Also:

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