Wednesday, December 26, 2018

Compact Number Formatting Comes to JDK 12

JDK 12 Early Access Build 24 introduces support for Compact Number Formatting. The JDK-8188147 (Compact Number Formatting support) CSR's "Summary" is the simple sentence, "Adding support for the compact/short number formatting in JDK." That same CSR also provides a detailed "Solution" section that provides background on providing numbers in multiple compact forms for each Locale and the constructs/APIs added to the JDK to support this functionality (new class, new enum, new methods, etc.)

The representations of compact and short formats of numbers in each locale are based on the Unicode Common Locale Data Repository (CLDR). A newly added class, java.text.CompactNumberFormat, has class-level Javadoc comments that provide quite a bit of detail regarding how numbers are expressed in "short" and "long" compact number formats. That class's Javadoc comments also specify compact number patterns, formatting, parsing, and rounding (RoundingMode.HALF_EVEN by default) related to custom number formats.

In the request for review of the addition of compact number formatting to JDK 12, Nishit Jain writes:

The existing NumberFormat API provides locale based support for formatting and parsing numbers which includes formatting decimal, percent, currency etc, but the support for formatting a number into a human readable or compact form is missing. This RFE adds that feature to format a decimal number in a compact format (e.g. 1000 -> 1K, 1000000 -> 1M in en_US locale), which is useful for the environment where display space is limited, so that the formatted string can be displayed in that limited space. It is defined by LDML's specification for Compact Number Formats.

http://unicode.org/reports/tr35/tr35-numbers.html#Compact_Number_Formats

It is probably easiest to understand compact number formatting via code example. The following class (CompactNumberFormatDemo) was compiled and executed against JDK 12 Early Access Build 24 and is also available on GitHub.

package dustin.examples.jdk12.format;

import static java.lang.System.out;

import java.text.NumberFormat;
import java.util.Locale;

/**
 * Demonstrate Compact Number Format support added to
 * JDK 12 as of Early Access Build 24 (see also
 * JDK-8177552: Compact Number Formatting support).
 */
public class CompactNumberFormatDemo
{
   private static void demonstrateCompactNumberFormatting(final long numberToFormat)
   {
      final NumberFormat numberFormatDefault
         = NumberFormat.getCompactNumberInstance();
      final NumberFormat numberFormatUsLong
         = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.LONG);
      final NumberFormat numberFormatUkShort
         = NumberFormat.getCompactNumberInstance(Locale.UK, NumberFormat.Style.SHORT);
      final NumberFormat numberFormatUkLong
         = NumberFormat.getCompactNumberInstance(Locale.UK, NumberFormat.Style.LONG);
      final NumberFormat numberFormatFrShort
         = NumberFormat.getCompactNumberInstance(Locale.FRANCE, NumberFormat.Style.SHORT);
      final NumberFormat numberFormatFrLong
         = NumberFormat.getCompactNumberInstance(Locale.FRANCE, NumberFormat.Style.LONG);
      final NumberFormat numberFormatGrShort
         = NumberFormat.getCompactNumberInstance(Locale.GERMANY, NumberFormat.Style.SHORT);
      final NumberFormat numberFormatGrLong
         = NumberFormat.getCompactNumberInstance(Locale.GERMANY, NumberFormat.Style.LONG);
      final NumberFormat numberFormatItShort
         = NumberFormat.getCompactNumberInstance(Locale.ITALY, NumberFormat.Style.SHORT);
      final NumberFormat numberFormatItLong
         = NumberFormat.getCompactNumberInstance(Locale.ITALY, NumberFormat.Style.LONG);

      out.println("Demonstrating Compact Number Formatting on '" + numberToFormat + "':");
      out.println("\tDefault:  " + numberFormatDefault.format(numberToFormat));
      out.println("\tUS/Long:  " + numberFormatUsLong.format(numberToFormat));
      out.println("\tUK/Short: " + numberFormatUkShort.format(numberToFormat));
      out.println("\tUK/Long:  " + numberFormatUkLong.format(numberToFormat));
      out.println("\tFR/Short: " + numberFormatFrShort.format(numberToFormat));
      out.println("\tFR/Long:  " + numberFormatFrLong.format(numberToFormat));
      out.println("\tDE/Short: " + numberFormatGrShort.format(numberToFormat));
      out.println("\tDE/Long:  " + numberFormatGrLong.format(numberToFormat));
      out.println("\tIT/Short: " + numberFormatItShort.format(numberToFormat));
      out.println("\tIT/Long:  " + numberFormatItLong.format(numberToFormat));
   }

   /**
    * Main demonstration executable.
    * @param arguments Command-line arguments: none expected.
    */
   public static void main(final String[] arguments)
   {
      demonstrateCompactNumberFormatting(15);
      demonstrateCompactNumberFormatting(150);
      demonstrateCompactNumberFormatting(1500);
      demonstrateCompactNumberFormatting(15000);
      demonstrateCompactNumberFormatting(150000);
      demonstrateCompactNumberFormatting(1500000);
      demonstrateCompactNumberFormatting(15000000);
   }
}

When executed, the above code writes the following to standard output:

Demonstrating Compact Number Formatting on '15':
 Default:  15
 US/Long:  15
 UK/Short: 15
 UK/Long:  15
 FR/Short: 15
 FR/Long:  15
 DE/Short: 15
 DE/Long:  15
 IT/Short: 15
 IT/Long:  15
Demonstrating Compact Number Formatting on '150':
 Default:  150
 US/Long:  150
 UK/Short: 150
 UK/Long:  150
 FR/Short: 150
 FR/Long:  150
 DE/Short: 150
 DE/Long:  150
 IT/Short: 150
 IT/Long:  150
Demonstrating Compact Number Formatting on '1500':
 Default:  2K
 US/Long:  2 thousand
 UK/Short: 2K
 UK/Long:  2 thousand
 FR/Short: 2 k
 FR/Long:  2 millier
 DE/Short: 1.500
 DE/Long:  2 Tausend
 IT/Short: 1.500
 IT/Long:  2 mille
Demonstrating Compact Number Formatting on '15000':
 Default:  15K
 US/Long:  15 thousand
 UK/Short: 15K
 UK/Long:  15 thousand
 FR/Short: 15 k
 FR/Long:  15 mille
 DE/Short: 15.000
 DE/Long:  15 Tausend
 IT/Short: 15.000
 IT/Long:  15 mila
Demonstrating Compact Number Formatting on '150000':
 Default:  150K
 US/Long:  150 thousand
 UK/Short: 150K
 UK/Long:  150 thousand
 FR/Short: 150 k
 FR/Long:  150 mille
 DE/Short: 150.000
 DE/Long:  150 Tausend
 IT/Short: 150.000
 IT/Long:  150 mila
Demonstrating Compact Number Formatting on '1500000':
 Default:  2M
 US/Long:  2 million
 UK/Short: 2M
 UK/Long:  2 million
 FR/Short: 2 M
 FR/Long:  2 million
 DE/Short: 2 Mio.
 DE/Long:  2 Million
 IT/Short: 2 Mln
 IT/Long:  2 milione
Demonstrating Compact Number Formatting on '15000000':
 Default:  15M
 US/Long:  15 million
 UK/Short: 15M
 UK/Long:  15 million
 FR/Short: 15 M
 FR/Long:  15 million
 DE/Short: 15 Mio.
 DE/Long:  15 Millionen
 IT/Short: 15 Mln
 IT/Long:  15 milioni

The compact number format support that has been added to JDK 12 via Early Access Build 24 allows for formatting and parsing numeric representations in a locale-specific "long" or "short" compact forms.

1 comment:

@DustinMarx said...

See post "Using Minimum Fractional Digits with JDK 12 Compact Number Formatting" for a demonstration of how NumberFormat.setMinimumFractionDigits(int) can be used to adjust the presentation of the compact formatted numbers shown in this post.