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

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
 * 

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 10³. The * mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0), * but it need not be. DecimalFormat supports arbitrary mantissas. * DecimalFormat can be instructed to use scientific * notation through the API or through the pattern. In a pattern, the exponent * character immediately followed by one or more digit characters indicates * scientific notation. Example: "0.###E0" formats the number 1234 as * "1.234E3". * *

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

*
• Significant 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 * 50. "#,##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. */ class U_I18N_API DecimalFormat : public NumberFormat { public: /** * Pad position. * @stable ICU 2.4 */ enum EPadPosition { kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, kPadAfterSuffix }; /** * 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. * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. * @stable ICU 2.0 */ DecimalFormat(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. * @param pattern A non-localized pattern string. * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. * @stable ICU 2.0 */ DecimalFormat(const UnicodeString& pattern, 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. * * @param pattern a non-localized pattern string * @param symbolsToAdopt the set of symbols to be used. The caller should not * delete this object after making this call. * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. * @stable ICU 2.0 */ DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, UErrorCode& status); #ifndef U_HIDE_INTERNAL_API /** * This API is for ICU use only. * Create a DecimalFormat from the given pattern, symbols, and style. * * @param pattern a non-localized pattern string * @param symbolsToAdopt the set of symbols to be used. The caller should not * delete this object after making this call. * @param style style of decimal format * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. * @internal */ DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, UNumberFormatStyle style, UErrorCode& status); #if UCONFIG_HAVE_PARSEALLINPUT /** * @internal */ void setParseAllInput(UNumberFormatAttributeValue value); #endif #endif /* U_HIDE_INTERNAL_API */ private: /** * Internal constructor for DecimalFormat; sets up internal fields. All public constructors should * call this constructor. */ DecimalFormat(const DecimalFormatSymbols* symbolsToAdopt, UErrorCode& status); public: /** * Set an integer attribute on this DecimalFormat. * May return U_UNSUPPORTED_ERROR if this instance does not support * the specified attribute. * @param attr the attribute to set * @param newValue new value * @param status the error type * @return *this - for chaining (example: format.setAttribute(...).setAttribute(...) ) * @stable ICU 51 */ virtual DecimalFormat& setAttribute(UNumberFormatAttribute attr, int32_t newValue, UErrorCode& status); /** * Get an integer * May return U_UNSUPPORTED_ERROR if this instance does not support * the specified attribute. * @param attr the attribute to set * @param status the error type * @return the attribute value. Undefined if there is an error. * @stable ICU 51 */ virtual int32_t getAttribute(UNumberFormatAttribute attr, UErrorCode& status) const; /** * Set whether or not grouping will be used in this format. * @param newValue True, grouping will be used in this format. * @see getGroupingUsed * @stable ICU 53 */ void setGroupingUsed(UBool newValue) U_OVERRIDE; /** * Sets whether or not numbers should be parsed as integers only. * @param value set True, this format will parse numbers as integers * only. * @see isParseIntegerOnly * @stable ICU 53 */ void setParseIntegerOnly(UBool value) U_OVERRIDE; /** * Sets whether lenient parsing should be enabled (it is off by default). * * @param enable \c TRUE if lenient parsing should be used, * \c FALSE otherwise. * @stable ICU 4.8 */ void setLenient(UBool enable) U_OVERRIDE; /** * 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. * * @param pattern a non-localized pattern string * @param symbolsToAdopt the set of symbols to be used. The caller should not * delete this object after making this call. * @param parseError Output param to receive errors occured during parsing * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. * @stable ICU 2.0 */ DecimalFormat(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. * * @param pattern a non-localized pattern string * @param symbols the set of symbols to be used * @param status Output param set to success/failure code. If the * pattern is invalid this will be set to a failure code. * @stable ICU 2.0 */ DecimalFormat(const UnicodeString& pattern, const DecimalFormatSymbols& symbols, UErrorCode& status); /** * Copy constructor. * * @param source the DecimalFormat object to be copied from. * @stable ICU 2.0 */ DecimalFormat(const DecimalFormat& source); /** * Assignment operator. * * @param rhs the DecimalFormat object to be copied. * @stable ICU 2.0 */ DecimalFormat& operator=(const DecimalFormat& rhs); /** * Destructor. * @stable ICU 2.0 */ ~DecimalFormat() U_OVERRIDE; /** * Clone this Format object polymorphically. The caller owns the * result and should delete it when done. * * @return a polymorphic copy of this DecimalFormat. * @stable ICU 2.0 */ Format* clone(void) const U_OVERRIDE; /** * Return true if the given Format objects are semantically equal. * Objects of different subclasses are considered unequal. * * @param other the object to be compared with. * @return true if the given Format objects are semantically equal. * @stable ICU 2.0 */ UBool operator==(const Format& other) const U_OVERRIDE; using NumberFormat::format; /** * Format a double or long number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. * On output: the offsets of the alignment field. * @return Reference to 'appendTo' parameter. * @stable ICU 2.0 */ UnicodeString& format(double number, UnicodeString& appendTo, FieldPosition& pos) const U_OVERRIDE; #ifndef U_HIDE_INTERNAL_API /** * Format a double or long number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. * On output: the offsets of the alignment field. * @param status * @return Reference to 'appendTo' parameter. * @internal */ UnicodeString& format(double number, UnicodeString& appendTo, FieldPosition& pos, UErrorCode& status) const U_OVERRIDE; #endif /* U_HIDE_INTERNAL_API */ /** * Format a double or long number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param posIter On return, can be used to iterate over positions * of fields generated by this format call. * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @stable ICU 4.4 */ UnicodeString& format(double number, UnicodeString& appendTo, FieldPositionIterator* posIter, UErrorCode& status) const U_OVERRIDE; /** * Format a long number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. * On output: the offsets of the alignment field. * @return Reference to 'appendTo' parameter. * @stable ICU 2.0 */ UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPosition& pos) const U_OVERRIDE; #ifndef U_HIDE_INTERNAL_API /** * Format a long number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. * On output: the offsets of the alignment field. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @internal */ UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPosition& pos, UErrorCode& status) const U_OVERRIDE; #endif /* U_HIDE_INTERNAL_API */ /** * Format a long number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param posIter On return, can be used to iterate over positions * of fields generated by this format call. * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @stable ICU 4.4 */ UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPositionIterator* posIter, UErrorCode& status) const U_OVERRIDE; /** * Format an int64 number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. * On output: the offsets of the alignment field. * @return Reference to 'appendTo' parameter. * @stable ICU 2.8 */ UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPosition& pos) const U_OVERRIDE; #ifndef U_HIDE_INTERNAL_API /** * Format an int64 number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. * On output: the offsets of the alignment field. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @internal */ UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPosition& pos, UErrorCode& status) const U_OVERRIDE; #endif /* U_HIDE_INTERNAL_API */ /** * Format an int64 number using base-10 representation. * * @param number The value to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param posIter On return, can be used to iterate over positions * of fields generated by this format call. * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @stable ICU 4.4 */ UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPositionIterator* posIter, UErrorCode& status) const U_OVERRIDE; /** * 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 * * @param number The unformatted number, as a string. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param posIter On return, can be used to iterate over positions * of fields generated by this format call. * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @stable ICU 4.4 */ UnicodeString& format(StringPiece number, UnicodeString& appendTo, FieldPositionIterator* posIter, UErrorCode& status) const U_OVERRIDE; #ifndef U_HIDE_INTERNAL_API /** * 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. * * @param number The number, a DecimalQuantity format Decimal Floating Point. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param posIter On return, can be used to iterate over positions * of fields generated by this format call. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @internal */ UnicodeString& format(const number::impl::DecimalQuantity& number, UnicodeString& appendTo, FieldPositionIterator* posIter, UErrorCode& status) const U_OVERRIDE; /** * 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. * * @param number The number, a DecimalQuantity format Decimal Floating Point. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. * On output: the offsets of the alignment field. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @internal */ UnicodeString& format(const number::impl::DecimalQuantity& number, UnicodeString& appendTo, FieldPosition& pos, UErrorCode& status) const U_OVERRIDE; #endif // U_HIDE_INTERNAL_API using NumberFormat::parse; /** * 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. * * @param text The text to be parsed. * @param result Formattable to be set to the parse result. * If parse fails, return contents are undefined. * @param 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 Formattable * @stable ICU 2.0 */ void parse(const UnicodeString& text, Formattable& result, ParsePosition& parsePosition) const U_OVERRIDE; /** * 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. * * @param text the string to parse * @param 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. * @return 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 */ CurrencyAmount* parseCurrency(const UnicodeString& text, ParsePosition& pos) const U_OVERRIDE; /** * Returns the decimal format symbols, which is generally not changed * by the programmer or user. * @return desired DecimalFormatSymbols * @see DecimalFormatSymbols * @stable ICU 2.0 */ virtual const DecimalFormatSymbols* getDecimalFormatSymbols(void) const; /** * Sets the decimal format symbols, which is generally not changed * by the programmer or user. * @param symbolsToAdopt DecimalFormatSymbols to be adopted. * @stable ICU 2.0 */ virtual void adoptDecimalFormatSymbols(DecimalFormatSymbols* symbolsToAdopt); /** * Sets the decimal format symbols, which is generally not changed * by the programmer or user. * @param symbols DecimalFormatSymbols. * @stable ICU 2.0 */ virtual void setDecimalFormatSymbols(const DecimalFormatSymbols& symbols); /** * Returns the currency plural format information, * which is generally not changed by the programmer or user. * @return desired CurrencyPluralInfo * @stable ICU 4.2 */ virtual const CurrencyPluralInfo* getCurrencyPluralInfo(void) const; /** * Sets the currency plural format information, * which is generally not changed by the programmer or user. * @param toAdopt CurrencyPluralInfo to be adopted. * @stable ICU 4.2 */ virtual void adoptCurrencyPluralInfo(CurrencyPluralInfo* toAdopt); /** * Sets the currency plural format information, * which is generally not changed by the programmer or user. * @param info Currency Plural Info. * @stable ICU 4.2 */ virtual void setCurrencyPluralInfo(const CurrencyPluralInfo& info); /** * Get the positive prefix. * * @param result Output param which will receive the positive prefix. * @return A reference to 'result'. * Examples: +123, $123, sFr123 * @stable ICU 2.0 */ UnicodeString& getPositivePrefix(UnicodeString& result) const; /** * Set the positive prefix. * * @param newValue the new value of the the positive prefix to be set. * Examples: +123, $123, sFr123 * @stable ICU 2.0 */ virtual void setPositivePrefix(const UnicodeString& newValue); /** * Get the negative prefix. * * @param result Output param which will receive the negative prefix. * @return A reference to 'result'. * Examples: -123, ($123) (with negative suffix), sFr-123 * @stable ICU 2.0 */ UnicodeString& getNegativePrefix(UnicodeString& result) const; /** * Set the negative prefix. * * @param 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 setNegativePrefix(const UnicodeString& newValue); /** * Get the positive suffix. * * @param result Output param which will receive the positive suffix. * @return A reference to 'result'. * Example: 123% * @stable ICU 2.0 */ UnicodeString& getPositiveSuffix(UnicodeString& result) const; /** * Set the positive suffix. * * @param newValue the new value of the positive suffix to be set. * Example: 123% * @stable ICU 2.0 */ virtual void setPositiveSuffix(const UnicodeString& newValue); /** * Get the negative suffix. * * @param result Output param which will receive the negative suffix. * @return A reference to 'result'. * Examples: -123%, ($123) (with positive suffixes) * @stable ICU 2.0 */ UnicodeString& getNegativeSuffix(UnicodeString& result) const; /** * Set the negative suffix. * * @param newValue the new value of the negative suffix to be set. * Examples: 123% * @stable ICU 2.0 */ virtual void setNegativeSuffix(const UnicodeString& newValue); #ifndef U_HIDE_INTERNAL_API /** * Whether to show the plus sign on positive (non-negative) numbers; for example, "+12" * @internal Technical Preview */ UBool isSignAlwaysShown() const; #endif /* U_HIDE_INTERNAL_API */ /** * Set whether to show the plus sign on positive (non-negative) numbers; for example, "+12" * @param value The new setting for whether to show plus sign on positive numbers * @internal Technical Preview */ virtual void setSignAlwaysShown(UBool value); /** * 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(). * * @return the multiplier for use in percent, permill, etc. * Examples: with 100, 1.23 -> "123", and "123" -> 1.23 * @stable ICU 2.0 */ int32_t getMultiplier(void) const; /** * 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(). * * @param 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 setMultiplier(int32_t newValue); #ifndef U_HIDE_DRAFT_API /** * 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. * * @return the current value of the power-of-ten multiplier. * @draft ICU 62 */ int32_t getMultiplierScale(void) const; #endif /* U_HIDE_DRAFT_API */ /** * 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);
     * 

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

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

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

     * LocalizedNumberFormatter f = df->toNumberFormatter();
     * 

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

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