← 返回首页
NumberFormat (Java SE 26 & JDK 26)
JavaScript is disabled on your browser.
  1. java.base
  2. java.text
  3. NumberFormat
Contents  
  1. Description
    1. Getting a NumberFormat
      1. Locale Extensions
    2. Using NumberFormat
    3. Customizing NumberFormat
    4. Leniency
    5. Synchronization
  2. Nested Class Summary
  3. Field Summary
  4. Constructor Summary
  5. Method Summary
    1. Methods declared in class Format
    2. Methods declared in class Object
  6. Field Details
    1. INTEGER_FIELD
    2. FRACTION_FIELD
  7. Constructor Details
    1. NumberFormat()
  8. Method Details
    1. format(Object, StringBuffer, FieldPosition)
    2. parseObject(String, ParsePosition)
    3. format(double)
    4. format(long)
    5. format(double, StringBuffer, FieldPosition)
    6. format(long, StringBuffer, FieldPosition)
    7. parse(String, ParsePosition)
    8. parse(String)
    9. isParseIntegerOnly()
    10. setParseIntegerOnly(boolean)
    11. isStrict()
    12. setStrict(boolean)
    13. getInstance()
    14. getInstance(Locale)
    15. getNumberInstance()
    16. getNumberInstance(Locale)
    17. getIntegerInstance()
    18. getIntegerInstance(Locale)
    19. getCurrencyInstance()
    20. getCurrencyInstance(Locale)
    21. getPercentInstance()
    22. getPercentInstance(Locale)
    23. getCompactNumberInstance()
    24. getCompactNumberInstance(Locale, NumberFormat.Style)
    25. getAvailableLocales()
    26. hashCode()
    27. equals(Object)
    28. clone()
    29. isGroupingUsed()
    30. setGroupingUsed(boolean)
    31. getMaximumIntegerDigits()
    32. setMaximumIntegerDigits(int)
    33. getMinimumIntegerDigits()
    34. setMinimumIntegerDigits(int)
    35. getMaximumFractionDigits()
    36. setMaximumFractionDigits(int)
    37. getMinimumFractionDigits()
    38. setMinimumFractionDigits(int)
    39. getCurrency()
    40. setCurrency(Currency)
    41. getRoundingMode()
    42. setRoundingMode(RoundingMode)
Hide sidebar  Show sidebar

Class NumberFormat

java.lang.Object
java.text.Format
java.text.NumberFormat
All Implemented Interfaces: Serializable, Cloneable Direct Known Subclasses: ChoiceFormat, CompactNumberFormat, DecimalFormat
public abstract class NumberFormat extends Format
NumberFormat is the abstract base class for all number formats. This class provides the interface for formatting and parsing numbers in a localized manner. This enables code that can be completely independent of the locale conventions for decimal points, thousands-separators, the particular decimal digits used, or whether the number format is even decimal. For example, this class could be used within an application to produce a number in a currency format according to the conventions of the desired locale.

Getting a NumberFormat

To get a NumberFormat for the default Locale, use one of the static factory methods that return a concrete subclass of NumberFormat. The following formats all provide an example of formatting the Number "2000.50" with the US locale as the default locale. Alternatively, if a NumberFormat for a different locale is required, use one of the overloaded factory methods that take Locale as a parameter, for example, getIntegerInstance(Locale). If the installed locale-sensitive service implementation does not support the given Locale, the parent locale chain will be looked up, and a Locale used that is supported.

Locale Extensions

Formatting behavior can be changed when using a locale that contains any of the following Unicode extensions,

For both "nu" and "cu", if they are specified in addition to "rg", the respective values from the "nu" and "cu" extension supersede the implicit ones from the "rg" extension. Although Unicode extensions defines various keys and values, actual locale-sensitive service implementations in a Java Runtime Environment might not support any particular Unicode locale attributes or key/type pairs.

Below is an example of a "US" locale currency format with accounting style, NumberFormat.getCurrencyInstance(Locale.forLanguageTag("en-US-u-cf-account")); With this style, a negative value is formatted enclosed in parentheses, instead of being prepended with a minus sign.

Using NumberFormat

The following is an example of formatting and parsing in a localized fashion,
Copy NumberFormat currencyFormat = NumberFormat.getCurrencyInstance(Locale.US); currencyFormat.format(100000); // returns "$100,000.00" currencyFormat.parse("$100,000.00"); // returns 100000

Customizing NumberFormat

NumberFormat provides API to customize formatting and parsing behavior,
  • setParseIntegerOnly(boolean); when true, will only return the integer portion of the number parsed from the String.
  • setMinimumFractionDigits(int); Use to adjust the expected digits when formatting. Use any of the other minimum/maximum or fraction/integer setter methods in the same manner. These methods have no impact on parsing behavior.
  • setGroupingUsed(boolean); when true, formatted numbers will be displayed with grouping separators. Additionally, when false, parsing will not expect grouping separators in the parsed String.
  • setStrict(boolean); when true, parsing will be done strictly. The behavior of strict parsing should be referred to in the implementing NumberFormat subclass.

To provide more control over formatting or parsing behavior, type checking can be done to safely convert to an implementing subclass of NumberFormat; this provides additional methods defined by the subclass. For example,

Copy NumberFormat nFmt = NumberFormat.getInstance(Locale.US); if (nFmt instanceof DecimalFormat dFmt) { dFmt.setDecimalSeparatorAlwaysShown(true); dFmt.format(100); // returns "100." }
The NumberFormat subclass returned by the factory methods is dependent on the locale-service provider implementation installed, and may not always be DecimalFormat or CompactNumberFormat.

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to:

  • Progressively parse through pieces of a string
  • Align the decimal point and other areas
For example, you can align numbers in two ways:
  1. If you are using a monospaced font with spacing for alignment, you can pass the FieldPosition in your format call, with field = INTEGER_FIELD. On output, getEndIndex will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.
  2. If you are using proportional fonts, instead of padding with spaces, measure the width of the string in pixels from the start to getEndIndex. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. It also works where there is no decimal, but possibly additional characters at the end, e.g., with parentheses in negative numbers: "(12)" for -12.

Leniency

NumberFormat by default, parses leniently. Subclasses may consider implementing strict parsing and as such, overriding and providing implementations for the optional isStrict() and setStrict(boolean) methods.

Lenient parsing should be used when attempting to parse a number out of a String that contains non-numerical or non-format related values. For example, using a Locale.US currency format to parse the number 1000 out of the String "$1,000.00 was paid". Lenient parsing also allows loose matching of characters in the source text. For example, an implementation of the NumberFormat class may allow matching "−" (U+2212 MINUS SIGN) to the "-" (U+002D HYPHEN-MINUS) pattern character when used as a negative prefix.

Strict parsing should be used when attempting to ensure a String adheres exactly to a locale's conventions, and can thus serve to validate input. For example, successfully parsing the number 1000.55 out of the String "1.000,55" confirms the String exactly adhered to the Locale.GERMANY numerical conventions.

Synchronization

Number formats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.
Implementation Requirements: Null Parameter Handling Default RoundingMode Since: 1.1 External Specifications See Also:

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples. Other versions.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2026, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.

Scripting on this page tracks web page traffic, but does not change the content in any way.