IMPORTANT: New users are strongly encouraged to see if + * numberformatter.h fits their use case. Although not deprecated, this header + * is provided for backwards compatibility only. * * 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" *
* NumberFormat helps you to format and parse numbers for any locale. @@ -166,6 +173,33 @@ class StringEnumeration; */ class U_I18N_API NumberFormat : public Format { public: + /** + * Rounding mode. + * + *
+ * 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 + }; + /** * Alignment Field constants used to construct a FieldPosition object. * Signifies that the position of the integer part or fraction part of @@ -204,6 +238,12 @@ public: 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. @@ -266,7 +306,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, @@ -389,7 +429,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, @@ -441,7 +481,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, @@ -494,7 +534,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, @@ -515,22 +555,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. + * 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 @@ -539,20 +581,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. + * 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. @@ -561,13 +603,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: - /** * Return a long if possible (e.g. within range LONG_MAX, * LONG_MAX], and with no decimals), otherwise a double. If @@ -674,6 +714,9 @@ public: /** * Create a default style NumberFormat for the current default locale. * The default formatting style is locale dependent. + *
+ * NOTE: New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @stable ICU 2.0 */ static NumberFormat* U_EXPORT2 createInstance(UErrorCode&); @@ -682,6 +725,9 @@ public: * Create a default style NumberFormat for the specified locale. * The default formatting style is locale dependent. * @param inLocale the given locale. + *
+ * NOTE: 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, @@ -689,6 +735,9 @@ public: /** * Create a specific style NumberFormat for the specified locale. + *
+ * NOTE: New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param desiredLocale the given locale. * @param style the given style. * @param errorCode Output param filled with success/failure status. @@ -725,12 +774,18 @@ public: /** * Returns a currency format for the current default locale. + *
+ * NOTE: 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. + *
+ * NOTE: New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -739,12 +794,18 @@ public: /** * Returns a percentage format for the current default locale. + *
+ * NOTE: 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. + *
+ * NOTE: New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -753,12 +814,18 @@ public: /** * Returns a scientific format for the current default locale. + *
+ * NOTE: 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. + *
+ * NOTE: New users are strongly encouraged to use + * {@link icu::number::NumberFormatter} instead of NumberFormat. * @param inLocale the given locale. * @stable ICU 2.0 */ @@ -812,7 +879,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 @@ -929,7 +996,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 @@ -938,8 +1005,8 @@ 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. @@ -963,6 +1030,31 @@ public: */ 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: /** @@ -1016,7 +1108,7 @@ 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 /** @@ -1063,7 +1155,7 @@ private: UBool fLenient; // TRUE => lenient parse is enabled // ISO currency code - UChar fCurrency[4]; + char16_t fCurrency[4]; UDisplayContext fCapitalizationContext; @@ -1171,6 +1263,7 @@ NumberFormat::isLenient() const } U_NAMESPACE_END +#endif // U_SHOW_CPLUSPLUS_API #endif /* #if !UCONFIG_NO_FORMATTING */