icuSources/i18n/unicode/compactdecimalformat.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 ********************************************************************************
   5 *   Copyright (C) 2012-2016, International Business Machines
   6 *   Corporation and others.  All Rights Reserved.
   7 ********************************************************************************
   8 *
   9 * File COMPACTDECIMALFORMAT.H
  10 ********************************************************************************
  11 */
  12
  13 #ifndef __COMPACT_DECIMAL_FORMAT_H__
  14 #define __COMPACT_DECIMAL_FORMAT_H__
  15
  16 #include "unicode/utypes.h"
  17 /**
  18  * \file
  19  * \brief C++ API: Compatibility APIs for compact decimal number formatting.
  20  */
  21
  22 #if !UCONFIG_NO_FORMATTING
  23
  24 #include "unicode/decimfmt.h"
  25
  26 struct UHashtable;
  27
  28 #if U_SHOW_CPLUSPLUS_API
  29 U_NAMESPACE_BEGIN
  30
  31 class PluralRules;
  32
  33 /**
  34  * **IMPORTANT:** New users are strongly encouraged to see if
  35  * numberformatter.h fits their use case.  Although not deprecated, this header
  36  * is provided for backwards compatibility only.
  37  *
  38  * -----------------------------------------------------------------------------
  39  *
  40  * The CompactDecimalFormat produces abbreviated numbers, suitable for display in
  41  * environments will limited real estate. For example, 'Hits: 1.2B' instead of
  42  * 'Hits: 1,200,000,000'. The format will be appropriate for the given language,
  43  * such as "1,2 Mrd." for German.
  44  *
  45  * For numbers under 1000 trillion (under 10^15, such as 123,456,789,012,345),
  46  * the result will be short for supported languages. However, the result may
  47  * sometimes exceed 7 characters, such as when there are combining marks or thin
  48  * characters. In such cases, the visual width in fonts should still be short.
  49  *
  50  * By default, there are 3 significant digits. After creation, if more than
  51  * three significant digits are set (with setMaximumSignificantDigits), or if a
  52  * fixed number of digits are set (with setMaximumIntegerDigits or
  53  * setMaximumFractionDigits), then result may be wider.
  54  *
  55  * At this time, parsing is not supported, and will produce a U_UNSUPPORTED_ERROR.
  56  * Resetting the pattern prefixes or suffixes is not supported; the method calls
  57  * are ignored.
  58  *
  59  * @stable ICU 51
  60  */
  61 class U_I18N_API CompactDecimalFormat : public DecimalFormat {
  62 public:
  63
  64      /**
  65       * Returns a compact decimal instance for specified locale.
  66       *
  67       * **NOTE:** New users are strongly encouraged to use
  68       * `number::NumberFormatter` instead of NumberFormat.
  69       * @param inLocale the given locale.
  70       * @param style whether to use short or long style.
  71       * @param status error code returned  here.
  72       * @stable ICU 51
  73       */
  74      static CompactDecimalFormat* U_EXPORT2 createInstance(
  75           const Locale& inLocale, UNumberCompactStyle style, UErrorCode& status);
  76
  77     /**
  78      * Copy constructor.
  79      *
  80      * @param source    the DecimalFormat object to be copied from.
  81      * @stable ICU 51
  82       */
  83     CompactDecimalFormat(const CompactDecimalFormat& source);
  84
  85     /**
  86      * Destructor.
  87      * @stable ICU 51
  88      */
  89     ~CompactDecimalFormat() U_OVERRIDE;
  90
  91     /**
  92      * Assignment operator.
  93      *
  94      * @param rhs    the DecimalFormat object to be copied.
  95      * @stable ICU 51
  96      */
  97     CompactDecimalFormat& operator=(const CompactDecimalFormat& rhs);
  98
  99     /**
 100      * Clone this Format object polymorphically. The caller owns the
 101      * result and should delete it when done.
 102      *
 103      * @return    a polymorphic copy of this CompactDecimalFormat.
 104      * @stable ICU 51
 105      */
 106     Format* clone() const U_OVERRIDE;
 107
 108     using DecimalFormat::format;
 109
 110     /**
 111      * CompactDecimalFormat does not support parsing. This implementation
 112      * does nothing.
 113      * @param text           Unused.
 114      * @param result         Does not change.
 115      * @param parsePosition  Does not change.
 116      * @see Formattable
 117      * @stable ICU 51
 118      */
 119     void parse(const UnicodeString& text, Formattable& result,
 120                ParsePosition& parsePosition) const U_OVERRIDE;
 121
 122     /**
 123      * CompactDecimalFormat does not support parsing. This implementation
 124      * sets status to U_UNSUPPORTED_ERROR
 125      *
 126      * @param text      Unused.
 127      * @param result    Does not change.
 128      * @param status    Always set to U_UNSUPPORTED_ERROR.
 129      * @stable ICU 51
 130      */
 131     void parse(const UnicodeString& text, Formattable& result, UErrorCode& status) const U_OVERRIDE;
 132
 133 #ifndef U_HIDE_INTERNAL_API
 134     /**
 135      * Parses text from the given string as a currency amount.  Unlike
 136      * the parse() method, this method will attempt to parse a generic
 137      * currency name, searching for a match of this object's locale's
 138      * currency display names, or for a 3-letter ISO currency code.
 139      * This method will fail if this format is not a currency format,
 140      * that is, if it does not contain the currency pattern symbol
 141      * (U+00A4) in its prefix or suffix. This implementation always returns
 142      * NULL.
 143      *
 144      * @param text the string to parse
 145      * @param pos  input-output position; on input, the position within text
 146      *             to match; must have 0 <= pos.getIndex() < text.length();
 147      *             on output, the position after the last matched character.
 148      *             If the parse fails, the position in unchanged upon output.
 149      * @return     if parse succeeds, a pointer to a newly-created CurrencyAmount
 150      *             object (owned by the caller) containing information about
 151      *             the parsed currency; if parse fails, this is NULL.
 152      * @internal
 153      */
 154     CurrencyAmount* parseCurrency(const UnicodeString& text, ParsePosition& pos) const U_OVERRIDE;
 155 #endif  /* U_HIDE_INTERNAL_API */
 156
 157     /**
 158      * Return the class ID for this class.  This is useful only for
 159      * comparing to a return value from getDynamicClassID().  For example:
 160      * <pre>
 161      * .      Base* polymorphic_pointer = createPolymorphicObject();
 162      * .      if (polymorphic_pointer->getDynamicClassID() ==
 163      * .          Derived::getStaticClassID()) ...
 164      * </pre>
 165      * @return          The class ID for all objects of this class.
 166      * @stable ICU 51
 167      */
 168     static UClassID U_EXPORT2 getStaticClassID();
 169
 170     /**
 171      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
 172      * This method is to implement a simple version of RTTI, since not all
 173      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
 174      * clone() methods call this method.
 175      *
 176      * @return          The class ID for this object. All objects of a
 177      *                  given class have the same class ID.  Objects of
 178      *                  other classes have different class IDs.
 179      * @stable ICU 51
 180      */
 181     UClassID getDynamicClassID() const U_OVERRIDE;
 182
 183   private:
 184     CompactDecimalFormat(const Locale& inLocale, UNumberCompactStyle style, UErrorCode& status);
 185 };
 186
 187 U_NAMESPACE_END
 188 #endif // U_SHOW_CPLUSPLUS_API
 189
 190 #endif /* #if !UCONFIG_NO_FORMATTING */
 191
 192 #endif // __COMPACT_DECIMAL_FORMAT_H__
 193 //eof