Класс 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)". Каждый подшаблон имеет префикс, числовую часть и суффикс. Отрицательный подшаблон является необязательным; если он отсутствует, то положительный подшаблон с префиксом «минус» ('-' 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 и показать как процент
\u2030	Префикс или суффикс	Да	Умножить на 1000 и показать как промилле
¤ (\u00A4)	Префикс или суффикс	Нет	Знак валюты, заменяется символом валюты. Если удвоенный, заменяется международным символом валюты. Если присутствует в шаблоне, денежные десятичные/групповые разделители используются вместо десятичных/групповых разделителей.
'	Префикс или суффикс	Нет	Используется для заключения специальных символов в префикс или суффикс, например, "'#'#" форматирует 123 как "#123". Чтобы создать одиночную кавычку, используйте две подряд: "# o''clock".

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

Числа в научной записи выражаются как произведение мантиссы и степени десяти, например, 1234 можно выразить как 1,234 х 10^3. Мантисса часто находится в диапазоне 1,0 ≤ x < 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() истинно,
• Long(0) если isParseBigDecimal() ложно и isParseIntegerOnly() истинно,
• Double(-0.0) если оба isParseBigDecimal() и isParseIntegerOnly() ложны.

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

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

Пример

 // 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 (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) {}
     }
 }