michael@0: /* michael@0: ******************************************************************************** michael@0: * Copyright (C) 1997-2013, International Business Machines michael@0: * Corporation and others. All Rights Reserved. michael@0: ******************************************************************************** michael@0: * michael@0: * File DECIMFMT.H michael@0: * michael@0: * Modification History: michael@0: * michael@0: * Date Name Description michael@0: * 02/19/97 aliu Converted from java. michael@0: * 03/20/97 clhuang Updated per C++ implementation. michael@0: * 04/03/97 aliu Rewrote parsing and formatting completely, and michael@0: * cleaned up and debugged. Actually works now. michael@0: * 04/17/97 aliu Changed DigitCount to int per code review. michael@0: * 07/10/97 helena Made ParsePosition a class and get rid of the function michael@0: * hiding problems. michael@0: * 09/09/97 aliu Ported over support for exponential formats. michael@0: * 07/20/98 stephen Changed documentation michael@0: * 01/30/13 emmons Added Scaling methods michael@0: ******************************************************************************** michael@0: */ michael@0: michael@0: #ifndef DECIMFMT_H michael@0: #define DECIMFMT_H michael@0: michael@0: #include "unicode/utypes.h" michael@0: /** michael@0: * \file michael@0: * \brief C++ API: Formats decimal numbers. michael@0: */ michael@0: michael@0: #if !UCONFIG_NO_FORMATTING michael@0: michael@0: #include "unicode/dcfmtsym.h" michael@0: #include "unicode/numfmt.h" michael@0: #include "unicode/locid.h" michael@0: #include "unicode/fpositer.h" michael@0: #include "unicode/stringpiece.h" michael@0: #include "unicode/curramt.h" michael@0: #include "unicode/enumset.h" michael@0: michael@0: /** michael@0: * \def UNUM_DECIMALFORMAT_INTERNAL_SIZE michael@0: * @internal michael@0: */ michael@0: #if UCONFIG_FORMAT_FASTPATHS_49 michael@0: #define UNUM_DECIMALFORMAT_INTERNAL_SIZE 16 michael@0: #endif michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: class DigitList; michael@0: class ChoiceFormat; michael@0: class CurrencyPluralInfo; michael@0: class Hashtable; michael@0: class UnicodeSet; michael@0: class FieldPositionHandler; michael@0: class DecimalFormatStaticSets; michael@0: class FixedDecimal; michael@0: michael@0: // explicit template instantiation. see digitlst.h michael@0: #if defined (_MSC_VER) michael@0: template class U_I18N_API EnumSet; michael@0: #endif michael@0: michael@0: /** michael@0: * DecimalFormat is a concrete subclass of NumberFormat that formats decimal michael@0: * numbers. It has a variety of features designed to make it possible to parse michael@0: * and format numbers in any locale, including support for Western, Arabic, or michael@0: * Indic digits. It also supports different flavors of numbers, including michael@0: * integers ("123"), fixed-point numbers ("123.4"), scientific notation michael@0: * ("1.23E4"), percentages ("12%"), and currency amounts ("$123", "USD123", michael@0: * "123 US dollars"). All of these flavors can be easily localized. michael@0: * michael@0: *

To obtain a NumberFormat for a specific locale (including the default michael@0: * locale) call one of NumberFormat's factory methods such as michael@0: * createInstance(). Do not call the DecimalFormat constructors directly, unless michael@0: * you know what you are doing, since the NumberFormat factory methods may michael@0: * return subclasses other than DecimalFormat. michael@0: * michael@0: *

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

michael@0: * Another example use createInstance(style) michael@0: *

michael@0: *

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

michael@0: * michael@0: * michael@0: *

Patterns michael@0: * michael@0: *

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

Special Pattern Characters michael@0: * michael@0: *

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

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

The characters listed here are used in non-localized patterns. Localized michael@0: * patterns use the corresponding characters taken from this formatter's michael@0: * DecimalFormatSymbols object instead, and these characters lose michael@0: * their special status. Two exceptions are the currency sign and quote, which michael@0: * are not localized. michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: *
Symbol michael@0: * Location michael@0: * Localized? michael@0: * Meaning michael@0: *
0 michael@0: * Number michael@0: * Yes michael@0: * Digit michael@0: *
1-9 michael@0: * Number michael@0: * Yes michael@0: * '1' through '9' indicate rounding. michael@0: *
\htmlonly@\endhtmlonly michael@0: * Number michael@0: * No michael@0: * Significant digit michael@0: *
# michael@0: * Number michael@0: * Yes michael@0: * Digit, zero shows as absent michael@0: *
. michael@0: * Number michael@0: * Yes michael@0: * Decimal separator or monetary decimal separator michael@0: *
- michael@0: * Number michael@0: * Yes michael@0: * Minus sign michael@0: *
, michael@0: * Number michael@0: * Yes michael@0: * Grouping separator michael@0: *
E michael@0: * Number michael@0: * Yes michael@0: * Separates mantissa and exponent in scientific notation. michael@0: * Need not be quoted in prefix or suffix. michael@0: *
+ michael@0: * Exponent michael@0: * Yes michael@0: * Prefix positive exponents with localized plus sign. michael@0: * Need not be quoted in prefix or suffix. michael@0: *
; michael@0: * Subpattern boundary michael@0: * Yes michael@0: * Separates positive and negative subpatterns michael@0: *
\% michael@0: * Prefix or suffix michael@0: * Yes michael@0: * Multiply by 100 and show as percentage michael@0: *
\\u2030 michael@0: * Prefix or suffix michael@0: * Yes michael@0: * Multiply by 1000 and show as per mille michael@0: *
\htmlonly¤\endhtmlonly (\\u00A4) michael@0: * Prefix or suffix michael@0: * No michael@0: * Currency sign, replaced by currency symbol. If michael@0: * doubled, replaced by international currency symbol. michael@0: * If tripled, replaced by currency plural names, for example, michael@0: * "US dollar" or "US dollars" for America. michael@0: * If present in a pattern, the monetary decimal separator michael@0: * is used instead of the decimal separator. michael@0: *
' michael@0: * Prefix or suffix michael@0: * No michael@0: * Used to quote special characters in a prefix or suffix, michael@0: * for example, "'#'#" formats 123 to michael@0: * "#123". To create a single quote michael@0: * itself, use two in a row: "# o''clock". michael@0: *
* michael@0: * Prefix or suffix boundary michael@0: * Yes michael@0: * Pad escape, precedes pad character michael@0: *
michael@0: * michael@0: *

A DecimalFormat pattern contains a postive and negative michael@0: * subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a michael@0: * prefix, a numeric part, and a suffix. If there is no explicit negative michael@0: * subpattern, the negative subpattern is the localized minus sign prefixed to the michael@0: * positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there michael@0: * is an explicit negative subpattern, it serves only to specify the negative michael@0: * prefix and suffix; the number of digits, minimal digits, and other michael@0: * characteristics are ignored in the negative subpattern. That means that michael@0: * "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)". michael@0: * michael@0: *

The prefixes, suffixes, and various symbols used for infinity, digits, michael@0: * thousands separators, decimal separators, etc. may be set to arbitrary michael@0: * values, and they will appear properly during formatting. However, care must michael@0: * be taken that the symbols and strings do not conflict, or parsing will be michael@0: * unreliable. For example, either the positive and negative prefixes or the michael@0: * suffixes must be distinct for parse() to be able michael@0: * to distinguish positive from negative values. Another example is that the michael@0: * decimal separator and thousands separator should be distinct characters, or michael@0: * parsing will be impossible. michael@0: * michael@0: *

The grouping separator is a character that separates clusters of michael@0: * integer digits to make large numbers more legible. It commonly used for michael@0: * thousands, but in some locales it separates ten-thousands. The grouping michael@0: * size is the number of digits between the grouping separators, such as 3 michael@0: * for "100,000,000" or 4 for "1 0000 0000". There are actually two different michael@0: * grouping sizes: One used for the least significant integer digits, the michael@0: * primary grouping size, and one used for all others, the michael@0: * secondary grouping size. In most locales these are the same, but michael@0: * sometimes they are different. For example, if the primary grouping interval michael@0: * is 3, and the secondary is 2, then this corresponds to the pattern michael@0: * "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a michael@0: * pattern contains multiple grouping separators, the interval between the last michael@0: * one and the end of the integer defines the primary grouping size, and the michael@0: * interval between the last two defines the secondary grouping size. All others michael@0: * are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####". michael@0: * michael@0: *

Illegal patterns, such as "#.#.#" or "#.###,###", will cause michael@0: * DecimalFormat to set a failing UErrorCode. michael@0: * michael@0: *

Pattern BNF michael@0: * michael@0: *

michael@0:  * pattern    := subpattern (';' subpattern)?
michael@0:  * subpattern := prefix? number exponent? suffix?
michael@0:  * number     := (integer ('.' fraction)?) | sigDigits
michael@0:  * prefix     := '\\u0000'..'\\uFFFD' - specialCharacters
michael@0:  * suffix     := '\\u0000'..'\\uFFFD' - specialCharacters
michael@0:  * integer    := '#'* '0'* '0'
michael@0:  * fraction   := '0'* '#'*
michael@0:  * sigDigits  := '#'* '@' '@'* '#'*
michael@0:  * exponent   := 'E' '+'? '0'* '0'
michael@0:  * padSpec    := '*' padChar
michael@0:  * padChar    := '\\u0000'..'\\uFFFD' - quote
michael@0:  *  
michael@0:  * Notation:
michael@0:  *   X*       0 or more instances of X
michael@0:  *   X?       0 or 1 instances of X
michael@0:  *   X|Y      either X or Y
michael@0:  *   C..D     any character from C up to D, inclusive
michael@0:  *   S-T      characters in S, except those in T
michael@0:  *

michael@0: * The first subpattern is for positive numbers. The second (optional) michael@0: * subpattern is for negative numbers. michael@0: * michael@0: *

Not indicated in the BNF syntax above: michael@0: * michael@0: *

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

michael@0: * michael@0: *

Parsing michael@0: * michael@0: *

DecimalFormat parses all Unicode characters that represent michael@0: * decimal digits, as defined by u_charDigitValue(). In addition, michael@0: * DecimalFormat also recognizes as digits the ten consecutive michael@0: * characters starting with the localized zero digit defined in the michael@0: * DecimalFormatSymbols object. During formatting, the michael@0: * DecimalFormatSymbols-based digits are output. michael@0: * michael@0: *

During parsing, grouping separators are ignored if in lenient mode; michael@0: * otherwise, if present, they must be in appropriate positions. michael@0: * michael@0: *

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

If parse(UnicodeString&,Formattable&,ParsePosition&) michael@0: * fails to parse a string, it leaves the parse position unchanged. michael@0: * The convenience method parse(UnicodeString&,Formattable&,UErrorCode&) michael@0: * indicates parse failure by setting a failing michael@0: * UErrorCode. michael@0: * michael@0: *

Formatting michael@0: * michael@0: *

Formatting is guided by several parameters, all of which can be michael@0: * specified either using a pattern or using the API. The following michael@0: * description applies to formats that do not use scientific michael@0: * notation or significant digits. michael@0: * michael@0: *

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

michael@0: * michael@0: *

Special Values michael@0: * michael@0: *

NaN is represented as a single character, typically michael@0: * \\uFFFD. This character is determined by the michael@0: * DecimalFormatSymbols object. This is the only value for which michael@0: * the prefixes and suffixes are not used. michael@0: * michael@0: *

Infinity is represented as a single character, typically michael@0: * \\u221E, with the positive or negative prefixes and suffixes michael@0: * applied. The infinity character is determined by the michael@0: * DecimalFormatSymbols object. michael@0: * michael@0: * Scientific Notation michael@0: * michael@0: *

Numbers in scientific notation are expressed as the product of a mantissa michael@0: * and a power of ten, for example, 1234 can be expressed as 1.234 x 10³. The michael@0: * mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0), michael@0: * but it need not be. DecimalFormat supports arbitrary mantissas. michael@0: * DecimalFormat can be instructed to use scientific michael@0: * notation through the API or through the pattern. In a pattern, the exponent michael@0: * character immediately followed by one or more digit characters indicates michael@0: * scientific notation. Example: "0.###E0" formats the number 1234 as michael@0: * "1.234E3". michael@0: * michael@0: *

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

michael@0: * michael@0: * Significant Digits michael@0: * michael@0: * DecimalFormat has two ways of controlling how many michael@0: * digits are shows: (a) significant digits counts, or (b) integer and michael@0: * fraction digit counts. Integer and fraction digit counts are michael@0: * described above. When a formatter is using significant digits michael@0: * counts, the number of integer and fraction digits is not specified michael@0: * directly, and the formatter settings for these counts are ignored. michael@0: * Instead, the formatter uses however many integer and fraction michael@0: * digits are required to display the specified number of significant michael@0: * digits. Examples: michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: *

Pattern michael@0: *	Minimum significant digits michael@0: *	Maximum significant digits michael@0: *	Number michael@0: *	Output of format() michael@0: *
`\@\@\@` michael@0: *	3 michael@0: *	3 michael@0: *	12345 michael@0: *	`12300` michael@0: *
`\@\@\@` michael@0: *	3 michael@0: *	3 michael@0: *	0.12345 michael@0: *	`0.123` michael@0: *
`\@\@##` michael@0: *	2 michael@0: *	4 michael@0: *	3.14159 michael@0: *	`3.142` michael@0: *
`\@\@##` michael@0: *	2 michael@0: *	4 michael@0: *	1.23004 michael@0: *	`1.23` michael@0: *

michael@0: * michael@0: *

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

michael@0: * michael@0: *

Padding michael@0: * michael@0: *

DecimalFormat supports padding the result of michael@0: * format() to a specific width. Padding may be specified either michael@0: * through the API or through the pattern syntax. In a pattern the pad escape michael@0: * character, followed by a single pad character, causes padding to be parsed michael@0: * and formatted. The pad escape character is '*' in unlocalized patterns, and michael@0: * can be localized using DecimalFormatSymbols::setSymbol() with a michael@0: * DecimalFormatSymbols::kPadEscapeSymbol michael@0: * selector. For example, "$*x#,##0.00" formats 123 to michael@0: * "$xx123.00", and 1234 to "$1,234.00". michael@0: * michael@0: *

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

michael@0: * michael@0: *

Rounding michael@0: * michael@0: *

DecimalFormat supports rounding to a specific increment. For michael@0: * example, 1230 rounded to the nearest 50 is 1250. 1.234 rounded to the michael@0: * nearest 0.65 is 1.3. The rounding increment may be specified through the API michael@0: * or in a pattern. To specify a rounding increment in a pattern, include the michael@0: * increment in the pattern itself. "#,#50" specifies a rounding increment of michael@0: * 50. "#,##0.05" specifies a rounding increment of 0.05. michael@0: * michael@0: *

In the absense of an explicit rounding increment numbers are michael@0: * rounded to their formatted width. michael@0: * michael@0: *

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

michael@0: * michael@0: *

Synchronization michael@0: * michael@0: *

DecimalFormat objects are not synchronized. Multiple michael@0: * threads should not access one formatter concurrently. michael@0: * michael@0: *

Subclassing michael@0: * michael@0: *

User subclasses are not supported. While clients may write michael@0: * subclasses, such code will not necessarily work and will not be michael@0: * guaranteed to work stably from release to release. michael@0: */ michael@0: class U_I18N_API DecimalFormat: public NumberFormat { michael@0: public: michael@0: /** michael@0: * Rounding mode. michael@0: * @stable ICU 2.4 michael@0: */ michael@0: enum ERoundingMode { michael@0: kRoundCeiling, /**< Round towards positive infinity */ michael@0: kRoundFloor, /**< Round towards negative infinity */ michael@0: kRoundDown, /**< Round towards zero */ michael@0: kRoundUp, /**< Round away from zero */ michael@0: kRoundHalfEven, /**< Round towards the nearest integer, or michael@0: towards the nearest even integer if equidistant */ michael@0: kRoundHalfDown, /**< Round towards the nearest integer, or michael@0: towards zero if equidistant */ michael@0: kRoundHalfUp, /**< Round towards the nearest integer, or michael@0: away from zero if equidistant */ michael@0: /** michael@0: * Return U_FORMAT_INEXACT_ERROR if number does not format exactly. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: kRoundUnnecessary michael@0: }; michael@0: michael@0: /** michael@0: * Pad position. michael@0: * @stable ICU 2.4 michael@0: */ michael@0: enum EPadPosition { michael@0: kPadBeforePrefix, michael@0: kPadAfterPrefix, michael@0: kPadBeforeSuffix, michael@0: kPadAfterSuffix michael@0: }; michael@0: michael@0: /** michael@0: * Create a DecimalFormat using the default pattern and symbols michael@0: * for the default locale. This is a convenient way to obtain a michael@0: * DecimalFormat when internationalization is not the main concern. michael@0: *

michael@0: * To obtain standard formats for a given locale, use the factory methods michael@0: * on NumberFormat such as createInstance. These factories will michael@0: * return the most appropriate sub-class of NumberFormat for a given michael@0: * locale. michael@0: * @param status Output param set to success/failure code. If the michael@0: * pattern is invalid this will be set to a failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: DecimalFormat(UErrorCode& status); michael@0: michael@0: /** michael@0: * Create a DecimalFormat from the given pattern and the symbols michael@0: * for the default locale. This is a convenient way to obtain a michael@0: * DecimalFormat when internationalization is not the main concern. michael@0: *

michael@0: * To obtain standard formats for a given locale, use the factory methods michael@0: * on NumberFormat such as createInstance. These factories will michael@0: * return the most appropriate sub-class of NumberFormat for a given michael@0: * locale. michael@0: * @param pattern A non-localized pattern string. michael@0: * @param status Output param set to success/failure code. If the michael@0: * pattern is invalid this will be set to a failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: DecimalFormat(const UnicodeString& pattern, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Create a DecimalFormat from the given pattern and symbols. michael@0: * Use this constructor when you need to completely customize the michael@0: * behavior of the format. michael@0: *

michael@0: * To obtain standard formats for a given michael@0: * locale, use the factory methods on NumberFormat such as michael@0: * createInstance or createCurrencyInstance. If you need only minor adjustments michael@0: * to a standard format, you can modify the format returned by michael@0: * a NumberFormat factory method. michael@0: * michael@0: * @param pattern a non-localized pattern string michael@0: * @param symbols the set of symbols to be used michael@0: * @param status Output param set to success/failure code. If the michael@0: * pattern is invalid this will be set to a failure code. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: DecimalFormat( const UnicodeString& pattern, michael@0: const DecimalFormatSymbols& symbols, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Copy constructor. michael@0: * michael@0: * @param source the DecimalFormat object to be copied from. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: DecimalFormat(const DecimalFormat& source); michael@0: michael@0: /** michael@0: * Assignment operator. michael@0: * michael@0: * @param rhs the DecimalFormat object to be copied. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: DecimalFormat& operator=(const DecimalFormat& rhs); michael@0: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual ~DecimalFormat(); michael@0: michael@0: /** michael@0: * Clone this Format object polymorphically. The caller owns the michael@0: * result and should delete it when done. michael@0: * michael@0: * @return a polymorphic copy of this DecimalFormat. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual Format* clone(void) const; michael@0: michael@0: /** michael@0: * Return true if the given Format objects are semantically equal. michael@0: * Objects of different subclasses are considered unequal. michael@0: * michael@0: * @param other the object to be compared with. michael@0: * @return true if the given Format objects are semantically equal. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UBool operator==(const Format& other) const; michael@0: michael@0: michael@0: using NumberFormat::format; michael@0: michael@0: /** michael@0: * Format a double or long number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& format(double number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos) const; michael@0: michael@0: michael@0: /** michael@0: * Format a double or long number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(double number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Format a double or long number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(double number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format a long number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& format(int32_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos) const; michael@0: michael@0: /** michael@0: * Format a long number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(int32_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Format a long number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(int32_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format an int64 number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable ICU 2.8 michael@0: */ michael@0: virtual UnicodeString& format(int64_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos) const; michael@0: michael@0: /** michael@0: * Format an int64 number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(int64_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Format an int64 number using base-10 representation. michael@0: * michael@0: * @param number The value to be formatted. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(int64_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format a decimal number. michael@0: * The syntax of the unformatted number is a "numeric string" michael@0: * as defined in the Decimal Arithmetic Specification, available at michael@0: * http://speleotrove.com/decimal michael@0: * michael@0: * @param number The unformatted number, as a string. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * Can be NULL. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @stable 4.4 michael@0: */ michael@0: virtual UnicodeString& format(const StringPiece &number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: michael@0: /** michael@0: * Format a decimal number. michael@0: * The number is a DigitList wrapper onto a floating point decimal number. michael@0: * The default implementation in NumberFormat converts the decimal number michael@0: * to a double and formats that. michael@0: * michael@0: * @param number The number, a DigitList format Decimal Floating Point. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param posIter On return, can be used to iterate over positions michael@0: * of fields generated by this format call. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(const DigitList &number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionIterator* posIter, michael@0: UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Format a decimal number. michael@0: * The number is a DigitList wrapper onto a floating point decimal number. michael@0: * The default implementation in NumberFormat converts the decimal number michael@0: * to a double and formats that. michael@0: * michael@0: * @param number The number, a DigitList format Decimal Floating Point. michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param pos On input: an alignment field, if desired. michael@0: * On output: the offsets of the alignment field. michael@0: * @param status Output param filled with success/failure status. michael@0: * @return Reference to 'appendTo' parameter. michael@0: * @internal michael@0: */ michael@0: virtual UnicodeString& format(const DigitList &number, michael@0: UnicodeString& appendTo, michael@0: FieldPosition& pos, michael@0: UErrorCode& status) const; michael@0: michael@0: using NumberFormat::parse; michael@0: michael@0: /** michael@0: * Parse the given string using this object's choices. The method michael@0: * does string comparisons to try to find an optimal match. michael@0: * If no object can be parsed, index is unchanged, and NULL is michael@0: * returned. The result is returned as the most parsimonious michael@0: * type of Formattable that will accomodate all of the michael@0: * necessary precision. For example, if the result is exactly 12, michael@0: * it will be returned as a long. However, if it is 1.5, it will michael@0: * be returned as a double. michael@0: * michael@0: * @param text The text to be parsed. michael@0: * @param result Formattable to be set to the parse result. michael@0: * If parse fails, return contents are undefined. michael@0: * @param parsePosition The position to start parsing at on input. michael@0: * On output, moved to after the last successfully michael@0: * parse character. On parse failure, does not change. michael@0: * @see Formattable michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void parse(const UnicodeString& text, michael@0: Formattable& result, michael@0: ParsePosition& parsePosition) const; michael@0: michael@0: /** michael@0: * Parses text from the given string as a currency amount. Unlike michael@0: * the parse() method, this method will attempt to parse a generic michael@0: * currency name, searching for a match of this object's locale's michael@0: * currency display names, or for a 3-letter ISO currency code. michael@0: * This method will fail if this format is not a currency format, michael@0: * that is, if it does not contain the currency pattern symbol michael@0: * (U+00A4) in its prefix or suffix. michael@0: * michael@0: * @param text the string to parse michael@0: * @param pos input-output position; on input, the position within text michael@0: * to match; must have 0 <= pos.getIndex() < text.length(); michael@0: * on output, the position after the last matched character. michael@0: * If the parse fails, the position in unchanged upon output. michael@0: * @return if parse succeeds, a pointer to a newly-created CurrencyAmount michael@0: * object (owned by the caller) containing information about michael@0: * the parsed currency; if parse fails, this is NULL. michael@0: * @stable ICU 49 michael@0: */ michael@0: virtual CurrencyAmount* parseCurrency(const UnicodeString& text, michael@0: ParsePosition& pos) const; michael@0: michael@0: /** michael@0: * Returns the decimal format symbols, which is generally not changed michael@0: * by the programmer or user. michael@0: * @return desired DecimalFormatSymbols michael@0: * @see DecimalFormatSymbols michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual const DecimalFormatSymbols* getDecimalFormatSymbols(void) const; michael@0: michael@0: /** michael@0: * Sets the decimal format symbols, which is generally not changed michael@0: * by the programmer or user. michael@0: * @param symbolsToAdopt DecimalFormatSymbols to be adopted. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void adoptDecimalFormatSymbols(DecimalFormatSymbols* symbolsToAdopt); michael@0: michael@0: /** michael@0: * Sets the decimal format symbols, which is generally not changed michael@0: * by the programmer or user. michael@0: * @param symbols DecimalFormatSymbols. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setDecimalFormatSymbols(const DecimalFormatSymbols& symbols); michael@0: michael@0: michael@0: /** michael@0: * Returns the currency plural format information, michael@0: * which is generally not changed by the programmer or user. michael@0: * @return desired CurrencyPluralInfo michael@0: * @stable ICU 4.2 michael@0: */ michael@0: virtual const CurrencyPluralInfo* getCurrencyPluralInfo(void) const; michael@0: michael@0: /** michael@0: * Sets the currency plural format information, michael@0: * which is generally not changed by the programmer or user. michael@0: * @param toAdopt CurrencyPluralInfo to be adopted. michael@0: * @stable ICU 4.2 michael@0: */ michael@0: virtual void adoptCurrencyPluralInfo(CurrencyPluralInfo* toAdopt); michael@0: michael@0: /** michael@0: * Sets the currency plural format information, michael@0: * which is generally not changed by the programmer or user. michael@0: * @param info Currency Plural Info. michael@0: * @stable ICU 4.2 michael@0: */ michael@0: virtual void setCurrencyPluralInfo(const CurrencyPluralInfo& info); michael@0: michael@0: michael@0: /** michael@0: * Get the positive prefix. michael@0: * michael@0: * @param result Output param which will receive the positive prefix. michael@0: * @return A reference to 'result'. michael@0: * Examples: +123, $123, sFr123 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getPositivePrefix(UnicodeString& result) const; michael@0: michael@0: /** michael@0: * Set the positive prefix. michael@0: * michael@0: * @param newValue the new value of the the positive prefix to be set. michael@0: * Examples: +123, $123, sFr123 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setPositivePrefix(const UnicodeString& newValue); michael@0: michael@0: /** michael@0: * Get the negative prefix. michael@0: * michael@0: * @param result Output param which will receive the negative prefix. michael@0: * @return A reference to 'result'. michael@0: * Examples: -123, ($123) (with negative suffix), sFr-123 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getNegativePrefix(UnicodeString& result) const; michael@0: michael@0: /** michael@0: * Set the negative prefix. michael@0: * michael@0: * @param newValue the new value of the the negative prefix to be set. michael@0: * Examples: -123, ($123) (with negative suffix), sFr-123 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setNegativePrefix(const UnicodeString& newValue); michael@0: michael@0: /** michael@0: * Get the positive suffix. michael@0: * michael@0: * @param result Output param which will receive the positive suffix. michael@0: * @return A reference to 'result'. michael@0: * Example: 123% michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getPositiveSuffix(UnicodeString& result) const; michael@0: michael@0: /** michael@0: * Set the positive suffix. michael@0: * michael@0: * @param newValue the new value of the positive suffix to be set. michael@0: * Example: 123% michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setPositiveSuffix(const UnicodeString& newValue); michael@0: michael@0: /** michael@0: * Get the negative suffix. michael@0: * michael@0: * @param result Output param which will receive the negative suffix. michael@0: * @return A reference to 'result'. michael@0: * Examples: -123%, ($123) (with positive suffixes) michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UnicodeString& getNegativeSuffix(UnicodeString& result) const; michael@0: michael@0: /** michael@0: * Set the negative suffix. michael@0: * michael@0: * @param newValue the new value of the negative suffix to be set. michael@0: * Examples: 123% michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setNegativeSuffix(const UnicodeString& newValue); michael@0: michael@0: /** michael@0: * Get the multiplier for use in percent, permill, etc. michael@0: * For a percentage, set the suffixes to have "%" and the multiplier to be 100. michael@0: * (For Arabic, use arabic percent symbol). michael@0: * For a permill, set the suffixes to have "\\u2031" and the multiplier to be 1000. michael@0: * michael@0: * @return the multiplier for use in percent, permill, etc. michael@0: * Examples: with 100, 1.23 -> "123", and "123" -> 1.23 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: int32_t getMultiplier(void) const; michael@0: michael@0: /** michael@0: * Set the multiplier for use in percent, permill, etc. michael@0: * For a percentage, set the suffixes to have "%" and the multiplier to be 100. michael@0: * (For Arabic, use arabic percent symbol). michael@0: * For a permill, set the suffixes to have "\\u2031" and the multiplier to be 1000. michael@0: * michael@0: * @param newValue the new value of the multiplier for use in percent, permill, etc. michael@0: * Examples: with 100, 1.23 -> "123", and "123" -> 1.23 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setMultiplier(int32_t newValue); michael@0: michael@0: /** michael@0: * Get the rounding increment. michael@0: * @return A positive rounding increment, or 0.0 if a custom rounding michael@0: * increment is not in effect. michael@0: * @see #setRoundingIncrement michael@0: * @see #getRoundingMode michael@0: * @see #setRoundingMode michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual double getRoundingIncrement(void) const; michael@0: michael@0: /** michael@0: * Set the rounding increment. In the absence of a rounding increment, michael@0: * numbers will be rounded to the number of digits displayed. michael@0: * @param newValue A positive rounding increment, or 0.0 to michael@0: * use the default rounding increment. michael@0: * Negative increments are equivalent to 0.0. michael@0: * @see #getRoundingIncrement michael@0: * @see #getRoundingMode michael@0: * @see #setRoundingMode michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setRoundingIncrement(double newValue); michael@0: michael@0: /** michael@0: * Get the rounding mode. michael@0: * @return A rounding mode michael@0: * @see #setRoundingIncrement michael@0: * @see #getRoundingIncrement michael@0: * @see #setRoundingMode michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual ERoundingMode getRoundingMode(void) const; michael@0: michael@0: /** michael@0: * Set the rounding mode. michael@0: * @param roundingMode A rounding mode michael@0: * @see #setRoundingIncrement michael@0: * @see #getRoundingIncrement michael@0: * @see #getRoundingMode michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setRoundingMode(ERoundingMode roundingMode); michael@0: michael@0: /** michael@0: * Get the width to which the output of format() is padded. michael@0: * The width is counted in 16-bit code units. michael@0: * @return the format width, or zero if no padding is in effect michael@0: * @see #setFormatWidth michael@0: * @see #getPadCharacterString michael@0: * @see #setPadCharacter michael@0: * @see #getPadPosition michael@0: * @see #setPadPosition michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual int32_t getFormatWidth(void) const; michael@0: michael@0: /** michael@0: * Set the width to which the output of format() is padded. michael@0: * The width is counted in 16-bit code units. michael@0: * This method also controls whether padding is enabled. michael@0: * @param width the width to which to pad the result of michael@0: * format(), or zero to disable padding. A negative michael@0: * width is equivalent to 0. michael@0: * @see #getFormatWidth michael@0: * @see #getPadCharacterString michael@0: * @see #setPadCharacter michael@0: * @see #getPadPosition michael@0: * @see #setPadPosition michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setFormatWidth(int32_t width); michael@0: michael@0: /** michael@0: * Get the pad character used to pad to the format width. The michael@0: * default is ' '. michael@0: * @return a string containing the pad character. This will always michael@0: * have a length of one 32-bit code point. michael@0: * @see #setFormatWidth michael@0: * @see #getFormatWidth michael@0: * @see #setPadCharacter michael@0: * @see #getPadPosition michael@0: * @see #setPadPosition michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString getPadCharacterString() const; michael@0: michael@0: /** michael@0: * Set the character used to pad to the format width. If padding michael@0: * is not enabled, then this will take effect if padding is later michael@0: * enabled. michael@0: * @param padChar a string containing the pad charcter. If the string michael@0: * has length 0, then the pad characer is set to ' '. Otherwise michael@0: * padChar.char32At(0) will be used as the pad character. michael@0: * @see #setFormatWidth michael@0: * @see #getFormatWidth michael@0: * @see #getPadCharacterString michael@0: * @see #getPadPosition michael@0: * @see #setPadPosition michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setPadCharacter(const UnicodeString &padChar); michael@0: michael@0: /** michael@0: * Get the position at which padding will take place. This is the location michael@0: * at which padding will be inserted if the result of format() michael@0: * is shorter than the format width. michael@0: * @return the pad position, one of kPadBeforePrefix, michael@0: * kPadAfterPrefix, kPadBeforeSuffix, or michael@0: * kPadAfterSuffix. michael@0: * @see #setFormatWidth michael@0: * @see #getFormatWidth michael@0: * @see #setPadCharacter michael@0: * @see #getPadCharacterString michael@0: * @see #setPadPosition michael@0: * @see #EPadPosition michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual EPadPosition getPadPosition(void) const; michael@0: michael@0: /** michael@0: * Set the position at which padding will take place. This is the location michael@0: * at which padding will be inserted if the result of format() michael@0: * is shorter than the format width. This has no effect unless padding is michael@0: * enabled. michael@0: * @param padPos the pad position, one of kPadBeforePrefix, michael@0: * kPadAfterPrefix, kPadBeforeSuffix, or michael@0: * kPadAfterSuffix. michael@0: * @see #setFormatWidth michael@0: * @see #getFormatWidth michael@0: * @see #setPadCharacter michael@0: * @see #getPadCharacterString michael@0: * @see #getPadPosition michael@0: * @see #EPadPosition michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setPadPosition(EPadPosition padPos); michael@0: michael@0: /** michael@0: * Return whether or not scientific notation is used. michael@0: * @return TRUE if this object formats and parses scientific notation michael@0: * @see #setScientificNotation michael@0: * @see #getMinimumExponentDigits michael@0: * @see #setMinimumExponentDigits michael@0: * @see #isExponentSignAlwaysShown michael@0: * @see #setExponentSignAlwaysShown michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UBool isScientificNotation(void) const; michael@0: michael@0: /** michael@0: * Set whether or not scientific notation is used. When scientific notation michael@0: * is used, the effective maximum number of integer digits is <= 8. If the michael@0: * maximum number of integer digits is set to more than 8, the effective michael@0: * maximum will be 1. This allows this call to generate a 'default' scientific michael@0: * number format without additional changes. michael@0: * @param useScientific TRUE if this object formats and parses scientific michael@0: * notation michael@0: * @see #isScientificNotation michael@0: * @see #getMinimumExponentDigits michael@0: * @see #setMinimumExponentDigits michael@0: * @see #isExponentSignAlwaysShown michael@0: * @see #setExponentSignAlwaysShown michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setScientificNotation(UBool useScientific); michael@0: michael@0: /** michael@0: * Return the minimum exponent digits that will be shown. michael@0: * @return the minimum exponent digits that will be shown michael@0: * @see #setScientificNotation michael@0: * @see #isScientificNotation michael@0: * @see #setMinimumExponentDigits michael@0: * @see #isExponentSignAlwaysShown michael@0: * @see #setExponentSignAlwaysShown michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual int8_t getMinimumExponentDigits(void) const; michael@0: michael@0: /** michael@0: * Set the minimum exponent digits that will be shown. This has no michael@0: * effect unless scientific notation is in use. michael@0: * @param minExpDig a value >= 1 indicating the fewest exponent digits michael@0: * that will be shown. Values less than 1 will be treated as 1. michael@0: * @see #setScientificNotation michael@0: * @see #isScientificNotation michael@0: * @see #getMinimumExponentDigits michael@0: * @see #isExponentSignAlwaysShown michael@0: * @see #setExponentSignAlwaysShown michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setMinimumExponentDigits(int8_t minExpDig); michael@0: michael@0: /** michael@0: * Return whether the exponent sign is always shown. michael@0: * @return TRUE if the exponent is always prefixed with either the michael@0: * localized minus sign or the localized plus sign, false if only negative michael@0: * exponents are prefixed with the localized minus sign. michael@0: * @see #setScientificNotation michael@0: * @see #isScientificNotation michael@0: * @see #setMinimumExponentDigits michael@0: * @see #getMinimumExponentDigits michael@0: * @see #setExponentSignAlwaysShown michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UBool isExponentSignAlwaysShown(void) const; michael@0: michael@0: /** michael@0: * Set whether the exponent sign is always shown. This has no effect michael@0: * unless scientific notation is in use. michael@0: * @param expSignAlways TRUE if the exponent is always prefixed with either michael@0: * the localized minus sign or the localized plus sign, false if only michael@0: * negative exponents are prefixed with the localized minus sign. michael@0: * @see #setScientificNotation michael@0: * @see #isScientificNotation michael@0: * @see #setMinimumExponentDigits michael@0: * @see #getMinimumExponentDigits michael@0: * @see #isExponentSignAlwaysShown michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setExponentSignAlwaysShown(UBool expSignAlways); michael@0: michael@0: /** michael@0: * Return the grouping size. Grouping size is the number of digits between michael@0: * grouping separators in the integer portion of a number. For example, michael@0: * in the number "123,456.78", the grouping size is 3. michael@0: * michael@0: * @return the grouping size. michael@0: * @see setGroupingSize michael@0: * @see NumberFormat::isGroupingUsed michael@0: * @see DecimalFormatSymbols::getGroupingSeparator michael@0: * @stable ICU 2.0 michael@0: */ michael@0: int32_t getGroupingSize(void) const; michael@0: michael@0: /** michael@0: * Set the grouping size. Grouping size is the number of digits between michael@0: * grouping separators in the integer portion of a number. For example, michael@0: * in the number "123,456.78", the grouping size is 3. michael@0: * michael@0: * @param newValue the new value of the grouping size. michael@0: * @see getGroupingSize michael@0: * @see NumberFormat::setGroupingUsed michael@0: * @see DecimalFormatSymbols::setGroupingSeparator michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setGroupingSize(int32_t newValue); michael@0: michael@0: /** michael@0: * Return the secondary grouping size. In some locales one michael@0: * grouping interval is used for the least significant integer michael@0: * digits (the primary grouping size), and another is used for all michael@0: * others (the secondary grouping size). A formatter supporting a michael@0: * secondary grouping size will return a positive integer unequal michael@0: * to the primary grouping size returned by michael@0: * getGroupingSize(). For example, if the primary michael@0: * grouping size is 4, and the secondary grouping size is 2, then michael@0: * the number 123456789 formats as "1,23,45,6789", and the pattern michael@0: * appears as "#,##,###0". michael@0: * @return the secondary grouping size, or a value less than michael@0: * one if there is none michael@0: * @see setSecondaryGroupingSize michael@0: * @see NumberFormat::isGroupingUsed michael@0: * @see DecimalFormatSymbols::getGroupingSeparator michael@0: * @stable ICU 2.4 michael@0: */ michael@0: int32_t getSecondaryGroupingSize(void) const; michael@0: michael@0: /** michael@0: * Set the secondary grouping size. If set to a value less than 1, michael@0: * then secondary grouping is turned off, and the primary grouping michael@0: * size is used for all intervals, not just the least significant. michael@0: * michael@0: * @param newValue the new value of the secondary grouping size. michael@0: * @see getSecondaryGroupingSize michael@0: * @see NumberFormat#setGroupingUsed michael@0: * @see DecimalFormatSymbols::setGroupingSeparator michael@0: * @stable ICU 2.4 michael@0: */ michael@0: virtual void setSecondaryGroupingSize(int32_t newValue); michael@0: michael@0: /** michael@0: * Allows you to get the behavior of the decimal separator with integers. michael@0: * (The decimal separator will always appear with decimals.) michael@0: * michael@0: * @return TRUE if the decimal separator always appear with decimals. michael@0: * Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: UBool isDecimalSeparatorAlwaysShown(void) const; michael@0: michael@0: /** michael@0: * Allows you to set the behavior of the decimal separator with integers. michael@0: * (The decimal separator will always appear with decimals.) michael@0: * michael@0: * @param newValue set TRUE if the decimal separator will always appear with decimals. michael@0: * Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345 michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setDecimalSeparatorAlwaysShown(UBool newValue); michael@0: michael@0: /** michael@0: * Synthesizes a pattern string that represents the current state michael@0: * of this Format object. michael@0: * michael@0: * @param result Output param which will receive the pattern. michael@0: * Previous contents are deleted. michael@0: * @return A reference to 'result'. michael@0: * @see applyPattern michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& toPattern(UnicodeString& result) const; michael@0: michael@0: /** michael@0: * Synthesizes a localized pattern string that represents the current michael@0: * state of this Format object. michael@0: * michael@0: * @param result Output param which will receive the localized pattern. michael@0: * Previous contents are deleted. michael@0: * @return A reference to 'result'. michael@0: * @see applyPattern michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UnicodeString& toLocalizedPattern(UnicodeString& result) const; michael@0: michael@0: /** michael@0: * Apply the given pattern to this Format object. A pattern is a michael@0: * short-hand specification for the various formatting properties. michael@0: * These properties can also be changed individually through the michael@0: * various setter methods. michael@0: *

michael@0: * There is no limit to integer digits are set michael@0: * by this routine, since that is the typical end-user desire; michael@0: * use setMaximumInteger if you want to set a real value. michael@0: * For negative numbers, use a second pattern, separated by a semicolon michael@0: *

michael@0:      * .      Example "#,#00.0#" -> 1,234.56
michael@0:      *

michael@0: * This means a minimum of 2 integer digits, 1 fraction digit, and michael@0: * a maximum of 2 fraction digits. michael@0: *

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

michael@0: * In negative patterns, the minimum and maximum counts are ignored; michael@0: * these are presumed to be set in the positive pattern. michael@0: * michael@0: * @param pattern The pattern to be applied. michael@0: * @param parseError Struct to recieve information on position michael@0: * of error if an error is encountered michael@0: * @param status Output param set to success/failure code on michael@0: * exit. If the pattern is invalid, this will be michael@0: * set to a failure result. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void applyPattern(const UnicodeString& pattern, michael@0: UParseError& parseError, michael@0: UErrorCode& status); michael@0: /** michael@0: * Sets the pattern. michael@0: * @param pattern The pattern to be applied. michael@0: * @param status Output param set to success/failure code on michael@0: * exit. If the pattern is invalid, this will be michael@0: * set to a failure result. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void applyPattern(const UnicodeString& pattern, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Apply the given pattern to this Format object. The pattern michael@0: * is assumed to be in a localized notation. A pattern is a michael@0: * short-hand specification for the various formatting properties. michael@0: * These properties can also be changed individually through the michael@0: * various setter methods. michael@0: *

michael@0:      * .      Example "#,#00.0#" -> 1,234.56
michael@0:      *

michael@0: * This means a minimum of 2 integer digits, 1 fraction digit, and michael@0: * a maximum of 2 fraction digits. michael@0: * michael@0: * Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses. michael@0: * michael@0: * In negative patterns, the minimum and maximum counts are ignored; michael@0: * these are presumed to be set in the positive pattern. michael@0: * michael@0: * @param pattern The localized pattern to be applied. michael@0: * @param parseError Struct to recieve information on position michael@0: * of error if an error is encountered michael@0: * @param status Output param set to success/failure code on michael@0: * exit. If the pattern is invalid, this will be michael@0: * set to a failure result. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void applyLocalizedPattern(const UnicodeString& pattern, michael@0: UParseError& parseError, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Apply the given pattern to this Format object. michael@0: * michael@0: * @param pattern The localized pattern to be applied. michael@0: * @param status Output param set to success/failure code on michael@0: * exit. If the pattern is invalid, this will be michael@0: * set to a failure result. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void applyLocalizedPattern(const UnicodeString& pattern, michael@0: UErrorCode& status); michael@0: michael@0: michael@0: /** michael@0: * Sets the maximum number of digits allowed in the integer portion of a michael@0: * number. This override limits the integer digit count to 309. michael@0: * michael@0: * @param newValue the new value of the maximum number of digits michael@0: * allowed in the integer portion of a number. michael@0: * @see NumberFormat#setMaximumIntegerDigits michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setMaximumIntegerDigits(int32_t newValue); michael@0: michael@0: /** michael@0: * Sets the minimum number of digits allowed in the integer portion of a michael@0: * number. This override limits the integer digit count to 309. michael@0: * michael@0: * @param newValue the new value of the minimum number of digits michael@0: * allowed in the integer portion of a number. michael@0: * @see NumberFormat#setMinimumIntegerDigits michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setMinimumIntegerDigits(int32_t newValue); michael@0: michael@0: /** michael@0: * Sets the maximum number of digits allowed in the fraction portion of a michael@0: * number. This override limits the fraction digit count to 340. michael@0: * michael@0: * @param newValue the new value of the maximum number of digits michael@0: * allowed in the fraction portion of a number. michael@0: * @see NumberFormat#setMaximumFractionDigits michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setMaximumFractionDigits(int32_t newValue); michael@0: michael@0: /** michael@0: * Sets the minimum number of digits allowed in the fraction portion of a michael@0: * number. This override limits the fraction digit count to 340. michael@0: * michael@0: * @param newValue the new value of the minimum number of digits michael@0: * allowed in the fraction portion of a number. michael@0: * @see NumberFormat#setMinimumFractionDigits michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual void setMinimumFractionDigits(int32_t newValue); michael@0: michael@0: /** michael@0: * Returns the minimum number of significant digits that will be michael@0: * displayed. This value has no effect unless areSignificantDigitsUsed() michael@0: * returns true. michael@0: * @return the fewest significant digits that will be shown michael@0: * @stable ICU 3.0 michael@0: */ michael@0: int32_t getMinimumSignificantDigits() const; michael@0: michael@0: /** michael@0: * Returns the maximum number of significant digits that will be michael@0: * displayed. This value has no effect unless areSignificantDigitsUsed() michael@0: * returns true. michael@0: * @return the most significant digits that will be shown michael@0: * @stable ICU 3.0 michael@0: */ michael@0: int32_t getMaximumSignificantDigits() const; michael@0: michael@0: /** michael@0: * Sets the minimum number of significant digits that will be michael@0: * displayed. If min is less than one then it is set michael@0: * to one. If the maximum significant digits count is less than michael@0: * min, then it is set to min. michael@0: * This function also enables the use of significant digits michael@0: * by this formatter - areSignificantDigitsUsed() will return TRUE. michael@0: * @see #areSignificantDigitsUsed michael@0: * @param min the fewest significant digits to be shown michael@0: * @stable ICU 3.0 michael@0: */ michael@0: void setMinimumSignificantDigits(int32_t min); michael@0: michael@0: /** michael@0: * Sets the maximum number of significant digits that will be michael@0: * displayed. If max is less than one then it is set michael@0: * to one. If the minimum significant digits count is greater michael@0: * than max, then it is set to max. michael@0: * This function also enables the use of significant digits michael@0: * by this formatter - areSignificantDigitsUsed() will return TRUE. michael@0: * @see #areSignificantDigitsUsed michael@0: * @param max the most significant digits to be shown michael@0: * @stable ICU 3.0 michael@0: */ michael@0: void setMaximumSignificantDigits(int32_t max); michael@0: michael@0: /** michael@0: * Returns true if significant digits are in use, or false if michael@0: * integer and fraction digit counts are in use. michael@0: * @return true if significant digits are in use michael@0: * @stable ICU 3.0 michael@0: */ michael@0: UBool areSignificantDigitsUsed() const; michael@0: michael@0: /** michael@0: * Sets whether significant digits are in use, or integer and michael@0: * fraction digit counts are in use. michael@0: * @param useSignificantDigits true to use significant digits, or michael@0: * false to use integer and fraction digit counts michael@0: * @stable ICU 3.0 michael@0: */ michael@0: void setSignificantDigitsUsed(UBool useSignificantDigits); michael@0: michael@0: public: michael@0: /** michael@0: * Sets the currency used to display currency michael@0: * amounts. This takes effect immediately, if this format is a michael@0: * currency format. If this format is not a currency format, then michael@0: * the currency is used if and when this object becomes a michael@0: * currency format through the application of a new pattern. michael@0: * @param theCurrency a 3-letter ISO code indicating new currency michael@0: * to use. It need not be null-terminated. May be the empty michael@0: * string or NULL to indicate no currency. michael@0: * @param ec input-output error code michael@0: * @stable ICU 3.0 michael@0: */ michael@0: virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec); michael@0: michael@0: /** michael@0: * Sets the currency used to display currency amounts. See michael@0: * setCurrency(const UChar*, UErrorCode&). michael@0: * @deprecated ICU 3.0. Use setCurrency(const UChar*, UErrorCode&). michael@0: */ michael@0: virtual void setCurrency(const UChar* theCurrency); michael@0: michael@0: /** michael@0: * The resource tags we use to retrieve decimal format data from michael@0: * locale resource bundles. michael@0: * @deprecated ICU 3.4. This string has no public purpose. Please don't use it. michael@0: */ michael@0: static const char fgNumberPatterns[]; michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Get a FixedDecimal corresponding to a double as it would be michael@0: * formatted by this DecimalFormat. michael@0: * Internal, not intended for public use. michael@0: * @internal michael@0: */ michael@0: FixedDecimal getFixedDecimal(double number, UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Get a FixedDecimal corresponding to a formattable as it would be michael@0: * formatted by this DecimalFormat. michael@0: * Internal, not intended for public use. michael@0: * @internal michael@0: */ michael@0: FixedDecimal getFixedDecimal(const Formattable &number, UErrorCode &status) const; michael@0: michael@0: /** michael@0: * Get a FixedDecimal corresponding to a DigitList as it would be michael@0: * formatted by this DecimalFormat. Note: the DigitList may be modified. michael@0: * Internal, not intended for public use. michael@0: * @internal michael@0: */ michael@0: FixedDecimal getFixedDecimal(DigitList &number, UErrorCode &status) const; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: public: michael@0: michael@0: /** michael@0: * Return the class ID for this class. This is useful only for michael@0: * comparing to a return value from getDynamicClassID(). For example: michael@0: *

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

michael@0: * @return The class ID for all objects of this class. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: static UClassID U_EXPORT2 getStaticClassID(void); michael@0: michael@0: /** michael@0: * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. michael@0: * This method is to implement a simple version of RTTI, since not all michael@0: * C++ compilers support genuine RTTI. Polymorphic operator==() and michael@0: * clone() methods call this method. michael@0: * michael@0: * @return The class ID for this object. All objects of a michael@0: * given class have the same class ID. Objects of michael@0: * other classes have different class IDs. michael@0: * @stable ICU 2.0 michael@0: */ michael@0: virtual UClassID getDynamicClassID(void) const; michael@0: michael@0: private: michael@0: michael@0: DecimalFormat(); // default constructor not implemented michael@0: michael@0: int32_t precision() const; michael@0: michael@0: /** michael@0: * Initialize all fields of a new DecimalFormatter to a safe default value. michael@0: * Common code for use by constructors. michael@0: */ michael@0: void init(); michael@0: michael@0: /** michael@0: * Do real work of constructing a new DecimalFormat. michael@0: */ michael@0: void construct(UErrorCode& status, michael@0: UParseError& parseErr, michael@0: const UnicodeString* pattern = 0, michael@0: DecimalFormatSymbols* symbolsToAdopt = 0 michael@0: ); michael@0: michael@0: /** michael@0: * Does the real work of generating a pattern. michael@0: * michael@0: * @param result Output param which will receive the pattern. michael@0: * Previous contents are deleted. michael@0: * @param localized TRUE return localized pattern. michael@0: * @return A reference to 'result'. michael@0: */ michael@0: UnicodeString& toPattern(UnicodeString& result, UBool localized) const; michael@0: michael@0: /** michael@0: * Does the real work of applying a pattern. michael@0: * @param pattern The pattern to be applied. michael@0: * @param localized If true, the pattern is localized; else false. michael@0: * @param parseError Struct to recieve information on position michael@0: * of error if an error is encountered michael@0: * @param status Output param set to success/failure code on michael@0: * exit. If the pattern is invalid, this will be michael@0: * set to a failure result. michael@0: */ michael@0: void applyPattern(const UnicodeString& pattern, michael@0: UBool localized, michael@0: UParseError& parseError, michael@0: UErrorCode& status); michael@0: michael@0: /* michael@0: * similar to applyPattern, but without re-gen affix for currency michael@0: */ michael@0: void applyPatternInternally(const UnicodeString& pluralCount, michael@0: const UnicodeString& pattern, michael@0: UBool localized, michael@0: UParseError& parseError, michael@0: UErrorCode& status); michael@0: michael@0: /* michael@0: * only apply pattern without expand affixes michael@0: */ michael@0: void applyPatternWithoutExpandAffix(const UnicodeString& pattern, michael@0: UBool localized, michael@0: UParseError& parseError, michael@0: UErrorCode& status); michael@0: michael@0: michael@0: /* michael@0: * expand affixes (after apply patter) and re-compute fFormatWidth michael@0: */ michael@0: void expandAffixAdjustWidth(const UnicodeString* pluralCount); michael@0: michael@0: michael@0: /** michael@0: * Do the work of formatting a number, either a double or a long. michael@0: * michael@0: * @param appendTo Output parameter to receive result. michael@0: * Result is appended to existing contents. michael@0: * @param handler Records information about field positions. michael@0: * @param digits the digits to be formatted. michael@0: * @param isInteger if TRUE format the digits as Integer. michael@0: * @return Reference to 'appendTo' parameter. michael@0: */ michael@0: UnicodeString& subformat(UnicodeString& appendTo, michael@0: FieldPositionHandler& handler, michael@0: DigitList& digits, michael@0: UBool isInteger, michael@0: UErrorCode &status) const; michael@0: michael@0: michael@0: void parse(const UnicodeString& text, michael@0: Formattable& result, michael@0: ParsePosition& pos, michael@0: UChar* currency) const; michael@0: michael@0: enum { michael@0: fgStatusInfinite, michael@0: fgStatusLength // Leave last in list. michael@0: } StatusFlags; michael@0: michael@0: UBool subparse(const UnicodeString& text, michael@0: const UnicodeString* negPrefix, michael@0: const UnicodeString* negSuffix, michael@0: const UnicodeString* posPrefix, michael@0: const UnicodeString* posSuffix, michael@0: UBool complexCurrencyParsing, michael@0: int8_t type, michael@0: ParsePosition& parsePosition, michael@0: DigitList& digits, UBool* status, michael@0: UChar* currency) const; michael@0: michael@0: // Mixed style parsing for currency. michael@0: // It parses against the current currency pattern michael@0: // using complex affix comparison michael@0: // parses against the currency plural patterns using complex affix comparison, michael@0: // and parses against the current pattern using simple affix comparison. michael@0: UBool parseForCurrency(const UnicodeString& text, michael@0: ParsePosition& parsePosition, michael@0: DigitList& digits, michael@0: UBool* status, michael@0: UChar* currency) const; michael@0: michael@0: int32_t skipPadding(const UnicodeString& text, int32_t position) const; michael@0: michael@0: int32_t compareAffix(const UnicodeString& input, michael@0: int32_t pos, michael@0: UBool isNegative, michael@0: UBool isPrefix, michael@0: const UnicodeString* affixPat, michael@0: UBool complexCurrencyParsing, michael@0: int8_t type, michael@0: UChar* currency) const; michael@0: michael@0: static UnicodeString& trimMarksFromAffix(const UnicodeString& affix, UnicodeString& trimmedAffix); michael@0: michael@0: UBool equalWithSignCompatibility(UChar32 lhs, UChar32 rhs) const; michael@0: michael@0: int32_t compareSimpleAffix(const UnicodeString& affix, michael@0: const UnicodeString& input, michael@0: int32_t pos, michael@0: UBool lenient) const; michael@0: michael@0: static int32_t skipPatternWhiteSpace(const UnicodeString& text, int32_t pos); michael@0: michael@0: static int32_t skipUWhiteSpace(const UnicodeString& text, int32_t pos); michael@0: michael@0: static int32_t skipUWhiteSpaceAndMarks(const UnicodeString& text, int32_t pos); michael@0: michael@0: static int32_t skipBidiMarks(const UnicodeString& text, int32_t pos); michael@0: michael@0: int32_t compareComplexAffix(const UnicodeString& affixPat, michael@0: const UnicodeString& input, michael@0: int32_t pos, michael@0: int8_t type, michael@0: UChar* currency) const; michael@0: michael@0: static int32_t match(const UnicodeString& text, int32_t pos, UChar32 ch); michael@0: michael@0: static int32_t match(const UnicodeString& text, int32_t pos, const UnicodeString& str); michael@0: michael@0: static UBool matchSymbol(const UnicodeString &text, int32_t position, int32_t length, const UnicodeString &symbol, michael@0: UnicodeSet *sset, UChar32 schar); michael@0: michael@0: static UBool matchDecimal(UChar32 symbolChar, michael@0: UBool sawDecimal, UChar32 sawDecimalChar, michael@0: const UnicodeSet *sset, UChar32 schar); michael@0: michael@0: static UBool matchGrouping(UChar32 groupingChar, michael@0: UBool sawGrouping, UChar32 sawGroupingChar, michael@0: const UnicodeSet *sset, michael@0: UChar32 decimalChar, const UnicodeSet *decimalSet, michael@0: UChar32 schar); michael@0: michael@0: /** michael@0: * Get a decimal format symbol. michael@0: * Returns a const reference to the symbol string. michael@0: * @internal michael@0: */ michael@0: inline const UnicodeString &getConstSymbol(DecimalFormatSymbols::ENumberFormatSymbol symbol) const; michael@0: michael@0: int32_t appendAffix(UnicodeString& buf, michael@0: double number, michael@0: FieldPositionHandler& handler, michael@0: UBool isNegative, michael@0: UBool isPrefix) const; michael@0: michael@0: /** michael@0: * Append an affix to the given UnicodeString, using quotes if michael@0: * there are special characters. Single quotes themselves must be michael@0: * escaped in either case. michael@0: */ michael@0: void appendAffixPattern(UnicodeString& appendTo, const UnicodeString& affix, michael@0: UBool localized) const; michael@0: michael@0: void appendAffixPattern(UnicodeString& appendTo, michael@0: const UnicodeString* affixPattern, michael@0: const UnicodeString& expAffix, UBool localized) const; michael@0: michael@0: void expandAffix(const UnicodeString& pattern, michael@0: UnicodeString& affix, michael@0: double number, michael@0: FieldPositionHandler& handler, michael@0: UBool doFormat, michael@0: const UnicodeString* pluralCount) const; michael@0: michael@0: void expandAffixes(const UnicodeString* pluralCount); michael@0: michael@0: void addPadding(UnicodeString& appendTo, michael@0: FieldPositionHandler& handler, michael@0: int32_t prefixLen, int32_t suffixLen) const; michael@0: michael@0: UBool isGroupingPosition(int32_t pos) const; michael@0: michael@0: void setCurrencyForSymbols(); michael@0: michael@0: // similar to setCurrency without re-compute the affixes for currency. michael@0: // If currency changes, the affix pattern for currency is not changed, michael@0: // but the affix will be changed. So, affixes need to be michael@0: // re-computed in setCurrency(), but not in setCurrencyInternally(). michael@0: virtual void setCurrencyInternally(const UChar* theCurrency, UErrorCode& ec); michael@0: michael@0: // set up currency affix patterns for mix parsing. michael@0: // The patterns saved here are the affix patterns of default currency michael@0: // pattern and the unique affix patterns of the plural currency patterns. michael@0: // Those patterns are used by parseForCurrency(). michael@0: void setupCurrencyAffixPatterns(UErrorCode& status); michael@0: michael@0: // set up the currency affixes used in currency plural formatting. michael@0: // It sets up both fAffixesForCurrency for currency pattern if the current michael@0: // pattern contains 3 currency signs, michael@0: // and it sets up fPluralAffixesForCurrency for currency plural patterns. michael@0: void setupCurrencyAffixes(const UnicodeString& pattern, michael@0: UBool setupForCurrentPattern, michael@0: UBool setupForPluralPattern, michael@0: UErrorCode& status); michael@0: michael@0: // hashtable operations michael@0: Hashtable* initHashForAffixPattern(UErrorCode& status); michael@0: Hashtable* initHashForAffix(UErrorCode& status); michael@0: michael@0: void deleteHashForAffixPattern(); michael@0: void deleteHashForAffix(Hashtable*& table); michael@0: michael@0: void copyHashForAffixPattern(const Hashtable* source, michael@0: Hashtable* target, UErrorCode& status); michael@0: void copyHashForAffix(const Hashtable* source, michael@0: Hashtable* target, UErrorCode& status); michael@0: michael@0: UnicodeString& _format(int64_t number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionHandler& handler, michael@0: UErrorCode &status) const; michael@0: UnicodeString& _format(double number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionHandler& handler, michael@0: UErrorCode &status) const; michael@0: UnicodeString& _format(const DigitList &number, michael@0: UnicodeString& appendTo, michael@0: FieldPositionHandler& handler, michael@0: UErrorCode &status) const; michael@0: michael@0: // currency sign count michael@0: enum { michael@0: fgCurrencySignCountZero, michael@0: fgCurrencySignCountInSymbolFormat, michael@0: fgCurrencySignCountInISOFormat, michael@0: fgCurrencySignCountInPluralFormat michael@0: } CurrencySignCount; michael@0: michael@0: /** michael@0: * Constants. michael@0: */ michael@0: michael@0: UnicodeString fPositivePrefix; michael@0: UnicodeString fPositiveSuffix; michael@0: UnicodeString fNegativePrefix; michael@0: UnicodeString fNegativeSuffix; michael@0: UnicodeString* fPosPrefixPattern; michael@0: UnicodeString* fPosSuffixPattern; michael@0: UnicodeString* fNegPrefixPattern; michael@0: UnicodeString* fNegSuffixPattern; michael@0: michael@0: /** michael@0: * Formatter for ChoiceFormat-based currency names. If this field michael@0: * is not null, then delegate to it to format currency symbols. michael@0: * @since ICU 2.6 michael@0: */ michael@0: ChoiceFormat* fCurrencyChoice; michael@0: michael@0: DigitList * fMultiplier; // NULL for multiplier of one michael@0: int32_t fScale; michael@0: int32_t fGroupingSize; michael@0: int32_t fGroupingSize2; michael@0: UBool fDecimalSeparatorAlwaysShown; michael@0: DecimalFormatSymbols* fSymbols; michael@0: michael@0: UBool fUseSignificantDigits; michael@0: int32_t fMinSignificantDigits; michael@0: int32_t fMaxSignificantDigits; michael@0: michael@0: UBool fUseExponentialNotation; michael@0: int8_t fMinExponentDigits; michael@0: UBool fExponentSignAlwaysShown; michael@0: michael@0: EnumSet michael@0: fBoolFlags; michael@0: michael@0: DigitList* fRoundingIncrement; // NULL if no rounding increment specified. michael@0: ERoundingMode fRoundingMode; michael@0: michael@0: UChar32 fPad; michael@0: int32_t fFormatWidth; michael@0: EPadPosition fPadPosition; michael@0: michael@0: /* michael@0: * Following are used for currency format michael@0: */ michael@0: // pattern used in this formatter michael@0: UnicodeString fFormatPattern; michael@0: // style is only valid when decimal formatter is constructed by michael@0: // DecimalFormat(pattern, decimalFormatSymbol, style) michael@0: int fStyle; michael@0: /* michael@0: * Represents whether this is a currency format, and which michael@0: * currency format style. michael@0: * 0: not currency format type; michael@0: * 1: currency style -- symbol name, such as "$" for US dollar. michael@0: * 2: currency style -- ISO name, such as USD for US dollar. michael@0: * 3: currency style -- plural long name, such as "US Dollar" for michael@0: * "1.00 US Dollar", or "US Dollars" for michael@0: * "3.00 US Dollars". michael@0: */ michael@0: int fCurrencySignCount; michael@0: michael@0: michael@0: /* For currency parsing purose, michael@0: * Need to remember all prefix patterns and suffix patterns of michael@0: * every currency format pattern, michael@0: * including the pattern of default currecny style michael@0: * and plural currency style. And the patterns are set through applyPattern. michael@0: */ michael@0: // TODO: innerclass? michael@0: /* This is not needed in the class declaration, so it is moved into decimfmp.cpp michael@0: struct AffixPatternsForCurrency : public UMemory { michael@0: // negative prefix pattern michael@0: UnicodeString negPrefixPatternForCurrency; michael@0: // negative suffix pattern michael@0: UnicodeString negSuffixPatternForCurrency; michael@0: // positive prefix pattern michael@0: UnicodeString posPrefixPatternForCurrency; michael@0: // positive suffix pattern michael@0: UnicodeString posSuffixPatternForCurrency; michael@0: int8_t patternType; michael@0: michael@0: AffixPatternsForCurrency(const UnicodeString& negPrefix, michael@0: const UnicodeString& negSuffix, michael@0: const UnicodeString& posPrefix, michael@0: const UnicodeString& posSuffix, michael@0: int8_t type) { michael@0: negPrefixPatternForCurrency = negPrefix; michael@0: negSuffixPatternForCurrency = negSuffix; michael@0: posPrefixPatternForCurrency = posPrefix; michael@0: posSuffixPatternForCurrency = posSuffix; michael@0: patternType = type; michael@0: } michael@0: }; michael@0: */ michael@0: michael@0: /* affix for currency formatting when the currency sign in the pattern michael@0: * equals to 3, such as the pattern contains 3 currency sign or michael@0: * the formatter style is currency plural format style. michael@0: */ michael@0: /* This is not needed in the class declaration, so it is moved into decimfmp.cpp michael@0: struct AffixesForCurrency : public UMemory { michael@0: // negative prefix michael@0: UnicodeString negPrefixForCurrency; michael@0: // negative suffix michael@0: UnicodeString negSuffixForCurrency; michael@0: // positive prefix michael@0: UnicodeString posPrefixForCurrency; michael@0: // positive suffix michael@0: UnicodeString posSuffixForCurrency; michael@0: michael@0: int32_t formatWidth; michael@0: michael@0: AffixesForCurrency(const UnicodeString& negPrefix, michael@0: const UnicodeString& negSuffix, michael@0: const UnicodeString& posPrefix, michael@0: const UnicodeString& posSuffix) { michael@0: negPrefixForCurrency = negPrefix; michael@0: negSuffixForCurrency = negSuffix; michael@0: posPrefixForCurrency = posPrefix; michael@0: posSuffixForCurrency = posSuffix; michael@0: } michael@0: }; michael@0: */ michael@0: michael@0: // Affix pattern set for currency. michael@0: // It is a set of AffixPatternsForCurrency, michael@0: // each element of the set saves the negative prefix pattern, michael@0: // negative suffix pattern, positive prefix pattern, michael@0: // and positive suffix pattern of a pattern. michael@0: // It is used for currency mixed style parsing. michael@0: // It is actually is a set. michael@0: // The set contains the default currency pattern from the locale, michael@0: // and the currency plural patterns. michael@0: // Since it is a set, it does not contain duplicated items. michael@0: // For example, if 2 currency plural patterns are the same, only one pattern michael@0: // is included in the set. When parsing, we do not check whether the plural michael@0: // count match or not. michael@0: Hashtable* fAffixPatternsForCurrency; michael@0: michael@0: // Following 2 are affixes for currency. michael@0: // It is a hash map from plural count to AffixesForCurrency. michael@0: // AffixesForCurrency saves the negative prefix, michael@0: // negative suffix, positive prefix, and positive suffix of a pattern. michael@0: // It is used during currency formatting only when the currency sign count michael@0: // is 3. In which case, the affixes are getting from here, not michael@0: // from the fNegativePrefix etc. michael@0: Hashtable* fAffixesForCurrency; // for current pattern michael@0: Hashtable* fPluralAffixesForCurrency; // for plural pattern michael@0: michael@0: // Information needed for DecimalFormat to format/parse currency plural. michael@0: CurrencyPluralInfo* fCurrencyPluralInfo; michael@0: michael@0: #if UCONFIG_HAVE_PARSEALLINPUT michael@0: UNumberFormatAttributeValue fParseAllInput; michael@0: #endif michael@0: michael@0: // Decimal Format Static Sets singleton. michael@0: const DecimalFormatStaticSets *fStaticSets; michael@0: michael@0: michael@0: protected: michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Rounds a value according to the rules of this object. michael@0: * @internal michael@0: */ michael@0: DigitList& _round(const DigitList& number, DigitList& adjustedNum, UBool& isNegative, UErrorCode& status) const; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * Returns the currency in effect for this formatter. Subclasses michael@0: * should override this method as needed. Unlike getCurrency(), michael@0: * this method should never return "". michael@0: * @result output parameter for null-terminated result, which must michael@0: * have a capacity of at least 4 michael@0: * @internal michael@0: */ michael@0: virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const; michael@0: michael@0: /** number of integer digits michael@0: * @stable ICU 2.4 michael@0: */ michael@0: static const int32_t kDoubleIntegerDigits; michael@0: /** number of fraction digits michael@0: * @stable ICU 2.4 michael@0: */ michael@0: static const int32_t kDoubleFractionDigits; michael@0: michael@0: /** michael@0: * When someone turns on scientific mode, we assume that more than this michael@0: * number of digits is due to flipping from some other mode that didn't michael@0: * restrict the maximum, and so we force 1 integer digit. We don't bother michael@0: * to track and see if someone is using exponential notation with more than michael@0: * this number, it wouldn't make sense anyway, and this is just to make sure michael@0: * that someone turning on scientific mode with default settings doesn't michael@0: * end up with lots of zeroes. michael@0: * @stable ICU 2.8 michael@0: */ michael@0: static const int32_t kMaxScientificIntegerDigits; michael@0: michael@0: #if UCONFIG_FORMAT_FASTPATHS_49 michael@0: private: michael@0: /** michael@0: * Internal state. michael@0: * @internal michael@0: */ michael@0: uint8_t fReserved[UNUM_DECIMALFORMAT_INTERNAL_SIZE]; michael@0: michael@0: michael@0: /** michael@0: * Called whenever any state changes. Recomputes whether fastpath is OK to use. michael@0: */ michael@0: void handleChanged(); michael@0: #endif michael@0: }; michael@0: michael@0: inline const UnicodeString & michael@0: DecimalFormat::getConstSymbol(DecimalFormatSymbols::ENumberFormatSymbol symbol) const { michael@0: return fSymbols->getConstSymbol(symbol); michael@0: } michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */ michael@0: michael@0: #endif // _DECIMFMT michael@0: //eof

Symbol michael@0: *	Location michael@0: *	Localized? michael@0: *	Meaning michael@0: *
`0` michael@0: *	Number michael@0: *	Yes michael@0: *	Digit michael@0: *
`1-9` michael@0: *	Number michael@0: *	Yes michael@0: *	'1' through '9' indicate rounding. michael@0: *
`\htmlonly@\endhtmlonly` michael@0: *	Number michael@0: *	No michael@0: *	Significant digit michael@0: *
`#` michael@0: *	Number michael@0: *	Yes michael@0: *	Digit, zero shows as absent michael@0: *
`.` michael@0: *	Number michael@0: *	Yes michael@0: *	Decimal separator or monetary decimal separator michael@0: *
`-` michael@0: *	Number michael@0: *	Yes michael@0: *	Minus sign michael@0: *
`,` michael@0: *	Number michael@0: *	Yes michael@0: *	Grouping separator michael@0: *
`E` michael@0: *	Number michael@0: *	Yes michael@0: *	Separates mantissa and exponent in scientific notation. michael@0: * Need not be quoted in prefix or suffix. michael@0: *
`+` michael@0: *	Exponent michael@0: *	Yes michael@0: *	Prefix positive exponents with localized plus sign. michael@0: * Need not be quoted in prefix or suffix. michael@0: *
`;` michael@0: *	Subpattern boundary michael@0: *	Yes michael@0: *	Separates positive and negative subpatterns michael@0: *
`\%` michael@0: *	Prefix or suffix michael@0: *	Yes michael@0: *	Multiply by 100 and show as percentage michael@0: *
`\\u2030` michael@0: *	Prefix or suffix michael@0: *	Yes michael@0: *	Multiply by 1000 and show as per mille michael@0: *
`\htmlonly¤\endhtmlonly` (`\\u00A4`) michael@0: *	Prefix or suffix michael@0: *	No michael@0: *	Currency sign, replaced by currency symbol. If michael@0: * doubled, replaced by international currency symbol. michael@0: * If tripled, replaced by currency plural names, for example, michael@0: * "US dollar" or "US dollars" for America. michael@0: * If present in a pattern, the monetary decimal separator michael@0: * is used instead of the decimal separator. michael@0: *
`'` michael@0: *	Prefix or suffix michael@0: *	No michael@0: *	Used to quote special characters in a prefix or suffix, michael@0: * for example, `"'#'#"` formats 123 to michael@0: * `"#123"`. To create a single quote michael@0: * itself, use two in a row: `"# o''clock"`. michael@0: *
`` michael@0:	Prefix or suffix boundary michael@0: *	Yes michael@0: *	Pad escape, precedes pad character michael@0: *