com.ibm.icu.text

Class DecimalFormat

public class DecimalFormat extends NumberFormat

DecimalFormat is a concrete subclass of NumberFormat that formats decimal numbers. It has a variety of features designed to make it possible to parse and format numbers in any locale, including support for Western, Arabic, or Indic digits. It also supports different flavors of numbers, including integers ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency amounts ("$123"). All of these flavors can be easily localized.

This is an enhanced version of DecimalFormat that is based on the standard version in the JDK. New or changed functionality is labeled NEW or CHANGED.

To obtain a NumberFormat for a specific locale (including the default locale) call one of NumberFormat's factory methods such as NumberFormat. Do not call the DecimalFormat constructors directly, unless you know what you are doing, since the NumberFormat factory methods may return subclasses other than DecimalFormat. If you need to customize the format object, do something like this:

 NumberFormat f = NumberFormat.getInstance(loc);
 if (f instanceof DecimalFormat) {
     ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true);
 }

Example Usage

 // Print out a number using the localized number, currency,
 // and percent format for each locale
 Locale[] locales = NumberFormat.getAvailableLocales();
 double myNumber = -1234.56;
 NumberFormat format;
 for (int j=0; j<3; ++j) {
     System.out.println("FORMAT");
     for (int i = 0; i < locales.length; ++i) {
         if (locales[i].getCountry().length() == 0) {
            // Skip language-only locales
            continue;
         }
         System.out.print(locales[i].getDisplayName());
         switch (j) {
         case 0:
             format = NumberFormat.getInstance(locales[i]); break;
         case 1:
             format = NumberFormat.getCurrencyInstance(locales[i]); break;
         default:
             format = NumberFormat.getPercentInstance(locales[i]); break;
         }
         try {
             // Assume format is a DecimalFormat
             System.out.print(": " + ((DecimalFormat) format).toPattern()
                              + " -> " + form.format(myNumber));
         } catch (Exception e) {}
         try {
             System.out.println(" -> " + format.parse(form.format(myNumber)));
         } catch (ParseException e) {}
     }
 }

Patterns

A DecimalFormat consists of a pattern and a set of symbols. The pattern may be set directly using DecimalFormat, or indirectly using other API methods which manipulate aspects of the pattern, such as the minimum number of integer digits. The symbols are stored in a DecimalFormatSymbols object. When using the NumberFormat factory methods, the pattern and symbols are read from ICU's locale data.

Special Pattern Characters

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, the ',' grouping character is replaced by ','. However, the replacement is still happening, and if the symbols are modified, the grouping character changes. 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.

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.

The characters listed here are used in non-localized patterns. Localized patterns use the corresponding characters taken from this formatter's DecimalFormatSymbols object instead, and these characters lose their special status. Two exceptions are the currency sign and quote, which are not localized.

Symbol Location Localized? Meaning
0 Number Yes Digit
1-9 Number Yes NEW '1' through '9' indicate rounding.
@ Number No NEW Significant 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.
+ Exponent Yes NEW Prefix positive exponents with localized plus sign. 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 a row: "# o''clock".
* Prefix or suffix boundary Yes NEW Pad escape, precedes pad character

A DecimalFormat pattern contains a postive and negative subpattern, for example, "#,##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, either the positive and negative prefixes or the suffixes must be distinct for DecimalFormat to be able to distinguish positive from negative values. Another example is that 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". There are actually two different grouping sizes: One used for the least significant integer digits, the primary grouping size, and one used for all others, the secondary grouping size. In most locales these are the same, but sometimes they are different. For example, if the primary grouping interval is 3, and the secondary is 2, then this corresponds to the pattern "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a pattern contains multiple grouping separators, the interval between the last one and the end of the integer defines the primary grouping size, and the interval between the last two defines the secondary grouping size. All others are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####".

Illegal patterns, such as "#.#.#" or "#.###,###", will cause DecimalFormat to throw an IllegalArgumentException with a message that describes the problem.

Pattern BNF

 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.

Not indicated in the BNF syntax above:

Parsing

DecimalFormat parses all Unicode characters that represent decimal digits, as defined by UCharacter. In addition, DecimalFormat also recognizes as digits the ten consecutive characters starting with the localized zero digit defined in the DecimalFormatSymbols object. During formatting, the DecimalFormatSymbols-based digits are output.

During parsing, grouping separators are ignored.

If DecimalFormat fails to parse a string, it returns null and leaves the parse position unchanged. The convenience method DecimalFormat indicates parse failure by throwing a java.text.ParseException.

Formatting

Formatting is guided by several parameters, all of which can be specified either using a pattern or using the API. The following description applies to formats that do not use scientific notation or significant digits.

Special Values

NaN is represented as a single character, typically \uFFFD. This character is determined by the DecimalFormatSymbols object. This is the only value for which the prefixes and suffixes are not used.

Infinity is represented as a single character, typically \u221E, with the positive or negative prefixes and suffixes applied. The infinity character is determined by the DecimalFormatSymbols object.

Scientific Notation

Numbers in scientific notation are expressed as the product of a mantissa and a power of ten, for example, 1234 can be expressed as 1.234 x 103. The mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0), but it need not be. DecimalFormat supports arbitrary mantissas. DecimalFormat can be instructed to use scientific notation through the API or through the pattern. In a pattern, the exponent character immediately followed by one or more digit characters indicates scientific notation. Example: "0.###E0" formats the number 1234 as "1.234E3".

NEW Significant Digits

DecimalFormat has two ways of controlling how many digits are shows: (a) significant digits counts, or (b) integer and fraction digit counts. Integer and fraction digit counts are described above. When a formatter is using significant digits counts, the number of integer and fraction digits is not specified directly, and the formatter settings for these counts are ignored. Instead, the formatter uses however many integer and fraction digits are required to display the specified number of significant digits. Examples:
Pattern Minimum significant digits Maximum significant digits Number Output of format()
@@@ 3 3 12345 12300
@@@ 3 3 0.12345 0.123
@@## 2 4 3.14159 3.142
@@## 2 4 1.23004 1.23

NEW Padding

DecimalFormat supports padding the result of DecimalFormat to a specific width. Padding may be specified either through the API or through the pattern syntax. In a pattern the pad escape character, followed by a single pad character, causes padding to be parsed and formatted. The pad escape character is '*' in unlocalized patterns, and can be localized using DecimalFormatSymbols. For example, "$*x#,##0.00" formats 123 to "$xx123.00", and 1234 to "$1,234.00".

NEW Rounding

DecimalFormat supports rounding to a specific increment. For example, 1230 rounded to the nearest 50 is 1250. 1.234 rounded to the nearest 0.65 is 1.3. The rounding increment may be specified through the API or in a pattern. To specify a rounding increment in a pattern, include the increment in the pattern itself. "#,#50" specifies a rounding increment of 50. "#,##0.05" specifies a rounding increment of 0.05.

Synchronization

DecimalFormat objects are not synchronized. Multiple threads should not access one formatter concurrently.

Author: Mark Davis Alan Liu

See Also: java.text.Format NumberFormat

UNKNOWN: ICU 2.0

Field Summary
static intPAD_AFTER_PREFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted after the prefix.
static intPAD_AFTER_SUFFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted after the suffix.
static intPAD_BEFORE_PREFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted before the prefix.
static intPAD_BEFORE_SUFFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted before the suffix.
Constructor Summary
DecimalFormat()
Create a DecimalFormat using the default pattern and symbols for the default locale.
DecimalFormat(String pattern)
Create a DecimalFormat from the given pattern and the symbols for the default locale.
DecimalFormat(String pattern, DecimalFormatSymbols symbols)
Create a DecimalFormat from the given pattern and symbols.
Method Summary
voidapplyLocalizedPattern(String pattern)
Apply the given pattern to this Format object.
voidapplyPattern(String pattern)
Apply the given pattern to this Format object.
booleanareSignificantDigitsUsed()
Returns true if significant digits are in use or false if integer and fraction digit counts are in use.
Objectclone()
Standard override; no change in semantics.
booleanequals(Object obj)
Overrides equals
StringBufferformat(double number, StringBuffer result, FieldPosition fieldPosition)
StringBufferformat(long number, StringBuffer result, FieldPosition fieldPosition)
StringBufferformat(BigInteger number, StringBuffer result, FieldPosition fieldPosition)
NEW Format a BigInteger number.
StringBufferformat(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)
NEW Format a BigDecimal number.
StringBufferformat(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)
NEW Format a BigDecimal number.
AttributedCharacterIteratorformatToCharacterIterator(Object obj)
Format the object to an attributed string, and return the corresponding iterator Overrides superclass method.
DecimalFormatSymbolsgetDecimalFormatSymbols()
Returns a copy of the decimal format symbols used by this format.
protected CurrencygetEffectiveCurrency()
Returns the currency in effect for this formatter.
intgetFormatWidth()
NEW Get the width to which the output of format() is padded.
intgetGroupingSize()
Return the grouping size.
intgetMaximumSignificantDigits()
Returns the maximum number of significant digits that will be displayed.
bytegetMinimumExponentDigits()
NEW Return the minimum exponent digits that will be shown.
intgetMinimumSignificantDigits()
Returns the minimum number of significant digits that will be displayed.
intgetMultiplier()
Get the multiplier for use in percent, permill, etc.
StringgetNegativePrefix()
Get the negative prefix.
StringgetNegativeSuffix()
Get the negative suffix.
chargetPadCharacter()
NEW Get the character used to pad to the format width.
intgetPadPosition()
NEW Get the position at which padding will take place.
StringgetPositivePrefix()
Get the positive prefix.
StringgetPositiveSuffix()
Get the positive suffix.
BigDecimalgetRoundingIncrement()
NEW Get the rounding increment.
intgetRoundingMode()
NEW Get the rounding mode.
intgetSecondaryGroupingSize()
Return the secondary grouping size.
inthashCode()
Overrides hashCode
booleanisDecimalSeparatorAlwaysShown()
Allows you to get the behavior of the decimal separator with integers.
booleanisExponentSignAlwaysShown()
NEW Return whether the exponent sign is always shown.
booleanisParseBigDecimal()
Returns whether DecimalFormat method returns BigDecimal.
booleanisScientificNotation()
NEW Return whether or not scientific notation is used.
Numberparse(String text, ParsePosition parsePosition)
CHANGED Parse the given string, returning a Number object to represent the parsed value.
voidsetCurrency(Currency theCurrency)
Sets the Currency object used to display currency amounts.
voidsetDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
Sets the decimal format symbols used by this format.
voidsetDecimalSeparatorAlwaysShown(boolean newValue)
Allows you to set the behavior of the decimal separator with integers.
voidsetExponentSignAlwaysShown(boolean expSignAlways)
NEW Set whether the exponent sign is always shown.
voidsetFormatWidth(int width)
NEW Set the width to which the output of format() is padded.
voidsetGroupingSize(int newValue)
Set the grouping size.
voidsetMaximumFractionDigits(int newValue)
Sets the maximum number of digits allowed in the fraction portion of a number.
voidsetMaximumIntegerDigits(int newValue)
Sets the maximum number of digits allowed in the integer portion of a number.
voidsetMaximumSignificantDigits(int max)
Sets the maximum number of significant digits that will be displayed.
voidsetMinimumExponentDigits(byte minExpDig)
NEW Set the minimum exponent digits that will be shown.
voidsetMinimumFractionDigits(int newValue)
Sets the minimum number of digits allowed in the fraction portion of a number.
voidsetMinimumIntegerDigits(int newValue)
Sets the minimum number of digits allowed in the integer portion of a number.
voidsetMinimumSignificantDigits(int min)
Sets the minimum number of significant digits that will be displayed.
voidsetMultiplier(int newValue)
Set the multiplier for use in percent, permill, etc.
voidsetNegativePrefix(String newValue)
Set the negative prefix.
voidsetNegativeSuffix(String newValue)
Set the positive suffix.
voidsetPadCharacter(char padChar)
NEW Set the character used to pad to the format width.
voidsetPadPosition(int padPos)
NEW Set the position at which padding will take place.
voidsetParseBigDecimal(boolean value)
Sets whether DecimalFormat method returns BigDecimal.
voidsetPositivePrefix(String newValue)
Set the positive prefix.
voidsetPositiveSuffix(String newValue)
Set the positive suffix.
voidsetRoundingIncrement(BigDecimal newValue)
NEW Set the rounding increment.
voidsetRoundingIncrement(BigDecimal newValue)
NEW Set the rounding increment.
voidsetRoundingIncrement(double newValue)
NEW Set the rounding increment.
voidsetRoundingMode(int roundingMode)
NEW Set the rounding mode.
voidsetScientificNotation(boolean useScientific)
NEW Set whether or not scientific notation is used.
voidsetSecondaryGroupingSize(int newValue)
Set the secondary grouping size.
voidsetSignificantDigitsUsed(boolean useSignificantDigits)
Sets whether significant digits are in use, or integer and fraction digit counts are in use.
StringtoLocalizedPattern()
Synthesizes a localized pattern string that represents the current state of this Format object.
StringtoPattern()
Synthesizes a pattern string that represents the current state of this Format object.

Field Detail

PAD_AFTER_PREFIX

public static final int PAD_AFTER_PREFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted after the prefix.

See Also: DecimalFormat DecimalFormat PAD_BEFORE_PREFIX PAD_BEFORE_SUFFIX PAD_AFTER_SUFFIX

UNKNOWN: ICU 2.0

PAD_AFTER_SUFFIX

public static final int PAD_AFTER_SUFFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted after the suffix.

See Also: DecimalFormat DecimalFormat PAD_BEFORE_PREFIX PAD_AFTER_PREFIX PAD_BEFORE_SUFFIX

UNKNOWN: ICU 2.0

PAD_BEFORE_PREFIX

public static final int PAD_BEFORE_PREFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted before the prefix.

See Also: DecimalFormat DecimalFormat PAD_AFTER_PREFIX PAD_BEFORE_SUFFIX PAD_AFTER_SUFFIX

UNKNOWN: ICU 2.0

PAD_BEFORE_SUFFIX

public static final int PAD_BEFORE_SUFFIX
NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted before the suffix.

See Also: DecimalFormat DecimalFormat PAD_BEFORE_PREFIX PAD_AFTER_PREFIX PAD_AFTER_SUFFIX

UNKNOWN: ICU 2.0

Constructor Detail

DecimalFormat

public DecimalFormat()
Create a DecimalFormat using the default pattern and symbols for the default locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

See Also: NumberFormat NumberFormat NumberFormat NumberFormat

UNKNOWN: ICU 2.0

DecimalFormat

public DecimalFormat(String pattern)
Create a DecimalFormat from the given pattern and the symbols for the default locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

Parameters: pattern A non-localized pattern string.

Throws: IllegalArgumentException if the given pattern is invalid.

See Also: NumberFormat NumberFormat NumberFormat NumberFormat

UNKNOWN: ICU 2.0

DecimalFormat

public DecimalFormat(String pattern, DecimalFormatSymbols symbols)
Create a DecimalFormat from the given pattern and symbols. Use this constructor when you need to completely customize the behavior of the format.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getInstance or getCurrencyInstance. If you need only minor adjustments to a standard format, you can modify the format returned by a NumberFormat factory method.

Parameters: pattern a non-localized pattern string symbols the set of symbols to be used

Throws: IllegalArgumentException if the given pattern is invalid

See Also: NumberFormat NumberFormat NumberFormat NumberFormat DecimalFormatSymbols

UNKNOWN: ICU 2.0

Method Detail

applyLocalizedPattern

public void applyLocalizedPattern(String pattern)
Apply the given pattern to this Format object. The pattern is assumed to be in a localized notation. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.

There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon

Example "#,#00.0#" -> 1,234.56

This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.

Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses.

In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.

UNKNOWN: ICU 2.0

applyPattern

public void applyPattern(String pattern)
Apply the given pattern to this Format object. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.

There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon

Example "#,#00.0#" -> 1,234.56

This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.

Example: "#,#00.0#;(#,#00.0#)" for negatives in parentheses.

In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.

UNKNOWN: ICU 2.0

areSignificantDigitsUsed

public boolean areSignificantDigitsUsed()
Returns true if significant digits are in use or false if integer and fraction digit counts are in use.

Returns: true if significant digits are in use

UNKNOWN: ICU 3.0

clone

public Object clone()
Standard override; no change in semantics.

UNKNOWN: ICU 2.0

equals

public boolean equals(Object obj)
Overrides equals

UNKNOWN: ICU 2.0

format

public StringBuffer format(double number, StringBuffer result, FieldPosition fieldPosition)

UNKNOWN: ICU 2.0

format

public StringBuffer format(long number, StringBuffer result, FieldPosition fieldPosition)

UNKNOWN: ICU 2.0

format

public StringBuffer format(BigInteger number, StringBuffer result, FieldPosition fieldPosition)
NEW Format a BigInteger number.

UNKNOWN: ICU 2.0

format

public StringBuffer format(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)
NEW Format a BigDecimal number.

UNKNOWN: ICU 2.0

format

public StringBuffer format(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)
NEW Format a BigDecimal number.

UNKNOWN: ICU 2.0

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)
Format the object to an attributed string, and return the corresponding iterator Overrides superclass method.

UNKNOWN: ICU 3.6

getDecimalFormatSymbols

public DecimalFormatSymbols getDecimalFormatSymbols()
Returns a copy of the decimal format symbols used by this format.

Returns: desired DecimalFormatSymbols

See Also: DecimalFormatSymbols

UNKNOWN: ICU 2.0

getEffectiveCurrency

protected Currency getEffectiveCurrency()

Deprecated: This API is ICU internal only.

Returns the currency in effect for this formatter. Subclasses should override this method as needed. Unlike getCurrency(), this method should never return null.

UNKNOWN:

getFormatWidth

public int getFormatWidth()
NEW Get the width to which the output of format() is padded. The width is counted in 16-bit code units.

Returns: the format width, or zero if no padding is in effect

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

getGroupingSize

public int getGroupingSize()
Return the grouping size. Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "123,456.78", the grouping size is 3.

See Also: DecimalFormat NumberFormat DecimalFormatSymbols

UNKNOWN: ICU 2.0

getMaximumSignificantDigits

public int getMaximumSignificantDigits()
Returns the maximum number of significant digits that will be displayed. This value has no effect unless areSignificantDigitsUsed() returns true.

Returns: the most significant digits that will be shown

UNKNOWN: ICU 3.0

getMinimumExponentDigits

public byte getMinimumExponentDigits()
NEW Return the minimum exponent digits that will be shown.

Returns: the minimum exponent digits that will be shown

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

getMinimumSignificantDigits

public int getMinimumSignificantDigits()
Returns the minimum number of significant digits that will be displayed. This value has no effect unless areSignificantDigitsUsed() returns true.

Returns: the fewest significant digits that will be shown

UNKNOWN: ICU 3.0

getMultiplier

public int getMultiplier()
Get the multiplier for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the multiplier to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "‱" and the multiplier to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23

UNKNOWN: ICU 2.0

getNegativePrefix

public String getNegativePrefix()
Get the negative prefix.

Examples: -123, ($123) (with negative suffix), sFr-123

UNKNOWN: ICU 2.0

getNegativeSuffix

public String getNegativeSuffix()
Get the negative suffix.

Examples: -123%, ($123) (with positive suffixes)

UNKNOWN: ICU 2.0

getPadCharacter

public char getPadCharacter()
NEW Get the character used to pad to the format width. The default is ' '.

Returns: the pad character

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

getPadPosition

public int getPadPosition()
NEW Get the position at which padding will take place. This is the location at which padding will be inserted if the result of format() is shorter than the format width.

Returns: the pad position, one of PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, or PAD_AFTER_SUFFIX.

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat PAD_BEFORE_PREFIX PAD_AFTER_PREFIX PAD_BEFORE_SUFFIX PAD_AFTER_SUFFIX

UNKNOWN: ICU 2.0

getPositivePrefix

public String getPositivePrefix()
Get the positive prefix.

Examples: +123, $123, sFr123

UNKNOWN: ICU 2.0

getPositiveSuffix

public String getPositiveSuffix()
Get the positive suffix.

Example: 123%

UNKNOWN: ICU 2.0

getRoundingIncrement

public BigDecimal getRoundingIncrement()
NEW Get the rounding increment.

Returns: A positive rounding increment, or null if rounding is not in effect.

See Also: DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

getRoundingMode

public int getRoundingMode()
NEW Get the rounding mode.

Returns: A rounding mode, between BigDecimal.ROUND_UP and BigDecimal.ROUND_UNNECESSARY.

See Also: DecimalFormat DecimalFormat DecimalFormat java.math.BigDecimal

UNKNOWN: ICU 2.0

getSecondaryGroupingSize

public int getSecondaryGroupingSize()
Return the secondary grouping size. In some locales one grouping interval is used for the least significant integer digits (the primary grouping size), and another is used for all others (the secondary grouping size). A formatter supporting a secondary grouping size will return a positive integer unequal to the primary grouping size returned by getGroupingSize(). For example, if the primary grouping size is 4, and the secondary grouping size is 2, then the number 123456789 formats as "1,23,45,6789", and the pattern appears as "#,##,###0". [NEW]

Returns: the secondary grouping size, or a value less than one if there is none

See Also: DecimalFormat NumberFormat DecimalFormatSymbols

UNKNOWN: ICU 2.0

hashCode

public int hashCode()
Overrides hashCode

UNKNOWN: ICU 2.0

isDecimalSeparatorAlwaysShown

public boolean isDecimalSeparatorAlwaysShown()
Allows you to get the behavior of the decimal separator with integers. (The decimal separator will always appear with decimals.)

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345

UNKNOWN: ICU 2.0

isExponentSignAlwaysShown

public boolean isExponentSignAlwaysShown()
NEW Return whether the exponent sign is always shown.

Returns: true if the exponent is always prefixed with either the localized minus sign or the localized plus sign, false if only negative exponents are prefixed with the localized minus sign.

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

isParseBigDecimal

public boolean isParseBigDecimal()
Returns whether DecimalFormat method returns BigDecimal.

Returns: true if DecimalFormat method returns BigDecimal.

UNKNOWN: ICU 3.6

isScientificNotation

public boolean isScientificNotation()
NEW Return whether or not scientific notation is used.

Returns: true if this object formats and parses scientific notation

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

parse

public Number parse(String text, ParsePosition parsePosition)
CHANGED Parse the given string, returning a Number object to represent the parsed value. Double objects are returned to represent non-integral values which cannot be stored in a BigDecimal. These are NaN, infinity, -infinity, and -0.0. If isParseBigDecimal is false (the default), all other values are returned as Long, BigInteger, or BigDecimal values, in that order of preference. If isParseBigDecimal is true, all other values are returned as BigDecimal valuse. If the parse fails, null is returned.

Parameters: text the string to be parsed parsePosition defines the position where parsing is to begin, and upon return, the position where parsing left off. If the position has not changed upon return, then parsing failed.

Returns: a Number object with the parsed value or null if the parse failed

UNKNOWN: ICU 2.0

setCurrency

public void setCurrency(Currency theCurrency)
Sets the Currency object used to display currency amounts. This takes effect immediately, if this format is a currency format. If this format is not a currency format, then the currency object is used if and when this object becomes a currency format through the application of a new pattern.

Parameters: theCurrency new currency object to use. Must not be null.

UNKNOWN: ICU 2.2

setDecimalFormatSymbols

public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
Sets the decimal format symbols used by this format. The format uses a copy of the provided symbols.

Parameters: newSymbols desired DecimalFormatSymbols

See Also: DecimalFormatSymbols

UNKNOWN: ICU 2.0

setDecimalSeparatorAlwaysShown

public void setDecimalSeparatorAlwaysShown(boolean newValue)
Allows you to set the behavior of the decimal separator with integers. (The decimal separator will always appear with decimals.)

This only affects formatting, and only where there might be no digits after the decimal point, 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.

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345

UNKNOWN: ICU 2.0

setExponentSignAlwaysShown

public void setExponentSignAlwaysShown(boolean expSignAlways)
NEW Set whether the exponent sign is always shown. This has no effect unless scientific notation is in use.

Parameters: expSignAlways true if the exponent is always prefixed with either the localized minus sign or the localized plus sign, false if only negative exponents are prefixed with the localized minus sign.

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

setFormatWidth

public void setFormatWidth(int width)
NEW Set the width to which the output of format() is padded. The width is counted in 16-bit code units. This method also controls whether padding is enabled.

Parameters: width the width to which to pad the result of format(), or zero to disable padding

Throws: IllegalArgumentException if width is < 0

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

setGroupingSize

public void setGroupingSize(int newValue)
Set the grouping size. Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "123,456.78", the grouping size is 3.

See Also: DecimalFormat NumberFormat DecimalFormatSymbols

UNKNOWN: ICU 2.0

setMaximumFractionDigits

public void setMaximumFractionDigits(int newValue)
Sets the maximum number of digits allowed in the fraction portion of a number. This override limits the fraction digit count to 340.

See Also: NumberFormat

UNKNOWN: ICU 2.0

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int newValue)
Sets the maximum number of digits allowed in the integer portion of a number. This override limits the integer digit count to 309.

See Also: NumberFormat

UNKNOWN: ICU 2.0

setMaximumSignificantDigits

public void setMaximumSignificantDigits(int max)
Sets the maximum number of significant digits that will be displayed. If max is less than one then it is set to one. If the minimum significant digits count is greater than max, then it is set to max. This value has no effect unless areSignificantDigitsUsed() returns true.

Parameters: max the most significant digits to be shown

UNKNOWN: ICU 3.0

setMinimumExponentDigits

public void setMinimumExponentDigits(byte minExpDig)
NEW Set the minimum exponent digits that will be shown. This has no effect unless scientific notation is in use.

Parameters: minExpDig a value >= 1 indicating the fewest exponent digits that will be shown

Throws: IllegalArgumentException if minExpDig < 1

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

setMinimumFractionDigits

public void setMinimumFractionDigits(int newValue)
Sets the minimum number of digits allowed in the fraction portion of a number. This override limits the fraction digit count to 340.

See Also: NumberFormat

UNKNOWN: ICU 2.0

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int newValue)
Sets the minimum number of digits allowed in the integer portion of a number. This override limits the integer digit count to 309.

See Also: NumberFormat

UNKNOWN: ICU 2.0

setMinimumSignificantDigits

public void setMinimumSignificantDigits(int min)
Sets the minimum number of significant digits that will be displayed. If min is less than one then it is set to one. If the maximum significant digits count is less than min, then it is set to min. This value has no effect unless areSignificantDigitsUsed() returns true.

Parameters: min the fewest significant digits to be shown

UNKNOWN: ICU 3.0

setMultiplier

public void setMultiplier(int newValue)
Set the multiplier for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the multiplier to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "‱" and the multiplier to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23

UNKNOWN: ICU 2.0

setNegativePrefix

public void setNegativePrefix(String newValue)
Set the negative prefix.

Examples: -123, ($123) (with negative suffix), sFr-123

UNKNOWN: ICU 2.0

setNegativeSuffix

public void setNegativeSuffix(String newValue)
Set the positive suffix.

Examples: 123%

UNKNOWN: ICU 2.0

setPadCharacter

public void setPadCharacter(char padChar)
NEW Set the character used to pad to the format width. If padding is not enabled, then this will take effect if padding is later enabled.

Parameters: padChar the pad character

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

setPadPosition

public void setPadPosition(int padPos)
NEW Set the position at which padding will take place. This is the location at which padding will be inserted if the result of format() is shorter than the format width. This has no effect unless padding is enabled.

Parameters: padPos the pad position, one of PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, or PAD_AFTER_SUFFIX.

Throws: IllegalArgumentException if the pad position in unrecognized

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat PAD_BEFORE_PREFIX PAD_AFTER_PREFIX PAD_BEFORE_SUFFIX PAD_AFTER_SUFFIX

UNKNOWN: ICU 2.0

setParseBigDecimal

public void setParseBigDecimal(boolean value)
Sets whether DecimalFormat method returns BigDecimal. The default value is false.

Parameters: value true if DecimalFormat method returns BigDecimal.

UNKNOWN: ICU 3.6

setPositivePrefix

public void setPositivePrefix(String newValue)
Set the positive prefix.

Examples: +123, $123, sFr123

UNKNOWN: ICU 2.0

setPositiveSuffix

public void setPositiveSuffix(String newValue)
Set the positive suffix.

Example: 123%

UNKNOWN: ICU 2.0

setRoundingIncrement

public void setRoundingIncrement(BigDecimal newValue)
NEW Set the rounding increment. This method also controls whether rounding is enabled.

Parameters: newValue A positive rounding increment, or null or BigDecimal(0.0) to disable rounding.

Throws: IllegalArgumentException if newValue is < 0.0

See Also: DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

setRoundingIncrement

public void setRoundingIncrement(BigDecimal newValue)
NEW Set the rounding increment. This method also controls whether rounding is enabled.

Parameters: newValue A positive rounding increment, or null or BigDecimal(0.0) to disable rounding.

Throws: IllegalArgumentException if newValue is < 0.0

See Also: DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 3.4.2 This API might change or be removed in a future release.

setRoundingIncrement

public void setRoundingIncrement(double newValue)
NEW Set the rounding increment. This method also controls whether rounding is enabled.

Parameters: newValue A positive rounding increment, or 0.0 to disable rounding.

Throws: IllegalArgumentException if newValue is < 0.0

See Also: DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

setRoundingMode

public void setRoundingMode(int roundingMode)
NEW Set the rounding mode. This has no effect unless the rounding increment is greater than zero.

Parameters: roundingMode A rounding mode, between BigDecimal.ROUND_UP and BigDecimal.ROUND_UNNECESSARY.

Throws: IllegalArgumentException if roundingMode is unrecognized.

See Also: DecimalFormat DecimalFormat DecimalFormat java.math.BigDecimal

UNKNOWN: ICU 2.0

setScientificNotation

public void setScientificNotation(boolean useScientific)
NEW Set whether or not scientific notation is used. When scientific notation is used, the effective maximum number of integer digits is <= 8. If the maximum number of integer digits is set to more than 8, the effective maximum will be 1. This allows this call to generate a 'default' scientific number format without additional changes.

Parameters: useScientific true if this object formats and parses scientific notation

See Also: DecimalFormat DecimalFormat DecimalFormat DecimalFormat DecimalFormat

UNKNOWN: ICU 2.0

setSecondaryGroupingSize

public void setSecondaryGroupingSize(int newValue)
Set the secondary grouping size. If set to a value less than 1, then secondary grouping is turned off, and the primary grouping size is used for all intervals, not just the least significant. [NEW]

See Also: DecimalFormat NumberFormat DecimalFormatSymbols

UNKNOWN: ICU 2.0

setSignificantDigitsUsed

public void setSignificantDigitsUsed(boolean useSignificantDigits)
Sets whether significant digits are in use, or integer and fraction digit counts are in use.

Parameters: useSignificantDigits true to use significant digits, or false to use integer and fraction digit counts

UNKNOWN: ICU 3.0

toLocalizedPattern

public String toLocalizedPattern()
Synthesizes a localized pattern string that represents the current state of this Format object.

See Also: DecimalFormat

UNKNOWN: ICU 2.0

toPattern

public String toPattern()
Synthesizes a pattern string that represents the current state of this Format object.

See Also: DecimalFormat

UNKNOWN: ICU 2.0

Copyright (c) 2007 IBM Corporation and others.