java.lang.Object | |
↳ | com.google.gwt.i18n.client.NumberFormat |
Formats and parses numbers using locale-sensitive patterns. This class provides comprehensive and flexible support for a wide variety of localized formats, including
decimal
,
currency
,
percentages
, and
scientific
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
. 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 |
; |
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".
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.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
defaultNumberConstants | Current NumberConstants interface to use, see
setForcedLatinDigits(boolean) for changing it. |
||||||||||
localizedNumberConstants |
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a format object based on the specified settings.
| |||||||||||
Constructs a format object for the default locale based on the specified
settings.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns true if all new NumberFormat instances will use latin digits and
related characters rather than the localized ones.
| |||||||||||
This method formats a Number to produce a string.
| |||||||||||
This method formats a double to produce a string.
| |||||||||||
Provides the standard currency format for the default locale using a
specified currency.
| |||||||||||
Provides the standard currency format for the default locale using a
specified currency.
| |||||||||||
Provides the standard currency format for the default locale.
| |||||||||||
Provides the standard decimal format for the default locale.
| |||||||||||
Gets a custom
NumberFormat instance for the default locale
using the specified pattern and currency code. | |||||||||||
Gets a custom
NumberFormat instance for the default locale
using the specified pattern and currency code. | |||||||||||
Gets a
NumberFormat instance for the default locale using
the specified pattern and the default currencyCode. | |||||||||||
Returns the pattern used by this number format.
| |||||||||||
Provides the standard percent format for the default locale.
| |||||||||||
Provides the standard scientific format for the default locale.
| |||||||||||
Parses text to produce a numeric value.
| |||||||||||
Parses text to produce a numeric value.
| |||||||||||
Specify whether all new NumberFormat instances will use latin digits
and related characters rather than the localized ones.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Create a delocalized NumberConstants instance from a localized one.
| |||||||||||
Format a number with its significant digits already represented in string
form.
| |||||||||||
Format a possibly scaled long value.
| |||||||||||
Returns the number of digits between grouping separators in the integer
portion of a number.
| |||||||||||
Returns the prefix to use for negative values.
| |||||||||||
Returns the suffix to use for negative values.
| |||||||||||
Returns the NumberConstants instance for this formatter.
| |||||||||||
Returns the prefix to use for positive values.
| |||||||||||
Returns the suffix to use for positive values.
| |||||||||||
Returns true if the decimal separator should always be shown.
| |||||||||||
Remap a localized separator to an equivalent latin one.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Current NumberConstants interface to use, see
setForcedLatinDigits(boolean)
for changing it.
Constructs a format object based on the specified settings.
numberConstants | the locale-specific number constants to use for this
format -- **NOTE** subclasses passing their own instance here
should pay attention to forcedLatinDigits() and remap
localized symbols using
createLatinNumberConstants(NumberConstants) |
---|---|
pattern | pattern that specify how number should be formatted |
cdata | currency data that should be used |
userSuppliedPattern | true if the pattern was supplied by the user |
Constructs a format object for the default locale based on the specified settings.
pattern | pattern that specify how number should be formatted |
---|---|
cdata | currency data that should be used |
userSuppliedPattern | true if the pattern was supplied by the user |
Returns true if all new NumberFormat instances will use latin digits and related characters rather than the localized ones.
This method formats a Number to produce a string.
Any Number
which is not a BigDecimal
, BigInteger
,
or Long
instance is formatted as a double
value.
number | The Number instance to format |
---|
This method formats a double to produce a string.
number | The double to format |
---|
Provides the standard currency format for the default locale using a specified currency.
currencyCode | valid currency code, as defined in com.google.gwt.i18n.client.constants.CurrencyCodeMapConstants.properties |
---|
NumberFormat
capable of producing and consuming
currency format for the default localeIllegalArgumentException | if the currency code is unknown |
---|
Provides the standard currency format for the default locale using a specified currency.
currencyData | currency data to use |
---|
NumberFormat
capable of producing and consuming
currency format for the default locale
Provides the standard currency format for the default locale.
NumberFormat
capable of producing and consuming
currency format for the default locale
Provides the standard decimal format for the default locale.
NumberFormat
capable of producing and consuming
decimal format for the default locale
Gets a custom NumberFormat
instance for the default locale
using the specified pattern and currency code.
pattern | pattern for this formatter |
---|---|
currencyCode | international currency code |
IllegalArgumentException | if the specified pattern is invalid or the currency code is unknown |
---|
Gets a custom NumberFormat
instance for the default locale
using the specified pattern and currency code.
pattern | pattern for this formatter |
---|---|
currencyData | currency data |
IllegalArgumentException | if the specified pattern is invalid |
---|
Gets a NumberFormat
instance for the default locale using
the specified pattern and the default currencyCode.
pattern | pattern for this formatter |
---|
IllegalArgumentException | if the specified pattern is invalid |
---|
Provides the standard percent format for the default locale.
NumberFormat
capable of producing and consuming
percent format for the default locale
Provides the standard scientific format for the default locale.
NumberFormat
capable of producing and consuming
scientific format for the default locale
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.
text | the string to be parsed |
---|---|
inOutPos | position to pass in and get back |
NumberFormatException | if the text segment could not be converted into a double |
---|
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.
text | the string being parsed |
---|
NumberFormatException | if the entire text could not be converted into a double |
---|
Specify whether all new NumberFormat instances will use latin digits and related characters rather than the localized ones.
useLatinDigits | true if latin digits/etc should be used, false if localized digits/etc should be used. |
---|
Create a delocalized NumberConstants instance from a localized one.
orig | localized NumberConstants instance |
---|
Format a number with its significant digits already represented in string form. This is done so both double and BigInteger/Decimal formatting can share code without requiring all users to pay the code size penalty for BigDecimal/etc.
Example values passed in:
isNegative=true, digits="13", scale=2
isNegative=false, digits="314158", scale=-5
isNegative=false, digits="1" ("0001" would be ok), scale=-4
isNegative | true if the value to be formatted is negative |
---|---|
digits | a StringBuilder containing just the significant digits in the value to be formatted, the formatted result will be left here |
scale | the number of places to the right the decimal point should be moved in the digit string -- negative means the value contains fractional digits |
Format a possibly scaled long value.
value | value to format |
---|---|
scale | the number of places to the right the decimal point should be moved in the digit string -- negative means the value contains fractional digits |
Returns the number of digits between grouping separators in the integer portion of a number.
Returns the NumberConstants instance for this formatter.
Returns true if the decimal separator should always be shown.
Remap a localized separator to an equivalent latin one.