Java NumberFormat

last modified January 10, 2023

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 Java 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.

Java NumberFormat 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).

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.

Java NumberFormat 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.

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.

Java NumberFormat 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.

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.

Java NumberFormat 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.

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

NumberFormat formatting percentages

The NumberFormat.getPercentInstance is used to format percentages.

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%

Java NumberFormat 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.

package com.zetcode;

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

public class Currencies {

    public static void main(String[] args) {

        var val = new BigDecimal("23500");

        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

Java NumberFormat parsing numbers

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

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 article, 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.

List all Java tutorials.