com.ibm.icu.text
Class DecimalFormat

java.lang.Object
  |
  +--java.text.Format
        |
        +--com.ibm.icu.text.NumberFormat
              |
              +--com.ibm.icu.text.DecimalFormat
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable

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 getInstance(). 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);
 }
 

A DecimalFormat comprises a pattern and a set of symbols. The pattern may be set directly using applyPattern(), or indirectly using the API methods. The symbols are stored in a DecimalFormatSymbols object. When using the NumberFormat factory methods, the pattern and symbols are read from localized ResourceBundles in the package java.text.resource.

Synchronization

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

Example

 // Print out a number using the localized number, currency,
 // and percent format for each locale
 Locale[] locales = NumberFormat.getAvailableLocales();
 double myNumber = -1234.56;
 NumberFormat form;
 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:
             form = NumberFormat.getInstance(locales[i]); break;
         case 1:
             form = NumberFormat.getCurrencyInstance(locales[i]); break;
         default:
             form = NumberFormat.getPercentInstance(locales[i]); break;
         }
         try {
             // Assume form is a DecimalFormat
             System.out.print(": " + ((DecimalFormat) form).toPattern()
                              + " -> " + form.format(myNumber));
         } catch (IllegalArgumentException e) {}
         try {
             System.out.println(" -> " + form.parse(form.format(myNumber)));
         } catch (ParseException e) {}
     }
 }
 

Notes

A DecimalFormat pattern contains a postive and negative subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, numeric part, and suffix. If there is no explicit negative subpattern, the localized minus sign, typically '-', is prefixed to the positive form. 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 all the same as the positive pattern. 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.parse() 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 commonly used for thousands, but in some countries it separates ten-thousands. The grouping size is a constant number of digits between the grouping characters, such as 3 for 100,000,000 or 4 for 1,0000,0000. If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer determines the primary grouping size, and the interval between the last two determines the secondary grouping size (see below); all others are ignored. So "#,##,###,####" == "###,###,####" == "##,#,###,####".

Some locales have two different grouping intervals: One used for the least significant integer digits (the primary grouping size), and one used for all others (the secondary grouping size). 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".

DecimalFormat parses all Unicode characters that represent decimal digits, as defined by Character.digit(). 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.

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

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

Special Cases

NaN is formatted 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 formatted as a single character, typically \u221E, with the positive or negative prefixes and suffixes applied. The infinity character is determined by the DecimalFormatSymbols object.

NEW 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 10^3. The mantissa is often in the range 1.0 <= x < 10.0, but it need not be. DecimalFormat can be instructed to format and parse scientific notation through the API or via a 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 Padding

DecimalFormat supports padding the result of format() 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.setPadEscape(). 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.

Pattern Syntax

 pattern    := subpattern{';' subpattern}
 subpattern := {prefix}number{suffix}
 number     := integer{'.' fraction}{exponent}
 prefix     := '\u0000'..'\uFFFD' - specialCharacters
 suffix     := '\u0000'..'\uFFFD' - specialCharacters
 integer    := '#'* '0'* '0'
 fraction   := '0'* '#'*
 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     any character from X up to Y, 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:

Special Pattern Characters

Here are the special characters used in the pattern, with notes on their usage. Special characters must be quoted, unless noted otherwise, if they are to appear in the prefix or suffix. This does not apply to those listed with location "prefix or suffix." Such characters should only be quoted in order to remove their special meaning.

SymbolLocationMeaning
0-9NumberDigit. NEW '1' through '9' indicate rounding
#NumberDigit, zero shows as absent
.NumberDecimal separator or monetary decimal separator
,NumberGrouping separator
ENumber Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
NEW +Exponent Prefix positive exponents with localized plus sign. Need not be quoted in prefix or suffix.
;Subpattern boundary Separates positive and negative subpatterns
%Prefix or suffixMultiply by 100 and show as percentage
\u2030Prefix or suffix Multiply by 1000 and show as per mille
\u00A4Prefix or suffix 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 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".
NEW *Prefix or suffix boundary Pad escape, precedes pad character

Version:
1.48 09/21/98
Author:
Mark Davis, Alan Liu
See Also:
Format, NumberFormat, Serialized Form

Field Summary
static int PAD_AFTER_PREFIX
          NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted after the prefix.
static int PAD_AFTER_SUFFIX
          NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted after the suffix.
static int PAD_BEFORE_PREFIX
          NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted before the prefix.
static int PAD_BEFORE_SUFFIX
          NEW Constant for getPadPosition() and setPadPosition() specifying pad characters inserted before the suffix.
 
Fields inherited from class com.ibm.icu.text.NumberFormat
FRACTION_FIELD, INTEGER_FIELD
 
Constructor Summary
DecimalFormat()
          Create a DecimalFormat using the default pattern and symbols for the default locale.
DecimalFormat(java.lang.String pattern)
          Create a DecimalFormat from the given pattern and the symbols for the default locale.
DecimalFormat(java.lang.String pattern, DecimalFormatSymbols symbols)
          Create a DecimalFormat from the given pattern and symbols.
 
Method Summary
 void applyLocalizedPattern(java.lang.String pattern)
          Apply the given pattern to this Format object.
 void applyPattern(java.lang.String pattern)
          Apply the given pattern to this Format object.
 java.lang.Object clone()
          Standard override; no change in semantics.
 boolean equals(java.lang.Object obj)
          Overrides equals
 java.lang.StringBuffer format(java.math.BigDecimal number, java.lang.StringBuffer result, java.text.FieldPosition fieldPosition)
          NEW Format a BigDecimal number.
 java.lang.StringBuffer format(BigDecimal number, java.lang.StringBuffer result, java.text.FieldPosition fieldPosition)
          NEW Format a BigDecimal.
 java.lang.StringBuffer format(java.math.BigInteger number, java.lang.StringBuffer result, java.text.FieldPosition fieldPosition)
          NEW Format a BigInteger number.
 java.lang.StringBuffer format(double number, java.lang.StringBuffer result, java.text.FieldPosition fieldPosition)
          Specialization of format.
 java.lang.StringBuffer format(long number, java.lang.StringBuffer result, java.text.FieldPosition fieldPosition)
          Specialization of format.
 DecimalFormatSymbols getDecimalFormatSymbols()
          Returns the decimal format symbols, which is generally not changed by the programmer or user.
 int getFormatWidth()
          NEW Get the width to which the output of format() is padded.
 int getGroupingSize()
          Return the grouping size.
 byte getMinimumExponentDigits()
          NEW Return the minimum exponent digits that will be shown.
 int getMultiplier()
          Get the multiplier for use in percent, permill, etc.
 java.lang.String getNegativePrefix()
          Get the negative prefix.
 java.lang.String getNegativeSuffix()
          Get the negative suffix.
 char getPadCharacter()
          NEW Get the character used to pad to the format width.
 int getPadPosition()
          NEW Get the position at which padding will take place.
 java.lang.String getPositivePrefix()
          Get the positive prefix.
 java.lang.String getPositiveSuffix()
          Get the positive suffix.
 java.math.BigDecimal getRoundingIncrement()
          NEW Get the rounding increment.
 int getRoundingMode()
          NEW Get the rounding mode.
 int getSecondaryGroupingSize()
          Return the secondary grouping size.
 int hashCode()
          Overrides hashCode
 boolean isDecimalSeparatorAlwaysShown()
          Allows you to get the behavior of the decimal separator with integers.
 boolean isExponentSignAlwaysShown()
          NEW Return whether the exponent sign is always shown.
 boolean isScientificNotation()
          NEW Return whether or not scientific notation is used.
 java.lang.Number parse(java.lang.String text, java.text.ParsePosition parsePosition)
          CHANGED Parse the given string, returning a Number object to represent the parsed value.
 void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
          Sets the decimal format symbols, which is generally not changed by the programmer or user.
 void setDecimalSeparatorAlwaysShown(boolean newValue)
          Allows you to set the behavior of the decimal separator with integers.
 void setExponentSignAlwaysShown(boolean expSignAlways)
          NEW Set whether the exponent sign is always shown.
 void setFormatWidth(int width)
          NEW Set the width to which the output of format() is padded.
 void setGroupingSize(int newValue)
          Set the grouping size.
 void setMaximumFractionDigits(int newValue)
          Sets the maximum number of digits allowed in the fraction portion of a number.
 void setMaximumIntegerDigits(int newValue)
          Sets the maximum number of digits allowed in the integer portion of a number.
 void setMinimumExponentDigits(byte minExpDig)
          NEW Set the minimum exponent digits that will be shown.
 void setMinimumFractionDigits(int newValue)
          Sets the minimum number of digits allowed in the fraction portion of a number.
 void setMinimumIntegerDigits(int newValue)
          Sets the minimum number of digits allowed in the integer portion of a number.
 void setMultiplier(int newValue)
          Set the multiplier for use in percent, permill, etc.
 void setNegativePrefix(java.lang.String newValue)
          Set the negative prefix.
 void setNegativeSuffix(java.lang.String newValue)
          Set the positive suffix.
 void setPadCharacter(char padChar)
          NEW Set the character used to pad to the format width.
 void setPadPosition(int padPos)
          NEW Set the position at which padding will take place.
 void setPositivePrefix(java.lang.String newValue)
          Set the positive prefix.
 void setPositiveSuffix(java.lang.String newValue)
          Set the positive suffix.
 void setRoundingIncrement(java.math.BigDecimal newValue)
          NEW Set the rounding increment.
 void setRoundingIncrement(double newValue)
          NEW Set the rounding increment.
 void setRoundingMode(int roundingMode)
          NEW Set the rounding mode.
 void setScientificNotation(boolean useScientific)
          NEW Set whether or not scientific notation is used.
 void setSecondaryGroupingSize(int newValue)
          Set the secondary grouping size.
 java.lang.String toLocalizedPattern()
          Synthesizes a localized pattern string that represents the current state of this Format object.
 java.lang.String toPattern()
          Synthesizes a pattern string that represents the current state of this Format object.
 
Methods inherited from class com.ibm.icu.text.NumberFormat
format, format, format, format, format, format, getAvailableLocales, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getMaximumFractionDigits, getMaximumIntegerDigits, getMinimumFractionDigits, getMinimumIntegerDigits, getNumberInstance, getNumberInstance, getPattern, getPercentInstance, getPercentInstance, getScientificInstance, getScientificInstance, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setGroupingUsed, setParseIntegerOnly
 
Methods inherited from class java.text.Format
format, parseObject
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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:
setPadPosition(int), getPadPosition(), PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

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:
setPadPosition(int), getPadPosition(), PAD_BEFORE_PREFIX, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

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:
setPadPosition(int), getPadPosition(), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_AFTER_SUFFIX

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:
setPadPosition(int), getPadPosition(), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX
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.getInstance(), NumberFormat.getNumberInstance(), NumberFormat.getCurrencyInstance(), NumberFormat.getPercentInstance()

DecimalFormat

public DecimalFormat(java.lang.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:
java.lang.IllegalArgumentException - if the given pattern is invalid.
See Also:
NumberFormat.getInstance(), NumberFormat.getNumberInstance(), NumberFormat.getCurrencyInstance(), NumberFormat.getPercentInstance()

DecimalFormat

public DecimalFormat(java.lang.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:
java.lang.IllegalArgumentException - if the given pattern is invalid
See Also:
NumberFormat.getInstance(), NumberFormat.getNumberInstance(), NumberFormat.getCurrencyInstance(), NumberFormat.getPercentInstance(), DecimalFormatSymbols
Method Detail

format

public java.lang.StringBuffer format(double number,
                                     java.lang.StringBuffer result,
                                     java.text.FieldPosition fieldPosition)
Description copied from class: NumberFormat
Specialization of format.
Overrides:
format in class NumberFormat
Following copied from class: com.ibm.icu.text.NumberFormat
See Also:
Format.format(java.lang.Object)

format

public java.lang.StringBuffer format(long number,
                                     java.lang.StringBuffer result,
                                     java.text.FieldPosition fieldPosition)
Description copied from class: NumberFormat
Specialization of format.
Overrides:
format in class NumberFormat
Following copied from class: com.ibm.icu.text.NumberFormat
See Also:
Format.format(java.lang.Object)

format

public java.lang.StringBuffer format(java.math.BigInteger number,
                                     java.lang.StringBuffer result,
                                     java.text.FieldPosition fieldPosition)
NEW Format a BigInteger number.
Overrides:
format in class NumberFormat

format

public java.lang.StringBuffer format(java.math.BigDecimal number,
                                     java.lang.StringBuffer result,
                                     java.text.FieldPosition fieldPosition)
NEW Format a BigDecimal number.
Overrides:
format in class NumberFormat

format

public java.lang.StringBuffer format(BigDecimal number,
                                     java.lang.StringBuffer result,
                                     java.text.FieldPosition fieldPosition)
Description copied from class: NumberFormat
NEW Format a BigDecimal.
Overrides:
format in class NumberFormat

parse

public java.lang.Number parse(java.lang.String text,
                              java.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. All other values are returned as Long, BigInteger, or BigDecimal values, in that order of preference. If the parse fails, null is returned.
Overrides:
parse in class NumberFormat
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

getDecimalFormatSymbols

public DecimalFormatSymbols getDecimalFormatSymbols()
Returns the decimal format symbols, which is generally not changed by the programmer or user.
Returns:
desired DecimalFormatSymbols
See Also:
DecimalFormatSymbols

setDecimalFormatSymbols

public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
Sets the decimal format symbols, which is generally not changed by the programmer or user.
Parameters:
newSymbols - desired DecimalFormatSymbols
See Also:
DecimalFormatSymbols

getPositivePrefix

public java.lang.String getPositivePrefix()
Get the positive prefix.

Examples: +123, $123, sFr123


setPositivePrefix

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

Examples: +123, $123, sFr123


getNegativePrefix

public java.lang.String getNegativePrefix()
Get the negative prefix.

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


setNegativePrefix

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

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


getPositiveSuffix

public java.lang.String getPositiveSuffix()
Get the positive suffix.

Example: 123%


setPositiveSuffix

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

Example: 123%


getNegativeSuffix

public java.lang.String getNegativeSuffix()
Get the negative suffix.

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


setNegativeSuffix

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

Examples: 123%


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


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


getRoundingIncrement

public java.math.BigDecimal getRoundingIncrement()
NEW Get the rounding increment.
Returns:
A positive rounding increment, or null if rounding is not in effect.
See Also:
setRoundingIncrement(java.math.BigDecimal), getRoundingMode(), setRoundingMode(int)

setRoundingIncrement

public void setRoundingIncrement(java.math.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:
java.lang.IllegalArgumentException - if newValue is < 0.0
See Also:
getRoundingIncrement(), getRoundingMode(), setRoundingMode(int)

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:
java.lang.IllegalArgumentException - if newValue is < 0.0
See Also:
getRoundingIncrement(), getRoundingMode(), setRoundingMode(int)

getRoundingMode

public int getRoundingMode()
NEW Get the rounding mode.
Returns:
A rounding mode, between BigDecimal.ROUND_UP and BigDecimal.ROUND_UNNECESSARY.
See Also:
setRoundingIncrement(java.math.BigDecimal), getRoundingIncrement(), setRoundingMode(int), BigDecimal

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:
java.lang.IllegalArgumentException - if roundingMode is unrecognized.
See Also:
setRoundingIncrement(java.math.BigDecimal), getRoundingIncrement(), getRoundingMode(), BigDecimal

getFormatWidth

public int getFormatWidth()
NEW Get the width to which the output of format() is padded.
Returns:
the format width, or zero if no padding is in effect
See Also:
setFormatWidth(int), getPadCharacter(), setPadCharacter(char), getPadPosition(), setPadPosition(int)

setFormatWidth

public void setFormatWidth(int width)
NEW Set the width to which the output of format() is padded. 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:
java.lang.IllegalArgumentException - if width is < 0
See Also:
getFormatWidth(), getPadCharacter(), setPadCharacter(char), getPadPosition(), setPadPosition(int)

getPadCharacter

public char getPadCharacter()
NEW Get the character used to pad to the format width. The default is ' '.
Returns:
the pad character
See Also:
setFormatWidth(int), getFormatWidth(), setPadCharacter(char), getPadPosition(), setPadPosition(int)

setPadCharacter

public void setPadCharacter(char padChar)
NEW Set the character used to pad to the format width. This has no effect unless padding is enabled.
Parameters:
padChar - the pad character
See Also:
setFormatWidth(int), getFormatWidth(), getPadCharacter(), getPadPosition(), setPadPosition(int)

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:
setFormatWidth(int), getFormatWidth(), setPadCharacter(char), getPadCharacter(), setPadPosition(int), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

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:
java.lang.IllegalArgumentException - if the pad position in unrecognized
See Also:
setFormatWidth(int), getFormatWidth(), setPadCharacter(char), getPadCharacter(), getPadPosition(), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

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:
setScientificNotation(boolean), getMinimumExponentDigits(), setMinimumExponentDigits(byte), isExponentSignAlwaysShown(), setExponentSignAlwaysShown(boolean)

setScientificNotation

public void setScientificNotation(boolean useScientific)
NEW Set whether or not scientific notation is used.
Parameters:
useScientific - true if this object formats and parses scientific notation
See Also:
isScientificNotation(), getMinimumExponentDigits(), setMinimumExponentDigits(byte), isExponentSignAlwaysShown(), setExponentSignAlwaysShown(boolean)

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:
setScientificNotation(boolean), isScientificNotation(), setMinimumExponentDigits(byte), isExponentSignAlwaysShown(), setExponentSignAlwaysShown(boolean)

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:
java.lang.IllegalArgumentException - if minExpDig < 1
See Also:
setScientificNotation(boolean), isScientificNotation(), getMinimumExponentDigits(), isExponentSignAlwaysShown(), setExponentSignAlwaysShown(boolean)

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:
setScientificNotation(boolean), isScientificNotation(), setMinimumExponentDigits(byte), getMinimumExponentDigits(), setExponentSignAlwaysShown(boolean)

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:
setScientificNotation(boolean), isScientificNotation(), setMinimumExponentDigits(byte), getMinimumExponentDigits(), isExponentSignAlwaysShown()

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:
setGroupingSize(int), NumberFormat.isGroupingUsed(), DecimalFormatSymbols.getGroupingSeparator()

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:
getGroupingSize(), NumberFormat.setGroupingUsed(boolean), DecimalFormatSymbols.setGroupingSeparator(char)

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:
setSecondaryGroupingSize(int), NumberFormat.isGroupingUsed(), DecimalFormatSymbols.getGroupingSeparator()

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:
getSecondaryGroupingSize(), NumberFormat.setGroupingUsed(boolean), DecimalFormatSymbols.setGroupingSeparator(char)

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


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

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


clone

public java.lang.Object clone()
Standard override; no change in semantics.
Overrides:
clone in class NumberFormat

equals

public boolean equals(java.lang.Object obj)
Overrides equals
Overrides:
equals in class NumberFormat

hashCode

public int hashCode()
Overrides hashCode
Overrides:
hashCode in class NumberFormat

toPattern

public java.lang.String toPattern()
Synthesizes a pattern string that represents the current state of this Format object.
See Also:
applyPattern(java.lang.String)

toLocalizedPattern

public java.lang.String toLocalizedPattern()
Synthesizes a localized pattern string that represents the current state of this Format object.
See Also:
applyPattern(java.lang.String)

applyPattern

public void applyPattern(java.lang.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.


applyLocalizedPattern

public void applyLocalizedPattern(java.lang.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.


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.
Overrides:
setMaximumIntegerDigits in class NumberFormat
See Also:
NumberFormat.setMaximumIntegerDigits(int)

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.
Overrides:
setMinimumIntegerDigits in class NumberFormat
See Also:
NumberFormat.setMinimumIntegerDigits(int)

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.
Overrides:
setMaximumFractionDigits in class NumberFormat
See Also:
NumberFormat.setMaximumFractionDigits(int)

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.
Overrides:
setMinimumFractionDigits in class NumberFormat
See Also:
NumberFormat.setMinimumFractionDigits(int)


Copyright (c) 2001 IBM Corporation and others.