DecimalFormat Class Reference

DecimalFormat is a concrete subclass of NumberFormat that formats decimal numbers. More...

#include <decimfmt.h>

Inheritance diagram for DecimalFormat:


Public Types
enum	ERoundingMode { kRoundCeiling, kRoundFloor, kRoundDown, kRoundUp, kRoundHalfEven, kRoundHalfDown, kRoundHalfUp }
	Rounding mode. More...
enum	EPadPosition { kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, kPadAfterSuffix }
	Pad position. More...
Public Member Functions
	DecimalFormat (UErrorCode &status)
	Create a DecimalFormat using the default pattern and symbols for the default locale.
	DecimalFormat (const UnicodeString &pattern, UErrorCode &status)
	Create a DecimalFormat from the given pattern and the symbols for the default locale.
	DecimalFormat (const UnicodeString &pattern, DecimalFormatSymbols *symbolsToAdopt, UErrorCode &status)
	Create a DecimalFormat from the given pattern and symbols.
	DecimalFormat (const UnicodeString &pattern, DecimalFormatSymbols *symbolsToAdopt, UParseError &parseError, UErrorCode &status)
	Create a DecimalFormat from the given pattern and symbols.
	DecimalFormat (const UnicodeString &pattern, const DecimalFormatSymbols &symbols, UErrorCode &status)
	Create a DecimalFormat from the given pattern and symbols.
	DecimalFormat (const DecimalFormat &source)
	Copy constructor.
DecimalFormat &	operator= (const DecimalFormat &rhs)
	Assignment operator.
virtual	~DecimalFormat ()
	Destructor.
virtual Format *	clone (void) const
	Clone this Format object polymorphically.
virtual UBool	operator== (const Format &other) const
	Return true if the given Format objects are semantically equal.
virtual UnicodeString &	format (double number, UnicodeString &appendTo, FieldPosition &pos) const
	Format a double or long number using base-10 representation.
virtual UnicodeString &	format (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const
	Format a long number using base-10 representation.
virtual UnicodeString &	format (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const
	Format an int64 number using base-10 representation.
virtual UnicodeString &	format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
	Format a Formattable using base-10 representation.
UnicodeString &	format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
	Redeclared NumberFormat method.
UnicodeString &	format (double number, UnicodeString &appendTo) const
	Redeclared NumberFormat method.
UnicodeString &	format (int32_t number, UnicodeString &appendTo) const
	Redeclared NumberFormat method.
UnicodeString &	format (int64_t number, UnicodeString &appendTo) const
	Redeclared NumberFormat method.
virtual void	parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const
	Parse the given string using this object's choices.
virtual void	parse (const UnicodeString &text, Formattable &result, UErrorCode &status) const
	Parse the given string using this object's choices.
virtual Formattable &	parseCurrency (const UnicodeString &text, Formattable &result, ParsePosition &pos) const
	Parses text from the given string as a currency amount.
virtual const DecimalFormatSymbols *	getDecimalFormatSymbols (void) const
	Returns the decimal format symbols, which is generally not changed by the programmer or user.
virtual void	adoptDecimalFormatSymbols (DecimalFormatSymbols *symbolsToAdopt)
	Sets the decimal format symbols, which is generally not changed by the programmer or user.
virtual void	setDecimalFormatSymbols (const DecimalFormatSymbols &symbols)
	Sets the decimal format symbols, which is generally not changed by the programmer or user.
UnicodeString &	getPositivePrefix (UnicodeString &result) const
	Get the positive prefix.
virtual void	setPositivePrefix (const UnicodeString &newValue)
	Set the positive prefix.
UnicodeString &	getNegativePrefix (UnicodeString &result) const
	Get the negative prefix.
virtual void	setNegativePrefix (const UnicodeString &newValue)
	Set the negative prefix.
UnicodeString &	getPositiveSuffix (UnicodeString &result) const
	Get the positive suffix.
virtual void	setPositiveSuffix (const UnicodeString &newValue)
	Set the positive suffix.
UnicodeString &	getNegativeSuffix (UnicodeString &result) const
	Get the negative suffix.
virtual void	setNegativeSuffix (const UnicodeString &newValue)
	Set the negative suffix.
int32_t	getMultiplier (void) const
	Get the multiplier for use in percent, permill, etc.
virtual void	setMultiplier (int32_t newValue)
	Set the multiplier for use in percent, permill, etc.
virtual double	getRoundingIncrement (void) const
	Get the rounding increment.
virtual void	setRoundingIncrement (double newValue)
	Set the rounding increment.
virtual ERoundingMode	getRoundingMode (void) const
	Get the rounding mode.
virtual void	setRoundingMode (ERoundingMode roundingMode)
	Set the rounding mode.
virtual int32_t	getFormatWidth (void) const
	Get the width to which the output of format() is padded.
virtual void	setFormatWidth (int32_t width)
	Set the width to which the output of format() is padded.
virtual UnicodeString	getPadCharacterString () const
	Get the pad character used to pad to the format width.
virtual void	setPadCharacter (const UnicodeString &padChar)
	Set the character used to pad to the format width.
virtual EPadPosition	getPadPosition (void) const
	Get the position at which padding will take place.
virtual void	setPadPosition (EPadPosition padPos)
	Set the position at which padding will take place.
virtual UBool	isScientificNotation (void)
	Return whether or not scientific notation is used.
virtual void	setScientificNotation (UBool useScientific)
	Set whether or not scientific notation is used.
virtual int8_t	getMinimumExponentDigits (void) const
	Return the minimum exponent digits that will be shown.
virtual void	setMinimumExponentDigits (int8_t minExpDig)
	Set the minimum exponent digits that will be shown.
virtual UBool	isExponentSignAlwaysShown (void)
	Return whether the exponent sign is always shown.
virtual void	setExponentSignAlwaysShown (UBool expSignAlways)
	Set whether the exponent sign is always shown.
int32_t	getGroupingSize (void) const
	Return the grouping size.
virtual void	setGroupingSize (int32_t newValue)
	Set the grouping size.
int32_t	getSecondaryGroupingSize (void) const
	Return the secondary grouping size.
virtual void	setSecondaryGroupingSize (int32_t newValue)
	Set the secondary grouping size.
UBool	isDecimalSeparatorAlwaysShown (void) const
	Allows you to get the behavior of the decimal separator with integers.
virtual void	setDecimalSeparatorAlwaysShown (UBool newValue)
	Allows you to set the behavior of the decimal separator with integers.
virtual UnicodeString &	toPattern (UnicodeString &result) const
	Synthesizes a pattern string that represents the current state of this Format object.
virtual UnicodeString &	toLocalizedPattern (UnicodeString &result) const
	Synthesizes a localized pattern string that represents the current state of this Format object.
virtual void	applyPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
	Apply the given pattern to this Format object.
virtual void	applyPattern (const UnicodeString &pattern, UErrorCode &status)
	Sets the pattern.
virtual void	applyLocalizedPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
	Apply the given pattern to this Format object.
virtual void	applyLocalizedPattern (const UnicodeString &pattern, UErrorCode &status)
	Apply the given pattern to this Format object.
virtual void	setMaximumIntegerDigits (int32_t newValue)
	Sets the maximum number of digits allowed in the integer portion of a number.
virtual void	setMinimumIntegerDigits (int32_t newValue)
	Sets the minimum number of digits allowed in the integer portion of a number.
virtual void	setMaximumFractionDigits (int32_t newValue)
	Sets the maximum number of digits allowed in the fraction portion of a number.
virtual void	setMinimumFractionDigits (int32_t newValue)
	Sets the minimum number of digits allowed in the fraction portion of a number.
int32_t	getMinimumSignificantDigits () const
	Returns the minimum number of significant digits that will be displayed.
int32_t	getMaximumSignificantDigits () const
	Returns the maximum number of significant digits that will be displayed.
void	setMinimumSignificantDigits (int32_t min)
	Sets the minimum number of significant digits that will be displayed.
void	setMaximumSignificantDigits (int32_t max)
	Sets the maximum number of significant digits that will be displayed.
UBool	areSignificantDigitsUsed () const
	Returns true if significant digits are in use, or false if integer and fraction digit counts are in use.
void	setSignificantDigitsUsed (UBool useSignificantDigits)
	Sets whether significant digits are in use, or integer and fraction digit counts are in use.
virtual void	setCurrency (const UChar *theCurrency, UErrorCode &ec)
	Sets the currency used to display currency amounts.
virtual void	setCurrency (const UChar *theCurrency)
	Sets the currency used to display currency amounts.
virtual UClassID	getDynamicClassID (void) const
	Returns a unique class ID POLYMORPHICALLY.
Static Public Member Functions
static UClassID	getStaticClassID (void)
	Return the class ID for this class.
Static Public Attributes
static const char	fgNumberPatterns []
	The resource tags we use to retrieve decimal format data from locale resource bundles.
Protected Member Functions
virtual void	getEffectiveCurrency (UChar *result, UErrorCode &ec) const
	Returns the currency in effect for this formatter.
Static Protected Attributes
static const int32_t	kDoubleIntegerDigits
	number of integer digits
static const int32_t	kDoubleFractionDigits
	number of fraction digits
static const int32_t	kMaxScientificIntegerDigits
	When someone turns on scientific mode, we assume that more than this number of digits is due to flipping from some other mode that didn't restrict the maximum, and so we force 1 integer digit.

Detailed Description

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.

To obtain a NumberFormat for a specific locale (including the default locale) call one of NumberFormat's factory methods such as createInstance(). 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.

Example Usage

     // Normally we would have a GUI with a menu for this
     int32_t locCount;
     const Locale* locales = NumberFormat::getAvailableLocales(locCount);
 
     double myNumber = -1234.56;
     UErrorCode success = U_ZERO_ERROR;
     NumberFormat* form;
 
     // Print out a number with the localized number, currency and percent
     // format for each locale.
     UnicodeString countryName;
     UnicodeString displayName;
     UnicodeString str;
     UnicodeString pattern;
     Formattable fmtable;
     for (int32_t j = 0; j < 3; ++j) {
         cout << endl << "FORMAT " << j << endl;
         for (int32_t i = 0; i < locCount; ++i) {
             if (locales[i].getCountry(countryName).size() == 0) {
                 // skip language-only
                 continue;
             }
             switch (j) {
             case 0:
                 form = NumberFormat::createInstance(locales[i], success ); break;
             case 1:
                 form = NumberFormat::createCurrencyInstance(locales[i], success ); break;
             default:
                 form = NumberFormat::createPercentInstance(locales[i], success ); break;
             }
             if (form) {
                 str.remove();
                 pattern = ((DecimalFormat*)form)->toPattern(pattern);
                 cout << locales[i].getDisplayName(displayName) << ": " << pattern;
                 cout << "  ->  " << form->format(myNumber,str) << endl;
                 form->parse(form->format(myNumber,str), fmtable, success);
                 delete form;  
             }
         }
     }

Patterns

A DecimalFormat consists of a pattern and a set of symbols. The pattern may be set directly using applyPattern(), 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 '1' through '9' indicate rounding.

@ Number No 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 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 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 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 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 set a failing UErrorCode.

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:

The grouping separator ',' can occur inside the integer and sigDigits elements, between any two pattern characters of that element, as long as the integer or sigDigits element is not followed by the exponent element.
Two grouping intervals are recognized: That between the decimal point and the first grouping symbol, and that between the first and second grouping symbols. These intervals are identical in most locales, but in some locales they differ. For example, the pattern "#,##,###" formats the number 123456789 as "12,34,56,789".
The pad specifier padSpec may appear before the prefix, after the prefix, before the suffix, after the suffix, or not at all.
In place of '0', the digits '1' through '9' may be used to indicate a rounding increment.

Parsing

DecimalFormat parses all Unicode characters that represent decimal digits, as defined by u_charDigitValue(). 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 parse(UnicodeString&,Formattable&,ParsePosition&) fails to parse a string, it leaves the parse position unchanged. The convenience method parse(UnicodeString&,Formattable&,UErrorCode&) indicates parse failure by setting a failing UErrorCode.

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.

If the number of actual integer digits exceeds the maximum integer digits, then only the least significant digits are shown. For example, 1997 is formatted as "97" if the maximum integer digits is set to 2.
If the number of actual integer digits is less than the minimum integer digits, then leading zeros are added. For example, 1997 is formatted as "01997" if the minimum integer digits is set to 5.
If the number of actual fraction digits exceeds the maximum fraction digits, then half-even rounding it performed to the maximum fraction digits. For example, 0.125 is formatted as "0.12" if the maximum fraction digits is 2. This behavior can be changed by specifying a rounding increment and a rounding mode.
If the number of actual fraction digits is less than the minimum fraction digits, then trailing zeros are added. For example, 0.125 is formatted as "0.1250" if the mimimum fraction digits is set to 4.
Trailing fractional zeros are not displayed if they occur j positions after the decimal, where j is less than the maximum fraction digits. For example, 0.10004 is formatted as "0.1" if the maximum fraction digits is four or less.

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 10³. 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".

The number of digit characters after the exponent character gives the minimum exponent digit count. There is no maximum. Negative exponents are formatted using the localized minus sign, not the prefix and suffix from the pattern. This allows patterns such as "0.###E0 m/s". To prefix positive exponents with a localized plus sign, specify '+' between the exponent and the digits: "0.###E+0" will produce formats "1E+1", "1E+0", "1E-1", etc. (In localized patterns, use the localized plus sign rather than '+'.)
The minimum number of integer digits is achieved by adjusting the exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". This only happens if there is no maximum number of integer digits. If there is a maximum, then the minimum number of integer digits is fixed at one.
The maximum number of integer digits, if present, specifies the exponent grouping. The most common use of this is to generate engineering notation, in which the exponent is a multiple of three, e.g., "##0.###E0". The number 12345 is formatted using "##0.####E0" as "12.345E3".
When using scientific notation, the formatter controls the digit counts using significant digits logic. The maximum number of significant digits limits the total number of integer and fraction digits that will be shown in the mantissa; it does not affect parsing. For example, 12345 formatted with "##0.##E0" is "12.3E3". See the section on significant digits for more details.
The number of significant digits shown is determined as follows: If areSignificantDigitsUsed() returns false, then the minimum number of significant digits shown is one, and the maximum number of significant digits shown is the sum of the minimum integer and maximum fraction digits, and is unaffected by the maximum integer digits. If this sum is zero, then all significant digits are shown. If areSignificantDigitsUsed() returns true, then the significant digit counts are specified by getMinimumSignificantDigits() and getMaximumSignificantDigits(). In this case, the number of integer digits is fixed at one, and there is no exponent grouping.
Exponential patterns may not contain grouping separators.

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

Significant digit counts may be expressed using patterns that specify a minimum and maximum number of significant digits. These are indicated by the '@' and '#' characters. The minimum number of significant digits is the number of '@' characters. The maximum number of significant digits is the number of '@' characters plus the number of '#' characters following on the right. For example, the pattern "@@@" indicates exactly 3 significant digits. The pattern "@##" indicates from 1 to 3 significant digits. Trailing zero digits to the right of the decimal separator are suppressed after the minimum number of significant digits have been shown. For example, the pattern "@##" formats the number 0.1203 as "0.12".
If a pattern uses significant digits, it may not contain a decimal separator, nor the '0' pattern character. Patterns such as "@00" or "@.###" are disallowed.
Any number of '#' characters may be prepended to the left of the leftmost '@' character. These have no effect on the minimum and maximum significant digits counts, but may be used to position grouping separators. For example, "#,#@#" indicates a minimum of one significant digits, a maximum of two significant digits, and a grouping size of three.
In order to enable significant digits formatting, use a pattern containing the '@' pattern character. Alternatively, call setSignificantDigitsUsed(TRUE).
In order to disable significant digits formatting, use a pattern that does not contain the '@' pattern character. Alternatively, call setSignificantDigitsUsed(FALSE).
The number of significant digits has no effect on parsing.
Significant digits may be used together with exponential notation. Such patterns are equivalent to a normal exponential pattern with a minimum and maximum integer digit count of one, a minimum fraction digit count of getMinimumSignificantDigits() - 1, and a maximum fraction digit count of getMaximumSignificantDigits() - 1. For example, the pattern "@@###E0" is equivalent to "0.0###E0".
If signficant digits are in use, then the integer and fraction digit counts, as set via the API, are ignored. If significant digits are not in use, then the signficant digit counts, as set via the API, are ignored.

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::setSymbol() with a DecimalFormatSymbols::kPadEscapeSymbol selector. For example, "$*x#,##0.00" formats 123 to "$xx123.00", and 1234 to "$1,234.00".

When padding is in effect, the width of the positive subpattern, including prefix and suffix, determines the format width. For example, in the pattern "* #0 o''clock", the format width is 10.
The width is counted in 16-bit code units (UChars).
Some parameters which usually do not matter have meaning when padding is used, because the pattern width is significant with padding. In the pattern "* ##,##,#,##0.##", the format width is 14. The initial characters "##,##," do not affect the grouping size or maximum integer digits, but they do affect the format width.
Padding may be inserted at one of four locations: before the prefix, after the prefix, before the suffix, or after the suffix. If padding is specified in any other location, applyPattern() sets a failing UErrorCode. If there is no prefix, before the prefix and after the prefix are equivalent, likewise for the suffix.
When specified in a pattern, the 32-bit code point immediately following the pad escape is the pad character. This may be any character, including a special pattern character. That is, the pad escape escapes the following character. If there is no character after the pad escape, then the pattern is illegal.

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.

Rounding only affects the string produced by formatting. It does not affect parsing or change any numerical values.
A rounding mode determines how values are rounded; see DecimalFormat::ERoundingMode. Rounding increments specified in patterns use the default mode, DecimalFormat::kRoundHalfEven.
Some locales use rounding in their currency formats to reflect the smallest currency denomination.
In a pattern, digits '1' through '9' specify rounding, but otherwise behave identically to digit '0'.

Synchronization

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

Subclassing

User subclasses are not supported. While clients may write subclasses, such code will not necessarily work and will not be guaranteed to work stably from release to release.

Definition at line 603 of file decimfmt.h.

Member Enumeration Documentation

enum DecimalFormat::ERoundingMode

Rounding mode.

Stable:: ICU 2.4

Enumerator:

kRoundCeiling	Round towards positive infinity.
kRoundFloor	Round towards negative infinity.
kRoundDown	Round towards zero.
kRoundUp	Round away from zero.
kRoundHalfEven	Round towards the nearest integer, or towards the nearest even integer if equidistant.
kRoundHalfDown	Round towards the nearest integer, or towards zero if equidistant.
kRoundHalfUp	Round towards the nearest integer, or away from zero if equidistant.

Definition at line 609 of file decimfmt.h.

enum DecimalFormat::EPadPosition

Pad position.

Stable:: ICU 2.4

Definition at line 627 of file decimfmt.h.

Constructor & Destructor Documentation

DecimalFormat::DecimalFormat ( UErrorCode & status )

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 createInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

Parameters:

status

Output param set to success/failure code. If the pattern is invalid this will be set to a failure code.

Stable:: ICU 2.0

DecimalFormat::DecimalFormat	(	const UnicodeString &	pattern,
		UErrorCode &	status
	)

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 createInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

Parameters:

	pattern	A non-localized pattern string.
	status	Output param set to success/failure code. If the pattern is invalid this will be set to a failure code.

Stable:: ICU 2.0

DecimalFormat::DecimalFormat	(	const UnicodeString &	pattern,
		DecimalFormatSymbols *	symbolsToAdopt,
		UErrorCode &	status
	)

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 createInstance or createCurrencyInstance. 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
	symbolsToAdopt	the set of symbols to be used. The caller should not delete this object after making this call.
	status	Output param set to success/failure code. If the pattern is invalid this will be set to a failure code.

Stable:: ICU 2.0

DecimalFormat::DecimalFormat	(	const UnicodeString &	pattern,
		DecimalFormatSymbols *	symbolsToAdopt,
		UParseError &	parseError,
		UErrorCode &	status
	)

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 createInstance or createCurrencyInstance. 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
	symbolsToAdopt	the set of symbols to be used. The caller should not delete this object after making this call.
	parseError	Output param to receive errors occured during parsing
	status	Output param set to success/failure code. If the pattern is invalid this will be set to a failure code.

Stable:: ICU 2.0

DecimalFormat::DecimalFormat	(	const UnicodeString &	pattern,
		const DecimalFormatSymbols &	symbols,
		UErrorCode &	status
	)

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 createInstance or createCurrencyInstance. 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
	status	Output param set to success/failure code. If the pattern is invalid this will be set to a failure code.

Stable:: ICU 2.0

DecimalFormat::DecimalFormat ( const DecimalFormat & source )

Copy constructor.

Parameters:

source

the DecimalFormat object to be copied from.

Stable:: ICU 2.0

virtual DecimalFormat::~DecimalFormat ( ) [virtual]

Destructor.

Stable:: ICU 2.0

Member Function Documentation

DecimalFormat& DecimalFormat::operator= ( const DecimalFormat & rhs )

Assignment operator.

Parameters:

rhs

the DecimalFormat object to be copied.

Stable:: ICU 2.0

virtual Format* DecimalFormat::clone ( void ) const [virtual]

Clone this Format object polymorphically.

The caller owns the result and should delete it when done.

Returns:: a polymorphic copy of this DecimalFormat.

Stable:: ICU 2.0

Implements Format.

virtual UBool DecimalFormat::operator== ( const Format & other ) const [virtual]

Return true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Parameters:

other

the object to be compared with.

Returns:: true if the given Format objects are semantically equal.

Stable:: ICU 2.0

Reimplemented from NumberFormat.

virtual UnicodeString& DecimalFormat::format	(	double	number,
		UnicodeString &	appendTo,
		FieldPosition &	pos
	)			const `[virtual]`

Format a double or long number using base-10 representation.

Parameters:

	number	The value to be formatted.
	appendTo	Output parameter to receive result. Result is appended to existing contents.
	pos	On input: an alignment field, if desired. On output: the offsets of the alignment field.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.0

Implements NumberFormat.

Referenced by format().

virtual UnicodeString& DecimalFormat::format	(	int32_t	number,
		UnicodeString &	appendTo,
		FieldPosition &	pos
	)			const `[virtual]`

Format a long number using base-10 representation.

Parameters:

	number	The value to be formatted.
	appendTo	Output parameter to receive result. Result is appended to existing contents.
	pos	On input: an alignment field, if desired. On output: the offsets of the alignment field.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.0

Implements NumberFormat.

virtual UnicodeString& DecimalFormat::format	(	int64_t	number,
		UnicodeString &	appendTo,
		FieldPosition &	pos
	)			const `[virtual]`

Format an int64 number using base-10 representation.

Parameters:

	number	The value to be formatted.
	appendTo	Output parameter to receive result. Result is appended to existing contents.
	pos	On input: an alignment field, if desired. On output: the offsets of the alignment field.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.8

Reimplemented from NumberFormat.

virtual UnicodeString& DecimalFormat::format	(	const Formattable &	obj,
		UnicodeString &	appendTo,
		FieldPosition &	pos,
		UErrorCode &	status
	)			const `[virtual]`

Format a Formattable using base-10 representation.

Parameters:

	obj	The value to be formatted.
	appendTo	Output parameter to receive result. Result is appended to existing contents.
	pos	On input: an alignment field, if desired. On output: the offsets of the alignment field.
	status	Error code indicating success or failure.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.0

Reimplemented from NumberFormat.

UnicodeString & DecimalFormat::format	(	const Formattable &	obj,
		UnicodeString &	appendTo,
		UErrorCode &	status
	)			const `[inline]`

Redeclared NumberFormat method.

Formats an object to produce a string.

Parameters:

	obj	The object to format.
	appendTo	Output parameter to receive result. Result is appended to existing contents.
	status	Output parameter filled in with success or failure status.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.0

Reimplemented from NumberFormat.

Definition at line 1864 of file decimfmt.h.

References NumberFormat::format().

UnicodeString & DecimalFormat::format	(	double	number,
		UnicodeString &	appendTo
	)			const `[inline]`

Redeclared NumberFormat method.

Format a double number.

Parameters:

	number	The value to be formatted.
	appendTo	Output parameter to receive result. Result is appended to existing contents.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.0

Reimplemented from NumberFormat.

Definition at line 1873 of file decimfmt.h.

References format().

UnicodeString & DecimalFormat::format	(	int32_t	number,
		UnicodeString &	appendTo
	)			const `[inline]`

Redeclared NumberFormat method.

Format a long number. These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters:

	number	The value to be formatted.
	appendTo	Output parameter to receive result. Result is appended to existing contents.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.0

Reimplemented from NumberFormat.

Definition at line 1880 of file decimfmt.h.

References format().

UnicodeString& DecimalFormat::format	(	int64_t	number,
		UnicodeString &	appendTo
	)			const

Redeclared NumberFormat method.

Format an int64 number. These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters:

	number	The value to be formatted.
	appendTo	Output parameter to receive result. Result is appended to existing contents.

Returns:: Reference to 'appendTo' parameter.

Stable:: ICU 2.8

Reimplemented from NumberFormat.

virtual void DecimalFormat::parse	(	const UnicodeString &	text,
		Formattable &	result,
		ParsePosition &	parsePosition
	)			const `[virtual]`

Parse the given string using this object's choices.

The method does string comparisons to try to find an optimal match. If no object can be parsed, index is unchanged, and NULL is returned. The result is returned as the most parsimonious type of Formattable that will accomodate all of the necessary precision. For example, if the result is exactly 12, it will be returned as a long. However, if it is 1.5, it will be returned as a double.

Parameters:

	text	The text to be parsed.
	result	Formattable to be set to the parse result. If parse fails, return contents are undefined.
	parsePosition	The position to start parsing at on input. On output, moved to after the last successfully parse character. On parse failure, does not change.

See also:: Formattable

Stable:: ICU 2.0

Implements NumberFormat.

Symbol	Location	Localized?	Meaning
`0`	Number	Yes	Digit
`1-9`	Number	Yes	'1' through '9' indicate rounding.
`@`	Number	No	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	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	Pad escape, precedes pad character

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`

DecimalFormat Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation