Класс DecimalFormat

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

Чтобы получить NumberFormat для определённого региона, включая системный регион по умолчанию, вызовите один из методов-фабрик NumberFormat, таких как getInstance(). В общем случае не вызывайте конструкторы DecimalFormat напрямую, так как методы-фабрики NumberFormat могут возвращать подклассы, отличные от DecimalFormat. Если вам необходимо настроить объект форматирования, сделайте это так:

NumberFormat numFormat = NumberFormat.getInstance(loc);
if (numFormat instanceof DecimalFormat decFormat) {
    decFormat.setDecimalSeparatorAlwaysShown(true);
}

Формат DecimalFormat включает в себя шаблон и набор символов. Шаблон может быть установлен напрямую с помощью applyPattern(), или косвенно с помощью методов API. Символы хранятся в объекте DecimalFormatSymbols. При использовании методов-фабрик NumberFormat, шаблон и символы считываются из локализованных ResourceBundle.

Шаблоны

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

 Pattern:
         PositivePattern
         PositivePattern ; NegativePattern
 PositivePattern:
         Prefixopt Number Suffixopt
 NegativePattern:
         Prefixopt Number Suffixopt
 Prefix:
         any Unicode characters except U+FFFE, U+FFFF, and special characters
 Suffix:
         any Unicode characters except U+FFFE, U+FFFF, and special 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 содержит положительный и отрицательный подшаблон, например, "#,##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. Если вы предоставите шаблон с несколькими разделителями групп, интервал между последним и концом целой части — это тот, который используется. Таким образом, "#,##,###,####" == "######,####" == "##,####,####".

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

Многие символы в шаблоне интерпретируются буквально; они сопоставляются во время парсинга и выводятся без изменений при форматировании. Специальные символы, с другой стороны, представляют собой другие символы, строки или классы символов. Они должны быть заключены в кавычки, если они должны появиться в префиксе или суффиксе как литералы.

Перечисленные здесь символы используются в нелокализованных шаблонах. Локализованные шаблоны вместо этого используют соответствующие символы из объекта DecimalFormatSymbols форматировщика, и эти символы теряют свой специальный статус. Два исключения — знак валюты и кавычка, которые не локализованы.

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

Символ	Расположение	Локализован?	Значение
0	Число	Да	Цифра
#	Число	Да	Цифра, ноль отображается как отсутствие
.	Число	Да	Десятичный разделитель или денежный десятичный разделитель
-	Число	Да	Знак минус
,	Число	Да	Разделитель групп или денежный разделитель групп
E	Число	Да	Разделяет мантиссу и показатель степени в научной записи. Не нужно заключать в кавычки в префиксе или суффиксе.
;	Граница подшаблона	Да	Разделяет положительные и отрицательные подшаблоны
%	Префикс или суффикс	Да	Умножить на 100 и отобразить в виде процента
U+2030	Префикс или суффикс	Да	Умножить на 1000 и отобразить как промилле
¤ (U+00A4)	Префикс или суффикс	Нет	Знак валюты, заменяется символом валюты. Если удвоен, заменяется международным символом валюты. Если присутствует в шаблоне, денежные десятичные/разделители групп используются вместо десятичных/разделителей групп.
'	Префикс или суффикс	Нет	Используется для заключения в кавычки специальных символов в префиксе или суффиксе, например, "'#'#" форматирует 123 в "#123". Чтобы создать саму одинарную кавычку, используйте две подряд: "# o''clock".

Научная запись

Числа в научной записи выражаются как произведение мантиссы и степени десятки, например, 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"
  

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

Округление

DecimalFormat предоставляет режимы округления, определённые в RoundingMode, для форматирования. По умолчанию используется RoundingMode.HALF_EVEN.

Цифры

При форматировании DecimalFormat использует десять последовательных символов, начиная с локализованной цифры ноль, определённой в объекте DecimalFormatSymbols как цифры. При парсинге распознаются эти цифры, а также все Unicode-десятичные цифры, как определено в Character.digit.

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

Не число (NaN) форматируется как строка, которая обычно имеет один символ U+FFFD. Эта строка определяется объектом DecimalFormatSymbols. Это единственное значение, для которого префиксы и суффиксы не используются.

Бесконечность форматируется как строка, которая обычно имеет один символ U+221E, с применением положительных или отрицательных префиксов и суффиксов. Строка бесконечности определяется объектом DecimalFormatSymbols.

Отрицательный ноль ("-0") парсится в

• BigDecimal(0) если isParseBigDecimal() равно true,
• Long(0) если isParseBigDecimal() равно false и isParseIntegerOnly() равно true,
• Double(-0.0) если оба isParseBigDecimal() и isParseIntegerOnly() равны false.

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

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

Пример

// Print out a number using the localized number, integer, currency,
// and percent format for each locale
Locale[] locales = NumberFormat.getAvailableLocales();
double myNumber = -1234.56;
NumberFormat form;
for (int j = 0; j < 4; ++j) {
    System.out.println("FORMAT");
    for (Locale locale : locales) {
        if (locale.getCountry().length() == 0) {
            continue; // Skip language-only locales
        }
        System.out.print(locale.getDisplayName());
        form = switch (j) {
            case 0 -> NumberFormat.getInstance(locale);
            case 1 -> NumberFormat.getIntegerInstance(locale);
            case 2 -> NumberFormat.getCurrencyInstance(locale);
            default -> NumberFormat.getPercentInstance(locale);
        };
        if (form instanceof DecimalFormat decForm) {
            System.out.print(": " + decForm.toPattern());
        }
        System.out.print(" -> " + form.format(myNumber));
        try {
            System.out.println(" -> " + form.parse(form.format(myNumber)));
        } catch (ParseException e) {}
    }
}