Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.gwt.i18n.client
Class NumberFormat

    java.lang.Object
      com.google.gwt.i18n.client.NumberFormat

    public class NumberFormat

extends java.lang.Object

Formats and parses numbers using locale-sensitive patterns. This class provides comprehensive and flexible support for a wide variety of localized formats, including

- Locale-specific symbols such as decimal point, group separator, digit representation, currency symbol, percent, and permill
- Numeric variations including integers ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency amounts ("$123")
- Predefined standard patterns that can be used both for parsing and formatting, including `decimal`, `currency`, `percentages`, and `scientific`
- Custom patterns and supporting features designed to make it possible to parse and format numbers in any locale, including support for Western, Arabic, and Indic digits

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

Symbol | Location | Localized? | Meaning
--- | --- | --- | ---
`0` | Number | Yes | Digit
`#` | Number | Yes | Digit, zero shows as absent
`.` | Number | Yes | Decimal separator or monetary decimal separator
`-` | Number | Yes | Minus sign
`,` | Number | Yes | Grouping separator
`E` | Number | Yes | Separates mantissa and exponent in scientific notation; need not be quoted in prefix or suffix
`E` | Subpattern boundary | Yes | Separates positive and negative subpatterns
`%` | Prefix or suffix | Yes | Multiply by 100 and show as percentage
`‰` (\u2030) | Prefix or suffix | Yes | Multiply by 1000 and show as per mille
`¤` (\u00A4) | Prefix or suffix | No | Currency sign, replaced by currency symbol; if doubled, replaced by international currency symbol; if present in a pattern, the monetary decimal separator is used instead of the decimal separator
`'` | Prefix or suffix | No | Used to quote special characters in a prefix or suffix; for example, `"'#'#"` formats `123` to `"#123"`; to create a single quote itself, use two in succession, such as `"# o''clock"`

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:

pattern | := | subpattern ('`;`' subpattern)?
subpattern | := | prefix? number exponent? suffix?
number | := | (integer ('`.`' fraction)?) | sigDigits
prefix | := | '`\u0000`'..'`\uFFFD`' - specialCharacters
suffix | := | '`\u0000`'..'`\uFFFD`' - specialCharacters
integer | := | '`#`'* '`0`'*'`0`'
fraction | := | '`0`'* '`#`'*
sigDigits | := | '`#`'* '`@`''`@`'* '`#`'*
exponent | := | '`E`' '`+`'? '`0`'* '`0`'
padSpec | := | '`*`' padChar
padChar | := | '`\u0000`'..'`\uFFFD`' - quote

Notation:

X* | 0 or more instances of X
X? | 0 or 1 instances of X
X|Y | either X or Y
C..D | any character from C up to D, inclusive
S-T | characters in S, except those in T

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

### Example

>     public class NumberFormatExample implements EntryPoint {

>       public void onModuleLoad() {
>         NumberFormat fmt = NumberFormat.getDecimalFormat();
>         double value = 12345.6789;
>         String formatted = fmt.format(value);
>         // Prints 1,2345.6789 in the default locale
>         GWT.log("Formatted string is" + formatted, null);

>         // Turn a string back into a double
>         value = NumberFormat.getDecimalFormat().parse("12345.6789");
>         GWT.log("Parsed value is" + value, null);

>         // Scientific notation
>         value = 12345.6789;
>         formatted = NumberFormat.getScientificFormat().format(value);
>         // prints 1.2345E4 in the default locale
>         GWT.log("Formatted string is" + formatted, null);

>         // Currency
>         fmt = NumberFormat.getCurrencyFormat();
>         formatted = fmt.format(123456.7899);
>         // prints $123,456.79 in the default locale
>         GWT.log("Formatted currency is" + formatted, null);

>         // Custom format
>         value = 12345.6789;
>         formatted = NumberFormat.getFormat("000000.000000").format(value);
>         // prints 012345.678900 in the default locale
>         GWT.log("Formatted string is" + formatted, null);
>       }
>     }

Constructor Summary
`protected` | `NumberFormat(com.google.gwt.i18n.client.constants.NumberConstants numberConstants, com.google.gwt.i18n.client.constants.CurrencyCodeMapConstants currencyCodeMapConstants, java.lang.String pattern, java.lang.String currencyCode)` Constructs a format object based on the specified settings.
`protected` | `NumberFormat(java.lang.String pattern, java.lang.String currencyCode)` Constructs a format object for the default locale based on the specified settings.

Method Summary
`java.lang.String` | `format(double number)` This method formats a double to produce a string.
`static NumberFormat` | `getCurrencyFormat()` Provides the standard currency format for the default locale.
`static NumberFormat` | `getCurrencyFormat(java.lang.String currencyCode)` Provides the standard currency format for the default locale using a specified currency.
`static NumberFormat` | `getDecimalFormat()` Provides the standard decimal format for the default locale.
`static NumberFormat` | `getFormat(java.lang.String pattern)` Gets a `NumberFormat` instance for the default locale using the specified pattern and the default currencyCode.
`static NumberFormat` | `getFormat(java.lang.String pattern, java.lang.String currencyCode)` Gets a custom `NumberFormat` instance for the default locale using the specified pattern and currency code.
`java.lang.String` | `getPattern()` Returns the pattern used by this number format.
`static NumberFormat` | `getPercentFormat()` Provides the standard percent format for the default locale.
`static NumberFormat` | `getScientificFormat()` Provides the standard scientific format for the default locale.
`double` | `parse(java.lang.String text)` Parses text to produce a numeric value.
`double` | `parse(java.lang.String text, int[] inOutPos)` Parses text to produce a numeric value.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### NumberFormat

    protected NumberFormat(com.google.gwt.i18n.client.constants.NumberConstants numberConstants,
                           com.google.gwt.i18n.client.constants.CurrencyCodeMapConstants currencyCodeMapConstants,
                           java.lang.String pattern,
                           java.lang.String currencyCode)

  Constructs a format object based on the specified settings.

  Parameters:
    `numberConstants` - the locale-specific number constants to use for this format
    `currencyCodeMapConstants` - the locale-specific currency code map to use for this format
    `pattern` - pattern that specify how number should be formatted
    `currencyCode` - currency that should be used

### NumberFormat

    protected NumberFormat(java.lang.String pattern,
                           java.lang.String currencyCode)

  Constructs a format object for the default locale based on the specified settings.

  Parameters:
    `pattern` - pattern that specify how number should be formatted
    `currencyCode` - currency that should be used

Method Detail

### getCurrencyFormat

    public static NumberFormat getCurrencyFormat()

  Provides the standard currency format for the default locale.

  Returns:
    a `NumberFormat` capable of producing and consuming currency format for the default locale

### getCurrencyFormat

    public static NumberFormat getCurrencyFormat(java.lang.String currencyCode)

  Provides the standard currency format for the default locale using a specified currency.

  Parameters:
    `currencyCode` - valid currency code, as defined in com.google.gwt.i18n.client.constants.CurrencyCodeMapConstants.properties
  Returns:
    a `NumberFormat` capable of producing and consuming currency format for the default locale

### getDecimalFormat

    public static NumberFormat getDecimalFormat()

  Provides the standard decimal format for the default locale.

  Returns:
    a `NumberFormat` capable of producing and consuming decimal format for the default locale

### getFormat

    public static NumberFormat getFormat(java.lang.String pattern)

  Gets a `NumberFormat` instance for the default locale using the specified pattern and the default currencyCode.

  Parameters:
    `pattern` - pattern for this formatter
  Returns:
    a NumberFormat instance
  Throws:
    `java.lang.IllegalArgumentException` - if the specified pattern is invalid

### getFormat

    public static NumberFormat getFormat(java.lang.String pattern,
                                         java.lang.String currencyCode)

  Gets a custom `NumberFormat` instance for the default locale using the specified pattern and currency code.

  Parameters:
    `pattern` - pattern for this formatter
    `currencyCode` - international currency code
  Returns:
    a NumberFormat instance
  Throws:
    `java.lang.IllegalArgumentException` - if the specified pattern is invalid

### getPercentFormat

    public static NumberFormat getPercentFormat()

  Provides the standard percent format for the default locale.

  Returns:
    a `NumberFormat` capable of producing and consuming percent format for the default locale

### getScientificFormat

    public static NumberFormat getScientificFormat()

  Provides the standard scientific format for the default locale.

  Returns:
    a `NumberFormat` capable of producing and consuming scientific format for the default locale

### format

    public java.lang.String format(double number)

  This method formats a double to produce a string.

  Parameters:
    `number` - The double to format
  Returns:
    the formatted number string

### getPattern

    public java.lang.String getPattern()

  Returns the pattern used by this number format.

### parse

    public double parse(java.lang.String text)
                 throws java.lang.NumberFormatException

  Parses text to produce a numeric value. A `NumberFormatException` is thrown if either the text is empty or if the parse does not consume all characters of the text.

  Parameters:
    `text` - the string being parsed
  Returns:
    a parsed number value
  Throws:
    `java.lang.NumberFormatException` - if the entire text could not be converted into a number

### parse

    public double parse(java.lang.String text,
                        int[] inOutPos)
                 throws java.lang.NumberFormatException

  Parses text to produce a numeric value.

  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.

  Parameters:
    `text` - the string to be parsed
    `inOutPos` - position to pass in and get back
  Returns:
    a double value representing the parsed number, or `0.0` if the parse fails
  Throws:
    `java.lang.NumberFormatException` - if the text segment could not be converted into a number

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD