Java : DecimalFormat - API Examples

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


Summary

DecimalFormat is a concrete subclass of NumberFormat that formats decimal numbers. It has a variety of features designed to make it possible to parse and format numbers in any locale, including support for Western, Arabic, and Indic digits.

Class diagram

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

final var format = NumberFormat.getNumberInstance();
System.out.println(format.getClass().getSimpleName()); // DecimalFormat

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.getClass().getSimpleName()); // DecimalFormat
System.out.println(format1.format(number)); // $1,234.00

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

Fields declared in NumberFormat

FRACTION_FIELD, INTEGER_FIELD

Please see the link below.

Constructors

DecimalFormat ()

Creates a DecimalFormat using the default pattern and symbols for the default FORMAT locale.

final var format = new DecimalFormat();
System.out.println(format.toPattern()); // #,##0.###

System.out.println(format.format(1234000)); // 1,234,000
System.out.println(format.format(-5678)); // -5,678
System.out.println(format.format(0.12345)); // 0.123

DecimalFormat (String pattern)

Creates a DecimalFormat using the given pattern and the symbols for the default FORMAT locale.

final var format = new DecimalFormat("#,##0.0##");
System.out.println(format.toPattern()); // #,##0.0##

System.out.println(format.format(1234)); // 1,234.0
System.out.println(format.format(-5678)); // -5,678.0
System.out.println(format.format(0.12345)); // 0.123

DecimalFormat (String pattern, DecimalFormatSymbols symbols)

Creates a DecimalFormat using the given pattern and symbols.

final var pattern = "#,##0.###";

final var format1 = new DecimalFormat(pattern, DecimalFormatSymbols.getInstance(Locale.US));
System.out.println(format1.toLocalizedPattern()); // #,##0.###

System.out.println(format1.format(123000)); // 123,000
System.out.println(format1.format(0.456)); // 0.456

final var format2 = new DecimalFormat(pattern, DecimalFormatSymbols.getInstance(Locale.GERMANY));
System.out.println(format2.toLocalizedPattern()); // #.##0,###

System.out.println(format2.format(123000)); // 123.000
System.out.println(format2.format(0.456)); // 0,456

Methods

void applyLocalizedPattern (String pattern)

Apply the given pattern to this Format object.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = 1234;

    System.out.println(format.toLocalizedPattern()); // #,##0.###
    System.out.println(format.format(number)); // 1,234

    format.applyLocalizedPattern("#,##0.0##");

    System.out.println(format.toLocalizedPattern()); // #,##0.0##
    System.out.println(format.format(number)); // 1,234.0
}

if (NumberFormat.getNumberInstance(Locale.GERMANY) instanceof DecimalFormat format) {

    final var number = 1234;

    System.out.println(format.toLocalizedPattern()); // #.##0,###
    System.out.println(format.format(number)); // 1.234

    format.applyLocalizedPattern("#.##0,0##");

    System.out.println(format.toLocalizedPattern()); // #.##0,0##
    System.out.println(format.format(number)); // 1.234,0
}

void applyPattern (String pattern)

Apply the given pattern to this Format object.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = 1234;

    System.out.println(format.toPattern()); // #,##0.###
    System.out.println(format.format(number)); // 1,234

    format.applyPattern("#,##0.0##");

    System.out.println(format.toPattern()); // #,##0.0##
    System.out.println(format.format(number)); // 1,234.0
}

if (NumberFormat.getNumberInstance(Locale.GERMANY) instanceof DecimalFormat format) {

    final var number = 1234;

    System.out.println(format.toPattern()); // #,##0.###
    System.out.println(format.format(number)); // 1.234

    format.applyPattern("#,##0.0##");

    System.out.println(format.toPattern()); // #,##0.0##
    System.out.println(format.format(number)); // 1.234,0
}

Object clone ()

Standard override; no change in semantics.

final var format = new DecimalFormat();
System.out.println(format.toPattern()); // #,##0.###

if (format.clone() instanceof DecimalFormat cloned) {
    System.out.println(cloned.toPattern()); // #,##0.###
    System.out.println(cloned.equals(format)); // true
}

boolean equals (Object obj)

Overrides equals

final var format1 = new DecimalFormat("#0.###");
final var format2 = new DecimalFormat("#0.###");
final var format3 = new DecimalFormat("#0.0##");

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

StringBuffer format (double number, StringBuffer result, FieldPosition fieldPosition)

Formats a double to produce a string.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = 123.456;
    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
    }
}

StringBuffer format (long number, StringBuffer result, FieldPosition fieldPosition)

Format a long to produce a string.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    format.setMinimumFractionDigits(3);

    final var number = 123L;
    System.out.println(format.format(number)); // 123.000

    {
        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.000

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

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

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

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

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    format.setMinimumFractionDigits(3);

    final var number = new BigInteger("123");
    System.out.println(format.format(number)); // 123.000

    {
        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.000

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

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

AttributedCharacterIterator formatToCharacterIterator (Object obj)

Formats an Object producing an AttributedCharacterIterator.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var num = 123;
    System.out.println(format.format(num)); // 123

    final var it = format.formatToCharacterIterator(num);

    System.out.println("-- iterator --");
    for (char c = it.first(); c != CharacterIterator.DONE; c = it.next()) {
        System.out.println(c);
    }

    // Result
    // ↓
    //-- iterator --
    //1
    //2
    //3
}

Currency getCurrency ()

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

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

if (NumberFormat.getCurrencyInstance() instanceof DecimalFormat format) {

    final var number = 1234;

    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
}

DecimalFormatSymbols getDecimalFormatSymbols ()

Returns a copy of the decimal format symbols, which is generally not changed by the programmer or user.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = 1234.56;

    final var ret1 = format.getDecimalFormatSymbols();
    System.out.println(ret1.getDecimalSeparator()); // .
    System.out.println(ret1.getGroupingSeparator()); // ,
    System.out.println(format.format(number)); // 1,234.56

    format.setDecimalFormatSymbols(DecimalFormatSymbols.getInstance(Locale.GERMANY));

    final var ret2 = format.getDecimalFormatSymbols();
    System.out.println(ret2.getDecimalSeparator()); // ,
    System.out.println(ret2.getGroupingSeparator()); // .
    System.out.println(format.format(number)); // 1.234,56
}

int getGroupingSize ()

Return the grouping size.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var num = 123000;

    System.out.println(format.getGroupingSize()); // 3
    System.out.println(format.format(num)); // 123,000

    format.setGroupingSize(0);

    System.out.println(format.getGroupingSize()); // 0
    System.out.println(format.format(num)); // 123000
}

int getMaximumFractionDigits ()

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

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    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 ()

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

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    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 ()

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

Please see getMaximumFractionDigits().

int getMinimumIntegerDigits ()

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

Please see getMaximumIntegerDigits().

int getMultiplier ()

Gets the multiplier for use in percent, per mille, and similar formats.

if (NumberFormat.getPercentInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = 0.75;

    System.out.println(format.getMultiplier()); // 100
    System.out.println(format.format(number)); // 75%

    format.setMultiplier(1000);

    System.out.println(format.getMultiplier()); // 1000
    System.out.println(format.format(number)); // 750%
}

String getNegativePrefix ()

Get the negative prefix.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = -123;

    System.out.println(format.getNegativePrefix()); // -
    System.out.println(format.format(number)); // -123

    format.setNegativePrefix("Negative : ");

    System.out.println(format.getNegativePrefix()); // Negative :
    System.out.println(format.format(number)); // Negative : 123
}

String getNegativeSuffix ()

Get the negative suffix.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = -123;

    System.out.println(format.getNegativeSuffix().isEmpty()); // true
    System.out.println(format.format(number)); // -123

    format.setNegativeSuffix(" : Negative");

    System.out.println(format.getNegativeSuffix()); //  : Negative
    System.out.println(format.format(number)); // -123 : Negative
}

String getPositivePrefix ()

Get the positive prefix.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = 123;

    System.out.println(format.getPositivePrefix().isEmpty()); // true
    System.out.println(format.format(number)); // 123

    format.setPositivePrefix("Positive : ");

    System.out.println(format.getPositivePrefix()); // Positive :
    System.out.println(format.format(number)); // Positive : 123
}

String getPositiveSuffix ()

Get the positive suffix.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var number = 123;

    System.out.println(format.getPositiveSuffix().isEmpty()); // true
    System.out.println(format.format(number)); // 123

    format.setPositiveSuffix(" : Positive");

    System.out.println(format.getPositiveSuffix()); //  : Positive
    System.out.println(format.format(number)); // 123 : Positive
}

RoundingMode getRoundingMode ()

Gets the RoundingMode used in this DecimalFormat.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    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

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {
    System.out.println(format.hashCode()); // 423132
}

if (NumberFormat.getCurrencyInstance(Locale.US) instanceof DecimalFormat format) {
    System.out.println(format.hashCode()); // 423168
}

boolean isDecimalSeparatorAlwaysShown ()

Allows you to get the behavior of the decimal separator with integers.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    System.out.println(format.isDecimalSeparatorAlwaysShown()); // false
    System.out.println(format.format(1234)); // 1,234

    format.setDecimalSeparatorAlwaysShown(true);

    System.out.println(format.isDecimalSeparatorAlwaysShown()); // true
    System.out.println(format.format(1234)); // 1,234.
}

boolean isParseBigDecimal ()

Returns whether the parse(java.lang.String, java.text.ParsePosition) method returns BigDecimal.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    final var text = "12345678900000000000";

    System.out.println(format.isParseBigDecimal()); // false

    final var num1 = format.parse(text);
    System.out.println(num1); // 1.23456789E19
    System.out.println(num1.getClass().getSimpleName()); // Double

    format.setParseBigDecimal(true);
    System.out.println(format.isParseBigDecimal()); // true

    final var num2 = format.parse(text);
    System.out.println(num2); // 12345678900000000000
    System.out.println(num2.getClass().getSimpleName()); // BigDecimal
}

Number parse (String text, ParsePosition pos)

Parses text from a string to produce a Number.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    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
}

void setCurrency (Currency currency)

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

Please see getCurrency().

void setDecimalFormatSymbols (DecimalFormatSymbols newSymbols)

Sets the decimal format symbols, which is generally not changed by the programmer or user.

Please see getDecimalFormatSymbols().

void setDecimalSeparatorAlwaysShown (boolean newValue)

Allows you to set the behavior of the decimal separator with integers.

Please see isDecimalSeparatorAlwaysShown().

void setGroupingSize (int newValue)

Set the grouping size.

Please see getGroupingSize().

void setMaximumFractionDigits (int newValue)

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

Please see getMaximumFractionDigits().

void setMaximumIntegerDigits (int newValue)

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

Please see getMaximumIntegerDigits().

void setMinimumFractionDigits (int newValue)

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

Please see getMaximumFractionDigits().

void setMinimumIntegerDigits (int newValue)

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

Please see getMaximumIntegerDigits().

void setMultiplier (int newValue)

Sets the multiplier for use in percent, per mille, and similar formats.

Please see getMultiplier().

void setNegativePrefix (String newValue)

Set the negative prefix.

Please see getNegativePrefix().

void setNegativeSuffix (String newValue)

Set the negative suffix.

Please see getNegativeSuffix().

void setParseBigDecimal (boolean newValue)

Sets whether the parse(java.lang.String, java.text.ParsePosition) method returns BigDecimal.

Please see isParseBigDecimal().

void setPositivePrefix (String newValue)

Set the positive prefix.

Please see getPositivePrefix().

void setPositiveSuffix (String newValue)

Set the positive suffix.

Please see getPositiveSuffix().

void setRoundingMode (RoundingMode roundingMode)

Sets the RoundingMode used in this DecimalFormat.

Please see getRoundingMode().

String toLocalizedPattern ()

Synthesizes a localized pattern string that represents the current state of this Format object.

if (NumberFormat.getNumberInstance(Locale.US) instanceof DecimalFormat format) {

    System.out.println(format.toPattern()); // #,##0.###
    System.out.println(format.toLocalizedPattern()); // #,##0.###

    System.out.println(format.format(123000)); // 123,000
    System.out.println(format.format(0.456)); // 0.456
}

if (NumberFormat.getNumberInstance(Locale.GERMANY) instanceof DecimalFormat format) {

    System.out.println(format.toPattern()); // #,##0.###
    System.out.println(format.toLocalizedPattern()); // #.##0,###

    System.out.println(format.format(123000)); // 123.000
    System.out.println(format.format(0.456)); // 0,456
}

String toPattern ()

Synthesizes a pattern string that represents the current state of this Format object.

Please see toLocalizedPattern().

Methods declared in NumberFormat

format, format, getAvailableLocales, getCompactNumberInstance, getCompactNumberInstance, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getNumberInstance, getNumberInstance, getPercentInstance, getPercentInstance, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setGroupingUsed, setParseIntegerOnly

Please see the link below.

Methods declared in Format

format, parseObject

Please see the link below.


Related posts

Internationalization

Number

To top of page