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.
NumberFormat money = NumberFormat.getCurrencyInstance(Locale.US); money.format(1234.5); // "$1,234.50"
Try it
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.
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
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
Localeexplicitly 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")returns1.234without 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 inBigDecimaland 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.5formats as0,1.5as2,2.5as2. CallsetRoundingMode(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, not1,234,567). Use them for display only, and never parse them back for calculations.