Класс DecimalFormat

public class DecimalFormat extends NumberFormat

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
}

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

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

Особые значения

• Не число (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:
         Prefixopt Number Suffixopt
 NegativePattern:
         Prefixopt Number Suffixopt
 Prefix:
         Any characters except the special pattern characters
 Suffix:
         Any characters except the special pattern characters
 Number:
         Integer Exponentopt
         Integer . Fraction Exponentopt
 Integer:
         MinimumInteger
         #
         # Integer
         # , Integer
 MinimumInteger:
         0
         0 MinimumInteger
         0 , MinimumInteger
 Fraction:
         MinimumFractionopt OptionalFractionopt
 MinimumFraction:
         0 MinimumFractionopt
 OptionalFraction:
         # OptionalFractionopt
 Exponent:
         E MinimumExponent
 MinimumExponent:
         0 MinimumExponentopt
 

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

Специальные символы в таблице ниже интерпретируются синтаксически при использовании в шаблоне 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)	n/a (не локализован)	Префикс или суффикс	Знак валюты, заменяется символом валюты. При удвоении заменяется международным символом валюты. При наличии в шаблоне используются денежные разделители десятичных/группировки вместо десятичных/разделителей группировки.
' (U+0027)	n/a (не локализован)	Префикс или суффикс	Используется для заключения в кавычки специальных символов в префиксе или суффиксе, например, "'#'#" форматирует 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 × 10³. Мантисса часто находится в диапазоне 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"
  

• Шаблоны экспоненциальной записи не могут содержать разделителей группировки.

С момента:

1.1

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

• Язык разметки данных локали Unicode (LDML)

См. также:

• Java Tutorial
• NumberFormat
• DecimalFormatSymbols
• ParsePosition
• Locale
• Сериализованная форма