Class: java.text.NumberFormat

  • 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. NumberFormat also provides methods for determining which locales have number formats, and what their names are.

NumberFormat helps you to format and parse numbers for any locale. Your code can be completely independent of the locale conventions for decimal points, thousands-separators, or even the particular decimal digits used, or whether the number format is even decimal.

To format a number for the current Locale, use one of the factory class methods: 

  myString = NumberFormat.getInstance().format(myNumber);
If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times. 
 NumberFormat nf = NumberFormat.getInstance();
 for (int i = 0; i < a.length; ++i) {
     output.println(nf.format(myNumber[i]) + "; ");
 }
To format a number for a different Locale, specify it in the call to getInstance. 
 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
You can also use a NumberFormat to parse numbers: 
 myNumber = nf.parse(myString);
Use getInstance or getNumberInstance to get the normal number format. Use getIntegerInstance to get an integer number format. Use getCurrencyInstance to get the currency number format. And use getPercentInstance to get a format for displaying percentages. With this format, a fraction like 0.53 is displayed as 53%.

You can also control the display of numbers with such methods as setMinimumFractionDigits. If you want even more control over the format or parsing, or want to give your users more control, you can try casting the NumberFormat you get from the factory methods to a DecimalFormat. This will work for the vast majority of locales; just remember to put it in a try block in case you encounter an unusual one.

NumberFormat and DecimalFormat are designed such that some controls work for formatting and others work for parsing. The following is the detailed description for each these control methods,

setParseIntegerOnly : only affects parsing, e.g. if true, "3456.78" -> 3456 (and leaves the parse position just after index 6) if false, "3456.78" -> 3456.78 (and leaves the parse position just after index 8) This is independent of formatting. If you want to not show a decimal point where there might be no digits after the decimal point, use setDecimalSeparatorAlwaysShown.

setDecimalSeparatorAlwaysShown : only affects formatting, and only where there might be no digits after the decimal point, such as with a pattern like "#,##0.##", e.g., if true, 3456.00 -> "3,456." if false, 3456.00 -> "3456" This is independent of parsing. If you want parsing to stop at the decimal point, use setParseIntegerOnly.

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.

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.

Authors:
@author Mark Davis
@author Helena Shih
See:
@see java.text.DecimalFormat
@see java.text.ChoiceFormat
Version:
@version 1.65, 05/10/04

Inheritance

Superclass tree: Implements:

Methods

Fields

  • CURRENCYSTYLE

    static final private int CURRENCYSTYLE = 1

  • FRACTION_FIELD

    public static final int FRACTION_FIELD = 1
    Field constant used to construct a FieldPosition object. Signifies that the position of the fraction part of a formatted number should be returned.

  • INTEGERSTYLE

    static final private int INTEGERSTYLE = 4

  • INTEGER_FIELD

    public static final int INTEGER_FIELD = 0
    Field constant used to construct a FieldPosition object. Signifies that the position of the integer part of a formatted number should be returned.

  • NUMBERSTYLE

    static final private int NUMBERSTYLE = 0

  • PERCENTSTYLE

    static final private int PERCENTSTYLE = 2

  • SCIENTIFICSTYLE

    static final private int SCIENTIFICSTYLE = 3

  • cachedLocaleData

    static final private Hashtable cachedLocaleData
    Cache to hold the NumberPatterns of a Locale.

  • currentSerialVersion

    static final int currentSerialVersion = 1

  • groupingUsed

    private boolean groupingUsed
    True if the the grouping (i.e. thousands) separator is used when formatting and parsing numbers.

  • maxFractionDigits

    private byte maxFractionDigits
    The maximum number of digits allowed in the fractional portion of a number. maximumFractionDigits must be greater than or equal to minimumFractionDigits.

    Note: This field exists only for serialization compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new int field maximumFractionDigits is used instead. When writing to a stream, maxFractionDigits is set to maximumFractionDigits or Byte.MAX_VALUE, whichever is smaller. When reading from a stream, this field is used only if serialVersionOnStream is less than 1.

  • maxIntegerDigits

    private byte maxIntegerDigits
    The maximum number of digits allowed in the integer portion of a number. maxIntegerDigits must be greater than or equal to minIntegerDigits.

    Note: This field exists only for serialization compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new int field maximumIntegerDigits is used instead. When writing to a stream, maxIntegerDigits is set to maximumIntegerDigits or Byte.MAX_VALUE, whichever is smaller. When reading from a stream, this field is used only if serialVersionOnStream is less than 1.

  • maximumFractionDigits

    private int maximumFractionDigits
    The maximum number of digits allowed in the fractional portion of a number. maximumFractionDigits must be greater than or equal to minimumFractionDigits.

  • maximumIntegerDigits

    private int maximumIntegerDigits
    The maximum number of digits allowed in the integer portion of a number. maximumIntegerDigits must be greater than or equal to minimumIntegerDigits.

  • minFractionDigits

    private byte minFractionDigits
    The minimum number of digits allowed in the fractional portion of a number. minimumFractionDigits must be less than or equal to maximumFractionDigits.

    Note: This field exists only for serialization compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new int field minimumFractionDigits is used instead. When writing to a stream, minFractionDigits is set to minimumFractionDigits or Byte.MAX_VALUE, whichever is smaller. When reading from a stream, this field is used only if serialVersionOnStream is less than 1.

  • minIntegerDigits

    private byte minIntegerDigits
    The minimum number of digits allowed in the integer portion of a number. minimumIntegerDigits must be less than or equal to maximumIntegerDigits.

    Note: This field exists only for serialization compatibility with JDK 1.1. In Java platform 2 v1.2 and higher, the new int field minimumIntegerDigits is used instead. When writing to a stream, minIntegerDigits is set to minimumIntegerDigits or Byte.MAX_VALUE, whichever is smaller. When reading from a stream, this field is used only if serialVersionOnStream is less than 1.

  • minimumFractionDigits

    private int minimumFractionDigits
    The minimum number of digits allowed in the fractional portion of a number. minimumFractionDigits must be less than or equal to maximumFractionDigits.

  • minimumIntegerDigits

    private int minimumIntegerDigits
    The minimum number of digits allowed in the integer portion of a number. minimumIntegerDigits must be less than or equal to maximumIntegerDigits.

  • parseIntegerOnly

    private boolean parseIntegerOnly
    True if this format will parse numbers as integers only.

  • serialVersionOnStream

    private int serialVersionOnStream
    Describes the version of NumberFormat present on the stream. Possible values are:
    • 0 (or uninitialized): the JDK 1.1 version of the stream format. In this version, the int fields such as maximumIntegerDigits were not present, and the byte fields such as maxIntegerDigits are used instead.
    • 1: the 1.2 version of the stream format. The values of the byte fields such as maxIntegerDigits are ignored, and the int fields such as maximumIntegerDigits are used instead.
    When streaming out a NumberFormat, the most recent format (corresponding to the highest allowable serialVersionOnStream) is always written.

  • serialVersionUID

    static final long serialVersionUID = -2308460125733713944