ICU 64.2  64.2
Public Types | Public Member Functions | Static Public Member Functions | Friends
icu::DecimalFormat Class Reference

IMPORTANT: New users are strongly encouraged to see if numberformatter.h fits their use case. More...

#include <decimfmt.h>

Inheritance diagram for icu::DecimalFormat:
icu::NumberFormat icu::Format icu::UObject icu::UMemory icu::CompactDecimalFormat

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, kMeasureUnitField = UNUM_MEASURE_UNIT_FIELD,
  kCompactField = UNUM_COMPACT_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 DecimalFormatsetAttribute (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...
 
void setGroupingUsed (UBool newValue) U_OVERRIDE
 Set whether or not grouping will be used in this format. More...
 
void setParseIntegerOnly (UBool value) U_OVERRIDE
 Sets whether or not numbers should be parsed as integers only. More...
 
void setLenient (UBool enable) U_OVERRIDE
 Sets whether lenient parsing should be enabled (it is off by default). 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...
 
DecimalFormatoperator= (const DecimalFormat &rhs)
 Assignment operator. More...
 
 ~DecimalFormat () U_OVERRIDE
 Destructor. More...
 
Formatclone (void) const U_OVERRIDE
 Clone this Format object polymorphically. More...
 
UBool operator== (const Format &other) const U_OVERRIDE
 Return true if the given Format objects are semantically equal. More...
 
UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos) const U_OVERRIDE
 Format a double or long number using base-10 representation. More...
 
UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const U_OVERRIDE
 Format a double or long number using base-10 representation. More...
 
UnicodeStringformat (double number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const U_OVERRIDE
 Format a double or long number using base-10 representation. More...
 
UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const U_OVERRIDE
 Format a long number using base-10 representation. More...
 
UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const U_OVERRIDE
 Format a long number using base-10 representation. More...
 
UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const U_OVERRIDE
 Format a long number using base-10 representation. More...
 
UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const U_OVERRIDE
 Format an int64 number using base-10 representation. More...
 
UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const U_OVERRIDE
 Format an int64 number using base-10 representation. More...
 
UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const U_OVERRIDE
 Format an int64 number using base-10 representation. More...
 
UnicodeStringformat (StringPiece number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const U_OVERRIDE
 Format a decimal number. More...
 
UnicodeStringformat (const number::impl::DecimalQuantity &number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const U_OVERRIDE
 Format a decimal number. More...
 
UnicodeStringformat (const number::impl::DecimalQuantity &number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const U_OVERRIDE
 Format a decimal number. More...
 
void parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const U_OVERRIDE
 Parse the given string using this object's choices. More...
 
CurrencyAmountparseCurrency (const UnicodeString &text, ParsePosition &pos) const U_OVERRIDE
 Parses text from the given string as a currency amount. More...
 
virtual const DecimalFormatSymbolsgetDecimalFormatSymbols (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 CurrencyPluralInfogetCurrencyPluralInfo (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...
 
UnicodeStringgetPositivePrefix (UnicodeString &result) const
 Get the positive prefix. More...
 
virtual void setPositivePrefix (const UnicodeString &newValue)
 Set the positive prefix. More...
 
UnicodeStringgetNegativePrefix (UnicodeString &result) const
 Get the negative prefix. More...
 
virtual void setNegativePrefix (const UnicodeString &newValue)
 Set the negative prefix. More...
 
UnicodeStringgetPositiveSuffix (UnicodeString &result) const
 Get the positive suffix. More...
 
virtual void setPositiveSuffix (const UnicodeString &newValue)
 Set the positive suffix. More...
 
UnicodeStringgetNegativeSuffix (UnicodeString &result) const
 Get the negative suffix. More...
 
virtual void setNegativeSuffix (const UnicodeString &newValue)
 Set the negative suffix. More...
 
UBool isSignAlwaysShown () const
 Whether to show the plus sign on positive (non-negative) numbers; for example, "+12". More...
 
void setSignAlwaysShown (UBool value)
 Set whether to show the plus sign on positive (non-negative) numbers; for example, "+12". 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...
 
int32_t getMultiplierScale (void) const
 Gets the power of ten by which number should be multiplied before formatting, which can be combined with setMultiplier() to multiply by any arbitrary decimal value. More...
 
void setMultiplierScale (int32_t newValue)
 Sets a power of ten by which number should be multiplied before formatting, which can be combined with setMultiplier() to multiply by any arbitrary decimal value. 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 U_OVERRIDE
 Get the rounding mode. More...
 
virtual void setRoundingMode (ERoundingMode roundingMode) U_OVERRIDE
 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...
 
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 parse behavior of the pattern decimal mark. More...
 
UBool isParseNoExponent () const
 Returns whether to ignore exponents when parsing. More...
 
void setParseNoExponent (UBool value)
 Specifies whether to stop parsing when an exponent separator is encountered. More...
 
UBool isParseCaseSensitive () const
 Returns whether parsing is sensitive to case (lowercase/uppercase). More...
 
void setParseCaseSensitive (UBool value)
 Whether to pay attention to case when parsing; default is to ignore case (perform case-folding). More...
 
UBool isFormatFailIfMoreThanMaxDigits () const
 Returns whether truncation of high-order integer digits should result in an error. More...
 
void setFormatFailIfMoreThanMaxDigits (UBool value)
 Sets whether truncation of high-order integer digits should result in an error. More...
 
virtual UnicodeStringtoPattern (UnicodeString &result) const
 Synthesizes a pattern string that represents the current state of this Format object. More...
 
virtual UnicodeStringtoLocalizedPattern (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...
 
void setMaximumIntegerDigits (int32_t newValue) U_OVERRIDE
 Sets the maximum number of digits allowed in the integer portion of a number. More...
 
void setMinimumIntegerDigits (int32_t newValue) U_OVERRIDE
 Sets the minimum number of digits allowed in the integer portion of a number. More...
 
void setMaximumFractionDigits (int32_t newValue) U_OVERRIDE
 Sets the maximum number of digits allowed in the fraction portion of a number. More...
 
void setMinimumFractionDigits (int32_t newValue) U_OVERRIDE
 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...
 
void setCurrency (const char16_t *theCurrency, UErrorCode &ec) U_OVERRIDE
 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 Usage object used to display currency. More...
 
UCurrencyUsage getCurrencyUsage () const
 Returns the Currency Usage object used to display currency. More...
 
void formatToDecimalQuantity (double number, number::impl::DecimalQuantity &output, UErrorCode &status) const
 Format a number and save it into the given DecimalQuantity. More...
 
void formatToDecimalQuantity (const Formattable &number, number::impl::DecimalQuantity &output, UErrorCode &status) const
 Get a DecimalQuantity corresponding to a formattable as it would be formatted by this DecimalFormat. More...
 
const number::LocalizedNumberFormattertoNumberFormatter (UErrorCode &status) const
 Converts this DecimalFormat to a (Localized)NumberFormatter. More...
 
const number::LocalizedNumberFormattertoNumberFormatter () const
 Deprecated: Like toNumberFormatter(UErrorCode&) const, but does not take an error code. More...
 
UClassID getDynamicClassID (void) const U_OVERRIDE
 Returns a unique class ID POLYMORPHICALLY. More...
 
- Public Member Functions inherited from icu::NumberFormat
virtual ~NumberFormat ()
 Destructor. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format an object to produce a string. More...
 
virtual UnicodeStringformat (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...
 
UnicodeStringformat (double number, UnicodeString &appendTo) const
 Format a double number. More...
 
UnicodeStringformat (int32_t number, UnicodeString &appendTo) const
 Format a long number. More...
 
UnicodeStringformat (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 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 void setContext (UDisplayContext value, UErrorCode &status)
 Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE. 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...
 
UnicodeStringformat (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 NumberFormatcreateInstance (UErrorCode &)
 Create a default style NumberFormat for the current default locale. More...
 
static NumberFormatcreateInstance (const Locale &inLocale, UErrorCode &)
 Create a default style NumberFormat for the specified locale. More...
 
static NumberFormatcreateInstance (const Locale &desiredLocale, UNumberFormatStyle style, UErrorCode &errorCode)
 Create a specific style NumberFormat for the specified locale. More...
 
static NumberFormatinternalCreateInstance (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 NumberFormatcreateCurrencyInstance (UErrorCode &)
 Returns a currency format for the current default locale. More...
 
static NumberFormatcreateCurrencyInstance (const Locale &inLocale, UErrorCode &)
 Returns a currency format for the specified locale. More...
 
static NumberFormatcreatePercentInstance (UErrorCode &)
 Returns a percentage format for the current default locale. More...
 
static NumberFormatcreatePercentInstance (const Locale &inLocale, UErrorCode &)
 Returns a percentage format for the specified locale. More...
 
static NumberFormatcreateScientificInstance (UErrorCode &)
 Returns a scientific format for the current default locale. More...
 
static NumberFormatcreateScientificInstance (const Locale &inLocale, UErrorCode &)
 Returns a scientific format for the specified locale. More...
 
static const LocalegetAvailableLocales (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 StringEnumerationgetAvailableLocales (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...
 

Friends

class CompactDecimalFormat
 
class MeasureFormat
 

Additional Inherited Members

- Protected Member Functions inherited from icu::NumberFormat
 NumberFormat ()
 Default constructor for subclass use only. More...
 
 NumberFormat (const NumberFormat &)
 Copy constructor. More...
 
NumberFormatoperator= (const NumberFormat &)
 Assignment operator. 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::Format
void setLocaleIDs (const char *valid, const char *actual)
 
 Format ()
 Default constructor for subclass use only. More...
 
 Format (const Format &)
 
Formatoperator= (const Format &)
 
- Static Protected Member Functions inherited from icu::NumberFormat
static NumberFormatmakeInstance (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...
 
- Static Protected Attributes inherited from icu::NumberFormat
static const int32_t gDefaultMaxIntegerDigits
 
static const int32_t gDefaultMinIntegerDigits
 

Detailed Description

IMPORTANT: New users are strongly encouraged to see if numberformatter.h fits their use case.

Although not deprecated, this header is provided for backwards compatibility only.

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;
// 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</strong>
Locale* locale = new Locale("en", "US");
double myNumber = 1234.56;
UnicodeString str;
Formattable fmtable;
for (int j=NumberFormat::kNumberStyle;
j<=NumberFormat::kPluralCurrencyStyle;
++j) {
NumberFormat* form = NumberFormat::createInstance(locale, j, success);
str.remove();
cout << "format result " << form->format(myNumber, str) << endl;
format->parse(form->format(myNumber, str), fmtable, success);
delete form;
}

Patterns

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

Special Pattern Characters

Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit. Often the replacement character is the same as the pattern character; in the U.S. locale, the ',' grouping character is replaced by ','. However, the replacement is still happening, and if the symbols are modified, the grouping character changes. Some special characters affect the behavior of the formatter by their presence; for example, if the percent character is seen, then the value is multiplied by 100 before being displayed.

To insert a special character in a pattern as a literal, that is, without any special meaning, the character must be quoted. There are some exceptions to this which are noted below.

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

Symbol Location Localized? Meaning
0 Number Yes Digit
1-9 Number Yes '1' through '9' indicate rounding.
@ Number No Significant digit
# Number Yes Digit, zero shows as absent
. Number Yes Decimal separator or monetary decimal separator
- Number Yes Minus sign
, Number Yes Grouping separator
E Number Yes Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
+ Exponent Yes Prefix positive exponents with localized plus sign. Need not be quoted in prefix or suffix.
; Subpattern boundary Yes Separates positive and negative subpatterns
% Prefix or suffix Yes Multiply by 100 and show as percentage
\u2030 Prefix or suffix Yes Multiply by 1000 and show as per mille
¤ (\u00A4) Prefix or suffix No Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If 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 positive 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:

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.

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

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

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

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 absence of an explicit rounding increment numbers are rounded to their formatted width.

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

Member Enumeration Documentation

◆ EPadPosition

Pad position.

Stable:
ICU 2.4

Definition at line 671 of file decimfmt.h.

Constructor & Destructor Documentation

◆ DecimalFormat() [1/7]

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.

NOTE: New users are strongly encouraged to use icu::number::NumberFormatter instead of DecimalFormat.

Parameters
statusOutput param set to success/failure code. If the pattern is invalid this will be set to a failure code.
Stable:
ICU 2.0

◆ DecimalFormat() [2/7]

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.

NOTE: New users are strongly encouraged to use icu::number::NumberFormatter instead of DecimalFormat.

Parameters
patternA non-localized pattern string.
statusOutput param set to success/failure code. If the pattern is invalid this will be set to a failure code.
Stable:
ICU 2.0

◆ DecimalFormat() [3/7]

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.

NOTE: New users are strongly encouraged to use icu::number::NumberFormatter instead of DecimalFormat.

Parameters
patterna non-localized pattern string
symbolsToAdoptthe set of symbols to be used. The caller should not delete this object after making this call.
statusOutput param set to success/failure code. If the pattern is invalid this will be set to a failure code.
Stable:
ICU 2.0

◆ DecimalFormat() [4/7]

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
patterna non-localized pattern string
symbolsToAdoptthe set of symbols to be used. The caller should not delete this object after making this call.
stylestyle of decimal format
statusOutput 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.

◆ DecimalFormat() [5/7]

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.

NOTE: New users are strongly encouraged to use icu::number::NumberFormatter instead of DecimalFormat.

Parameters
patterna non-localized pattern string
symbolsToAdoptthe set of symbols to be used. The caller should not delete this object after making this call.
parseErrorOutput param to receive errors occurred during parsing
statusOutput param set to success/failure code. If the pattern is invalid this will be set to a failure code.
Stable:
ICU 2.0

◆ DecimalFormat() [6/7]

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.

NOTE: New users are strongly encouraged to use icu::number::NumberFormatter instead of DecimalFormat.

Parameters
patterna non-localized pattern string
symbolsthe set of symbols to be used
statusOutput param set to success/failure code. If the pattern is invalid this will be set to a failure code.
Stable:
ICU 2.0

◆ DecimalFormat() [7/7]

icu::DecimalFormat::DecimalFormat ( const DecimalFormat source)

Copy constructor.

Parameters
sourcethe DecimalFormat object to be copied from.
Stable:
ICU 2.0

◆ ~DecimalFormat()

icu::DecimalFormat::~DecimalFormat ( )

Destructor.

Stable:
ICU 2.0

Member Function Documentation

◆ adoptCurrencyPluralInfo()

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
toAdoptCurrencyPluralInfo to be adopted.
Stable:
ICU 4.2

◆ adoptDecimalFormatSymbols()

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

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

Parameters
symbolsToAdoptDecimalFormatSymbols to be adopted.
Stable:
ICU 2.0

◆ applyLocalizedPattern() [1/2]

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
patternThe localized pattern to be applied.
parseErrorStruct to recieve information on position of error if an error is encountered
statusOutput 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

◆ applyLocalizedPattern() [2/2]

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

Apply the given pattern to this Format object.

Parameters
patternThe localized pattern to be applied.
statusOutput 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

◆ applyPattern() [1/2]

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
patternThe pattern to be applied.
parseErrorStruct to recieve information on position of error if an error is encountered
statusOutput 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

◆ applyPattern() [2/2]

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

Sets the pattern.

Parameters
patternThe pattern to be applied.
statusOutput 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

◆ areSignificantDigitsUsed()

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

◆ clone()

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.

◆ format() [1/12]

UnicodeString& icu::DecimalFormat::format ( double  number,
UnicodeString appendTo,
FieldPosition pos 
) const
virtual

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

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn 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.

◆ format() [2/12]

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
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn 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.

◆ format() [3/12]

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
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [4/12]

UnicodeString& icu::DecimalFormat::format ( int32_t  number,
UnicodeString appendTo,
FieldPosition pos 
) const
virtual

Format a long number using base-10 representation.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn 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.

◆ format() [5/12]

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

Format a long number using base-10 representation.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusOutput 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.

◆ format() [6/12]

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

Format a long number using base-10 representation.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [7/12]

UnicodeString& icu::DecimalFormat::format ( int64_t  number,
UnicodeString appendTo,
FieldPosition pos 
) const
virtual

Format an int64 number using base-10 representation.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn 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.

◆ format() [8/12]

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

Format an int64 number using base-10 representation.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusOutput 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.

◆ format() [9/12]

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

Format an int64 number using base-10 representation.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [10/12]

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
numberThe unformatted number, as a string.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [11/12]

UnicodeString& icu::DecimalFormat::format ( const number::impl::DecimalQuantity &  number,
UnicodeString appendTo,
FieldPositionIterator posIter,
UErrorCode status 
) const
virtual

Format a decimal number.

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

Parameters
numberThe number, a DecimalQuantity format Decimal Floating Point.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call.
statusOutput 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.

◆ format() [12/12]

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

Format a decimal number.

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

Parameters
numberThe number, a DecimalQuantity format Decimal Floating Point.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusOutput 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.

◆ formatToDecimalQuantity() [1/2]

void icu::DecimalFormat::formatToDecimalQuantity ( double  number,
number::impl::DecimalQuantity &  output,
UErrorCode status 
) const

Format a number and save it into the given DecimalQuantity.

Internal, not intended for public use.

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

◆ formatToDecimalQuantity() [2/2]

void icu::DecimalFormat::formatToDecimalQuantity ( const Formattable number,
number::impl::DecimalQuantity &  output,
UErrorCode status 
) const

Get a DecimalQuantity 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.

◆ getAttribute()

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
attrthe attribute to set
statusthe error type
Returns
the attribute value. Undefined if there is an error.
Stable:
ICU 51

◆ getCurrencyPluralInfo()

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

◆ getCurrencyUsage()

UCurrencyUsage icu::DecimalFormat::getCurrencyUsage ( ) const

Returns the Currency Usage object used to display currency.

Stable:
ICU 54

◆ getDecimalFormatSymbols()

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

◆ getDynamicClassID()

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.

◆ getFormatWidth()

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

◆ getGroupingSize()

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

◆ getMaximumSignificantDigits()

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

◆ getMinimumExponentDigits()

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

◆ getMinimumGroupingDigits()

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"

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

NOTE: The CLDR data is used in NumberFormatter but not in DecimalFormat. This is for backwards compatibility reasons.

For more control over grouping strategies, use NumberFormatter.

See also
setMinimumGroupingDigits
getGroupingSize
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ getMinimumSignificantDigits()

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

◆ getMultiplier()

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.

The number may also be multiplied by a power of ten; see getMultiplierScale().

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

◆ getMultiplierScale()

int32_t icu::DecimalFormat::getMultiplierScale ( void  ) const

Gets the power of ten by which number should be multiplied before formatting, which can be combined with setMultiplier() to multiply by any arbitrary decimal value.

A multiplier scale of 2 corresponds to multiplication by 100, and a multiplier scale of -2 corresponds to multiplication by 0.01.

This method is analogous to UNUM_SCALE in getAttribute.

Returns
the current value of the power-of-ten multiplier.
Draft:
This API may be changed in the future versions and was introduced in ICU 62

◆ getNegativePrefix()

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

Get the negative prefix.

Parameters
resultOutput param which will receive the negative prefix.
Returns
A reference to 'result'. Examples: -123, ($123) (with negative suffix), sFr-123
Stable:
ICU 2.0

◆ getNegativeSuffix()

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

Get the negative suffix.

Parameters
resultOutput param which will receive the negative suffix.
Returns
A reference to 'result'. Examples: -123%, ($123) (with positive suffixes)
Stable:
ICU 2.0

◆ getPadCharacterString()

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

◆ getPadPosition()

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

◆ getPositivePrefix()

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

Get the positive prefix.

Parameters
resultOutput param which will receive the positive prefix.
Returns
A reference to 'result'. Examples: +123, $123, sFr123
Stable:
ICU 2.0

◆ getPositiveSuffix()

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

Get the positive suffix.

Parameters
resultOutput param which will receive the positive suffix.
Returns
A reference to 'result'. Example: 123%
Stable:
ICU 2.0

◆ getRoundingIncrement()

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

◆ getRoundingMode()

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.

◆ getSecondaryGroupingSize()

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

◆ getStaticClassID()

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

◆ isDecimalPatternMatchRequired()

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

◆ isDecimalSeparatorAlwaysShown()

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

◆ isExponentSignAlwaysShown()

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

◆ isFormatFailIfMoreThanMaxDigits()

UBool icu::DecimalFormat::isFormatFailIfMoreThanMaxDigits ( ) const

Returns whether truncation of high-order integer digits should result in an error.

By default, setMaximumIntegerDigits truncates high-order digits silently.

Returns
Whether an error code is set if high-order digits are truncated.
See also
setFormatFailIfMoreThanMaxDigits
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ isParseCaseSensitive()

UBool icu::DecimalFormat::isParseCaseSensitive ( ) const

Returns whether parsing is sensitive to case (lowercase/uppercase).

Returns
Whether parsing is case-sensitive.
See also
setParseCaseSensitive
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ isParseNoExponent()

UBool icu::DecimalFormat::isParseNoExponent ( ) const

Returns whether to ignore exponents when parsing.

Returns
Whether to ignore exponents when parsing.
See also
setParseNoExponent
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ isScientificNotation()

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

◆ isSignAlwaysShown()

UBool icu::DecimalFormat::isSignAlwaysShown ( ) const

Whether to show the plus sign on positive (non-negative) numbers; for example, "+12".

For more control over sign display, use NumberFormatter.

Returns
Whether the sign is shown on positive numbers and zero.
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ operator=()

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

Assignment operator.

Parameters
rhsthe DecimalFormat object to be copied.
Stable:
ICU 2.0

◆ operator==()

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
otherthe object to be compared with.
Returns
true if the given Format objects are semantically equal.
Stable:
ICU 2.0

Reimplemented from icu::NumberFormat.

◆ parse()

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 accommodate 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
textThe text to be parsed.
resultFormattable to be set to the parse result. If parse fails, return contents are undefined.
parsePositionThe 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.

◆ parseCurrency()

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
textthe string to parse
posinput-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.

◆ setAttribute()

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
attrthe attribute to set
newValuenew value
statusthe error type
Returns
*this - for chaining (example: format.setAttribute(...).setAttribute(...) )
Stable:
ICU 51

◆ setCurrency() [1/2]

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
theCurrencya 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.
ecinput-output error code
Stable:
ICU 3.0

Reimplemented from icu::NumberFormat.

◆ setCurrency() [2/2]

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

◆ setCurrencyPluralInfo()

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
infoCurrency Plural Info.
Stable:
ICU 4.2

◆ setCurrencyUsage()

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

Sets the Currency Usage object used to display currency.

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

Parameters
newUsagenew currency usage object to use.
ecinput-output error code
Stable:
ICU 54

◆ setDecimalFormatSymbols()

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
symbolsDecimalFormatSymbols.
Stable:
ICU 2.0

◆ setDecimalPatternMatchRequired()

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

Allows you to set the parse 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
newValueset TRUE if input must contain a match to decimal mark in pattern
Stable:
ICU 54

◆ setDecimalSeparatorAlwaysShown()

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
newValueset TRUE if the decimal separator will always appear with decimals. Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
Stable:
ICU 2.0

◆ setExponentSignAlwaysShown()

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
expSignAlwaysTRUE 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

◆ setFormatFailIfMoreThanMaxDigits()

void icu::DecimalFormat::setFormatFailIfMoreThanMaxDigits ( UBool  value)

Sets whether truncation of high-order integer digits should result in an error.

By default, setMaximumIntegerDigits truncates high-order digits silently.

Parameters
valueWhether to set an error code if high-order digits are truncated.
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ setFormatWidth()

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
widththe 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

◆ setGroupingSize()

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
newValuethe new value of the grouping size.
See also
getGroupingSize
NumberFormat::setGroupingUsed
DecimalFormatSymbols::setGroupingSeparator
Stable:
ICU 2.0

◆ setGroupingUsed()

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

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

Parameters
newValueTrue, grouping will be used in this format.
See also
getGroupingUsed
Stable:
ICU 53

Reimplemented from icu::NumberFormat.

◆ setLenient()

void icu::DecimalFormat::setLenient ( UBool  enable)
virtual

Sets whether lenient parsing should be enabled (it is off by default).

Parameters
enableTRUE if lenient parsing should be used, FALSE otherwise.
Stable:
ICU 4.8

Reimplemented from icu::NumberFormat.

◆ setMaximumFractionDigits()

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

◆ setMaximumIntegerDigits()

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

◆ setMaximumSignificantDigits()

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
maxthe most significant digits to be shown
Stable:
ICU 3.0

◆ setMinimumExponentDigits()

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
minExpDiga 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

◆ setMinimumFractionDigits()

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

◆ setMinimumGroupingDigits()

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

Sets the minimum grouping digits.

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

For more control over grouping strategies, use NumberFormatter.

Parameters
newValuethe new value of minimum grouping digits.
See also
getMinimumGroupingDigits
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ setMinimumIntegerDigits()

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

◆ setMinimumSignificantDigits()

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
minthe fewest significant digits to be shown
Stable:
ICU 3.0

◆ setMultiplier()

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.

This method only supports integer multipliers. To multiply by a non-integer, pair this method with setMultiplierScale().

Parameters
newValuethe 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

◆ setMultiplierScale()

void icu::DecimalFormat::setMultiplierScale ( int32_t  newValue)

Sets a power of ten by which number should be multiplied before formatting, which can be combined with setMultiplier() to multiply by any arbitrary decimal value.

A multiplier scale of 2 corresponds to multiplication by 100, and a multiplier scale of -2 corresponds to multiplication by 0.01.

For example, to multiply numbers by 0.5 before formatting, you can do:

df.setMultiplier(5);
df.setMultiplierScale(-1);

This method is analogous to UNUM_SCALE in setAttribute.

Parameters
newValuethe new value of the power-of-ten multiplier.
Draft:
This API may be changed in the future versions and was introduced in ICU 62

◆ setNegativePrefix()

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

Set the negative prefix.

Parameters
newValuethe new value of the the negative prefix to be set. Examples: -123, ($123) (with negative suffix), sFr-123
Stable:
ICU 2.0

◆ setNegativeSuffix()

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

Set the negative suffix.

Parameters
newValuethe new value of the negative suffix to be set. Examples: 123%
Stable:
ICU 2.0

◆ setPadCharacter()

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
padChara string containing the pad character. If the string has length 0, then the pad character 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

◆ setPadPosition()

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
padPosthe pad position, one of kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, or kPadAfterSuffix.
See also
setFormatWidth
getFormatWidth
setPadCharacter
getPadCharacterString
getPadPosition
EPadPosition
Stable:
ICU 2.0

◆ setParseCaseSensitive()

void icu::DecimalFormat::setParseCaseSensitive ( UBool  value)

Whether to pay attention to case when parsing; default is to ignore case (perform case-folding).

For example, "A" == "a" in case-insensitive but not case-sensitive mode.

Currency symbols are never case-folded. For example, "us$1.00" will not parse in case-insensitive mode, even though "US$1.00" parses.

Parameters
valuetrue to enable case-sensitive parsing (the default); false to force case-sensitive parsing behavior.
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ setParseIntegerOnly()

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

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

Parameters
valueset True, this format will parse numbers as integers only.
See also
isParseIntegerOnly
Stable:
ICU 53

Reimplemented from icu::NumberFormat.

◆ setParseNoExponent()

void icu::DecimalFormat::setParseNoExponent ( UBool  value)

Specifies whether to stop parsing when an exponent separator is encountered.

For example, parses "123E4" to 123 (with parse position 3) instead of 1230000 (with parse position 5).

Parameters
valuetrue to prevent exponents from being parsed; false to allow them to be parsed.
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ setPositivePrefix()

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

Set the positive prefix.

Parameters
newValuethe new value of the the positive prefix to be set. Examples: +123, $123, sFr123
Stable:
ICU 2.0

◆ setPositiveSuffix()

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

Set the positive suffix.

Parameters
newValuethe new value of the positive suffix to be set. Example: 123%
Stable:
ICU 2.0

◆ setRoundingIncrement()

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
newValueA 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

◆ setRoundingMode()

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

Set the rounding mode.

Parameters
roundingModeA rounding mode
See also
setRoundingIncrement
getRoundingIncrement
getRoundingMode
Stable:
ICU 2.0

Reimplemented from icu::NumberFormat.

◆ setScientificNotation()

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
useScientificTRUE if this object formats and parses scientific notation
See also
isScientificNotation
getMinimumExponentDigits
setMinimumExponentDigits
isExponentSignAlwaysShown
setExponentSignAlwaysShown
Stable:
ICU 2.0

◆ setSecondaryGroupingSize()

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
newValuethe new value of the secondary grouping size.
See also
getSecondaryGroupingSize
NumberFormat::setGroupingUsed
DecimalFormatSymbols::setGroupingSeparator
Stable:
ICU 2.4

◆ setSignAlwaysShown()

void icu::DecimalFormat::setSignAlwaysShown ( UBool  value)

Set whether to show the plus sign on positive (non-negative) numbers; for example, "+12".

For more control over sign display, use NumberFormatter.

Parameters
valuetrue to always show a sign; false to hide the sign on positive numbers and zero.
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ setSignificantDigitsUsed()

void icu::DecimalFormat::setSignificantDigitsUsed ( UBool  useSignificantDigits)

Sets whether significant digits are in use, or integer and fraction digit counts are in use.

Parameters
useSignificantDigitstrue to use significant digits, or false to use integer and fraction digit counts
Stable:
ICU 3.0

◆ toLocalizedPattern()

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

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

Parameters
resultOutput param which will receive the localized pattern. Previous contents are deleted.
Returns
A reference to 'result'.
See also
applyPattern
Stable:
ICU 2.0

◆ toNumberFormatter() [1/2]

const number::LocalizedNumberFormatter* icu::DecimalFormat::toNumberFormatter ( UErrorCode status) const

Converts this DecimalFormat to a (Localized)NumberFormatter.

Starting in ICU 60, NumberFormatter is the recommended way to format numbers. You can use the returned LocalizedNumberFormatter to format numbers and get a FormattedNumber, which contains a string as well as additional annotations about the formatted value.

If a memory allocation failure occurs, the return value of this method might be null. If you are concerned about correct recovery from out-of-memory situations, use this pattern:

FormattedNumber result;
if (auto* ptr = df->toNumberFormatter(status)) {
    result = ptr->formatDouble(123, status);
}

If you are not concerned about out-of-memory situations, or if your environment throws exceptions when memory allocation failure occurs, you can chain the methods, like this:

FormattedNumber result = df
    ->toNumberFormatter(status)
    ->formatDouble(123, status);

NOTE: The returned LocalizedNumberFormatter is owned by this DecimalFormat. If a non-const method is called on the DecimalFormat, or if the DecimalFormat is deleted, the object becomes invalid. If you plan to keep the return value beyond the lifetime of the DecimalFormat, copy it to a local variable:

LocalizedNumberFormatter lnf;
if (auto* ptr = df->toNumberFormatter(status)) {
    lnf = *ptr;
}
Parameters
statusSet on failure, like U_MEMORY_ALLOCATION_ERROR.
Returns
A pointer to an internal object, or nullptr on failure. Do not delete the return value!
Draft:
This API may be changed in the future versions and was introduced in ICU 64

◆ toNumberFormatter() [2/2]

const number::LocalizedNumberFormatter& icu::DecimalFormat::toNumberFormatter ( ) const

Deprecated: Like toNumberFormatter(UErrorCode&) const, but does not take an error code.

The new signature should be used in case an error occurs while returning the LocalizedNumberFormatter.

This old signature will be removed in ICU 65.

Returns
A reference to an internal object.
Deprecated:
ICU 64

◆ toPattern()

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

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

Parameters
resultOutput param which will receive the pattern. Previous contents are deleted.
Returns
A reference to 'result'.
See also
applyPattern
Stable:
ICU 2.0

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