Java : NumberFormat with Examples

NumberFormat (Java SE 18 & JDK 18) API Examples.
You will find code examples on most NumberFormat methods.

Summary

NumberFormat is the abstract base class for all number formats. This class provides the interface for formatting and parsing numbers. NumberFormat also provides methods for determining which locales have number formats, and what their names are.

Class diagram

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format = NumberFormat.getNumberInstance();

System.out.println(format.format(1234000)); // 1,234,000
System.out.println(format.format(-56789)); // -56,789
System.out.println(format.format(0.123456)); // 0.123

final var number = 1234;

final var format1 = NumberFormat.getCurrencyInstance(Locale.US);
System.out.println(format1.format(number)); // $1,234.00

final var format2 = NumberFormat.getCurrencyInstance(Locale.JAPAN);
System.out.println(format2.format(number)); // ￥1,234

final var number = 10000000;

final var format1 = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.LONG);
System.out.println(format1.format(number)); // 10 million

final var format2 = NumberFormat.getCompactNumberInstance(Locale.JAPAN, NumberFormat.Style.SHORT);
System.out.println(format2.format(number)); // 1000万

Fields

static final int FRACTION_FIELD

Field constant used to construct a FieldPosition object.

Please see format(double number, StringBuffer toAppendTo, FieldPosition pos).

static final int INTEGER_FIELD

Field constant used to construct a FieldPosition object.

Please see format(double number, StringBuffer toAppendTo, FieldPosition pos).

Constructors

NumberFormat ()

Sole constructor.

I think it's rare to create a subclass of NumberFormat. Therefore, the code example is omitted.

Methods

Object clone ()

Overrides Cloneable.

final var number = 1.234;

final var format = NumberFormat.getNumberInstance();
format.setMaximumFractionDigits(2);
System.out.println(format.format(number)); // 1.23

if (format.clone() instanceof NumberFormat cloned) {
    System.out.println(cloned.format(number)); // 1.23
    System.out.println(cloned.equals(format)); // true
}

boolean equals (Object obj)

Overrides equals.

final var format1 = NumberFormat.getNumberInstance();
final var format2 = NumberFormat.getCurrencyInstance();

System.out.println(format1.equals(format2)); // false

final var format1 = NumberFormat.getNumberInstance();
final var format2 = NumberFormat.getNumberInstance();

System.out.println(format1.equals(format2)); // true

format1.setMaximumFractionDigits(2);
System.out.println(format1.equals(format2)); // false

final String format (double number)

Specialization of format.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var number = 1.234;

final var format = NumberFormat.getNumberInstance();
System.out.println(format.format(number)); // 1.234

format.setMaximumFractionDigits(2);
System.out.println(format.format(number)); // 1.23

format.setMinimumIntegerDigits(3);
System.out.println(format.format(number)); // 001.23

abstract StringBuffer format (double number, StringBuffer toAppendTo, FieldPosition pos)

Specialization of format.

final var number = 123.456;

final var format = NumberFormat.getNumberInstance(Locale.US);
System.out.println(format.format(number)); // 123.456

{
    final var sb = new StringBuffer("num = ");
    System.out.println(sb); // num =

    final var pos = new FieldPosition(NumberFormat.INTEGER_FIELD);
    final var ret = format.format(number, sb, pos);
    System.out.println(ret); // num = 123.456

    System.out.println(pos.getBeginIndex()); // 6
    System.out.println(pos.getEndIndex()); // 9
}
{
    final var sb = new StringBuffer("num = ");
    System.out.println(sb); // num =

    final var pos = new FieldPosition(NumberFormat.FRACTION_FIELD);
    final var ret = format.format(number, sb, pos);
    System.out.println(ret); // num = 123.456

    System.out.println(pos.getBeginIndex()); // 10
    System.out.println(pos.getEndIndex()); // 13
}

final String format (long number)

Specialization of format.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var number = 1234L;

final var format1 = NumberFormat.getCurrencyInstance();
System.out.println(format1.format(number)); // $1,234.00

final var format2 = NumberFormat.getCurrencyInstance(Locale.JAPAN);
System.out.println(format2.format(number)); // ￥1,234

abstract StringBuffer format (long number, StringBuffer toAppendTo, FieldPosition pos)

Specialization of format.

final var format = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.SHORT);
format.setMinimumFractionDigits(2);

final var number = 12340L;
System.out.println(format.format(number)); // 12.34K

{
    final var sb = new StringBuffer("num = ");
    System.out.println(sb); // num =

    final var pos = new FieldPosition(NumberFormat.INTEGER_FIELD);
    final var ret = format.format(number, sb, pos);
    System.out.println(ret); // num = 12.34K

    System.out.println(pos.getBeginIndex()); // 6
    System.out.println(pos.getEndIndex()); // 8
}
{
    final var sb = new StringBuffer("num = ");
    System.out.println(sb); // num =

    final var pos = new FieldPosition(NumberFormat.FRACTION_FIELD);
    final var ret = format.format(number, sb, pos);
    System.out.println(ret); // num = 12.34K

    System.out.println(pos.getBeginIndex()); // 9
    System.out.println(pos.getEndIndex()); // 11
}

StringBuffer format (Object number, StringBuffer toAppendTo, FieldPosition pos)

Formats a number and appends the resulting text to the given string buffer.

final var format = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.SHORT);
format.setMinimumFractionDigits(2);

final var number = new BigInteger("12340000000000");
System.out.println(format.format(number)); // 12.34T

{
    final var sb = new StringBuffer("num = ");
    System.out.println(sb); // num =

    final var pos = new FieldPosition(NumberFormat.INTEGER_FIELD);
    final var ret = format.format(number, sb, pos);
    System.out.println(ret); // num = 12.34T

    System.out.println(pos.getBeginIndex()); // 6
    System.out.println(pos.getEndIndex()); // 8
}
{
    final var sb = new StringBuffer("num = ");
    System.out.println(sb); // num =

    final var pos = new FieldPosition(NumberFormat.FRACTION_FIELD);
    final var ret = format.format(number, sb, pos);
    System.out.println(ret); // num = 12.34T

    System.out.println(pos.getBeginIndex()); // 9
    System.out.println(pos.getEndIndex()); // 11
}

static Locale[] getAvailableLocales ()

Returns an array of all locales for which the get*Instance methods of this class can return localized instances.

final var locales = NumberFormat.getAvailableLocales();

for (final var locale : locales) {
    System.out.println(locale.toLanguageTag());
}

// Result
// ↓
//und
//he
//th-Thai-TH
//nds
//tk-Latn-TM
//ti-ET
//ta-SG
//lv
//en-NU
//...

static NumberFormat getCompactNumberInstance ()

Returns a compact number format for the default FORMAT locale with "SHORT" format style.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var number = 10000000;

final var format1 = NumberFormat.getCompactNumberInstance();
System.out.println(format1.format(number)); // 10M

final var format2 = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.SHORT);
System.out.println(format2.format(number)); // 10M

final var format3 = NumberFormat.getCompactNumberInstance(Locale.US, NumberFormat.Style.LONG);
System.out.println(format3.format(number)); // 10 million

final var format4 = NumberFormat.getCompactNumberInstance(Locale.JAPAN, NumberFormat.Style.SHORT);
System.out.println(format4.format(number)); // 1000万

static NumberFormat getCompactNumberInstance (Locale locale, NumberFormat.Style formatStyle)

Returns a compact number format for the specified locale and formatStyle.

Please see getCompactNumberInstance().

Currency getCurrency ()

Gets the currency used by this number format when formatting currency values.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var number = 1234;

final var format1 = NumberFormat.getCurrencyInstance();
System.out.println(format1.format(number)); // $1,234.00
System.out.println(format1.getCurrency()); // USD
System.out.println(format1.getMinimumFractionDigits()); // 2

final var format2 = NumberFormat.getCurrencyInstance(Locale.JAPAN);
System.out.println(format2.format(number)); // ￥1,234
System.out.println(format2.getCurrency()); // JPY
System.out.println(format2.getMinimumFractionDigits()); // 0

static final NumberFormat getCurrencyInstance ()

Returns a currency format for the current default FORMAT locale.

Please see getCurrency().

static NumberFormat getCurrencyInstance (Locale inLocale)

Returns a currency format for the specified locale.

Please see getCurrency().

static final NumberFormat getInstance ()

Returns a general-purpose number format for the current default FORMAT locale.

This method is equivalent to getNumberInstance().

static NumberFormat getInstance (Locale inLocale)

Returns a general-purpose number format for the specified locale.

This method is equivalent to getNumberInstance(inLocale).

static final NumberFormat getIntegerInstance ()

Returns an integer number format for the current default FORMAT locale.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format1 = NumberFormat.getIntegerInstance();
System.out.println(format1.getRoundingMode()); // HALF_EVEN
System.out.println(format1.isParseIntegerOnly()); // true

System.out.println(format1.format(12345678)); // 12,345,678
System.out.println(format1.format(9.9)); // 10

final var format2 = NumberFormat.getIntegerInstance(Locale.GERMANY);
System.out.println(format2.format(12345678)); // 12.345.678
System.out.println(format2.format(9.9)); // 10

static NumberFormat getIntegerInstance (Locale inLocale)

Returns an integer number format for the specified locale.

Please see getIntegerInstance().

int getMaximumFractionDigits ()

Returns the maximum number of digits allowed in the fraction portion of a number.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format = NumberFormat.getNumberInstance();

System.out.println(format.getMinimumFractionDigits()); // 0
System.out.println(format.getMaximumFractionDigits()); // 3

System.out.println(format.format(0.01234)); // 0.012
System.out.println(format.format(456.0)); // 456

format.setMinimumFractionDigits(1);
format.setMaximumFractionDigits(4);

System.out.println(format.getMinimumFractionDigits()); // 1
System.out.println(format.getMaximumFractionDigits()); // 4

System.out.println(format.format(0.01234)); // 0.0123
System.out.println(format.format(456.0)); // 456.0

int getMaximumIntegerDigits ()

Returns the maximum number of digits allowed in the integer portion of a number.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format = NumberFormat.getNumberInstance();

System.out.println(format.getMinimumIntegerDigits()); // 1
System.out.println(format.getMaximumIntegerDigits()); // 2147483647

System.out.println(format.format(1234567890)); // 1,234,567,890
System.out.println(format.format(1)); // 1

format.setMinimumIntegerDigits(3);
format.setMaximumIntegerDigits(8);

System.out.println(format.getMinimumIntegerDigits()); // 3
System.out.println(format.getMaximumIntegerDigits()); // 8

System.out.println(format.format(1234567890)); // 34,567,890
System.out.println(format.format(1)); // 001

int getMinimumFractionDigits ()

Returns the minimum number of digits allowed in the fraction portion of a number.

Please see getMaximumFractionDigits().

int getMinimumIntegerDigits ()

Returns the minimum number of digits allowed in the integer portion of a number.

Please see getMaximumIntegerDigits().

static final NumberFormat getNumberInstance ()

Returns a general-purpose number format for the current default FORMAT locale.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format1 = NumberFormat.getNumberInstance();

System.out.println(format1.format(12345678)); // 12,345,678
System.out.println(format1.format(0.123)); // 0.123

final var format2 = NumberFormat.getNumberInstance(Locale.GERMANY);

System.out.println(format2.format(12345678)); // 12.345.678
System.out.println(format2.format(0.123)); // 0,123

static NumberFormat getNumberInstance (Locale inLocale)

Returns a general-purpose number format for the specified locale.

Please see getNumberInstance().

static final NumberFormat getPercentInstance ()

Returns a percentage format for the current default FORMAT locale.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format1 = NumberFormat.getPercentInstance();
System.out.println(format1.format(0.75)); // 75%

final var format2 = NumberFormat.getPercentInstance(Locale.FRANCE);
System.out.println(format2.format(0.75)); // 75 %

static NumberFormat getPercentInstance (Locale inLocale)

Returns a percentage format for the specified locale.

Please see getPercentInstance().

RoundingMode getRoundingMode ()

Gets the RoundingMode used in this NumberFormat.

final var format = NumberFormat.getNumberInstance(Locale.US);
System.out.println(format.getMaximumFractionDigits()); // 3
System.out.println(format.getRoundingMode()); // HALF_EVEN

System.out.println(format.format(0.1114)); // 0.111
System.out.println(format.format(0.1115)); // 0.112
System.out.println(format.format(0.1116)); // 0.112

format.setRoundingMode(RoundingMode.UP);
System.out.println(format.getRoundingMode()); // UP

System.out.println(format.format(0.1114)); // 0.112
System.out.println(format.format(0.1115)); // 0.112
System.out.println(format.format(0.1116)); // 0.112

format.setRoundingMode(RoundingMode.DOWN);
System.out.println(format.getRoundingMode()); // DOWN

System.out.println(format.format(0.1114)); // 0.111
System.out.println(format.format(0.1115)); // 0.111
System.out.println(format.format(0.1116)); // 0.111

int hashCode ()

Overrides hashCode.

final var format1 = NumberFormat.getNumberInstance(Locale.US);
System.out.println(format1.hashCode()); // 423132

final var format2 = NumberFormat.getNumberInstance(Locale.JAPAN);
System.out.println(format2.hashCode()); // 423132

final var format3 = NumberFormat.getCurrencyInstance(Locale.US);
System.out.println(format3.hashCode()); // 423168

boolean isGroupingUsed ()

Returns true if grouping is used in this format.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format = NumberFormat.getNumberInstance();
System.out.println(format.isGroupingUsed()); // true

System.out.println(format.format(1234567)); // 1,234,567

format.setGroupingUsed(false);
System.out.println(format.isGroupingUsed()); // false

System.out.println(format.format(1234567)); // 1234567

boolean isParseIntegerOnly ()

Returns true if this format will parse numbers as integers only.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format = NumberFormat.getNumberInstance();
System.out.println(format.isParseIntegerOnly()); // false

final var ret1 = format.parse("123");
System.out.println(ret1); // 123

final var ret2 = format.parse("4.567");
System.out.println(ret2); // 4.567

format.setParseIntegerOnly(true);
System.out.println(format.isParseIntegerOnly()); // true

final var ret3 = format.parse("4.567");
System.out.println(ret3); // 4

Number parse (String source)

Parses text from the beginning of the given string to produce a number.

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var format = NumberFormat.getNumberInstance();

final var ret1 = format.parse("123,000");
System.out.println(ret1); // 123000
System.out.println(ret1.getClass().getSimpleName()); // Long

final var ret2 = format.parse("0.123");
System.out.println(ret2); // 0.123
System.out.println(ret2.getClass().getSimpleName()); // Double

final var format = NumberFormat.getPercentInstance();

final var ret = format.parse("75%");
System.out.println(ret); // 0.75
System.out.println(ret.getClass().getSimpleName()); // Double

final var format = NumberFormat.getCompactNumberInstance();

final var ret = format.parse("100K");
System.out.println(ret); // 100000
System.out.println(ret.getClass().getSimpleName()); // Long

abstract Number parse (String source, ParsePosition parsePosition)

Returns a Long if possible (e.g., within the range [Long.MIN_VALUE, Long.MAX_VALUE] and with no decimals), otherwise a Double.

final var format = NumberFormat.getNumberInstance(Locale.US);

final var source = "123 456";
final var pos = new ParsePosition(0);

final var ret1 = format.parse(source, pos);
System.out.println(ret1); // 123
System.out.println(pos.getIndex()); // 3

pos.setIndex(pos.getIndex() + 1);

final var ret2 = format.parse(source, pos);
System.out.println(ret2); // 456
System.out.println(pos.getIndex()); // 7

final var ret3 = format.parse(source, pos);
System.out.println(ret3); // null

final Object parseObject (String source, ParsePosition pos)

Parses text from a string to produce a Number.

final var format = NumberFormat.getNumberInstance(Locale.US);

final var source = "123 456";
final var pos = new ParsePosition(0);

final var ret1 = format.parseObject(source, pos);
System.out.println(ret1); // 123
System.out.println(pos.getIndex()); // 3

pos.setIndex(pos.getIndex() + 1);

final var ret2 = format.parseObject(source, pos);
System.out.println(ret2); // 456
System.out.println(pos.getIndex()); // 7

final var ret3 = format.parseObject(source, pos);
System.out.println(ret3); // null

void setCurrency (Currency currency)

Sets the currency used by this number format when formatting currency values.

Please see also : getCurrency()

System.out.println(Locale.getDefault().toLanguageTag()); // en-US

final var number = 1234;

final var format = NumberFormat.getCurrencyInstance();
System.out.println(format.format(number)); // $1,234.00
System.out.println(format.getCurrency()); // USD

format.setCurrency(Currency.getInstance(Locale.JAPAN));
format.setMinimumFractionDigits(0);

System.out.println(format.format(number)); // ¥1,234
System.out.println(format.getCurrency()); // JPY

void setGroupingUsed (boolean newValue)

Set whether or not grouping will be used in this format.

Please see isGroupingUsed().

void setMaximumFractionDigits (int newValue)

Sets the maximum number of digits allowed in the fraction portion of a number. maximumFractionDigits must be ≥ minimumFractionDigits.

Please getMaximumFractionDigits().

void setMaximumIntegerDigits (int newValue)

Sets the maximum number of digits allowed in the integer portion of a number. maximumIntegerDigits must be ≥ minimumIntegerDigits.

Please see getMaximumIntegerDigits().

void setMinimumFractionDigits (int newValue)

Sets the minimum number of digits allowed in the fraction portion of a number. minimumFractionDigits must be ≤ maximumFractionDigits.

Please see getMaximumFractionDigits().

void setMinimumIntegerDigits (int newValue)

Sets the minimum number of digits allowed in the integer portion of a number. minimumIntegerDigits must be ≤ maximumIntegerDigits.

Please see getMaximumIntegerDigits().

void setParseIntegerOnly (boolean value)

Sets whether or not numbers should be parsed as integers only.

Please see isParseIntegerOnly().

void setRoundingMode (RoundingMode roundingMode)

Sets the RoundingMode used in this NumberFormat.

Please see getRoundingMode().

Methods declared in Format

format, formatToCharacterIterator, parseObject

Please see the link below.

Java API Examples : Format

Internationalization

API Examples
- Currency
- Format
  - NumberFormat
- Locale

Number

API Examples
- Number
  - BigDecimal
  - BigInteger
  - Byte
  - Double
  - Float
  - Integer
  - Long
  - Short
- NumberFormat
- Math
- MathContext
- RoundingMode
- StrictMath

Java : NumberFormat with Examples

Summary

Fields

static final int FRACTION_FIELD

static final int INTEGER_FIELD

Constructors

NumberFormat ()

Methods

Object clone ()

boolean equals (Object obj)

final String format (double number)

abstract StringBuffer format (double number, StringBuffer toAppendTo, FieldPosition pos)

final String format (long number)

abstract StringBuffer format (long number, StringBuffer toAppendTo, FieldPosition pos)

StringBuffer format (Object number, StringBuffer toAppendTo, FieldPosition pos)

static Locale[] getAvailableLocales ()

static NumberFormat getCompactNumberInstance ()

static NumberFormat getCompactNumberInstance (Locale locale, NumberFormat.Style formatStyle)

Currency getCurrency ()

static final NumberFormat getCurrencyInstance ()

static NumberFormat getCurrencyInstance (Locale inLocale)

static final NumberFormat getInstance ()

static NumberFormat getInstance (Locale inLocale)

static final NumberFormat getIntegerInstance ()

static NumberFormat getIntegerInstance (Locale inLocale)

int getMaximumFractionDigits ()

int getMaximumIntegerDigits ()

int getMinimumFractionDigits ()

int getMinimumIntegerDigits ()

static final NumberFormat getNumberInstance ()

static NumberFormat getNumberInstance (Locale inLocale)

static final NumberFormat getPercentInstance ()

static NumberFormat getPercentInstance (Locale inLocale)

RoundingMode getRoundingMode ()

int hashCode ()

boolean isGroupingUsed ()

boolean isParseIntegerOnly ()

Number parse (String source)

abstract Number parse (String source, ParsePosition parsePosition)

final Object parseObject (String source, ParsePosition pos)

void setCurrency (Currency currency)

void setGroupingUsed (boolean newValue)

void setMaximumFractionDigits (int newValue)

void setMaximumIntegerDigits (int newValue)

void setMinimumFractionDigits (int newValue)

void setMinimumIntegerDigits (int newValue)

void setParseIntegerOnly (boolean value)

void setRoundingMode (RoundingMode roundingMode)

Methods declared in Format

format, formatToCharacterIterator, parseObject

Related posts