Класс DecimalFormat

java.text.DecimalFormat

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

public class DecimalFormat extends NumberFormat

DecimalFormat — конкретный подкласс NumberFormat, форматирующий десятичные числа с учетом локали. Он обладает рядом возможностей, позволяющих анализировать и форматировать числа для любой локали, включая поддержку западных, арабских и индийских цифр. Он также поддерживает различные виды чисел, включая целые числа (123), числа с фиксированной точкой (123.4), экспоненциальную запись (1.23E4), проценты (12%) и денежные суммы ($123).

Получение DecimalFormat

Чтобы получить стандартный десятичный формат для определенной локали, включая локаль по умолчанию, рекомендуется вызвать один из NumberFormat factory methods, например NumberFormat.getInstance(). В зависимости от установленной реализации поставщика локальных служб эти фабричные методы не всегда могут возвращать DecimalFormat. Поэтому для использования метода экземпляра, определенного в DecimalFormat, следует проверить тип NumberFormat, возвращенного фабричным методом, прежде чем преобразовывать его в DecimalFormat. Если установленная реализация службы с учетом локали не поддерживает указанную Locale, будет выполнен поиск по цепочке родительских локалей и использована поддерживаемая Locale.

Если фабричные методы не подходят, воспользуйтесь одним из конструкторов, например DecimalFormat(String pattern). Дополнительные сведения о параметре pattern см. в разделе Pattern.

Использование DecimalFormat

Ниже приведен пример форматирования и анализа:

NumberFormat nFmt = NumberFormat.getCurrencyInstance(Locale.US);
if (nFmt instanceof DecimalFormat dFmt) {
    // pattern match to DecimalFormat to use setPositiveSuffix(String)
    dFmt.setPositiveSuffix(" dollars");
    dFmt.format(100000); // returns "$100,000.00 dollars"
    dFmt.parse("$100,000.00 dollars"); // returns 100000
}

Форматирование и анализ

Округление

При форматировании DecimalFormat может изменять режим округления с помощью setRoundingMode(RoundingMode). По умолчанию используется RoundingMode.HALF_EVEN.

Цифры

При форматировании DecimalFormat использует в качестве цифр десять последовательных символов, начиная с локализованной цифры нуля, определенной в объекте DecimalFormatSymbols.

При анализе распознаются эти цифры, а также все десятичные цифры Юникода, определенные в Character.digit.

Ограничения на количество целых и дробных цифр

Ограничения на количество целых и дробных цифр задаются применением pattern или одним из соответствующих методов-сеттеров DecimalFormat, например setMinimumFractionDigits(int). Эти ограничения не влияют на поведение при анализе.

Специальные значения

Не число (NaN) форматируется как строка, обычно имеющая вид "NaN". Эта строка определяется методом DecimalFormatSymbols.getNaN(). Это единственное значение, к которому не добавляются префиксы и суффиксы.
Бесконечность форматируется как строка, обычно имеющая вид "∞" (U+221E), с добавлением положительных или отрицательных префиксов и суффиксов. Эта строка определяется методом DecimalFormatSymbols.getInfinity().
Отрицательный ноль ("-0") при анализе преобразуется в
- BigDecimal(0), если isParseBigDecimal() равно true
- Long(0), если isParseBigDecimal() равно false, а isParseIntegerOnly() равно true
- Double(-0.0), если и isParseBigDecimal(), и isParseIntegerOnly() равны false

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

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

Шаблон DecimalFormat

DecimalFormat состоит из шаблона и набора символов. Шаблон можно задать непосредственно с помощью applyPattern() или косвенно — с помощью различных методов API. Символы хранятся в объекте


DecimalFormatSymbols

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

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

Pattern:
        PositivePattern
        PositivePattern ; NegativePattern
PositivePattern:
        Prefix_opt Number Suffix_opt
NegativePattern:
        Prefix_opt Number Suffix_opt
Prefix:
        Any characters except the special pattern characters
Suffix:
        Any characters except the special pattern characters
Number:
        Integer Exponent_opt
        Integer . Fraction Exponent_opt
Integer:
        MinimumInteger
        #
        # Integer
        # , Integer
MinimumInteger:
        0
        0 MinimumInteger
        0 , MinimumInteger
Fraction:
        MinimumFraction_opt OptionalFraction_opt
MinimumFraction:
        0 MinimumFraction_opt
OptionalFraction:
        # OptionalFraction_opt
Exponent:
        E MinimumExponent
MinimumExponent:
        0 MinimumExponent_opt

Специальные символы шаблона

Специальные символы в таблице ниже интерпретируются синтаксически при использовании в шаблоне DecimalFormat. Если они должны появиться в префиксе или суффиксе как литералы, их необходимо заключать в кавычки, если не указано иное.

Символы в столбце Symbol используются в нелокализованных шаблонах. Соответствующие символы в столбце Localized Symbol используются в локализованных шаблонах, при этом символы в Symbol теряют синтаксическое значение. Исключение составляют знак валюты (U+00A4) и кавычка (U+0027), которые не локализуются.

При вызове applyPattern(String) следует использовать нелокализованные шаблоны. При вызове applyLocalizedPattern(String) следует использовать локализованные шаблоны.

Таблица с символами, расположением, локализованными символами и значениями.

Символ Локализованный символ Расположение Значение

0 DecimalFormatSymbols.getZeroDigit() Число Цифра

# DecimalFormatSymbols.getDigit() Число Цифра; ноль отображается как отсутствующий

. DecimalFormatSymbols.getDecimalSeparator() Число Десятичный разделитель или денежный десятичный разделитель

- (U+002D) DecimalFormatSymbols.getMinusSign() Число Знак минуса

, DecimalFormatSymbols.getGroupingSeparator() Число Разделитель групп разрядов или денежный разделитель групп разрядов

E DecimalFormatSymbols.getExponentSeparator() Число Разделяет мантиссу и показатель степени в экспоненциальной записи. Регистр этого значения учитывается. В префиксе или суффиксе его можно не заключать в кавычки.

; DecimalFormatSymbols.getPatternSeparator() Граница подшаблонов Разделяет положительный и отрицательный подшаблоны

% DecimalFormatSymbols.getPercent() Префикс или суффикс Умножить на 100 и отобразить в виде процента

‰ (U+2030) DecimalFormatSymbols.getPerMill() Префикс или суффикс Умножить на 1000 и отобразить в виде промилле

¤ (U+00A4) не применимо (не локализуется) Префикс или суффикс Знак валюты, заменяемый символом валюты. При удвоении заменяется международным символом валюты. Если присутствует в шаблоне, вместо десятичного разделителя и разделителя групп разрядов используются денежные разделители.

' (U+0027) не применимо (не локализуется) Префикс или суффикс Используется для заключения специальных символов в префиксе или суффиксе в кавычки. Например, "'#'#" форматирует 123 как "#123". Чтобы получить сам символ кавычки, укажите его дважды подряд: "# o''clock".

Таблица с символами, расположением, локализованными символами и значениями.
Символ	Локализованный символ	Расположение	Значение
`0`	`DecimalFormatSymbols.getZeroDigit()`	Число	Цифра
`#`	`DecimalFormatSymbols.getDigit()`	Число	Цифра; ноль отображается как отсутствующий
`.`	`DecimalFormatSymbols.getDecimalSeparator()`	Число	Десятичный разделитель или денежный десятичный разделитель
`- (U+002D)`	`DecimalFormatSymbols.getMinusSign()`	Число	Знак минуса
`,`	`DecimalFormatSymbols.getGroupingSeparator()`	Число	Разделитель групп разрядов или денежный разделитель групп разрядов
`E`	`DecimalFormatSymbols.getExponentSeparator()`	Число	Разделяет мантиссу и показатель степени в экспоненциальной записи. Регистр этого значения учитывается. В префиксе или суффиксе его можно не заключать в кавычки.
`;`	`DecimalFormatSymbols.getPatternSeparator()`	Граница подшаблонов	Разделяет положительный и отрицательный подшаблоны
`%`	`DecimalFormatSymbols.getPercent()`	Префикс или суффикс	Умножить на 100 и отобразить в виде процента
‰ (`U+2030`)	`DecimalFormatSymbols.getPerMill()`	Префикс или суффикс	Умножить на 1000 и отобразить в виде промилле
¤ (`U+00A4`)	не применимо (не локализуется)	Префикс или суффикс	Знак валюты, заменяемый символом валюты. При удвоении заменяется международным символом валюты. Если присутствует в шаблоне, вместо десятичного разделителя и разделителя групп разрядов используются денежные разделители.
`' (U+0027)`	не применимо (не локализуется)	Префикс или суффикс	Используется для заключения специальных символов в префиксе или суффиксе в кавычки. Например, `"'#'#"` форматирует 123 как `"#123"`. Чтобы получить сам символ кавычки, укажите его дважды подряд: `"# o''clock"`.

Определение максимального количества цифр

Для любого заданного шаблона DecimalFormat, если он не использует экспоненциальную запись, максимальное количество целых цифр не выводится из шаблона, а вместо этого устанавливается равным Integer.MAX_VALUE. Если же шаблон использует экспоненциальную запись, максимальное количество целых цифр выводится из шаблона. Это подробно описано в разделе Scientific Notation. Для ручной настройки максимального количества целых цифр можно использовать setMaximumIntegerDigits(int).

Отрицательные подшаблоны

Шаблон DecimalFormat содержит положительный и отрицательный подшаблоны, например "#,##0.00;(#,##0.00)". Каждый подшаблон включает префикс, числовую часть и суффикс. Отрицательный подшаблон является необязательным; если он отсутствует, в качестве отрицательного подшаблона используется положительный подшаблон с добавленным в начало знаком минуса '-' (U+002D HYPHEN-MINUS). То есть один "0.00" эквивалентен "0.00;-0.00". Если указан явный отрицательный подшаблон, он служит только для задания отрицательного префикса и суффикса; количество цифр, минимальное количество цифр и другие характеристики совпадают с положительным шаблоном. Это означает, что "#,##0.0#;(#)" работает точно так же, как "#,##0.0#;(#,##0.0#)".

Префиксы, суффиксы и различные символы, используемые для бесконечности, цифр, разделителей групп разрядов, десятичных разделителей и т. д., можно задать произвольными значениями, и при форматировании они будут отображаться корректно. Однако необходимо следить за тем, чтобы символы и строки не конфликтовали, иначе анализ будет ненадежным. Например, для различения положительных и отрицательных значений в DecimalFormat.parse() положительные и отрицательные префиксы или суффиксы должны различаться. (Если они совпадают, DecimalFormat будет работать так, как если бы отрицательный подшаблон не был задан.) Другой пример: десятичный разделитель и разделитель групп разрядов должны быть разными символами, иначе анализ будет невозможен.

Разделитель групп разрядов

Разделитель групп разрядов обычно используется для тысяч, но в некоторых локалях он разделяет десятки тысяч. Размер группы — это постоянное количество цифр между разделителями групп, например 3 для 100,000,000 или 4 для 1,0000,0000. Если шаблон содержит несколько разделителей групп, используется интервал между последним из них и концом целой части. Например, "#,##,###,####" == "######,####" == "##,####,####".

Экспоненциальная запись

Числа в экспоненциальной записи выражаются как произведение мантиссы и степени десяти; например, 1234 можно представить как 1.234 x 10^3. Мантисса часто находится в диапазоне 1.0 ≤ x < 10.0, но это необязательно. DecimalFormat можно настроить для форматирования и анализа чисел в экспоненциальной записи только с помощью шаблона; в настоящее время фабричного метода для создания формата экспоненциальной записи нет. В шаблоне символ экспоненты, за которым непосредственно следует один или несколько символов цифр, указывает на экспоненциальную запись. Пример: "0.###E0" форматирует число 1234 как "1.234E3".

Количество символов цифр после символа экспоненты задает минимальное количество цифр показателя степени. Максимальное количество не ограничено. Отрицательные показатели степени форматируются с локализованным знаком минуса, а не с префиксом и суффиксом из шаблона. Это позволяет использовать шаблоны, например "0.###E0 m/s".
Количество цифр максимальной целой части равно сумме символов '0' и '#' перед десятичной точкой. Количество цифр минимальной целой части равно сумме символов '0' перед десятичной точкой. Для цифр максимальной и минимальной дробной части действуют те же правила, но они применяются к цифрам после десятичной точки и перед экспонентой. Например, следующий шаблон: "#00.0####E0" задает минимальное количество целых цифр = 2("00") и максимальное количество целых цифр = 3("#00"). Минимальное количество дробных цифр равно 1("0"), а максимальное — 5("0####").
Минимальное и максимальное количество целых цифр интерпретируются совместно:
- Если максимальное количество целых цифр больше минимального и больше 1, показатель степени становится кратным максимальному количеству целых цифр, а минимальное количество целых цифр считается равным 1. Чаще всего это используется для создания инженерной записи, в которой показатель степени кратен трем, например "##0.#####E0". При использовании этого шаблона число 12345 форматируется как "12.345E3", а 123456 — как "123.456E3".
- В противном случае минимальное количество целых цифр достигается корректировкой показателя степени. Например, при форматировании 0.00123 с помощью "00.###E0" получается "12.3E-4".
Для заданного числа количество значащих цифр мантиссы можно вычислить следующим образом:
```
Mantissa Digits:
        min(max(Minimum Pattern Digits, Original Number Digits), Maximum Pattern Digits)
Minimum pattern Digits:
        Minimum Integer Digits + Minimum Fraction Digits
Maximum pattern Digits:
        Maximum Integer Digits + Maximum Fraction Digits
Original Number Digits:
        The amount of significant digits in the number to be formatted
```
В общем случае мантисса будет содержать не более суммы максимального количества целых и дробных цифр, если исходное число имеет достаточно значащих цифр. Однако если минимальное количество цифр в шаблоне превышает количество значащих цифр исходного числа, мантисса будет содержать количество значащих цифр, равное сумме минимального количества целых и дробных цифр. Количество значащих цифр не влияет на анализ.
Следует отметить, что лишние цифры целой части мантиссы будут перенесены в дробную часть — как для сохранения точности, так и для соблюдения общего минимального количества цифр.

Это поведение можно наблюдать в следующем примере:
```
    DecimalFormat df = new DecimalFormat("#000.000##E0");
    df.format(12); // returns "12.0000E0"
    df.format(123456789) // returns "1.23456789E8"
```
Экспоненциальные шаблоны не могут содержать разделители групп разрядов.

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

При форматировании Number, отличного от BigInteger и BigDecimal, в качестве верхнего предела для целых цифр используется 309, а для дробных цифр — 340. Это происходит даже в том случае, если один из методов-геттеров DecimalFormat, например getMinimumFractionDigits(), возвращает численно большее значение.

С версии:

1.1

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

См. также:

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

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

NumberFormat.Field, NumberFormat.Style

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

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

FRACTION_FIELD, INTEGER_FIELD

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

Конструктор	Описание
`DecimalFormat()`	Создает DecimalFormat, используя шаблон и символы по умолчанию для локали `FORMAT` по умолчанию.
`DecimalFormat(String pattern)`	Создает DecimalFormat, используя указанный шаблон и символы для локали `FORMAT` по умолчанию.
`DecimalFormat(String pattern, DecimalFormatSymbols symbols)`	Создает DecimalFormat, используя указанные шаблон и символы.

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

Модификатор и тип	Метод	Описание
`void`	`applyLocalizedPattern(String pattern)`	Применяет указанный шаблон к этому объекту Format.
`void`	`applyPattern(String pattern)`	Применяет указанный шаблон к этому объекту Format.
`Object`	`clone()`	Стандартное переопределение; семантика не изменяется.
`boolean`	`equals(Object obj)`	Сравнивает указанный объект с этим `DecimalFormat` на равенство.
`StringBuffer`	`format(double number, StringBuffer result, FieldPosition fieldPosition)`	Форматирует значение double в строку.
`StringBuffer`	`format(long number, StringBuffer result, FieldPosition fieldPosition)`	Форматирует значение long в строку.
`final StringBuffer`	`format(Object number, StringBuffer toAppendTo, FieldPosition pos)`	Форматирует число и добавляет полученный текст в указанный буфер строк.
`AttributedCharacterIterator`	`formatToCharacterIterator(Object obj)`	Форматирует объект, создавая `AttributedCharacterIterator`.
`Currency`	`getCurrency()`	Возвращает валюту, используемую этим десятичным форматом при форматировании денежных значений.
`DecimalFormatSymbols`	`getDecimalFormatSymbols()`	Возвращает копию символов десятичного формата, которые обычно не изменяются программистом или пользователем.
`int`	`getGroupingSize()`	Возвращает размер группы.
`int`	`getMaximumFractionDigits()`	Возвращает максимальное количество цифр дробной части числа, разрешенное при форматировании.
`int`	`getMaximumIntegerDigits()`	Возвращает максимальное количество цифр целой части числа, разрешенное при форматировании.
`int`	`getMinimumFractionDigits()`	Возвращает минимальное количество цифр дробной части числа, разрешенное при форматировании.
`int`	`getMinimumIntegerDigits()`	Возвращает минимальное количество цифр целой части числа, разрешенное при форматировании.
`int`	`getMultiplier()`	Возвращает множитель, используемый для процентов, промилле и подобных форматов.
`String`	`getNegativePrefix()`	Возвращает отрицательный префикс.
`String`	`getNegativeSuffix()`	Возвращает отрицательный суффикс.
`String`	`getPositivePrefix()`	Возвращает положительный префикс.
`String`	`getPositiveSuffix()`	Возвращает положительный суффикс.
`RoundingMode`	`getRoundingMode()`	Возвращает `RoundingMode`, используемый в этом DecimalFormat.
`int`	`hashCode()`	Возвращает хеш-код этого `DecimalFormat`.
`boolean`	`isDecimalSeparatorAlwaysShown()`	Позволяет получить поведение десятичного разделителя для целых чисел.
`boolean`	`isParseBigDecimal()`	Возвращает, возвращает ли метод `parse(java.lang.String, java.text.ParsePosition)` значение `BigDecimal`.
`boolean`	`isStrict()`	Возвращает `true`, если этот формат выполняет строгий анализ чисел; в противном случае — `false`.
`Number`	`parse(String text, ParsePosition pos)`	Анализирует текст от начала указанной строки и создает `Number`.
`void`	`setCurrency(Currency currency)`	Задает валюту, используемую этим числовым форматом при форматировании денежных значений.
`void`	`setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)`	Задает символы десятичного формата, которые обычно не изменяются программистом или пользователем.
`void`	`setDecimalSeparatorAlwaysShown(boolean newValue)`	Позволяет задать поведение десятичного разделителя для целых чисел.
`void`	`setGroupingSize(int newValue)`	Задает размер группы.
`void`	`setMaximumFractionDigits(int newValue)`	Задает максимальное количество цифр дробной части числа, разрешенное при форматировании.
`void`	`setMaximumIntegerDigits(int newValue)`	Задает максимальное количество цифр целой части числа, разрешенное при форматировании.
`void`	`setMinimumFractionDigits(int newValue)`	Задает минимальное количество цифр дробной части числа, разрешенное при форматировании.
`void`	`setMinimumIntegerDigits(int newValue)`	Задает минимальное количество цифр целой части числа, разрешенное при форматировании.
`void`	`setMultiplier(int newValue)`	Задает множитель, используемый для процентов, промилле и подобных форматов.
`void`	`setNegativePrefix(String newValue)`	Задает отрицательный префикс.
`void`	`setNegativeSuffix(String newValue)`	Задает отрицательный суффикс.
`void`	`setParseBigDecimal(boolean newValue)`	Задает, должен ли метод `parse(java.lang.String, java.text.ParsePosition)` возвращать значение `BigDecimal`.
`void`	`setPositivePrefix(String newValue)`	Задает положительный префикс.
`void`	`setPositiveSuffix(String newValue)`	Задает положительный суффикс.
`void`	`setRoundingMode(RoundingMode roundingMode)`	Задает `RoundingMode`, используемый в этом DecimalFormat.
`void`	`setStrict(boolean strict)`	Изменяет значение допуска при анализе.
`String`	`toLocalizedPattern()`	Создает локализованную строку шаблона, отражающую текущее состояние этого объекта Format.
`String`	`toPattern()`	Создает строку шаблона, отражающую текущее состояние этого объекта Format.
`String`	`toString()`	Возвращает строку, идентифицирующую этот `DecimalFormat`, для отладки.

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

format, format, getAvailableLocales, getCompactNumberInstance, getCompactNumberInstance, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getNumberInstance, getNumberInstance, getPercentInstance, getPercentInstance, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setGroupingUsed, setParseIntegerOnly

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

format, parseObject

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

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

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

DecimalFormat

public DecimalFormat()

Создает DecimalFormat, используя шаблон и символы по умолчанию для локали по умолчанию FORMAT. Это удобный способ получить DecimalFormat, если интернационализация не является главной задачей.

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

Чтобы получить стандартные форматы для заданной локали, используйте фабричные методы NumberFormat, такие как NumberFormat.getNumberInstance(Locale). Эти фабричные методы возвращают наиболее подходящий подкласс NumberFormat для заданной локали.

См. также:

DecimalFormat

public DecimalFormat(String pattern)

Создает DecimalFormat, используя заданный шаблон и символы для локали по умолчанию FORMAT. Это удобный способ получить DecimalFormat, если интернационализация не является главной задачей. Максимальное количество целых разрядов обычно не выводится из шаблона. Дополнительные сведения см. в примечании в разделе Patterns.

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

Параметры:

pattern — строка шаблона, не зависящая от локали.

Вызывает исключение:

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

IllegalArgumentException — если заданный шаблон недопустим.

См. также:

DecimalFormat

public DecimalFormat(String pattern, DecimalFormatSymbols symbols)

Создает DecimalFormat, используя заданный шаблон и символы. Используйте этот конструктор, если необходимо полностью настроить поведение формата. Максимальное количество целых разрядов обычно не выводится из шаблона. Дополнительные сведения см. в примечании в разделе Patterns.

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

Чтобы получить стандартные форматы для заданной локали, используйте фабричные методы NumberFormat, такие как NumberFormat.getInstance(Locale) или NumberFormat.getCurrencyInstance(Locale). Если нужно лишь немного изменить стандартный формат, можно изменить формат, возвращаемый фабричным методом NumberFormat.

Параметры:

pattern — строка шаблона, не зависящая от локали

symbols — набор используемых символов

Вызывает исключение:

NullPointerException — если какой-либо из заданных аргументов равен null

IllegalArgumentException — если заданный шаблон недопустим

См. также:

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

format

public final StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos)

Форматирует число и добавляет полученный текст в заданный строковый буфер. Число может быть экземпляром любого подкласса Number.

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

format в классе NumberFormat

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

Эта реализация использует максимально допустимую точность.

Параметры:

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

toAppendTo — StringBuffer, в который добавляется отформатированный текст

pos — отслеживает положение поля в возвращаемой строке. Например, при форматировании числа 1234567.89 в локали Locale.US, если заданный fieldPosition — это NumberFormat.INTEGER_FIELD, начальный и конечный индексы fieldPosition будут установлены в 0 и 9 соответственно для выходной строки 1,234,567.89.

Возвращает:

значение, переданное в toAppendTo

Вызывает исключение:

IllegalArgumentException — если number равно null или не является экземпляром Number.

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

ArithmeticException — если требуется округление, а для режима округления задано значение RoundingMode.UNNECESSARY

См. также:

format

public StringBuffer format(double number, StringBuffer result, FieldPosition fieldPosition)

Форматирует значение типа double и создает строку.

Указано в:

format в классе NumberFormat

Параметры:

number — значение типа double для форматирования

result — место, куда добавляется текст

fieldPosition — отслеживает положение поля в возвращаемой строке. Например, при форматировании числа 1234567.89 в локали Locale.US, если заданный fieldPosition — это NumberFormat.INTEGER_FIELD, начальный и конечный индексы fieldPosition будут установлены в 0 и 9 соответственно для выходной строки 1,234,567.89.

Возвращает:

строку с отформатированным числом

Вызывает исключение:

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

ArithmeticException — если требуется округление, а для режима округления задано значение RoundingMode.UNNECESSARY

См. также:

format

public StringBuffer format(long number, StringBuffer result, FieldPosition fieldPosition)

Форматирует значение типа long и создает строку.

Указано в:

format в классе NumberFormat

Параметры:

number — значение типа long для форматирования

result — место, куда добавляется текст

fieldPosition — отслеживает положение поля в возвращаемой строке. Например, при форматировании числа 123456789 в локали Locale.US, если заданный fieldPosition — это NumberFormat.INTEGER_FIELD, начальный и конечный индексы fieldPosition будут установлены в 0 и 11 соответственно для выходной строки 123,456,789.

Возвращает:

строку с отформатированным числом

Вызывает исключение:

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

ArithmeticException — если требуется округление, а для режима округления задано значение RoundingMode.UNNECESSARY

См. также:

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

Форматирует объект, создавая AttributedCharacterIterator. Возвращаемый AttributedCharacterIterator можно использовать для построения результирующей строки, а также для получения сведений о ней.

Каждый ключ атрибута AttributedCharacterIterator будет иметь тип NumberFormat.Field, а значение атрибута будет совпадать с его ключом.

Переопределяет:: formatToCharacterIterator в классе Format
Параметры:: obj — объект для форматирования
Возвращает:: AttributedCharacterIterator, описывающий отформатированное значение.
Вызывает исключение:: NullPointerException — если obj равно null.; IllegalArgumentException — если Format не может отформатировать заданный объект.; ArithmeticException — если требуется округление, а для режима округления задано значение RoundingMode.UNNECESSARY
Начиная с:: 1.4

parse

public Number parse(String text, ParsePosition pos)

Разбирает текст с начала заданной строки, чтобы получить Number.

Этот метод пытается разобрать текст, начиная с индекса, заданного в ParsePosition. Если разбор выполнен успешно, индекс ParsePosition обновляется до индекса после последнего использованного символа (при разборе не обязательно используются все символы до конца строки), а разобранное число возвращается. Обновленный ParsePosition можно использовать как начальную позицию для следующего вызова этого метода. Если возникает ошибка, индекс ParsePosition не изменяется, индекс ошибки в ParsePosition устанавливается в позицию символа, на котором произошла ошибка, и возвращается null.

Этот метод возвращает Long, если это возможно (например, значение входит в диапазон [Long.MIN_VALUE, Long.MAX_VALUE] и не содержит дробной части); в противном случае возвращается Double.

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

Разбор завершается неудачей в нестрогом режиме, если префикс и/или суффикс не пусты и не могут быть найдены из-за преждевременного завершения разбора либо если первый символ после префикса не удается разобрать.

Разбор завершается неудачей в строгом режиме, если в text выполняется одно из следующих условий:

Не найден префикс. Например, префикс формата валюты Locale.US: «$»
Не найден суффикс. Например, суффикс процентного формата Locale.US: «%»
Метод NumberFormat.isGroupingUsed() возвращает true, а группировка не соответствует значению getGroupingSize()
Метод NumberFormat.isGroupingUsed() возвращает false, а символ группировки присутствует
Метод NumberFormat.isGroupingUsed() возвращает true, а символ группировки находится после десятичного разделителя
Обнаружены другие символы, не являющиеся ожидаемыми символами или цифрами в числовой части

Возвращаемый подкласс зависит как от значения isParseBigDecimal(), так и от разбираемой строки.

Если isParseBigDecimal() имеет значение false (по умолчанию), большинство целых значений возвращаются как объекты Long независимо от способа их записи: "17" и "17.000" разбираются в Long(17). Значения, не помещающиеся в Long, возвращаются как Double. К ним относятся значения с дробной частью, бесконечные значения, NaN и значение -0.0. DecimalFormat не определяет, возвращать ли Double или Long, по наличию десятичного разделителя в исходной строке. Иначе целые числа, превышающие разрядность мантиссы типа double, например "-9,223,372,036,854,775,808.00", нельзя было бы разобрать точно.
Вызывающий код может использовать методы Number, такие как doubleValue, longValue и т. д., чтобы получить нужный тип.
Если isParseBigDecimal() имеет значение true, значения возвращаются как объекты BigDecimal. Это значения, создаваемые методом BigDecimal(String) для соответствующих строк в независимом от локали формате. Особые значения — отрицательная и положительная бесконечность и NaN — возвращаются как экземпляры Double, содержащие значения соответствующих констант Double.

DecimalFormat разбирает все символы Юникода, представляющие десятичные цифры согласно определению Character.digit(). Кроме того, DecimalFormat также распознает как цифры десять последовательных символов, начиная с локализованного нуля, определенного в объекте DecimalFormatSymbols.

Указано в:

parse в классе NumberFormat

Параметры:

text — строка для разбора

pos — объект ParsePosition с информацией об индексе и индексе ошибки, описанной выше.

Возвращает:

разобранное значение или null, если разбор завершился неудачей

Вызывает исключение:

NullPointerException — если text или pos равно null.

См. также:

getDecimalFormatSymbols

public DecimalFormatSymbols getDecimalFormatSymbols()

Возвращает копию символов десятичного формата, которые обычно не изменяются программистом или пользователем.

Возвращает:

копию требуемых DecimalFormatSymbols

См. также:

setDecimalFormatSymbols

public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)

Задает символы десятичного формата, которые обычно не изменяются программистом или пользователем.

Параметры:

newSymbols — требуемые DecimalFormatSymbols

См. также:

getPositivePrefix

public String getPositivePrefix()

Возвращает положительный префикс.

Примеры: +123, $123, sFr123

Возвращает:: положительный префикс

setPositivePrefix

public void setPositivePrefix(String newValue)

Задает положительный префикс.

Примеры: +123, $123, sFr123

Параметры:: newValue — новый положительный префикс. Не должен быть равен null.
Вызывает исключение:: NullPointerException — если newValue равно null

getNegativePrefix

public String getNegativePrefix()

Возвращает отрицательный префикс.

Примеры: -123, ($123) (с отрицательным суффиксом), sFr-123

Возвращает:: отрицательный префикс

setNegativePrefix

public void setNegativePrefix(String newValue)

Задает отрицательный префикс.

Примеры: -123, ($123) (с отрицательным суффиксом), sFr-123

Параметры:: newValue — новый отрицательный префикс. Не должен быть равен null.
Вызывает исключение:: NullPointerException — если newValue равно null

getPositiveSuffix

public String getPositiveSuffix()

Возвращает положительный суффикс.

Пример: 123%

Возвращает:: положительный суффикс

setPositiveSuffix

public void setPositiveSuffix(String newValue)

Задает положительный суффикс.

Пример: 123%

Параметры:: newValue — новый положительный суффикс. Не должен быть равен null.
Вызывает исключение:: NullPointerException — если newValue равно null

getNegativeSuffix

public String getNegativeSuffix()

Возвращает отрицательный суффикс.

Примеры: -123%, ($123) (с положительными суффиксами)

Возвращает:: отрицательный суффикс

setNegativeSuffix

public void setNegativeSuffix(String newValue)

Задает отрицательный суффикс.

Пример: 123%

Параметры:: newValue — новый отрицательный суффикс. Не должен быть равен null.
Вызывает исключение:: NullPointerException — если newValue равно null

getMultiplier

public int getMultiplier()

Возвращает множитель для процентов, промилле и аналогичных форматов.

Возвращает:

множитель

См. также:

setMultiplier

public void setMultiplier(int newValue)

Задает множитель для процентов, промилле и аналогичных форматов. Для процентного формата задайте множитель 100 и добавьте к суффиксам символ «%» (для арабского языка используйте арабский знак процента). Для формата промилле задайте множитель 1000 и добавьте к суффиксам символ «U+2030».

Пример: при множителе 100 значение 1.23 форматируется как «123», а строка «123» разбирается как 1.23. Если isParseIntegerOnly() возвращает true, строка «123» разбирается как 1.

Параметры:

newValue — новый множитель

См. также:

getGroupingSize

public int getGroupingSize()

Возвращает размер группировки. Размер группировки — это количество цифр между разделителями групп в целой части числа. Например, в числе «123,456.78» размер группировки равен 3. Нулевой размер группировки означает, что группировка не используется; форматирование при этом совпадает с результатом вызова setGroupingUsed(false).

Возвращает:

размер группировки

См. также:

setGroupingSize

public void setGroupingSize(int newValue)

Задает размер группировки. Размер группировки — это количество цифр между разделителями групп в целой части числа. Например, в числе «123,456.78» размер группировки равен 3. Нулевой размер группировки означает, что группировка не используется; форматирование при этом совпадает с результатом вызова setGroupingUsed(false).

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

Параметры:

newValue — новый размер группировки

Вызывает исключение:

IllegalArgumentException — если newValue отрицательно или больше Byte.MAX_VALUE

См. также:

isDecimalSeparatorAlwaysShown

public boolean isDecimalSeparatorAlwaysShown()

Позволяет получить сведения о поведении десятичного разделителя при форматировании целых чисел. (При наличии дробной части десятичный разделитель отображается всегда.)

Пример: десятичный разделитель ВКЛ.: 12345 → 12345.; ВЫКЛ.: 12345 → 12345

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

setDecimalSeparatorAlwaysShown

public void setDecimalSeparatorAlwaysShown(boolean newValue)

Позволяет задать поведение десятичного разделителя при форматировании целых чисел. (При наличии дробной части десятичный разделитель отображается всегда.)

Пример: десятичный разделитель ВКЛ.: 12345 → 12345.; ВЫКЛ.: 12345 → 12345

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

isStrict

public boolean isStrict()

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

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

isStrict в классе NumberFormat

Возвращает:

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

Начиная с:

См. также:

setStrict

public void setStrict(boolean strict)

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

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

setStrict в классе NumberFormat

Параметры:

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

Начиная с:

См. также:

isParseBigDecimal

public boolean isParseBigDecimal()

Возвращает сведения о том, возвращает ли метод parse(java.lang.String, java.text.ParsePosition) значение BigDecimal. Значение по умолчанию — false.

Возвращает:

true, если метод разбора возвращает BigDecimal; в противном случае — false

Начиная с:

1.5

См. также:

setParseBigDecimal

public void setParseBigDecimal(boolean newValue)

Задает, возвращает ли метод parse(java.lang.String, java.text.ParsePosition) значение BigDecimal.

Параметры:

newValue — true, если метод разбора возвращает BigDecimal; в противном случае — false

Начиная с:

1.5

См. также:

clone

public Object clone()

Стандартное переопределение; семантика не изменена.

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

clone в классе NumberFormat

Возвращает:

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

См. также:

equals

public boolean equals(Object obj)

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

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

equals в классе NumberFormat

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

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

Параметры:

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

Возвращает:

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

См. также:

hashCode

public int hashCode()

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

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

hashCode в классе NumberFormat

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

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

Возвращает:

хэш-код этого DecimalFormat

См. также:

toString

public String toString()

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

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

toPattern

public String toPattern()

Создает строку шаблона, представляющую текущее состояние этого объекта Format.

Возвращает:

строку шаблона

См. также:

toLocalizedPattern

public String toLocalizedPattern()

Создаёт локализованную строку шаблона, представляющую текущее состояние этого объекта Format.

Возвращает:

локализованную строку шаблона

См. также:

applyPattern

public void applyPattern(String pattern)

Применяет заданный шаблон к этому объекту Format. Шаблон представляет собой краткую спецификацию различных свойств форматирования. Эти свойства также можно изменять по отдельности с помощью различных методов-сеттеров.

Максимальное количество целых цифр обычно не определяется шаблоном. Подробнее см. примечание в разделе Patterns. Для отрицательных чисел используйте второй шаблон, отделив его точкой с запятой

Пример "#,#00.0#" → 1,234.56

Это означает минимум 2 целые цифры, 1 цифру дробной части и максимум 2 цифры дробной части.

Пример: "#,#00.0#;(#,#00.0#)" для отрицательных чисел в скобках.

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

Параметры:: pattern — новый шаблон
Выбрасывает:: NullPointerException — если pattern равно null; IllegalArgumentException — если заданный шаблон недопустим.

applyLocalizedPattern

public void applyLocalizedPattern(String pattern)

Применяет заданный шаблон к этому объекту Format. Предполагается, что шаблон задан в локализованной записи. Шаблон представляет собой краткую спецификацию различных свойств форматирования. Эти свойства также можно изменять по отдельности с помощью различных методов-сеттеров.

Пример "#,#00.0#" → 1,234.56

Это означает минимум 2 целые цифры, 1 цифру дробной части и максимум 2 цифры дробной части.

Пример: "#,#00.0#;(#,#00.0#)" для отрицательных чисел в скобках.

Параметры:: pattern — новый шаблон
Выбрасывает:: NullPointerException — если pattern равно null; IllegalArgumentException — если заданный шаблон недопустим.

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int newValue)

Задаёт максимальное количество цифр, допустимое в целой части числа при форматировании. maximumIntegerDigits должно быть ≥ minimumIntegerDigits. Если новое значение


maximumIntegerDigits

меньше текущего значения minimumIntegerDigits, то minimumIntegerDigits также будет установлено в новое значение. Отрицательные входные значения заменяются на 0.

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

setMaximumIntegerDigits в классе NumberFormat

Параметры:

newValue — максимальное количество отображаемых целых цифр.

См. также:

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int newValue)

Задаёт минимальное количество цифр, допустимое в целой части числа при форматировании. minimumIntegerDigits должно быть ≤ maximumIntegerDigits. Если новое значение minimumIntegerDigits превышает текущее значение maximumIntegerDigits, то


maximumIntegerDigits

также будет установлено в новое значение. Отрицательные входные значения заменяются на 0.

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

setMinimumIntegerDigits в классе NumberFormat

Параметры:

newValue — минимальное количество отображаемых целых цифр.

См. также:

setMaximumFractionDigits

public void setMaximumFractionDigits(int newValue)

Задаёт максимальное количество цифр, допустимое в дробной части числа при форматировании. maximumFractionDigits должно быть ≥ minimumFractionDigits. Если новое значение maximumFractionDigits меньше текущего значения minimumFractionDigits, то minimumFractionDigits также будет установлено в новое значение. Отрицательные входные значения заменяются на 0.

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

setMaximumFractionDigits в классе NumberFormat

Параметры:

newValue — максимальное количество отображаемых дробных цифр.

См. также:

setMinimumFractionDigits

public void setMinimumFractionDigits(int newValue)

Задаёт минимальное количество цифр, допустимое в дробной части числа при форматировании. minimumFractionDigits должно быть ≤ maximumFractionDigits. Если новое значение


minimumFractionDigits

превышает текущее значение


maximumFractionDigits

, то maximumFractionDigits также будет установлено в новое значение. Отрицательные входные значения заменяются на 0.

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

setMinimumFractionDigits в классе NumberFormat

Параметры:

newValue — минимальное количество отображаемых дробных цифр.

См. также:

getMaximumIntegerDigits

public int getMaximumIntegerDigits()

Возвращает максимальное количество цифр, допустимое в целой части числа при форматировании.

В отличие от других ограничений на количество цифр, maximumIntegerDigits не обновляется, если DecimalFormats создаётся или обновляется с помощью строкового шаблона.

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

getMaximumIntegerDigits в классе NumberFormat

Возвращает:

максимальное количество цифр

См. также:

getMinimumIntegerDigits

public int getMinimumIntegerDigits()

Возвращает минимальное количество цифр, допустимое в целой части числа при форматировании.

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

getMinimumIntegerDigits в классе NumberFormat

Возвращает:

минимальное количество цифр

См. также:

getMaximumFractionDigits

public int getMaximumFractionDigits()

Возвращает максимальное количество цифр, допустимое в дробной части числа при форматировании.

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

getMaximumFractionDigits в классе NumberFormat

Возвращает:

максимальное количество цифр.

См. также:

getMinimumFractionDigits

public int getMinimumFractionDigits()

Возвращает минимальное количество цифр, допустимое в дробной части числа при форматировании.

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

getMinimumFractionDigits в классе NumberFormat

Возвращает:

минимальное количество цифр

См. также:

getCurrency

public Currency getCurrency()

Получает валюту, используемую этим десятичным форматом при форматировании денежных значений. Валюта получается вызовом DecimalFormatSymbols.getCurrency у символов этого числового формата.

Переопределяет:: getCurrency в классе NumberFormat
Возвращает:: валюту, используемую этим десятичным форматом, или null
Начиная с версии:: 1.4

setCurrency

public void setCurrency(Currency currency)

Задаёт валюту, используемую этим числовым форматом при форматировании денежных значений. Это не изменяет минимальное или максимальное количество цифр дробной части, используемое числовым форматом. Валюта задаётся вызовом DecimalFormatSymbols.setCurrency у символов этого числового формата.

Переопределяет:: setCurrency в классе NumberFormat
Параметры:: currency — новая валюта, используемая этим десятичным форматом
Выбрасывает:: NullPointerException — если currency равно null
Начиная с версии:: 1.4

getRoundingMode

public RoundingMode getRoundingMode()

Получает RoundingMode, используемый в этом DecimalFormat.

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

getRoundingMode в классе NumberFormat

Возвращает:

RoundingMode, используемый этим DecimalFormat.

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

1.6

См. также:

setRoundingMode

public void setRoundingMode(RoundingMode roundingMode)

Задаёт RoundingMode, используемый в этом DecimalFormat.

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

setRoundingMode в классе NumberFormat

Параметры:

roundingMode — RoundingMode, который будет использоваться

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

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

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

1.6

См. также:

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