Formats and parses numbers using locale-sensitive patterns.

This class provides comprehensive and flexible support for a wide variety of localized formats, including <ul> <li><b>Locale-specific symbols</b> such as decimal point, group separator, digit representation, currency symbol, percent, and permill</li> <li><b>Numeric variations</b> including integers ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency amounts ("$123")</li> <li><b>Predefined standard patterns</b> that can be used both for parsing and formatting, including {@link #getDecimalFormat() decimal}, {@link #getCurrencyFormat() currency}, {@link #getPercentFormat() percentages}, and {@link #getScientificFormat() scientific}</li> <li><b>Custom patterns</b> and supporting features designed to make it possible to parse and format numbers in any locale, including support for Western, Arabic, and Indic digits</li> </ul>

Patterns

Formatting and parsing are based on customizable patterns that can include a combination of literal characters and special characters that act as placeholders and are replaced by their localized counterparts. Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit.

Often the replacement character is the same as the pattern character. In the U.S. locale, for example, the ',' grouping character is replaced by the same character ','. However, the replacement is still actually happening, and in a different locale, the grouping character may change to a different character, such as '.'. Some special characters affect the behavior of the formatter by their presence. For example, if the percent character is seen, then the value is multiplied by 100 before being displayed.

The characters listed below are used in patterns. Localized symbols use the corresponding characters taken from corresponding locale symbol collection, which can be found in the properties files residing in the com.google.gwt.i18n.client.constants. To insert a special character in a pattern as a literal (that is, without any special meaning) the character must be quoted. There are some exceptions to this which are noted below.

</table>

A NumberFormat pattern contains a postive and negative subpattern separated by a semicolon, such as "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part, and a suffix. If there is no explicit negative subpattern, the negative subpattern is the localized minus sign prefixed to the positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are ignored in the negative subpattern. That means that "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)".

The prefixes, suffixes, and various symbols used for infinity, digits, thousands separators, decimal separators, etc. may be set to arbitrary values, and they will appear properly during formatting. However, care must be taken that the symbols and strings do not conflict, or parsing will be unreliable. For example, the decimal separator and thousands separator should be distinct characters, or parsing will be impossible.

The grouping separator is a character that separates clusters of integer digits to make large numbers more legible. It commonly used for thousands, but in some locales it separates ten-thousands. The grouping size is the number of digits between the grouping separators, such as 3 for "100,000,000" or 4 for "1 0000 0000".

Pattern Grammar (BNF)

The pattern itself uses the following grammar:

Notation:

The first subpattern is for positive numbers. The second (optional) subpattern is for negative numbers.

<h3>Example</h3> {@example com.google.gwt.examples.NumberFormatExample}

class NumberFormat {

 static NumberFormat _cachedDecimalFormat;

 static NumberFormat getDecimalFormat() {
   if (_cachedDecimalFormat == null) {
     _cachedDecimalFormat = new NumberFormat._internal();
   }
   return _cachedDecimalFormat;
 }

 NumberFormat._internal();

 /**
  * This method formats a double to produce a string.
  *
  * @param number The double to format
  * @return the formatted number string
  */
 String formatDouble(double number) {
   if (number.isNaN) {
     return "NaN";
   }
   return number.toString();
 }

 /**
  * This method formats a Number to produce a string.
  * <p>
  * Any {@link Number} which is not a {@link BigDecimal}, {@link BigInteger},
  * or {@link Long} instance is formatted as a {@code double} value.
  *
  * @param number The Number instance to format
  * @return the formatted number string
  */
 String formatInt(int number) {
   if (number.isNaN) {
     return "NaN";
   }
   return number.toString();
 }

 /**
  * This method formats a Number to produce a string.
  * <p>
  * Any {@link Number} which is not a {@link BigDecimal}, {@link BigInteger},
  * or {@link Long} instance is formatted as a {@code double} value.
  *
  * @param number The Number instance to format
  * @return the formatted number string
  */
 String format(num number) {
   if (number is int) {
     return formatInt(number as int);
   } else {
     return formatDouble(number as double);
   }
   throw new Exception("Unknown type");
 }
}