ICU-64243.0.1.tar.gz

[apple/icu.git] / icuSources / i18n / unicode / numfmt.h

diff --git a/icuSources/i18n/unicode/numfmt.h b/icuSources/i18n/unicode/numfmt.h
index 1d1613126186fed01489d9e1c0cd37c7f4c59710..cf188eef996a92e861cffd37185365fec6f4eb11 100644 (file)
--- a/icuSources/i18n/unicode/numfmt.h
+++ b/icuSources/i18n/unicode/numfmt.h
@@ -1,3 +1,5 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html

 /*
 ********************************************************************************
 * Copyright (C) 1997-2016, International Business Machines Corporation and others.
 /*
 ********************************************************************************
 * Copyright (C) 1997-2016, International Business Machines Corporation and others.


@@ -26,7 +28,7 @@
 
 /**
  * \file
 
 /**
  * \file

- * \brief C++ API: Abstract base class for all number formats.
+ * \brief C++ API: Compatibility APIs for number formatting.

  */
 
 #if !UCONFIG_NO_FORMATTING
  */
 
 #if !UCONFIG_NO_FORMATTING


@@ -41,6 +43,7 @@
 
 class NumberFormatTest;
 
 
 class NumberFormatTest;
 

+#if U_SHOW_CPLUSPLUS_API

 U_NAMESPACE_BEGIN
 
 class SharedNumberFormat;
 U_NAMESPACE_BEGIN
 
 class SharedNumberFormat;


@@ -51,11 +54,15 @@ class StringEnumeration;
 #endif
 
 /**
 #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.
  *
  * 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.
  * \headerfile unicode/numfmt.h "unicode/numfmt.h"
  * <P>
  * 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:
  */
 class U_I18N_API NumberFormat : public Format {
 public:

+    /**
+     * 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
+    };
+

     /**
      * Alignment Field constants used to construct a FieldPosition object.
      * Signifies that the position of the integer part or fraction part of
     /**
      * 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,
         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.
 
     /**
      * 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.
      *                  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,
      */
     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.
      *                  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,
      */
     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.
      *                  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,
      */
     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.
      *                  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,
      */
     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.
      *                  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;
                                   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.
     /**
      * 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.
      *
      * 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
      * @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
      */
      * @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.
                                   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.
      *
      * 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.
      * @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
      */
      * @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;
 
                                   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
    /**
     * 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.
     /**
      * 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&);
      * @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.
      * 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,
      * @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.
 
     /**
      * 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 style            the given style.
      * @param errorCode        Output param filled with success/failure status.
      * @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.
 
     /**
      * 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.
      * @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
      */
      * @param inLocale    the given locale.
      * @stable ICU 2.0
      */


@@ -739,12 +794,18 @@ public:
 
     /**
      * Returns a percentage format for the current default locale.
 
     /**
      * 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.
      * @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
      */
      * @param inLocale    the given locale.
      * @stable ICU 2.0
      */


@@ -753,12 +814,18 @@ public:
 
     /**
      * Returns a scientific format for the current default locale.
 
     /**
      * 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.
      * @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
      */
      * @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
      * 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
      * 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
      */
      * @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
 
     /**
      * 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
      */
      * 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.
     /**
      * 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;
 
      */
     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:
 
     /**
 public:
 
     /**


@@ -1016,7 +1108,7 @@ protected:
      * have a capacity of at least 4
      * @internal
      */
      * 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
     /**
 
 #ifndef U_HIDE_INTERNAL_API
     /**


@@ -1063,7 +1155,7 @@ private:
     UBool      fLenient; // TRUE => lenient parse is enabled
 
     // ISO currency code
     UBool      fLenient; // TRUE => lenient parse is enabled
 
     // ISO currency code

-    UChar      fCurrency[4];
+    char16_t      fCurrency[4];

 
     UDisplayContext fCapitalizationContext;
 
 
     UDisplayContext fCapitalizationContext;
 


@@ -1171,6 +1263,7 @@ NumberFormat::isLenient() const
 }
 
 U_NAMESPACE_END
 }
 
 U_NAMESPACE_END

+#endif // U_SHOW_CPLUSPLUS_API

 
 #endif /* #if !UCONFIG_NO_FORMATTING */
 
 
 #endif /* #if !UCONFIG_NO_FORMATTING */