Класс DecimalFormat

public class DecimalFormat
extends NumberFormat

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

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

NumberFormat f = NumberFormat.getInstance(loc);
if (f instanceof DecimalFormat) {
    ((DecimalFormat) f).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 \uFFFE, \uFFFF, and special characters
Suffix:
        any Unicode characters except \uFFFE, \uFFFF, 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)". Каждый подшаблон имеет префикс, числовую часть и суффикс. Подшаблон для отрицательных значений необязателен; если его нет, то используется подшаблон для положительных значений с префиксом локализованного знака минус ('-' в большинстве локалей). То есть, "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 и отображает как процент
\u2030	Префикс или суффикс	Да	Умножает на 1000 и отображает как промилле
¤ (\u00A4)	Префикс или суффикс	Нет	Знак валюты, заменяется символом валюты. Если удвоен, заменяется международным символом валюты. Если присутствует в шаблоне, денежный десятичный разделитель используется вместо десятичного разделителя.
'	Префикс или суффикс	Нет	Используется для экранирования специальных символов в префиксе или суффиксе, например, "'#'#" форматирует 123 как "#123". Чтобы создать одиночную кавычку, используйте две подряд: "# o''clock".

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

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

• Количество цифр после символа показателя степени задаёт минимальное количество цифр в показателе степени. Максимальное количество не ограничено. Отрицательные показатели степени форматируются с использованием локализованного знака минус, а не префикса и суффикса из шаблона. Это позволяет использовать шаблоны, такие как "0.###E0 m/s".
• Минимальное и максимальное количество целых цифр интерпретируются вместе:
  • Если максимальное количество целых цифр больше их минимального количества и больше 1, оно заставляет показатель степени быть кратным максимальному количеству целых цифр, а минимальное количество целых цифр интерпретируется как 1. Наиболее распространённое применение — генерация инженерной нотации, в которой показатель степени является кратным трём, например, "##0.#####E0". С этим шаблоном число 12345 форматируется как "12.345E3", а 123456 — как "123.456E3".
  • В противном случае минимальное количество целых цифр достигается путём корректировки показателя степени. Например, 0,00123, отформатированный с помощью "00.###E0", даёт "12.3E-4".
• Количество значащих цифр в мантиссе является суммой минимального количества целых цифр и максимального количества дробных цифр и не зависит от максимального количества целых цифр. Например, 12345, отформатированный с помощью "##0.##E0", представляет собой "12.3E3". Чтобы отобразить все цифры, установите количество значащих цифр в ноль. Количество значащих цифр не влияет на парсинг.
• Шаблоны экспоненциальной записи не могут содержать разделители групп.

Округление

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

Цифры

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

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

NaN форматируется как строка, которая, как правило, имеет один символ \uFFFD. Эта строка определяется объектом DecimalFormatSymbols. Это единственное значение, для которого не используются префиксы и суффиксы.

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

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

• BigDecimal(0) если isParseBigDecimal() имеет значение true,
• Long(0) если isParseBigDecimal() имеет значение false и isParseIntegerOnly() имеет значение true,
• Double(-0.0) если оба isParseBigDecimal() и isParseIntegerOnly() имеют значение false.

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

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

Пример

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