Java NumberFormat

Java NumberFormat tutorial shows how to format numbers in Java. Different cultures use different ways to represent numbers. For instance, the way currencies are formatted is widely different in the countries around the world.

NumberFormat

NumberFormat is a Java class for formatting and parsing numbers. With NumberFormat, we can format and parse numbers for any locale.

NumberFormat allows us to round values, set decimal separators, set the number of fraction digits, or format values according to a specific locale.

Creating a NumberFormat

NumberFormat has several static methods to create number formats.

static NumberFormat getInstance(Locale inLocale)

This getInstance() method returns a general-purpose number format for the specified locale.

Formatting numbers

Numbers are formatted differently for different locales. For instance, some countries use a dot as a decimal separator (USA, Great Britain), others use a comma (Slovakia, France).

FormattingNumbers.java
package com.zetcode;

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

public class FormattingNumbers {

    public static void main(String[] args) {

        double n = 1240.35;

        NumberFormat nf = NumberFormat.getInstance(new Locale("en", "US"));
        String val = nf.format(n);

        System.out.println(val);
        
        NumberFormat nf2 = NumberFormat.getInstance(new Locale("sk", "SK"));
        String val2 = nf2.format(n);

        System.out.println(val2);        

        NumberFormat nf3 = NumberFormat.getInstance(new Locale("da", "DK"));
        String val3 = nf3.format(n);

        System.out.println(val3);
    }
}

The example displays a number in three different locales.

double n = 1240.35;

This is the value to be formatted.

NumberFormat nf = NumberFormat.getInstance(new Locale("en", "US"));

We create a NumberFormat for the US locale.

String val = nf.format(n);

We format the value with the format() method.

NumberFormat nf2 = NumberFormat.getInstance(new Locale("sk", "SK"));
String val2 = nf2.format(n);

Here we format the value for the Slovak locale.

1,240.35
1 240,35
1.240,35

USA, Slovakia, and Denmark use different characters for digit grouping and decimal mark.

Grouping digits

For ease of reading, numbers with many digits may be divided into groups using a delimiter. The setGroupingUsed() sets whether grouping is used in the format.

Grouping.java
package com.zetcode;

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

public class Grouping {

    public static void main(String[] args) {
        
        long val = 23_500_390_800_380L;
        
        NumberFormat nf = NumberFormat.getInstance(new Locale("sk", "SK"));
        nf.setGroupingUsed(true);
        
        System.out.println(nf.format(val));
        
        nf.setGroupingUsed(false);
        
        System.out.println(nf.format(val));        
    }
}

We have a long number. We demonstrate the grouping of digits for the Slovak locale.

long val = 23_500_390_800_380L;

Since Java 7, it is possible to use underscore characters in numeric literals.

nf.setGroupingUsed(true);

We set the grouping with the setGroupingUsed() method.

23 500 390 800 380
23500390800380

The first value is more readable than the second one. Slovakia uses a space character for digit grouping.

Fraction digits

We can control the number of fraction digits with the setMinimumFractionDigits() and setMaximumFractionDigits(). If there are fewer digits than the minimum number of fraction digits, zeros are added to the value. If there are more digits than the maximum number of fraction digits, the number is rounded.

FractionDigits.java
package com.zetcode;

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

public class FractionDigits {

    public static void main(String[] args) {
        
        double val1 = 4.5678934;
        double val2 = 2.3;
        
        NumberFormat nf = NumberFormat.getInstance(new Locale("sk", "SK"));
        nf.setMinimumFractionDigits(2);
        nf.setMaximumFractionDigits(4);
        
        System.out.println(nf.format(val1));
        System.out.println(nf.format(val2));
    }
}

In the example, we set the minimum and maximum number of fraction digits.

4,5679
2,30

The first value is rounded, the second value gets an additional zero digit.

Rounding numbers

As we have already stated above, if there are more fraction digits than the maximum number of allowed digits, the value is rounded. There are several rounding techniques available.

RoundingNumbers.java
package com.zetcode;

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

public class RoundingNumbers {

    public static void main(String[] args) {

        double nums[] = {2.32, 2.55, 3.19, 4.88, 5.54, 3.22, 8.78};

        NumberFormat nf = NumberFormat.getInstance(Locale.ENGLISH);
        nf.setMaximumFractionDigits(1);
        nf.setRoundingMode(RoundingMode.UP);

        for (double num : nums) {

            String number = nf.format(num);
            System.out.printf("%s ", number);
        }
        
        System.out.println();
        
        nf.setRoundingMode(RoundingMode.DOWN);
        
        for (double num : nums) {

            String number = nf.format(num);
            System.out.printf("%s ", number);
        }
        
        System.out.println();        
    }
}

The example rounds double numbers using two rounding modes: RoundingMode.UP and RoundingMode.DOWN.

nf.setMaximumFractionDigits(1);
nf.setRoundingMode(RoundingMode.UP);

We set the maximum number of fraction digits with setMaximumFractionDigits() and the rounding mode with setRoundingMode().

2.4 2.6 3.2 4.9 5.6 3.3 8.8 
2.3 2.5 3.1 4.8 5.5 3.2 8.7 

This is the output.

Formatting percentages

The NumberFormat.getPercentInstance() is used to format percentages.

Percentages.java
package com.zetcode;

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

public class Percentages {

    public static void main(String[] args) {
        
        double x = 25f / 100f;
        
        NumberFormat pf = NumberFormat.getPercentInstance(new Locale("sk", "SK"));
        
        System.out.println(pf.format(x));
    }
}

The example formats a double value as a percentage.

25%

This is the output.

Formatting currencies

One of the most complex tasks when working with numbers is to format currencies. We use the NumberFormat.getCurrencyInstance() to get the number format for the currencies.

Currencies.java
package com.zetcode;

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

public class Currencies {

    public static void main(String[] args) {

        int val = 23_500;

        NumberFormat cf1 = NumberFormat.getCurrencyInstance(new Locale("en", "US"));
        System.out.println(cf1.format(val));

        NumberFormat cf2 = NumberFormat.getCurrencyInstance(new Locale("sk", "SK"));
        System.out.println(cf2.format(val));  
        
        NumberFormat cf3 = NumberFormat.getCurrencyInstance(new Locale("zh", "CN"));
        System.out.println(cf3.format(val));         
    }
}

The example displays currencies for three different countries: USA, Slovakia, and China.

NumberFormat cf3 = NumberFormat.getCurrencyInstance(new Locale("zh", "CN"));

This line gets the number format for the Chinese currency.

$23,500.00
23 500,00 €
¥23,500.00

This is the output.

Parsing numbers

The parse() method parses text from the beginning of the given string to produce a number.

ParsingNumbers.java
package com.zetcode;

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

public class ParsingNumbers {

    public static void main(String[] args) throws ParseException {
        
        NumberFormat nf = NumberFormat.getInstance(new Locale("sk", "SK"));
        nf.setMaximumFractionDigits(3);
        
        Number num = nf.parse("150000,456");
        System.out.println(num.doubleValue());
    }
}

The example parses a value with the Slovak locale.

In this tutorial, we have worked with Java NumberFormat. We have formatted numbers, currencies, percentages, rounded numbers, set the number of fraction digits, and set the grouping of digits.

You might also be interested in the related tutorials: Java tutorial, Java StringBuilder tutorial, Java ArrayList tutorial, Java static keyword, Java 8 forEach tutorial, Reading text files in Java, and Reading and writing ICO images in Java.