Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Text, Formatting and Regex

The NumberFormat class

Reference for java.text.NumberFormat: locale-aware numbers, currency, percent and compact formats, fraction digits, rounding and locale-correct parsing.

java.text.NumberFormat formats and parses numbers the way people in a given locale write them. The same value is 1,234.5 in the US, 1.234,5 in Germany and 1 234,5 in France (with a special space). You choose a flavor through a factory method (plain numbers, integers, currency, percent, or compact), pass a Locale, and then call format().

Use NumberFormat for text shown to users. When you need a precise custom layout instead, see DecimalFormat, which is the concrete subclass most factory methods return.

Java
NumberFormat money = NumberFormat.getCurrencyInstance(Locale.US);
money.format(1234.5);   // "$1,234.50"

Try it

Java Numbers, currency and percent

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Compact numbers and parsing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public abstract class NumberFormat extends Format
Factory method Produces
getInstance() / getInstance(Locale) general numbers, up to 3 fraction digits, grouping on
getNumberInstance(...) same as getInstance
getIntegerInstance(...) no fraction digits, rounds with HALF_EVEN, parses integers only
getCurrencyInstance(...) currency symbol and the currency's usual fraction digits
getPercentInstance(...) multiplies by 100, adds a percent sign, no fraction digits
getCompactNumberInstance(Locale, Style) short (1K) or long (1 thousand) form, since Java 12
Method Description
format(double), format(long) returns the formatted string
parse(String) returns a Number (Long or Double); throws ParseException
setMaximumFractionDigits(int), setMinimumFractionDigits(int) fraction digit limits
setMinimumIntegerDigits(int) pad the integer part with zeros
setGroupingUsed(boolean) turn grouping separators on or off
setRoundingMode(RoundingMode) default HALF_EVEN
setCurrency(Currency) change the currency used by a currency instance (the symbol changes, not the amount)
setParseIntegerOnly(boolean) parse stops at the decimal separator

Usage notes

  • Pass a Locale explicitly when formatting for a specific audience, and use the user's locale in UI code. The no-argument versions use the JVM default, which makes tests flaky across machines.
  • Parse with the matching locale. NumberFormat.getInstance(Locale.US).parse("1.234,5") returns 1.234 without any error, because parsing stops at the first character it cannot use.
  • Currency formatting does not convert. setCurrency(EUR) changes the symbol, not the number. Keep money in BigDecimal and the currency in a separate field.
  • Special spaces. Several locales (French, many others) use a narrow no-break space as the grouping separator and a no-break space before the currency sign. Do not compare formatted strings with plain spaces.
  • Rounding is half-even. 0.5 formats as 0, 1.5 as 2, 2.5 as 2. Call setRoundingMode(RoundingMode.HALF_UP) for schoolbook rounding.
  • Not thread-safe. Create a format per use or per thread.
  • Output varies with the JDK's locale data. Since Java 9 the data comes from CLDR, and details change between releases, so do not hard-code expected strings for exotic locales in tests.
  • Compact formats drop precision (1.2M, not 1,234,567). Use them for display only, and never parse them back for calculations.