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
| 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 (\u005Cu2030) | Prefix or suffix | Yes | Multiply by 1000 and show as per mille |
\u00A4 (\u005Cu00A4) | 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 | := | '\u005Cu0000'..'\u005CuFFFD' - specialCharacters |
| suffix | := | '\u005Cu0000'..'\u005CuFFFD' - specialCharacters |
| integer | := | '#'* '0'*'0' |
| fraction | := | '0'* '#'* |
| sigDigits | := | '#'* '@''@'* '#'* |
| exponent | := | 'E' '+'? '0'* '0' |
| padSpec | := | '*' padChar |
| padChar | := | '\u005Cu0000'..'\u005CuFFFD' - 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.
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. This is an enhanced version of NumberFormat that is based on the standard version in the JDK. New or changed functionality is labeled NEW or CHANGED.
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:
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.myString = NumberFormat.getInstance().format(myNumber);
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. You can also use aNumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
NumberFormat to parse numbers: UsemyNumber = nf.parse(myString);
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 is 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 '6') if false, "3456.78" -> 3456.78 (and leaves the parse position just after '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 on DecimalFormat.
You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to:
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. 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. 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.
DecimalFormat is the concrete implementation of NumberFormat, and the NumberFormat API is essentially an abstraction from DecimalFormat's API. Refer to DecimalFormat for more information about this API.
see DecimalFormat see java.text.ChoiceFormat @author Mark Davis @author Helena Shih @author Alan Liu @stable ICU 2.0NumberFormat 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:
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.myString = NumberFormat.getInstance().format(myNumber);
NumberFormat nf = NumberFormat.getInstance(); for (int i = 0; i < myNumber.length; ++i) { output.println(nf.format(myNumber[i]) + "; "); } To format a number for a different Locale, specify it in the call to getInstance. You can also use aNumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
NumberFormat to parse numbers: UsemyNumber = nf.parse(myString);
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:
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. 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. 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 DecimalFormat @see ChoiceFormat @version 1.74, 11/17/05 @author Mark Davis @author Helena Shih
| |
| |
| |
| |
| |
| |
| |
| |
| |