X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/729e4ab9bc6618bc3d8a898e575df7f4019e29ca..HEAD:/icuSources/i18n/unicode/numfmt.h diff --git a/icuSources/i18n/unicode/numfmt.h b/icuSources/i18n/unicode/numfmt.h index 222fde1e..b770245c 100644 --- a/icuSources/i18n/unicode/numfmt.h +++ b/icuSources/i18n/unicode/numfmt.h @@ -1,6 +1,8 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************** -* Copyright (C) 1997-2010, International Business Machines Corporation and others. +* Copyright (C) 1997-2016, International Business Machines Corporation and others. * All Rights Reserved. ******************************************************************************** * @@ -24,9 +26,11 @@ #include "unicode/utypes.h" +#if U_SHOW_CPLUSPLUS_API + /** * \file - * \brief C++ API: Abstract base class for all number formats. + * \brief C++ API: Compatibility APIs for number formatting. */ #if !UCONFIG_NO_FORMATTING @@ -36,20 +40,31 @@ #include "unicode/unum.h" // UNumberFormatStyle #include "unicode/locid.h" #include "unicode/stringpiece.h" +#include "unicode/curramt.h" +#include "unicode/udisplaycontext.h" + +class NumberFormatTest; U_NAMESPACE_BEGIN +class SharedNumberFormat; + #if !UCONFIG_NO_SERVICE class NumberFormatFactory; class StringEnumeration; #endif /** + * <p><strong>IMPORTANT:</strong> New users are strongly encouraged to see if + * numberformatter.h fits their use case. Although not deprecated, this header + * is provided for backwards compatibility only. * * Abstract base class for all number formats. Provides interface for * formatting and parsing a number. Also provides methods for * determining which locales have number formats, and what their names * are. + * + * \headerfile unicode/numfmt.h "unicode/numfmt.h" * <P> * NumberFormat helps you to format and parse numbers for any locale. * Your code can be completely independent of the locale conventions @@ -58,82 +73,79 @@ class StringEnumeration; * <P> * To format a number for the current Locale, use one of the static * factory methods: - * <pre> * \code - * double myNumber = 7.0; - * UnicodeString myString; - * UErrorCode success = U_ZERO_ERROR; - * NumberFormat* nf = NumberFormat::createInstance(success) - * nf->format(myNumber, myString); - * cout << " Example 1: " << myString << endl; + * #include <iostream> + * #include "unicode/numfmt.h" + * #include "unicode/unistr.h" + * #include "unicode/ustream.h" + * using namespace std; + * + * int main() { + * double myNumber = 7.0; + * UnicodeString myString; + * UErrorCode success = U_ZERO_ERROR; + * NumberFormat* nf = NumberFormat::createInstance(success); + * nf->format(myNumber, myString); + * cout << " Example 1: " << myString << endl; + * } * \endcode - * </pre> + * Note that there are additional factory methods within subclasses of + * NumberFormat. + * <P> * If you are formatting multiple numbers, it is more efficient to get * the format and use it multiple times so that the system doesn't * have to fetch the information about the local language and country * conventions multiple times. - * <pre> * \code * UnicodeString myString; * UErrorCode success = U_ZERO_ERROR; - * nf = NumberFormat::createInstance( success ); - * int32_t a[] = { 123, 3333, -1234567 }; - * const int32_t a_len = sizeof(a) / sizeof(a[0]); - * myString.remove(); - * for (int32_t i = 0; i < a_len; i++) { - * nf->format(a[i], myString); - * myString += " ; "; + * NumberFormat *nf = NumberFormat::createInstance( success ); + * for (int32_t number: {123, 3333, -1234567}) { + * nf->format(number, myString); + * myString += "; "; * } * cout << " Example 2: " << myString << endl; * \endcode - * </pre> * To format a number for a different Locale, specify it in the - * call to createInstance(). - * <pre> + * call to \c createInstance(). * \code - * nf = NumberFormat::createInstance( Locale::FRENCH, success ); + * nf = NumberFormat::createInstance(Locale::getFrench(), success); * \endcode - * </pre> - * You can use a NumberFormat to parse also. - * <pre> + * You can use a \c NumberFormat to parse also. * \code * UErrorCode success; * Formattable result(-999); // initialized with error code * nf->parse(myString, result, success); * \endcode - * </pre> - * Use createInstance to get the normal number format for that country. - * There are other static factory methods available. Use getCurrency - * to get the currency number format for that country. Use getPercent + * Use \c createInstance() to get the normal number format for a \c Locale. + * There are other static factory methods available. Use \c createCurrencyInstance() + * to get the currency number format for that country. Use \c createPercentInstance() * to get a format for displaying percentages. With this format, a * fraction from 0.53 is displayed as 53%. * <P> - * Starting from ICU 4.2, you can use createInstance() by passing in a 'style' - * as parameter to get the correct instance. - * For example, - * use createInstance(...kNumberStyle...) to get the normal number format, - * createInstance(...kPercentStyle...) to get a format for displaying - * percentage, - * createInstance(...kScientificStyle...) to get a format for displaying - * scientific number, - * createInstance(...kCurrencyStyle...) to get the currency number format, - * in which the currency is represented by its symbol, for example, "$3.00". - * createInstance(...kIsoCurrencyStyle...) to get the currency number format, - * in which the currency is represented by its ISO code, for example "USD3.00". - * createInstance(...kPluralCurrencyStyle...) to get the currency number format, + * The type of number formatting can be specified by passing a 'style' parameter to \c createInstance(). + * For example, use\n + * \c createInstance(locale, UNUM_DECIMAL, errorCode) to get the normal number format,\n + * \c createInstance(locale, UNUM_PERCENT, errorCode) to get a format for displaying percentage,\n + * \c createInstance(locale, UNUM_SCIENTIFIC, errorCode) to get a format for displaying scientific number,\n + * \c createInstance(locale, UNUM_CURRENCY, errorCode) to get the currency number format, + * in which the currency is represented by its symbol, for example, "$3.00".\n + * \c createInstance(locale, UNUM_CURRENCY_ISO, errorCode) to get the currency number format, + * in which the currency is represented by its ISO code, for example "USD3.00".\n + * \c createInstance(locale, UNUM_CURRENCY_PLURAL, errorCode) to get the currency number format, * in which the currency is represented by its full name in plural format, * for example, "3.00 US dollars" or "1.00 US dollar". * <P> * You can also control the display of numbers with such methods as - * getMinimumFractionDigits. If you want even more control over the + * \c getMinimumFractionDigits(). If you want even more control over the * format or parsing, or want to give your users more control, you can - * try casting the NumberFormat you get from the factory methods to a - * DecimalNumberFormat. This will work for the vast majority of - * countries; just remember to put it in a try block in case you + * try dynamic_casting the \c NumberFormat you get from the factory methods to a + * \c DecimalFormat. This will work for the vast majority of + * countries; just remember to test for NULL in case you * encounter an unusual one. * <P> * You can also use forms of the parse and format methods with - * ParsePosition and FieldPosition to allow you to: + * \c ParsePosition and \c FieldPosition to allow you to: * <ul type=round> * <li>(a) progressively parse through pieces of a string. * <li>(b) align the decimal point and other areas. @@ -141,8 +153,8 @@ class StringEnumeration; * For example, you can align numbers in two ways. * <P> * If you are using a monospaced font with spacing for alignment, you - * can pass the FieldPosition in your format call, with field = - * INTEGER_FIELD. On output, getEndIndex will be set to the offset + * can pass the \c FieldPosition in your format call, with field = + * \c UNUM_INTEGER_FIELD. On output, \c getEndIndex will be set to the offset * between the last character of the integer and the decimal. Add * (desiredSpaceCount - getEndIndex) spaces at the front of the * string. @@ -162,28 +174,31 @@ class StringEnumeration; */ class U_I18N_API NumberFormat : public Format { public: - /** - * Constants for various number format styles. - * kNumberStyle specifies a normal number style of format. - * kCurrencyStyle specifies a currency format using currency symbol name, - * such as in "$1.00". - * kPercentStyle specifies a style of format to display percent. - * kScientificStyle specifies a style of format to display scientific number. - * kISOCurrencyStyle specifies a currency format using ISO currency code, - * such as in "USD1.00". - * kPluralCurrencyStyle specifies a currency format using currency plural - * names, such as in "1.00 US dollar" and "3.00 US dollars". - * @draft ICU 4.2 - */ - enum EStyles { - kNumberStyle, - kCurrencyStyle, - kPercentStyle, - kScientificStyle, - kIsoCurrencyStyle, - kPluralCurrencyStyle, - kStyleCount // ALWAYS LAST ENUM: number of styles + * Rounding mode. + * + * <p> + * For more detail on rounding modes, see: + * http://userguide.icu-project.org/formatparse/numbers/rounding-modes + * + * @stable ICU 2.4 + */ + enum ERoundingMode { + kRoundCeiling, /**< Round towards positive infinity */ + kRoundFloor, /**< Round towards negative infinity */ + kRoundDown, /**< Round towards zero */ + kRoundUp, /**< Round away from zero */ + kRoundHalfEven, /**< Round towards the nearest integer, or + towards the nearest even integer if equidistant */ + kRoundHalfDown, /**< Round towards the nearest integer, or + towards zero if equidistant */ + kRoundHalfUp, /**< Round towards the nearest integer, or + away from zero if equidistant */ + /** + * Return U_FORMAT_INEXACT_ERROR if number does not format exactly. + * @stable ICU 4.8 + */ + kRoundUnnecessary }; /** @@ -195,29 +210,50 @@ public: * support identification of all number format fields, not just those * pertaining to alignment. * + * These constants are provided for backwards compatibility only. + * Please use the C style constants defined in the header file unum.h. + * * @see FieldPosition * @stable ICU 2.0 */ enum EAlignmentFields { - kIntegerField, - kFractionField, - kDecimalSeparatorField, - kExponentSymbolField, - kExponentSignField, - kExponentField, - kGroupingSeparatorField, - kCurrencyField, - kPercentField, - kPermillField, - kSignField, + /** @stable ICU 2.0 */ + kIntegerField = UNUM_INTEGER_FIELD, + /** @stable ICU 2.0 */ + kFractionField = UNUM_FRACTION_FIELD, + /** @stable ICU 2.0 */ + kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD, + /** @stable ICU 2.0 */ + kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD, + /** @stable ICU 2.0 */ + kExponentSignField = UNUM_EXPONENT_SIGN_FIELD, + /** @stable ICU 2.0 */ + kExponentField = UNUM_EXPONENT_FIELD, + /** @stable ICU 2.0 */ + kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD, + /** @stable ICU 2.0 */ + kCurrencyField = UNUM_CURRENCY_FIELD, + /** @stable ICU 2.0 */ + kPercentField = UNUM_PERCENT_FIELD, + /** @stable ICU 2.0 */ + kPermillField = UNUM_PERMILL_FIELD, + /** @stable ICU 2.0 */ + kSignField = UNUM_SIGN_FIELD, +#ifndef U_HIDE_DRAFT_API + /** @draft ICU 64 */ + kMeasureUnitField = UNUM_MEASURE_UNIT_FIELD, + /** @draft ICU 64 */ + kCompactField = UNUM_COMPACT_FIELD, +#endif // U_HIDE_DRAFT_API /** * These constants are provided for backwards compatibility only. - * Please use the C++ style constants defined above. - * @stable ICU 2.0 + * Please use the constants defined in the header file unum.h. */ - INTEGER_FIELD = kIntegerField, - FRACTION_FIELD = kFractionField + /** @stable ICU 2.0 */ + INTEGER_FIELD = UNUM_INTEGER_FIELD, + /** @stable ICU 2.0 */ + FRACTION_FIELD = UNUM_FRACTION_FIELD }; /** @@ -226,6 +262,14 @@ public: */ virtual ~NumberFormat(); + /** + * Clones this object polymorphically. + * The caller owns the result and should delete it when done. + * @return clone, or nullptr if an error occurred + * @stable ICU 2.0 + */ + virtual NumberFormat* clone() const = 0; + /** * Return true if the given Format objects are semantically equal. * Objects of different subclasses are considered unequal. @@ -271,7 +315,7 @@ public: * NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. - * @stable 4.4 + * @stable ICU 4.4 */ virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo, @@ -364,6 +408,24 @@ public: virtual UnicodeString& format(double number, UnicodeString& appendTo, FieldPosition& pos) const = 0; + /** + * Format a double number. By default, the parent function simply + * calls the base class and does not return an error status. + * Therefore, the status may be ignored in some subclasses. + * + * @param number The value to be formatted. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param pos On input: an alignment field, if desired. + * On output: the offsets of the alignment field. + * @param status error status + * @return Reference to 'appendTo' parameter. + * @internal + */ + virtual UnicodeString& format(double number, + UnicodeString& appendTo, + FieldPosition& pos, + UErrorCode &status) const; /** * Format a double number. Subclasses must implement * this method. @@ -376,7 +438,7 @@ public: * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. - * @stable 4.4 + * @stable ICU 4.4 */ virtual UnicodeString& format(double number, UnicodeString& appendTo, @@ -398,6 +460,24 @@ public: UnicodeString& appendTo, FieldPosition& pos) const = 0; + /** + * Format a long number. Concrete subclasses may override + * this function to provide status return. + * + * @param number The value to be formatted. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param pos On input: an alignment field, if desired. + * On output: the offsets of the alignment field. + * @param status the output status. + * @return Reference to 'appendTo' parameter. + * @internal + */ + virtual UnicodeString& format(int32_t number, + UnicodeString& appendTo, + FieldPosition& pos, + UErrorCode &status) const; + /** * Format an int32 number. Subclasses must implement * this method. @@ -410,7 +490,7 @@ public: * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. - * @stable 4.4 + * @stable ICU 4.4 */ virtual UnicodeString& format(int32_t number, UnicodeString& appendTo, @@ -432,6 +512,25 @@ public: virtual UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPosition& pos) const; + + /** + * Format an int64 number. (Not abstract to retain compatibility + * with earlier releases, however subclasses should override this + * method as it just delegates to format(int32_t number...); + * + * @param number The value to be formatted. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param pos On input: an alignment field, if desired. + * On output: the offsets of the alignment field. + * @param status Output param filled with success/failure status. + * @return Reference to 'appendTo' parameter. + * @internal + */ + virtual UnicodeString& format(int64_t number, + UnicodeString& appendTo, + FieldPosition& pos, + UErrorCode& status) const; /** * Format an int64 number. Subclasses must implement * this method. @@ -444,7 +543,7 @@ public: * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. - * @stable 4.4 + * @stable ICU 4.4 */ virtual UnicodeString& format(int64_t number, UnicodeString& appendTo, @@ -465,22 +564,24 @@ public: * Can be NULL. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. - * @stable 4.4 + * @stable ICU 4.4 */ - virtual UnicodeString& format(const StringPiece &number, + virtual UnicodeString& format(StringPiece number, UnicodeString& appendTo, FieldPositionIterator* posIter, UErrorCode& status) const; -public: + +// Can't use #ifndef U_HIDE_INTERNAL_API because these are virtual methods + /** - * Format a decimal number. - * The number is a DigitList wrapper onto a floating point decimal number. + * Format a decimal number. + * The number is a DecimalQuantity wrapper onto a floating point decimal number. * The default implementation in NumberFormat converts the decimal number * to a double and formats that. Subclasses of NumberFormat that want * to specifically handle big decimal numbers must override this method. * class DecimalFormat does so. * - * @param number The number, a DigitList format Decimal Floating Point. + * @param number The number, a DecimalQuantity format Decimal Floating Point. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param posIter On return, can be used to iterate over positions @@ -489,20 +590,20 @@ public: * @return Reference to 'appendTo' parameter. * @internal */ - virtual UnicodeString& format(const DigitList &number, + virtual UnicodeString& format(const number::impl::DecimalQuantity &number, UnicodeString& appendTo, FieldPositionIterator* posIter, UErrorCode& status) const; /** - * Format a decimal number. - * The number is a DigitList wrapper onto a floating point decimal number. + * Format a decimal number. + * The number is a DecimalQuantity wrapper onto a floating point decimal number. * The default implementation in NumberFormat converts the decimal number * to a double and formats that. Subclasses of NumberFormat that want * to specifically handle big decimal numbers must override this method. * class DecimalFormat does so. * - * @param number The number, a DigitList format Decimal Floating Point. + * @param number The number, a DecimalQuantity format Decimal Floating Point. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param pos On input: an alignment field, if desired. @@ -511,27 +612,11 @@ public: * @return Reference to 'appendTo' parameter. * @internal */ - virtual UnicodeString& format(const DigitList &number, + virtual UnicodeString& format(const number::impl::DecimalQuantity &number, UnicodeString& appendTo, FieldPosition& pos, UErrorCode& status) const; -public: - - /** - * Redeclared Format method. - * @param obj The object to be formatted. - * @param appendTo Output parameter to receive result. - * Result is appended to existing contents. - * @param status Output parameter set to a failure error code - * when a failure occurs. - * @return Reference to 'appendTo' parameter. - * @stable ICU 2.0 - */ - UnicodeString& format(const Formattable& obj, - UnicodeString& appendTo, - UErrorCode& status) const; - /** * Return a long if possible (e.g. within range LONG_MAX, * LONG_MAX], and with no decimals), otherwise a double. If @@ -549,8 +634,6 @@ public: * @param parsePosition The position to start parsing at on input. * On output, moved to after the last successfully * parse character. On parse failure, does not change. - * @return A Formattable object of numeric type. The caller - * owns this an must delete it. NULL on failure. * @stable ICU 2.0 */ virtual void parse(const UnicodeString& text, @@ -566,15 +649,15 @@ public: * @param result Formattable to be set to the parse result. * If parse fails, return contents are undefined. * @param status Output parameter set to a failure error code - * when a failure occurs. - * @return A Formattable object of numeric type. The caller - * owns this an must delete it. NULL on failure. + * when a failure occurs. The error code when the + * string fails to parse is U_INVALID_FORMAT_ERROR, + * unless overridden by a subclass. * @see NumberFormat::isParseIntegerOnly * @stable ICU 2.0 */ - virtual void parse( const UnicodeString& text, - Formattable& result, - UErrorCode& status) const; + virtual void parse(const UnicodeString& text, + Formattable& result, + UErrorCode& status) const; /** * Parses text from the given string as a currency amount. Unlike @@ -586,18 +669,17 @@ public: * (U+00A4) in its prefix or suffix. * * @param text the string to parse - * @param result output parameter to receive result. This will have - * its currency set to the parsed ISO currency code. - * @param pos input-output position; on input, the position within - * text to match; must have 0 <= pos.getIndex() < text.length(); - * on output, the position after the last matched character. If - * the parse fails, the position in unchanged upon output. - * @return a reference to result - * @internal + * @param pos input-output position; on input, the position within text + * to match; must have 0 <= pos.getIndex() < text.length(); + * on output, the position after the last matched character. + * If the parse fails, the position in unchanged upon output. + * @return if parse succeeds, a pointer to a newly-created CurrencyAmount + * object (owned by the caller) containing information about + * the parsed currency; if parse fails, this is NULL. + * @stable ICU 49 */ - virtual Formattable& parseCurrency(const UnicodeString& text, - Formattable& result, - ParsePosition& pos) const; + virtual CurrencyAmount* parseCurrency(const UnicodeString& text, + ParsePosition& pos) const; /** * Return true if this format will parse numbers as integers @@ -622,63 +704,99 @@ public: virtual void setParseIntegerOnly(UBool value); /** - * Return whether or not strict parsing is in effect. + * Sets whether lenient parsing should be enabled (it is off by default). * - * @return <code>TRUE</code> if strict parsing is in effect, - * <code>FALSE</code> otherwise. - * @internal + * @param enable \c TRUE if lenient parsing should be used, + * \c FALSE otherwise. + * @stable ICU 4.8 */ - UBool isParseStrict(void) const; + virtual void setLenient(UBool enable); /** - * Set whether or not strict parsing should be used. + * Returns whether lenient parsing is enabled (it is off by default). * - * @param value <code>TRUE</code> if strict parsing should be used, - * <code>FALSE</code> otherwise. - * @internal + * @return \c TRUE if lenient parsing is enabled, + * \c FALSE otherwise. + * @see #setLenient + * @stable ICU 4.8 */ - virtual void setParseStrict(UBool value); + virtual UBool isLenient(void) const; /** - * Returns the default number format for the current default - * locale. The default format is one of the styles provided by - * the other factory methods: getNumberInstance, - * getCurrencyInstance or getPercentInstance. Exactly which one - * is locale dependant. + * Create a default style NumberFormat for the current default locale. + * The default formatting style is locale dependent. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createInstance(UErrorCode&); /** - * Returns the default number format for the specified locale. - * The default format is one of the styles provided by the other - * factory methods: getNumberInstance, getCurrencyInstance or - * getPercentInstance. Exactly which one is locale dependant. + * Create a default style NumberFormat for the specified locale. + * The default formatting style is locale dependent. * @param inLocale the given locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale, UErrorCode&); /** - * Creates the specified decimal format style of the desired locale. + * Create a specific style NumberFormat for the specified locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param desiredLocale the given locale. - * @param choice the given style. - * @param success Output param filled with success/failure status. + * @param style the given style. + * @param errorCode Output param filled with success/failure status. * @return A new NumberFormat instance. - * @draft ICU 4.2 + * @stable ICU 4.8 + */ + static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale, + UNumberFormatStyle style, + UErrorCode& errorCode); + +#ifndef U_HIDE_INTERNAL_API + + /** + * ICU use only. + * Creates NumberFormat instance without using the cache. + * @internal + */ + static NumberFormat* internalCreateInstance( + const Locale& desiredLocale, + UNumberFormatStyle style, + UErrorCode& errorCode); + + /** + * ICU use only. + * Returns handle to the shared, cached NumberFormat instance for given + * locale. On success, caller must call removeRef() on returned value + * once it is done with the shared instance. + * @internal */ - static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success); + static const SharedNumberFormat* U_EXPORT2 createSharedInstance( + const Locale& inLocale, UNumberFormatStyle style, UErrorCode& status); +#endif /* U_HIDE_INTERNAL_API */ /** * Returns a currency format for the current default locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&); /** * Returns a currency format for the specified locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -687,12 +805,18 @@ public: /** * Returns a percentage format for the current default locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&); /** * Returns a percentage format for the specified locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -701,12 +825,18 @@ public: /** * Returns a scientific format for the current default locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&); /** * Returns a scientific format for the specified locale. + * <p> + * <strong>NOTE:</strong> New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -723,6 +853,9 @@ public: #if !UCONFIG_NO_SERVICE /** * Register a new NumberFormatFactory. The factory will be adopted. + * Because ICU may choose to cache NumberFormat objects internally, + * this must be called at application startup, prior to any calls to + * NumberFormat::createInstance to avoid undefined behavior. * @param toAdopt the NumberFormatFactory instance to be adopted * @param status the in/out status code, no special meanings are assigned * @return a registry key that can be used to unregister this factory @@ -734,6 +867,9 @@ public: * Unregister a previously-registered NumberFormatFactory using the key returned from the * register call. Key becomes invalid after a successful call and should not be used again. * The NumberFormatFactory corresponding to the key will be deleted. + * Because ICU may choose to cache NumberFormat objects internally, + * this should be called during application shutdown, after all calls to + * NumberFormat::createInstance to avoid undefined behavior. * @param key the registry key returned by a previous call to registerFactory * @param status the in/out status code, no special meanings are assigned * @return TRUE if the factory for the key was successfully unregistered @@ -754,7 +890,7 @@ public: * Returns true if grouping is used in this format. For example, * in the English locale, with grouping on, the number 1234567 * might be formatted as "1,234,567". The grouping separator as - * well as the size of each group is locale dependant and is + * well as the size of each group is locale dependent and is * determined by sub-classes of NumberFormat. * @see setGroupingUsed * @stable ICU 2.0 @@ -871,7 +1007,7 @@ public: * @param ec input-output error code * @stable ICU 3.0 */ - virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec); + virtual void setCurrency(const char16_t* theCurrency, UErrorCode& ec); /** * Gets the currency used to display currency @@ -880,7 +1016,55 @@ public: * the currency in use, or a pointer to the empty string. * @stable ICU 2.6 */ - const UChar* getCurrency() const; + const char16_t* getCurrency() const; + + /** + * Set a particular UDisplayContext value in the formatter, such as + * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. + * @param value The UDisplayContext value to set. + * @param status Input/output status. If at entry this indicates a failure + * status, the function will do nothing; otherwise this will be + * updated with any new status from the function. + * @stable ICU 53 + */ + virtual void setContext(UDisplayContext value, UErrorCode& status); + + /** + * Get the formatter's UDisplayContext value for the specified UDisplayContextType, + * such as UDISPCTX_TYPE_CAPITALIZATION. + * @param type The UDisplayContextType whose value to return + * @param status Input/output status. If at entry this indicates a failure + * status, the function will do nothing; otherwise this will be + * updated with any new status from the function. + * @return The UDisplayContextValue for the specified type. + * @stable ICU 53 + */ + virtual UDisplayContext getContext(UDisplayContextType type, UErrorCode& status) const; + + /** + * Get the rounding mode. This will always return NumberFormat::ERoundingMode::kRoundUnnecessary + * if the subclass does not support rounding. + * @return A rounding mode + * @stable ICU 60 + */ + virtual ERoundingMode getRoundingMode(void) const; + + /** + * Set the rounding mode. If a subclass does not support rounding, this will do nothing. + * @param roundingMode A rounding mode + * @stable ICU 60 + */ + virtual void setRoundingMode(ERoundingMode roundingMode); + + /** + * Group-set several settings used for numbers in date formats. + * Equivalent to: + * setGroupingUsed(FALSE); + * setParseIntegerOnly(TRUE); + * setMinimumFractionDigits(0); + * @internal + */ + virtual void setDateSettings(void); public: @@ -935,32 +1119,60 @@ protected: * have a capacity of at least 4 * @internal */ - virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const; + virtual void getEffectiveCurrency(char16_t* result, UErrorCode& ec) const; + +#ifndef U_HIDE_INTERNAL_API + /** + * Creates the specified number format style of the desired locale. + * If mustBeDecimalFormat is TRUE, then the returned pointer is + * either a DecimalFormat or it is NULL. + * @internal + */ + static NumberFormat* makeInstance(const Locale& desiredLocale, + UNumberFormatStyle style, + UBool mustBeDecimalFormat, + UErrorCode& errorCode); +#endif /* U_HIDE_INTERNAL_API */ private: + static UBool isStyleSupported(UNumberFormatStyle style); + /** * Creates the specified decimal format style of the desired locale. * @param desiredLocale the given locale. - * @param choice the given style. - * @param success Output param filled with success/failure status. + * @param style the given style. + * @param errorCode Output param filled with success/failure status. * @return A new NumberFormat instance. */ - static NumberFormat* makeInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success); + static NumberFormat* makeInstance(const Locale& desiredLocale, + UNumberFormatStyle style, + UErrorCode& errorCode); - UBool fGroupingUsed; + UBool fGroupingUsed; int32_t fMaxIntegerDigits; int32_t fMinIntegerDigits; int32_t fMaxFractionDigits; int32_t fMinFractionDigits; + + protected: + /** \internal */ + static const int32_t gDefaultMaxIntegerDigits; + /** \internal */ + static const int32_t gDefaultMinIntegerDigits; + + private: UBool fParseIntegerOnly; - UBool fParseStrict; + UBool fLenient; // TRUE => lenient parse is enabled // ISO currency code - UChar fCurrency[4]; + char16_t fCurrency[4]; + + UDisplayContext fCapitalizationContext; - friend class ICUNumberFormatFactory; // access to makeInstance, EStyles + friend class ICUNumberFormatFactory; // access to makeInstance friend class ICUNumberFormatService; + friend class ::NumberFormatTest; // access to isStyleSupported() }; #if !UCONFIG_NO_SERVICE @@ -1056,21 +1268,16 @@ NumberFormat::isParseIntegerOnly() const } inline UBool -NumberFormat::isParseStrict() const +NumberFormat::isLenient() const { - return fParseStrict; -} - -inline UnicodeString& -NumberFormat::format(const Formattable& obj, - UnicodeString& appendTo, - UErrorCode& status) const { - return Format::format(obj, appendTo, status); + return fLenient; } U_NAMESPACE_END #endif /* #if !UCONFIG_NO_FORMATTING */ +#endif /* U_SHOW_CPLUSPLUS_API */ + #endif // _NUMFMT //eof