ICU 60.2 60.2

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Attributes
icu::DecimalFormat Class Reference

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

`#include <decimfmt.h>`

Inheritance diagram for icu::DecimalFormat:

## Public Types
enum | EPadPosition { kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, kPadAfterSuffix }
| Pad position. More...
Public Types inherited from icu::NumberFormat
enum | ERoundingMode { kRoundCeiling, kRoundFloor, kRoundDown, kRoundUp, kRoundHalfEven, kRoundHalfDown, kRoundHalfUp, kRoundUnnecessary }
| Rounding mode. More...
enum | EAlignmentFields { kIntegerField = UNUM_INTEGER_FIELD, kFractionField = UNUM_FRACTION_FIELD, kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD, kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD, kExponentSignField = UNUM_EXPONENT_SIGN_FIELD, kExponentField = UNUM_EXPONENT_FIELD, kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD, kCurrencyField = UNUM_CURRENCY_FIELD, kPercentField = UNUM_PERCENT_FIELD, kPermillField = UNUM_PERMILL_FIELD, kSignField = UNUM_SIGN_FIELD, INTEGER_FIELD = UNUM_INTEGER_FIELD, FRACTION_FIELD = UNUM_FRACTION_FIELD }
| Alignment Field constants used to construct a FieldPosition object. More...

## Public Member Functions
| DecimalFormat (UErrorCode &status)
| Create a DecimalFormat using the default pattern and symbols for the default locale. More...
| DecimalFormat (const UnicodeString &pattern, UErrorCode &status)
| Create a DecimalFormat from the given pattern and the symbols for the default locale. More...
| DecimalFormat (const UnicodeString &pattern, DecimalFormatSymbols *symbolsToAdopt, UErrorCode &status)
| Create a DecimalFormat from the given pattern and symbols. More...
| DecimalFormat (const UnicodeString &pattern, DecimalFormatSymbols *symbolsToAdopt, UNumberFormatStyle style, UErrorCode &status)
| This API is for ICU use only. More...
virtual DecimalFormat & | setAttribute (UNumberFormatAttribute attr, int32_t newvalue, UErrorCode &status)
| Set an integer attribute on this DecimalFormat. More...
virtual int32_t | getAttribute (UNumberFormatAttribute attr, UErrorCode &status) const
| Get an integer May return U_UNSUPPORTED_ERROR if this instance does not support the specified attribute. More...
virtual void | setGroupingUsed (UBool newValue)
| Set whether or not grouping will be used in this format. More...
virtual void | setParseIntegerOnly (UBool value)
| Sets whether or not numbers should be parsed as integers only. More...
virtual void | setContext (UDisplayContext value, UErrorCode &status)
| Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE. More...
| DecimalFormat (const UnicodeString &pattern, DecimalFormatSymbols *symbolsToAdopt, UParseError &parseError, UErrorCode &status)
| Create a DecimalFormat from the given pattern and symbols. More...
| DecimalFormat (const UnicodeString &pattern, const DecimalFormatSymbols &symbols, UErrorCode &status)
| Create a DecimalFormat from the given pattern and symbols. More...
| DecimalFormat (const DecimalFormat &source)
| Copy constructor. More...
DecimalFormat & | operator= (const DecimalFormat &rhs)
| Assignment operator. More...
virtual | ~DecimalFormat ()
| Destructor. More...
virtual Format * | clone (void) const
| Clone this Format object polymorphically. More...
virtual UBool | operator== (const Format &other) const
| Return true if the given Format objects are semantically equal. More...
virtual UnicodeString & | format (double number, UnicodeString &appendTo, FieldPosition &pos) const
| Format a double or long number using base-10 representation. More...
virtual UnicodeString & | format (double number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Format a double or long number using base-10 representation. More...
virtual UnicodeString & | format (double number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format a double or long number using base-10 representation. More...
virtual UnicodeString & | format (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const
| Format a long number using base-10 representation. More...
virtual UnicodeString & | format (int32_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Format a long number using base-10 representation. More...
virtual UnicodeString & | format (int32_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format a long number using base-10 representation. More...
virtual UnicodeString & | format (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const
| Format an int64 number using base-10 representation. More...
virtual UnicodeString & | format (int64_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Format an int64 number using base-10 representation. More...
virtual UnicodeString & | format (int64_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format an int64 number using base-10 representation. More...
virtual UnicodeString & | format (StringPiece number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format a decimal number. More...
virtual UnicodeString & | format (const DigitList &number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format a decimal number. More...
virtual UnicodeString & | format (const VisibleDigitsWithExponent &number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Format a decimal number. More...
virtual UnicodeString & | format (const VisibleDigitsWithExponent &number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format a decimal number. More...
virtual UnicodeString & | format (const DigitList &number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Format a decimal number. More...
virtual void | parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const
| Parse the given string using this object's choices. More...
virtual CurrencyAmount * | parseCurrency (const UnicodeString &text, ParsePosition &pos) const
| Parses text from the given string as a currency amount. More...
virtual const DecimalFormatSymbols * | getDecimalFormatSymbols (void) const
| Returns the decimal format symbols, which is generally not changed by the programmer or user. More...
virtual void | adoptDecimalFormatSymbols (DecimalFormatSymbols *symbolsToAdopt)
| Sets the decimal format symbols, which is generally not changed by the programmer or user. More...
virtual void | setDecimalFormatSymbols (const DecimalFormatSymbols &symbols)
| Sets the decimal format symbols, which is generally not changed by the programmer or user. More...
virtual const CurrencyPluralInfo * | getCurrencyPluralInfo (void) const
| Returns the currency plural format information, which is generally not changed by the programmer or user. More...
virtual void | adoptCurrencyPluralInfo (CurrencyPluralInfo *toAdopt)
| Sets the currency plural format information, which is generally not changed by the programmer or user. More...
virtual void | setCurrencyPluralInfo (const CurrencyPluralInfo &info)
| Sets the currency plural format information, which is generally not changed by the programmer or user. More...
UnicodeString & | getPositivePrefix (UnicodeString &result) const
| Get the positive prefix. More...
virtual void | setPositivePrefix (const UnicodeString &newValue)
| Set the positive prefix. More...
UnicodeString & | getNegativePrefix (UnicodeString &result) const
| Get the negative prefix. More...
virtual void | setNegativePrefix (const UnicodeString &newValue)
| Set the negative prefix. More...
UnicodeString & | getPositiveSuffix (UnicodeString &result) const
| Get the positive suffix. More...
virtual void | setPositiveSuffix (const UnicodeString &newValue)
| Set the positive suffix. More...
UnicodeString & | getNegativeSuffix (UnicodeString &result) const
| Get the negative suffix. More...
virtual void | setNegativeSuffix (const UnicodeString &newValue)
| Set the negative suffix. More...
int32_t | getMultiplier (void) const
| Get the multiplier for use in percent, permill, etc. More...
virtual void | setMultiplier (int32_t newValue)
| Set the multiplier for use in percent, permill, etc. More...
virtual double | getRoundingIncrement (void) const
| Get the rounding increment. More...
virtual void | setRoundingIncrement (double newValue)
| Set the rounding increment. More...
virtual ERoundingMode | getRoundingMode (void) const
| Get the rounding mode. More...
virtual void | setRoundingMode (ERoundingMode roundingMode)
| Set the rounding mode. More...
virtual int32_t | getFormatWidth (void) const
| Get the width to which the output of format() is padded. More...
virtual void | setFormatWidth (int32_t width)
| Set the width to which the output of format() is padded. More...
virtual UnicodeString | getPadCharacterString () const
| Get the pad character used to pad to the format width. More...
virtual void | setPadCharacter (const UnicodeString &padChar)
| Set the character used to pad to the format width. More...
virtual EPadPosition | getPadPosition (void) const
| Get the position at which padding will take place. More...
virtual void | setPadPosition (EPadPosition padPos)
| Set the position at which padding will take place. More...
virtual UBool | isScientificNotation (void) const
| Return whether or not scientific notation is used. More...
virtual void | setScientificNotation (UBool useScientific)
| Set whether or not scientific notation is used. More...
virtual int8_t | getMinimumExponentDigits (void) const
| Return the minimum exponent digits that will be shown. More...
virtual void | setMinimumExponentDigits (int8_t minExpDig)
| Set the minimum exponent digits that will be shown. More...
virtual UBool | isExponentSignAlwaysShown (void) const
| Return whether the exponent sign is always shown. More...
virtual void | setExponentSignAlwaysShown (UBool expSignAlways)
| Set whether the exponent sign is always shown. More...
int32_t | getGroupingSize (void) const
| Return the grouping size. More...
virtual void | setGroupingSize (int32_t newValue)
| Set the grouping size. More...
int32_t | getSecondaryGroupingSize (void) const
| Return the secondary grouping size. More...
virtual void | setSecondaryGroupingSize (int32_t newValue)
| Set the secondary grouping size. More...
int32_t | getMinimumGroupingDigits () const
| Returns the minimum number of grouping digits. More...
virtual void | setMinimumGroupingDigits (int32_t newValue)
| Sets the minimum grouping digits. More...
UBool | isDecimalSeparatorAlwaysShown (void) const
| Allows you to get the behavior of the decimal separator with integers. More...
virtual void | setDecimalSeparatorAlwaysShown (UBool newValue)
| Allows you to set the behavior of the decimal separator with integers. More...
UBool | isDecimalPatternMatchRequired (void) const
| Allows you to get the parse behavior of the pattern decimal mark. More...
virtual void | setDecimalPatternMatchRequired (UBool newValue)
| Allows you to set the behavior of the pattern decimal mark. More...
virtual UnicodeString & | toPattern (UnicodeString &result) const
| Synthesizes a pattern string that represents the current state of this Format object. More...
virtual UnicodeString & | toLocalizedPattern (UnicodeString &result) const
| Synthesizes a localized pattern string that represents the current state of this Format object. More...
virtual void | applyPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
| Apply the given pattern to this Format object. More...
virtual void | applyPattern (const UnicodeString &pattern, UErrorCode &status)
| Sets the pattern. More...
virtual void | applyLocalizedPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
| Apply the given pattern to this Format object. More...
virtual void | applyLocalizedPattern (const UnicodeString &pattern, UErrorCode &status)
| Apply the given pattern to this Format object. More...
virtual void | setMaximumIntegerDigits (int32_t newValue)
| Sets the maximum number of digits allowed in the integer portion of a number. More...
virtual void | setMinimumIntegerDigits (int32_t newValue)
| Sets the minimum number of digits allowed in the integer portion of a number. More...
virtual void | setMaximumFractionDigits (int32_t newValue)
| Sets the maximum number of digits allowed in the fraction portion of a number. More...
virtual void | setMinimumFractionDigits (int32_t newValue)
| Sets the minimum number of digits allowed in the fraction portion of a number. More...
int32_t | getMinimumSignificantDigits () const
| Returns the minimum number of significant digits that will be displayed. More...
int32_t | getMaximumSignificantDigits () const
| Returns the maximum number of significant digits that will be displayed. More...
void | setMinimumSignificantDigits (int32_t min)
| Sets the minimum number of significant digits that will be displayed. More...
void | setMaximumSignificantDigits (int32_t max)
| Sets the maximum number of significant digits that will be displayed. More...
UBool | areSignificantDigitsUsed () const
| Returns true if significant digits are in use, or false if integer and fraction digit counts are in use. More...
void | setSignificantDigitsUsed (UBool useSignificantDigits)
| Sets whether significant digits are in use, or integer and fraction digit counts are in use. More...
virtual void | setCurrency (const char16_t *theCurrency, UErrorCode &ec)
| Sets the currency used to display currency amounts. More...
virtual void | setCurrency (const char16_t *theCurrency)
| Sets the currency used to display currency amounts. More...
void | setCurrencyUsage (UCurrencyUsage newUsage, UErrorCode *ec)
| Sets the `Currency Context` object used to display currency. More...
UCurrencyUsage | getCurrencyUsage () const
| Returns the `Currency Context` object used to display currency. More...
FixedDecimal | getFixedDecimal (double number, UErrorCode &status) const
| Get a FixedDecimal corresponding to a double as it would be formatted by this DecimalFormat. More...
FixedDecimal | getFixedDecimal (const Formattable &number, UErrorCode &status) const
| Get a FixedDecimal corresponding to a formattable as it would be formatted by this DecimalFormat. More...
FixedDecimal | getFixedDecimal (DigitList &number, UErrorCode &status) const
| Get a FixedDecimal corresponding to a DigitList as it would be formatted by this DecimalFormat. More...
VisibleDigitsWithExponent & | initVisibleDigitsWithExponent (double number, VisibleDigitsWithExponent &digits, UErrorCode &status) const
| Get a VisibleDigitsWithExponent corresponding to a double as it would be formatted by this DecimalFormat. More...
VisibleDigitsWithExponent & | initVisibleDigitsWithExponent (const Formattable &number, VisibleDigitsWithExponent &digits, UErrorCode &status) const
| Get a VisibleDigitsWithExponent corresponding to a formattable as it would be formatted by this DecimalFormat. More...
VisibleDigitsWithExponent & | initVisibleDigitsWithExponent (DigitList &number, VisibleDigitsWithExponent &digits, UErrorCode &status) const
| Get a VisibleDigitsWithExponent corresponding to a DigitList as it would be formatted by this DecimalFormat. More...
virtual UClassID | getDynamicClassID (void) const
| Returns a unique class ID POLYMORPHICALLY. More...
Public Member Functions inherited from icu::NumberFormat
virtual | ~NumberFormat ()
| Destructor. More...
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Format an object to produce a string. More...
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format an object to produce a string. More...
virtual void | parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const
| Parse a string to produce an object. More...
UnicodeString & | format (double number, UnicodeString &appendTo) const
| Format a double number. More...
UnicodeString & | format (int32_t number, UnicodeString &appendTo) const
| Format a long number. More...
UnicodeString & | format (int64_t number, UnicodeString &appendTo) const
| Format an int64 number. More...
virtual void | parse (const UnicodeString &text, Formattable &result, UErrorCode &status) const
| Parse a string as a numeric value, and return a Formattable numeric object. More...
UBool | isParseIntegerOnly (void) const
| Return true if this format will parse numbers as integers only. More...
virtual void | setLenient (UBool enable)
| Sets whether lenient parsing should be enabled (it is off by default). More...
virtual UBool | isLenient (void) const
| Returns whether lenient parsing is enabled (it is off by default). More...
UBool | isGroupingUsed (void) const
| Returns true if grouping is used in this format. More...
int32_t | getMaximumIntegerDigits (void) const
| Returns the maximum number of digits allowed in the integer portion of a number. More...
int32_t | getMinimumIntegerDigits (void) const
| Returns the minimum number of digits allowed in the integer portion of a number. More...
int32_t | getMaximumFractionDigits (void) const
| Returns the maximum number of digits allowed in the fraction portion of a number. More...
int32_t | getMinimumFractionDigits (void) const
| Returns the minimum number of digits allowed in the fraction portion of a number. More...
const char16_t * | getCurrency () const
| Gets the currency used to display currency amounts. More...
virtual UDisplayContext | getContext (UDisplayContextType type, UErrorCode &status) const
| Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYPE_CAPITALIZATION. More...
Public Member Functions inherited from icu::Format
virtual | ~Format ()
| Destructor. More...
UBool | operator!= (const Format &other) const
| Return true if the given Format objects are not semantically equal. More...
UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Formats an object to produce a string. More...
void | parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
| Parses a string to produce an object. More...
Locale | getLocale (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object. More...
const char * | getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object. More...
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor. More...

## Static Public Member Functions
static UClassID | getStaticClassID (void)
| Return the class ID for this class. More...
Static Public Member Functions inherited from icu::NumberFormat
static NumberFormat * | createInstance (UErrorCode &)
| Create a default style NumberFormat for the current default locale. More...
static NumberFormat * | createInstance (const Locale &inLocale, UErrorCode &)
| Create a default style NumberFormat for the specified locale. More...
static NumberFormat * | createInstance (const Locale &desiredLocale, UNumberFormatStyle style, UErrorCode &errorCode)
| Create a specific style NumberFormat for the specified locale. More...
static NumberFormat * | internalCreateInstance (const Locale &desiredLocale, UNumberFormatStyle style, UErrorCode &errorCode)
| ICU use only. More...
static const SharedNumberFormat * | createSharedInstance (const Locale &inLocale, UNumberFormatStyle style, UErrorCode &status)
| ICU use only. More...
static NumberFormat * | createCurrencyInstance (UErrorCode &)
| Returns a currency format for the current default locale. More...
static NumberFormat * | createCurrencyInstance (const Locale &inLocale, UErrorCode &)
| Returns a currency format for the specified locale. More...
static NumberFormat * | createPercentInstance (UErrorCode &)
| Returns a percentage format for the current default locale. More...
static NumberFormat * | createPercentInstance (const Locale &inLocale, UErrorCode &)
| Returns a percentage format for the specified locale. More...
static NumberFormat * | createScientificInstance (UErrorCode &)
| Returns a scientific format for the current default locale. More...
static NumberFormat * | createScientificInstance (const Locale &inLocale, UErrorCode &)
| Returns a scientific format for the specified locale. More...
static const Locale * | getAvailableLocales (int32_t &count)
| Get the set of Locales for which NumberFormats are installed. More...
static URegistryKey | registerFactory (NumberFormatFactory *toAdopt, UErrorCode &status)
| Register a new NumberFormatFactory. More...
static UBool | unregister (URegistryKey key, UErrorCode &status)
| Unregister a previously-registered NumberFormatFactory using the key returned from the register call. More...
static StringEnumeration * | getAvailableLocales (void)
| Return a StringEnumeration over the locales available at the time of the call, including registered locales. More...
static UClassID | getStaticClassID (void)
| Return the class ID for this class. More...

## Static Public Attributes
static const char | fgNumberPatterns []
| The resource tags we use to retrieve decimal format data from locale resource bundles. More...

## Protected Member Functions
DigitList & | _round (const DigitList &number, DigitList &adjustedNum, UBool &isNegative, UErrorCode &status) const
| Rounds a value according to the rules of this object. More...
virtual void | getEffectiveCurrency (char16_t *result, UErrorCode &ec) const
| Returns the currency in effect for this formatter. More...
Protected Member Functions inherited from icu::NumberFormat
| NumberFormat ()
| Default constructor for subclass use only. More...
| NumberFormat (const NumberFormat &)
| Copy constructor. More...
NumberFormat & | operator= (const NumberFormat &)
| Assignment operator. More...
Protected Member Functions inherited from icu::Format
void | setLocaleIDs (const char *valid, const char *actual)
| Format ()
| Default constructor for subclass use only. More...
| Format (const Format &)
Format & | operator= (const Format &)

## Static Protected Attributes
static const int32_t | kDoubleIntegerDigits
| number of integer digits More...
static const int32_t | kDoubleFractionDigits
| number of fraction digits More...
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. More...
Static Protected Attributes inherited from icu::NumberFormat
static const int32_t | gDefaultMaxIntegerDigits
static const int32_t | gDefaultMinIntegerDigits

## Additional Inherited Members
Static Protected Member Functions inherited from icu::NumberFormat
static NumberFormat * | makeInstance (const Locale &desiredLocale, UNumberFormatStyle style, UBool mustBeDecimalFormat, UErrorCode &errorCode)
| Creates the specified number format style of the desired locale. More...
Static Protected Member Functions inherited from icu::Format
static void | syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)
| Simple function for initializing a UParseError from a UnicodeString. More...

## 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", "USD123", "123 US dollars"). 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;
}
}
}

Another example use createInstance(style)

    // Print out a number using the localized number, currency,
    // percent, scientific, integer, iso currency, and plural currency
    // format for each locale
    Locale* locale = new Locale("en", "US");
    double myNumber = 1234.56;
    UErrorCode success = U_ZERO_ERROR;
    UnicodeString str;
    Formattable fmtable;
    for (int j=NumberFormat::kNumberStyle;
         j<=NumberFormat::kPluralCurrencyStyle;
         ++j) {
        NumberFormat* format = NumberFormat::createInstance(locale, j, success);
        str.remove();
        cout << "format result " << form->format(myNumber, str) << endl;
        format->parse(form->format(myNumber, str), fmtable, success);
    }

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 tripled, replaced by currency plural names, for example, "US dollar" or "US dollars" for America. 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 in lenient mode; otherwise, if present, they must be in appropriate positions.

For currency parsing, the formatter is able to parse every currency style formats no matter which style the formatter is constructed with. For example, a formatter instance gotten from NumberFormat.getInstance(ULocale, NumberFormat.CURRENCYSTYLE) can parse formats such as "USD1.00" and "3.00 US dollars".

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 rounding is 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/or 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 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".

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

- 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

1. "#,##0.05" specifies a rounding increment of 0.05.

In the absense of an explicit rounding increment numbers are rounded to their formatted width.

- 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. The default rounding mode is DecimalFormat::kRoundHalfEven. The rounding mode can only be set through the API; it can not be set with a pattern.

- 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 669 of file decimfmt.h.

## Member Enumeration Documentation

enum icu::DecimalFormat::EPadPosition

Pad position.

Stable:
  ICU 2.4

Definition at line 675 of file decimfmt.h.

## Constructor & Destructor Documentation

icu::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

icu::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

icu::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

icu::DecimalFormat::DecimalFormat | ( | const UnicodeString & | pattern,
|  | DecimalFormatSymbols * | symbolsToAdopt,
|  | UNumberFormatStyle | style,
|  | UErrorCode & | status
| ) |  |

This API is for ICU use only.

Create a DecimalFormat from the given pattern, symbols, and style.

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.
  style | style of decimal format
  status | Output param set to success/failure code. If the pattern is invalid this will be set to a failure code.

Internal:
  Do not use. This API is for internal use only.

icu::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

icu::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

icu::DecimalFormat::DecimalFormat | ( | const DecimalFormat & | source | ) |

Copy constructor.

Parameters

  source | the DecimalFormat object to be copied from.

Stable:
  ICU 2.0

virtual icu::DecimalFormat::~DecimalFormat | ( |  | ) |
| virtual

Destructor.

Stable:
  ICU 2.0

## Member Function Documentation

DigitList& icu::DecimalFormat::_round | ( | const DigitList & | number,
|  | DigitList & | adjustedNum,
|  | UBool & | isNegative,
|  | UErrorCode & | status
| ) |  | const
| protected

Rounds a value according to the rules of this object.

Internal:
  Do not use. This API is for internal use only.

virtual void icu::DecimalFormat::adoptCurrencyPluralInfo | ( | CurrencyPluralInfo * | toAdopt | ) |
| virtual

Sets the currency plural format information, which is generally not changed by the programmer or user.

Parameters

  toAdopt | CurrencyPluralInfo to be adopted.

Stable:
  ICU 4.2

virtual void icu::DecimalFormat::adoptDecimalFormatSymbols | ( | DecimalFormatSymbols * | symbolsToAdopt | ) |
| virtual

Sets the decimal format symbols, which is generally not changed by the programmer or user.

Parameters

  symbolsToAdopt | DecimalFormatSymbols to be adopted.

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::applyLocalizedPattern | ( | const UnicodeString & | pattern,
|  | UParseError & | parseError,
|  | UErrorCode & | status
| ) |  |
| virtual

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.

Parameters

  pattern | The localized pattern to be applied.
  parseError | Struct to recieve information on position of error if an error is encountered
  status | Output param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::applyLocalizedPattern | ( | const UnicodeString & | pattern,
|  | UErrorCode & | status
| ) |  |
| virtual

Apply the given pattern to this Format object.

Parameters

  pattern | The localized pattern to be applied.
  status | Output param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::applyPattern | ( | const UnicodeString & | pattern,
|  | UParseError & | parseError,
|  | UErrorCode & | status
| ) |  |
| virtual

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

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

Parameters

  pattern | The pattern to be applied.
  parseError | Struct to recieve information on position of error if an error is encountered
  status | Output param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::applyPattern | ( | const UnicodeString & | pattern,
|  | UErrorCode & | status
| ) |  |
| virtual

Sets the pattern.

Parameters

  pattern | The pattern to be applied.
  status | Output param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.

Stable:
  ICU 2.0

UBool icu::DecimalFormat::areSignificantDigitsUsed | ( |  | ) | const

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

Stable:
  ICU 3.0

virtual Format* icu::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 icu::Format.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::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 icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | double | number,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status
| ) |  | 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.
  status |

Returns
  Reference to 'appendTo' parameter.

Internal:
  Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | double | number,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status
| ) |  | 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.
  posIter | On return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.4

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::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 icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | int32_t | number,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status
| ) |  | 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.

Internal:
  Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | int32_t | number,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status
| ) |  | 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.
  posIter | On return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.4

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::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 icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | int64_t | number,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status
| ) |  | 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.

Internal:
  Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | int64_t | number,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status
| ) |  | 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.
  posIter | On return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.4

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | StringPiece | number,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status
| ) |  | const
| virtual

Format a decimal number.

The syntax of the unformatted number is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal

Parameters

  number | The unformatted number, as a string.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  posIter | On return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.4

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | const DigitList & | number,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status
| ) |  | const
| virtual

Format a decimal number.

The number is a DigitList wrapper onto a floating point decimal number. The default implementation in NumberFormat converts the decimal number to a double and formats that.

Parameters

  number | The number, a DigitList format Decimal Floating Point.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  posIter | On return, can be used to iterate over positions of fields generated by this format call.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Internal:
  Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual UnicodeString& icu::DecimalFormat::format | ( | const VisibleDigitsWithExponent & | number,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status
| ) |  | const
| virtual

Format a decimal number.

Parameters

  number | The number
  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 | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Internal:
  Do not use. This API is for internal use only.

virtual UnicodeString& icu::DecimalFormat::format | ( | const VisibleDigitsWithExponent & | number,
|  | UnicodeString & | appendTo,
|  | FieldPositionIterator * | posIter,
|  | UErrorCode & | status
| ) |  | const
| virtual

Format a decimal number.

Parameters

  number | The number
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  posIter | On return, can be used to iterate over positions of fields generated by this format call.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Internal:
  Do not use. This API is for internal use only.

virtual UnicodeString& icu::DecimalFormat::format | ( | const DigitList & | number,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | status
| ) |  | const
| virtual

Format a decimal number.

The number is a DigitList wrapper onto a floating point decimal number. The default implementation in NumberFormat converts the decimal number to a double and formats that.

Parameters

  number | The number, a DigitList format Decimal Floating Point.
  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 | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Internal:
  Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual int32_t icu::DecimalFormat::getAttribute | ( | UNumberFormatAttribute | attr,
|  | UErrorCode & | status
| ) |  | const
| virtual

Get an integer May return U_UNSUPPORTED_ERROR if this instance does not support the specified attribute.

Parameters

  attr | the attribute to set
  status | the error type

Returns
  the attribute value. Undefined if there is an error.

Stable:
  ICU 51

virtual const CurrencyPluralInfo* icu::DecimalFormat::getCurrencyPluralInfo | ( | void |  | ) | const
| virtual

Returns the currency plural format information, which is generally not changed by the programmer or user.

Returns
  desired CurrencyPluralInfo

Stable:
  ICU 4.2

UCurrencyUsage icu::DecimalFormat::getCurrencyUsage | ( |  | ) | const

Returns the `Currency Context` object used to display currency.

Stable:
  ICU 54

virtual const DecimalFormatSymbols* icu::DecimalFormat::getDecimalFormatSymbols | ( | void |  | ) | const
| virtual

Returns the decimal format symbols, which is generally not changed by the programmer or user.

Returns
  desired DecimalFormatSymbols

See also
  DecimalFormatSymbols

Stable:
  ICU 2.0

virtual UClassID icu::DecimalFormat::getDynamicClassID | ( | void |  | ) | const
| virtual

Returns a unique class ID POLYMORPHICALLY.

Pure virtual override. This method is to implement a simple version of RTTI, since not all C++ compilers support genuine RTTI. Polymorphic operator==() and clone() methods call this method.

Returns
  The class ID for this object. All objects of a given class have the same class ID. Objects of other classes have different class IDs.

Stable:
  ICU 2.0

Implements icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual void icu::DecimalFormat::getEffectiveCurrency | ( | char16_t * | result,
|  | UErrorCode & | ec
| ) |  | const
| protected virtual

Returns the currency in effect for this formatter.

Subclasses should override this method as needed. Unlike getCurrency(), this method should never return "".

Returns
  output parameter for null-terminated result, which must have a capacity of at least 4

Internal:
  Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

FixedDecimal icu::DecimalFormat::getFixedDecimal | ( | double | number,
|  | UErrorCode & | status
| ) |  | const

Get a FixedDecimal corresponding to a double as it would be formatted by this DecimalFormat.

Internal, not intended for public use.

Internal:
  Do not use. This API is for internal use only.

FixedDecimal icu::DecimalFormat::getFixedDecimal | ( | const Formattable & | number,
|  | UErrorCode & | status
| ) |  | const

Get a FixedDecimal corresponding to a formattable as it would be formatted by this DecimalFormat.

Internal, not intended for public use.

Internal:
  Do not use. This API is for internal use only.

FixedDecimal icu::DecimalFormat::getFixedDecimal | ( | DigitList & | number,
|  | UErrorCode & | status
| ) |  | const

Get a FixedDecimal corresponding to a DigitList as it would be formatted by this DecimalFormat.

Note: the DigitList may be modified. Internal, not intended for public use.

Internal:
  Do not use. This API is for internal use only.

virtual int32_t icu::DecimalFormat::getFormatWidth | ( | void |  | ) | const
| virtual

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
  setFormatWidth
  getPadCharacterString
  setPadCharacter
  getPadPosition
  setPadPosition

Stable:
  ICU 2.0

int32_t icu::DecimalFormat::getGroupingSize | ( | void |  | ) | const

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.

Returns
  the grouping size.

See also
  setGroupingSize
  NumberFormat::isGroupingUsed
  DecimalFormatSymbols::getGroupingSeparator

Stable:
  ICU 2.0

int32_t icu::DecimalFormat::getMaximumSignificantDigits | ( |  | ) | const

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

Stable:
  ICU 3.0

virtual int8_t icu::DecimalFormat::getMinimumExponentDigits | ( | void |  | ) | const
| virtual

Return the minimum exponent digits that will be shown.

Returns
  the minimum exponent digits that will be shown

See also
  setScientificNotation
  isScientificNotation
  setMinimumExponentDigits
  isExponentSignAlwaysShown
  setExponentSignAlwaysShown

Stable:
  ICU 2.0

int32_t icu::DecimalFormat::getMinimumGroupingDigits | ( |  | ) | const

Returns the minimum number of grouping digits.

Grouping separators are output if there are at least this many digits to the left of the first (rightmost) grouping separator, that is, there are at least (minimum grouping + grouping size) integer digits. (Subject to isGroupingUsed().)

For example, if this value is 2, and the grouping size is 3, then 9999 -> "9999" and 10000 -> "10,000"

This is a technology preview. This API may change behavior or may be removed.

The default value for this attribute is 0. A value of 1, 0, or lower, means that the use of grouping separators only depends on the grouping size (and on isGroupingUsed()). Currently, the corresponding CLDR data is not used; this is likely to change.

See also
  setMinimumGroupingDigits
  getGroupingSize

Internal:
  Do not use. This API is for internal use only. technology preview

int32_t icu::DecimalFormat::getMinimumSignificantDigits | ( |  | ) | const

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

Stable:
  ICU 3.0

int32_t icu::DecimalFormat::getMultiplier | ( | void |  | ) | const

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 "\\u2031" and the multiplier to be 1000.

Returns
  the multiplier for use in percent, permill, etc. Examples: with 100, 1.23 -> "123", and "123" -> 1.23

Stable:
  ICU 2.0

UnicodeString& icu::DecimalFormat::getNegativePrefix | ( | UnicodeString & | result | ) | const

Get the negative prefix.

Parameters

  result | Output param which will receive the negative prefix.

Returns
  A reference to 'result'. Examples: -123, ($123) (with negative suffix), sFr-123

Stable:
  ICU 2.0

UnicodeString& icu::DecimalFormat::getNegativeSuffix | ( | UnicodeString & | result | ) | const

Get the negative suffix.

Parameters

  result | Output param which will receive the negative suffix.

Returns
  A reference to 'result'. Examples: -123%, ($123) (with positive suffixes)

Stable:
  ICU 2.0

virtual UnicodeString icu::DecimalFormat::getPadCharacterString | ( |  | ) | const
| virtual

Get the pad character used to pad to the format width.

The default is ' '.

Returns
  a string containing the pad character. This will always have a length of one 32-bit code point.

See also
  setFormatWidth
  getFormatWidth
  setPadCharacter
  getPadPosition
  setPadPosition

Stable:
  ICU 2.0

virtual EPadPosition icu::DecimalFormat::getPadPosition | ( | void |  | ) | const
| virtual

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 kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, or kPadAfterSuffix.

See also
  setFormatWidth
  getFormatWidth
  setPadCharacter
  getPadCharacterString
  setPadPosition
  EPadPosition

Stable:
  ICU 2.0

UnicodeString& icu::DecimalFormat::getPositivePrefix | ( | UnicodeString & | result | ) | const

Get the positive prefix.

Parameters

  result | Output param which will receive the positive prefix.

Returns
  A reference to 'result'. Examples: +123, $123, sFr123

Stable:
  ICU 2.0

UnicodeString& icu::DecimalFormat::getPositiveSuffix | ( | UnicodeString & | result | ) | const

Get the positive suffix.

Parameters

  result | Output param which will receive the positive suffix.

Returns
  A reference to 'result'. Example: 123%

Stable:
  ICU 2.0

virtual double icu::DecimalFormat::getRoundingIncrement | ( | void |  | ) | const
| virtual

Get the rounding increment.

Returns
  A positive rounding increment, or 0.0 if a custom rounding increment is not in effect.

See also
  setRoundingIncrement
  getRoundingMode
  setRoundingMode

Stable:
  ICU 2.0

virtual ERoundingMode icu::DecimalFormat::getRoundingMode | ( | void |  | ) | const
| virtual

Get the rounding mode.

Returns
  A rounding mode

See also
  setRoundingIncrement
  getRoundingIncrement
  setRoundingMode

Stable:
  ICU 2.0

Reimplemented from icu::NumberFormat.

int32_t icu::DecimalFormat::getSecondaryGroupingSize | ( | void |  | ) | const

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

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

See also
  setSecondaryGroupingSize
  NumberFormat::isGroupingUsed
  DecimalFormatSymbols::getGroupingSeparator

Stable:
  ICU 2.4

static UClassID icu::DecimalFormat::getStaticClassID | ( | void |  | ) |
| static

Return the class ID for this class.

This is useful only for comparing to a return value from getDynamicClassID(). For example:

    .      Base* polymorphic_pointer = createPolymorphicObject();
    .      if (polymorphic_pointer->getDynamicClassID() ==
    .          Derived::getStaticClassID()) ...

Returns
  The class ID for all objects of this class.

Stable:
  ICU 2.0

VisibleDigitsWithExponent& icu::DecimalFormat::initVisibleDigitsWithExponent | ( | double | number,
|  | VisibleDigitsWithExponent & | digits,
|  | UErrorCode & | status
| ) |  | const

Get a VisibleDigitsWithExponent corresponding to a double as it would be formatted by this DecimalFormat.

Internal, not intended for public use.

Internal:
  Do not use. This API is for internal use only.

VisibleDigitsWithExponent& icu::DecimalFormat::initVisibleDigitsWithExponent | ( | const Formattable & | number,
|  | VisibleDigitsWithExponent & | digits,
|  | UErrorCode & | status
| ) |  | const

Get a VisibleDigitsWithExponent corresponding to a formattable as it would be formatted by this DecimalFormat.

Internal, not intended for public use.

Internal:
  Do not use. This API is for internal use only.

VisibleDigitsWithExponent& icu::DecimalFormat::initVisibleDigitsWithExponent | ( | DigitList & | number,
|  | VisibleDigitsWithExponent & | digits,
|  | UErrorCode & | status
| ) |  | const

Get a VisibleDigitsWithExponent corresponding to a DigitList as it would be formatted by this DecimalFormat.

Note: the DigitList may be modified. Internal, not intended for public use.

Internal:
  Do not use. This API is for internal use only.

UBool icu::DecimalFormat::isDecimalPatternMatchRequired | ( | void |  | ) | const

Allows you to get the parse behavior of the pattern decimal mark.

Returns
  TRUE if input must contain a match to decimal mark in pattern

Stable:
  ICU 54

UBool icu::DecimalFormat::isDecimalSeparatorAlwaysShown | ( | void |  | ) | const

Allows you to get the behavior of the decimal separator with integers.

(The decimal separator will always appear with decimals.)

Returns
  TRUE if the decimal separator always appear with decimals. Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345

Stable:
  ICU 2.0

virtual UBool icu::DecimalFormat::isExponentSignAlwaysShown | ( | void |  | ) | const
| virtual

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
  isScientificNotation
  setMinimumExponentDigits
  getMinimumExponentDigits
  setExponentSignAlwaysShown

Stable:
  ICU 2.0

virtual UBool icu::DecimalFormat::isScientificNotation | ( | void |  | ) | const
| virtual

Return whether or not scientific notation is used.

Returns
  TRUE if this object formats and parses scientific notation

See also
  setScientificNotation
  getMinimumExponentDigits
  setMinimumExponentDigits
  isExponentSignAlwaysShown
  setExponentSignAlwaysShown

Stable:
  ICU 2.0

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

Assignment operator.

Parameters

  rhs | the DecimalFormat object to be copied.

Stable:
  ICU 2.0

virtual UBool icu::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 icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual void icu::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 icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual CurrencyAmount* icu::DecimalFormat::parseCurrency | ( | const UnicodeString & | text,
|  | ParsePosition & | pos
| ) |  | const
| virtual

Parses text from the given string as a currency amount.

Unlike the parse() method, this method will attempt to parse a generic currency name, searching for a match of this object's locale's currency display names, or for a 3-letter ISO currency code. This method will fail if this format is not a currency format, that is, if it does not contain the currency pattern symbol (U+00A4) in its prefix or suffix.

Parameters

  text | the string to parse
  pos | input-output position; on input, the position within text to match; must have 0 <= pos.getIndex() < text.length(); on output, the position after the last matched character. If the parse fails, the position in unchanged upon output.

Returns
  if parse succeeds, a pointer to a newly-created CurrencyAmount object (owned by the caller) containing information about the parsed currency; if parse fails, this is NULL.

Stable:
  ICU 49

Reimplemented from icu::NumberFormat.

Reimplemented in icu::CompactDecimalFormat.

virtual DecimalFormat& icu::DecimalFormat::setAttribute | ( | UNumberFormatAttribute | attr,
|  | int32_t | newvalue,
|  | UErrorCode & | status
| ) |  |
| virtual

Set an integer attribute on this DecimalFormat.

May return U_UNSUPPORTED_ERROR if this instance does not support the specified attribute.

Parameters

  attr | the attribute to set
  newvalue | new value
  status | the error type

Returns
  *this - for chaining (example: format.setAttribute(...).setAttribute(...) )

Stable:
  ICU 51

virtual void icu::DecimalFormat::setContext | ( | UDisplayContext | value,
|  | UErrorCode & | status
| ) |  |
| virtual

Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE.

Parameters

  value | The UDisplayContext value to set.
  status | Input/output status. If at entry this indicates a failure status, the function will do nothing; otherwise this will be updated with any new status from the function.

Stable:
  ICU 53

Reimplemented from icu::NumberFormat.

virtual void icu::DecimalFormat::setCurrency | ( | const char16_t * | theCurrency,
|  | UErrorCode & | ec
| ) |  |
| virtual

Sets the currency 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 is used if and when this object becomes a currency format through the application of a new pattern.

Parameters

  theCurrency | a 3-letter ISO code indicating new currency to use. It need not be null-terminated. May be the empty string or NULL to indicate no currency.
  ec | input-output error code

Stable:
  ICU 3.0

Reimplemented from icu::NumberFormat.

virtual void icu::DecimalFormat::setCurrency | ( | const char16_t * | theCurrency | ) |
| virtual

Sets the currency used to display currency amounts.

See setCurrency(const char16_t*, UErrorCode&).

Deprecated:
  ICU 3.0. Use setCurrency(const char16_t*, UErrorCode&).

virtual void icu::DecimalFormat::setCurrencyPluralInfo | ( | const CurrencyPluralInfo & | info | ) |
| virtual

Sets the currency plural format information, which is generally not changed by the programmer or user.

Parameters

  info | Currency Plural Info.

Stable:
  ICU 4.2

void icu::DecimalFormat::setCurrencyUsage | ( | UCurrencyUsage | newUsage,
|  | UErrorCode * | ec
| ) |  |

Sets the `Currency Context` object used to display currency.

This takes effect immediately, if this format is a currency format.

Parameters

  currencyContext | new currency context object to use.

Stable:
  ICU 54

virtual void icu::DecimalFormat::setDecimalFormatSymbols | ( | const DecimalFormatSymbols & | symbols | ) |
| virtual

Sets the decimal format symbols, which is generally not changed by the programmer or user.

Parameters

  symbols | DecimalFormatSymbols.

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setDecimalPatternMatchRequired | ( | UBool | newValue | ) |
| virtual

Allows you to set the behavior of the pattern decimal mark.

if TRUE, the input must have a decimal mark if one was specified in the pattern. When FALSE the decimal mark may be omitted from the input.

Parameters

  newValue | set TRUE if input must contain a match to decimal mark in pattern

Stable:
  ICU 54

virtual void icu::DecimalFormat::setDecimalSeparatorAlwaysShown | ( | UBool | newValue | ) |
| virtual

Allows you to set the behavior of the decimal separator with integers.

(The decimal separator will always appear with decimals.)

Parameters

  newValue | set TRUE if the decimal separator will always appear with decimals. Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setExponentSignAlwaysShown | ( | UBool | expSignAlways | ) |
| virtual

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
  isScientificNotation
  setMinimumExponentDigits
  getMinimumExponentDigits
  isExponentSignAlwaysShown

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setFormatWidth | ( | int32_t | width | ) |
| virtual

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. A negative width is equivalent to 0.

See also
  getFormatWidth
  getPadCharacterString
  setPadCharacter
  getPadPosition
  setPadPosition

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setGroupingSize | ( | int32_t | newValue | ) |
| virtual

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.

Parameters

  newValue | the new value of the grouping size.

See also
  getGroupingSize
  NumberFormat::setGroupingUsed
  DecimalFormatSymbols::setGroupingSeparator

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setGroupingUsed | ( | UBool | newValue | ) |
| virtual

Set whether or not grouping will be used in this format.

Parameters

  newValue | True, grouping will be used in this format.

See also
  getGroupingUsed

Stable:
  ICU 53

Reimplemented from icu::NumberFormat.

virtual void icu::DecimalFormat::setMaximumFractionDigits | ( | int32_t | newValue | ) |
| virtual

Sets the maximum number of digits allowed in the fraction portion of a number.

This override limits the fraction digit count to 340.

Parameters

  newValue | the new value of the maximum number of digits allowed in the fraction portion of a number.

See also
  NumberFormat::setMaximumFractionDigits

Stable:
  ICU 2.0

Reimplemented from icu::NumberFormat.

virtual void icu::DecimalFormat::setMaximumIntegerDigits | ( | int32_t | newValue | ) |
| virtual

Sets the maximum number of digits allowed in the integer portion of a number.

This override limits the integer digit count to 309.

Parameters

  newValue | the new value of the maximum number of digits allowed in the integer portion of a number.

See also
  NumberFormat::setMaximumIntegerDigits

Stable:
  ICU 2.0

Reimplemented from icu::NumberFormat.

void icu::DecimalFormat::setMaximumSignificantDigits | ( | int32_t | 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 function also enables the use of significant digits by this formatter - areSignificantDigitsUsed() will return TRUE.

See also
  areSignificantDigitsUsed

Parameters

  max | the most significant digits to be shown

Stable:
  ICU 3.0

virtual void icu::DecimalFormat::setMinimumExponentDigits | ( | int8_t | minExpDig | ) |
| virtual

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. Values less than 1 will be treated as 1.

See also
  setScientificNotation
  isScientificNotation
  getMinimumExponentDigits
  isExponentSignAlwaysShown
  setExponentSignAlwaysShown

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setMinimumFractionDigits | ( | int32_t | newValue | ) |
| virtual

Sets the minimum number of digits allowed in the fraction portion of a number.

This override limits the fraction digit count to 340.

Parameters

  newValue | the new value of the minimum number of digits allowed in the fraction portion of a number.

See also
  NumberFormat::setMinimumFractionDigits

Stable:
  ICU 2.0

Reimplemented from icu::NumberFormat.

virtual void icu::DecimalFormat::setMinimumGroupingDigits | ( | int32_t | newValue | ) |
| virtual

Sets the minimum grouping digits.

Setting to a value less than or equal to 1 turns off minimum grouping digits.

Parameters

  newValue | the new value of minimum grouping digits.

See also
  getMinimumGroupingDigits

Internal:
  Do not use. This API is for internal use only. technology preview

virtual void icu::DecimalFormat::setMinimumIntegerDigits | ( | int32_t | newValue | ) |
| virtual

Sets the minimum number of digits allowed in the integer portion of a number.

This override limits the integer digit count to 309.

Parameters

  newValue | the new value of the minimum number of digits allowed in the integer portion of a number.

See also
  NumberFormat::setMinimumIntegerDigits

Stable:
  ICU 2.0

Reimplemented from icu::NumberFormat.

void icu::DecimalFormat::setMinimumSignificantDigits | ( | int32_t | 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 function also enables the use of significant digits by this formatter - areSignificantDigitsUsed() will return TRUE.

See also
  areSignificantDigitsUsed

Parameters

  min | the fewest significant digits to be shown

Stable:
  ICU 3.0

virtual void icu::DecimalFormat::setMultiplier | ( | int32_t | newValue | ) |
| virtual

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 "\\u2031" and the multiplier to be 1000.

Parameters

  newValue | the new value of the multiplier for use in percent, permill, etc. Examples: with 100, 1.23 -> "123", and "123" -> 1.23

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setNegativePrefix | ( | const UnicodeString & | newValue | ) |
| virtual

Set the negative prefix.

Parameters

  newValue | the new value of the the negative prefix to be set. Examples: -123, ($123) (with negative suffix), sFr-123

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setNegativeSuffix | ( | const UnicodeString & | newValue | ) |
| virtual

Set the negative suffix.

Parameters

  newValue | the new value of the negative suffix to be set. Examples: 123%

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setPadCharacter | ( | const UnicodeString & | padChar | ) |
| virtual

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 | a string containing the pad charcter. If the string has length 0, then the pad characer is set to ' '. Otherwise padChar.char32At(0) will be used as the pad character.

See also
  setFormatWidth
  getFormatWidth
  getPadCharacterString
  getPadPosition
  setPadPosition

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setPadPosition | ( | EPadPosition | padPos | ) |
| virtual

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 kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, or kPadAfterSuffix.

See also
  setFormatWidth
  getFormatWidth
  setPadCharacter
  getPadCharacterString
  getPadPosition
  EPadPosition

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setParseIntegerOnly | ( | UBool | value | ) |
| virtual

Sets whether or not numbers should be parsed as integers only.

Parameters

  value | set True, this format will parse numbers as integers only.

See also
  isParseIntegerOnly

Stable:
  ICU 53

Reimplemented from icu::NumberFormat.

virtual void icu::DecimalFormat::setPositivePrefix | ( | const UnicodeString & | newValue | ) |
| virtual

Set the positive prefix.

Parameters

  newValue | the new value of the the positive prefix to be set. Examples: +123, $123, sFr123

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setPositiveSuffix | ( | const UnicodeString & | newValue | ) |
| virtual

Set the positive suffix.

Parameters

  newValue | the new value of the positive suffix to be set. Example: 123%

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setRoundingIncrement | ( | double | newValue | ) |
| virtual

Set the rounding increment.

In the absence of a rounding increment, numbers will be rounded to the number of digits displayed.

Parameters

  newValue | A positive rounding increment, or 0.0 to use the default rounding increment. Negative increments are equivalent to 0.0.

See also
  getRoundingIncrement
  getRoundingMode
  setRoundingMode

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setRoundingMode | ( | ERoundingMode | roundingMode | ) |
| virtual

Set the rounding mode.

Parameters

  roundingMode | A rounding mode

See also
  setRoundingIncrement
  getRoundingIncrement
  getRoundingMode

Stable:
  ICU 2.0

Reimplemented from icu::NumberFormat.

virtual void icu::DecimalFormat::setScientificNotation | ( | UBool | useScientific | ) |
| virtual

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
  isScientificNotation
  getMinimumExponentDigits
  setMinimumExponentDigits
  isExponentSignAlwaysShown
  setExponentSignAlwaysShown

Stable:
  ICU 2.0

virtual void icu::DecimalFormat::setSecondaryGroupingSize | ( | int32_t | newValue | ) |
| virtual

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.

Parameters

  newValue | the new value of the secondary grouping size.

See also
  getSecondaryGroupingSize
  NumberFormat::setGroupingUsed
  DecimalFormatSymbols::setGroupingSeparator

Stable:
  ICU 2.4

void icu::DecimalFormat::setSignificantDigitsUsed | ( | UBool | 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

Stable:
  ICU 3.0

virtual UnicodeString& icu::DecimalFormat::toLocalizedPattern | ( | UnicodeString & | result | ) | const
| virtual

Synthesizes a localized pattern string that represents the current state of this Format object.

Parameters

  result | Output param which will receive the localized pattern. Previous contents are deleted.

Returns
  A reference to 'result'.

See also
  applyPattern

Stable:
  ICU 2.0

virtual UnicodeString& icu::DecimalFormat::toPattern | ( | UnicodeString & | result | ) | const
| virtual

Synthesizes a pattern string that represents the current state of this Format object.

Parameters

  result | Output param which will receive the pattern. Previous contents are deleted.

Returns
  A reference to 'result'.

See also
  applyPattern

Stable:
  ICU 2.0

## Field Documentation

const char icu::DecimalFormat::fgNumberPatterns[]
| static

The resource tags we use to retrieve decimal format data from locale resource bundles.

Deprecated:
  ICU 3.4. This string has no public purpose. Please don't use it.

Definition at line 1972 of file decimfmt.h.

const int32_t icu::DecimalFormat::kDoubleFractionDigits
| static protected

number of fraction digits

Stable:
  ICU 2.4

Definition at line 2259 of file decimfmt.h.

const int32_t icu::DecimalFormat::kDoubleIntegerDigits
| static protected

number of integer digits

Stable:
  ICU 2.4

Definition at line 2255 of file decimfmt.h.

const int32_t icu::DecimalFormat::kMaxScientificIntegerDigits
| static protected

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.

We don't bother to track and see if someone is using exponential notation with more than this number, it wouldn't make sense anyway, and this is just to make sure that someone turning on scientific mode with default settings doesn't end up with lots of zeroes.

Stable:
  ICU 2.8

Definition at line 2271 of file decimfmt.h.

The documentation for this class was generated from the following file:

- decimfmt.h