Java Doc for NumberFormat.java in  » 6.0-JDK-Core » text » java » text » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

 NumberFormat nf = NumberFormat.getInstance();
 for (int i = 0; i < myNumber.length; ++i) {
 output.println(nf.format(myNumber[i]) + "; ");
 }
 

 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
 

 myNumber = nf.parse(myString);
 

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

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.
See Also:   DecimalFormat
See Also:   ChoiceFormat
version:
   1.80, 05/05/07
author:
   Mark Davis
author:
   Helena Shih

This implementation extracts the number's value using java.lang.Number.longValue for all integral type values that can be converted to long without loss of information, including BigInteger values with a java.math.BigInteger.bitLength bit length of less than 64, and java.lang.Number.doubleValue for all other types.

See the NumberFormat.parse(String,ParsePosition) method for more information on number parsing.
Parameters:
  source - A String whose beginning should be parsed.

The method attempts to parse text starting at the index given by pos. If parsing succeeds, then the index of pos is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed number is returned.

This implementation extracts the number's value using java.lang.Number.longValue for all integral type values that can be converted to long without loss of information, including BigInteger values with a java.math.BigInteger.bitLength bit length of less than 64, and java.lang.Number.doubleValue for all other types. It then calls NumberFormat.format(long,java.lang.StringBuffer,java.text.FieldPosition) or NumberFormat.format(double,java.lang.StringBuffer,java.text.FieldPosition) . This may result in loss of magnitude information and precision for BigInteger and BigDecimal values.
Parameters:
  number - the number to format
Parameters:
  toAppendTo - the StringBuffer to which the formattedtext is to be appended
Parameters:
  pos - On input: an alignment field, if desired.On output: the offsets of the alignment field. the value passed in as toAppendTo
exception:
  IllegalArgumentException - if number isnull or not an instance of Number.
exception:
  NullPointerException - if toAppendTo orpos is null
exception:
  ArithmeticException - if rounding is needed with roundingmode being set to RoundingMode.UNNECESSARY
See Also:   java.text.FieldPosition

The default implementation throws UnsupportedOperationException. the currency used by this number format, or null
exception:
  UnsupportedOperationException - if the number format classdoesn't implement currency formatting
since:
   1.4

See the NumberFormat.parse(String,ParsePosition) method for more information on number parsing.
Parameters:
  source - A String whose beginning should be parsed. A Number parsed from the string.
exception:
  ParseException - if the beginning of the specified stringcannot be parsed.

The method attempts to parse text starting at the index given by pos. If parsing succeeds, then the index of pos is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string), and the parsed number is returned. The updated pos can be used to indicate the starting point for the next call to this method. If an error occurs, then the index of pos is not changed, the error index of pos is set to the index of the character where the error occurred, and null is returned.

See the NumberFormat.parse(String,ParsePosition) method for more information on number parsing.
Parameters:
  source - A String, part of which should be parsed.
Parameters:
  pos - A ParsePosition object with index and errorindex information as described above. A Number parsed from the string. In case oferror, returns null.
exception:
  NullPointerException - if pos is null.

The default implementation throws UnsupportedOperationException.
Parameters:
  currency - the new currency to be used by this number format
exception:
  UnsupportedOperationException - if the number format classdoesn't implement currency formatting
exception:
  NullPointerException - if currency is null
since:
   1.4