Класс CompactNumberFormat

public final class CompactNumberFormat extends NumberFormat

Класс US locale — конкретный подкласс NumberFormat, форматирующий десятичное число в компактной форме. Компактное форматирование чисел предназначено для сред, где пространство ограничено, и отформатированная строка может отображаться в этом ограниченном пространстве. Оно определяется спецификацией LDML для компактных форматов чисел. Компактное форматирование чисел относится к представлению числа в более короткой форме, основанной на шаблонах, предоставленных для данного языка и региона.

Например:
В US locale, число 1000 может быть отформатировано как "1K", а число 1000000 — как "1M", в зависимости от используемого стиля.
В языке и регионе "hi_IN", число 1000 может быть отформатировано как "1 हज़ार", а число 50000000 — как "5 क.", в зависимости от используемого стиля.

Чтобы получить экземпляр CompactNumberFormat для определенного региона, используйте один из фабричных методов, предоставленных классом NumberFormat для компактного форматирования чисел. Например, NumberFormat.getCompactNumberInstance(Locale, Style).

 NumberFormat fmt = NumberFormat.getCompactNumberInstance(
                             new Locale("hi", "IN"), NumberFormat.Style.SHORT);
 String result = fmt.format(1000);
 

Стиль

Число можно отформатировать в компактной форме с помощью двух различных стилей: SHORT и LONG. Используйте NumberFormat.getCompactNumberInstance(Locale, Style) для форматирования и разбора числа в SHORT или LONG компактной форме, где переданный параметр Style указывает требуемый формат. Экземпляр SHORT компактного числа в US locale форматирует 10000 как "10K". Однако, экземпляр LONG стиля в том же регионе форматирует 10000 как "10 thousand".

Шаблоны компактных чисел

Шаблоны компактных чисел представлены серией шаблонов, где каждый шаблон используется для форматирования диапазона чисел. Пример шаблонов SHORT компактных чисел для US locale — {"", "", "", "0K", "00K", "000K", "0M", "00M", "000M", "0B", "00B", "000B", "0T", "00T", "000T"}, охватывающий диапазон от 100 до 1014. Может быть любое количество шаблонов, и они основаны строго на индексах, начиная с диапазона 100. Например, в приведенных шаблонах шаблон с индексом 3 ("0K") используется для форматирования number >= 1000 and number < 10000, шаблон с индексом 4 ("00K") — для форматирования number >= 10000 and number < 100000 и так далее. В большинстве регионов шаблоны с диапазоном 100-102 являются пустыми строками, что неявно означает специальный шаблон "0". Специальный шаблон "0" используется для любого диапазона, не содержащего компактный шаблон. Этот специальный шаблон может быть указан явно для любого конкретного диапазона или рассматривается как шаблон по умолчанию для пустой строки.

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

Многие символы в компактном шаблоне интерпретируются буквально; они сопоставляются во время разбора и остаются неизменными при форматировании. Специальные символы, с другой стороны, представляют собой другие символы, строки или классы символов. Они должны быть заключены в одинарные кавычки ' (U+0027), если они должны отображаться в префиксе или суффиксе как литералы. Например, 0क'.'.

Множественное число

В тех случаях, когда некоторые языки требуют, чтобы компактные шаблоны чисел были разными для множественных чисел, каждый одиночный и множественный шаблон может быть перечислен в паре фигурных скобок '{' (U+007B) и '}' (U+007D), разделенных пробелом ' ' (U+0020). Если используется этот формат, каждый шаблон должен быть дополнен его count, за которым следует двоеточие ':' (U+003A). Если шаблон включает пробелы буквально, они должны быть заключены в кавычки.

Например, компактный шаблон числа, представляющего миллионы в немецком языке и регионе, может быть задан как "{one:0' 'Million other:0' 'Millionen}". count соответствует правилам множественного числа языка LDML.

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

 Pattern:
         SimplePattern
         '{' PluralPattern [' ' PluralPattern]optional '}'
 SimplePattern:
         PositivePattern
         PositivePattern [; NegativePattern]optional
 PluralPattern:
         Count:SimplePattern
 Count:
         "zero" / "one" / "two" / "few" / "many" / "other"
 PositivePattern:
         Prefixoptional MinimumInteger Suffixoptional
 NegativePattern:
        Prefixoptional MinimumInteger Suffixoptional
 Prefix:
      Any Unicode characters except \uFFFE, \uFFFF, and
      special characters.
 Suffix:
      Any Unicode characters except \uFFFE, \uFFFF, and
      special characters.
 MinimumInteger:
      0
      0 MinimumInteger
 

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

По умолчанию форматирование возвращает отформатированную строку без дробной части, но пользователи могут использовать метод setMinimumFractionDigits(int), чтобы включить дробную часть. Число 1000.0 или 1000 форматируется как "1K", а не "1.00K" (в US locale). По этой причине шаблоны, предоставленные для форматирования, содержат только минимальное количество целых цифр, префикс и/или суффикс, но не дробную часть. Например, используемые шаблоны — {"", "", "", 0K, 00K, ...}. Если выбранный для форматирования шаблон числа является "0" (специальный шаблон), явным или по умолчанию, то используется общее форматирование чисел, предоставляемое классом DecimalFormat для указанного языка и региона.

Разбор

По умолчанию разбор не допускает разделитель групп до тех пор, пока разделитель групп не будет установлен в true с помощью метода setGroupingUsed(boolean). Разбор дробной части зависит от метода isParseIntegerOnly(). Например, если разбор только целых чисел установлен в true, то дробная часть пропускается.

Округление

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