include/unicode/compactdecimalformat.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 ********************************************************************************
0005 *   Copyright (C) 2012-2016, International Business Machines
0006 *   Corporation and others.  All Rights Reserved.
0007 ********************************************************************************
0008 *
0009 * File COMPACTDECIMALFORMAT.H
0010 ********************************************************************************
0011 */
0012
0013 #ifndef __COMPACT_DECIMAL_FORMAT_H__
0014 #define __COMPACT_DECIMAL_FORMAT_H__
0015
0016 #include "unicode/utypes.h"
0017
0018 #if U_SHOW_CPLUSPLUS_API
0019
0020 /**
0021  * \file
0022  * \brief C++ API: Compatibility APIs for compact decimal number formatting.
0023  */
0024
0025 #if !UCONFIG_NO_FORMATTING
0026
0027 #include "unicode/decimfmt.h"
0028
0029 struct UHashtable;
0030
0031 U_NAMESPACE_BEGIN
0032
0033 class PluralRules;
0034
0035 /**
0036  * **IMPORTANT:** New users are strongly encouraged to see if
0037  * numberformatter.h fits their use case.  Although not deprecated, this header
0038  * is provided for backwards compatibility only.
0039  *
0040  * -----------------------------------------------------------------------------
0041  *
0042  * The CompactDecimalFormat produces abbreviated numbers, suitable for display in
0043  * environments will limited real estate. For example, 'Hits: 1.2B' instead of
0044  * 'Hits: 1,200,000,000'. The format will be appropriate for the given language,
0045  * such as "1,2 Mrd." for German.
0046  *
0047  * For numbers under 1000 trillion (under 10^15, such as 123,456,789,012,345),
0048  * the result will be short for supported languages. However, the result may
0049  * sometimes exceed 7 characters, such as when there are combining marks or thin
0050  * characters. In such cases, the visual width in fonts should still be short.
0051  *
0052  * By default, there are 3 significant digits. After creation, if more than
0053  * three significant digits are set (with setMaximumSignificantDigits), or if a
0054  * fixed number of digits are set (with setMaximumIntegerDigits or
0055  * setMaximumFractionDigits), then result may be wider.
0056  *
0057  * At this time, parsing is not supported, and will produce a U_UNSUPPORTED_ERROR.
0058  * Resetting the pattern prefixes or suffixes is not supported; the method calls
0059  * are ignored.
0060  *
0061  * @stable ICU 51
0062  */
0063 class U_I18N_API CompactDecimalFormat : public DecimalFormat {
0064 public:
0065
0066      /**
0067       * Returns a compact decimal instance for specified locale.
0068       *
0069       * **NOTE:** New users are strongly encouraged to use
0070       * `number::NumberFormatter` instead of NumberFormat.
0071       * @param inLocale the given locale.
0072       * @param style whether to use short or long style.
0073       * @param status error code returned  here.
0074       * @stable ICU 51
0075       */
0076      static CompactDecimalFormat* U_EXPORT2 createInstance(
0077           const Locale& inLocale, UNumberCompactStyle style, UErrorCode& status);
0078
0079     /**
0080      * Copy constructor.
0081      *
0082      * @param source    the DecimalFormat object to be copied from.
0083      * @stable ICU 51
0084       */
0085     CompactDecimalFormat(const CompactDecimalFormat& source);
0086
0087     /**
0088      * Destructor.
0089      * @stable ICU 51
0090      */
0091     ~CompactDecimalFormat() override;
0092
0093     /**
0094      * Assignment operator.
0095      *
0096      * @param rhs    the DecimalFormat object to be copied.
0097      * @stable ICU 51
0098      */
0099     CompactDecimalFormat& operator=(const CompactDecimalFormat& rhs);
0100
0101     /**
0102      * Clone this Format object polymorphically. The caller owns the
0103      * result and should delete it when done.
0104      *
0105      * @return    a polymorphic copy of this CompactDecimalFormat.
0106      * @stable ICU 51
0107      */
0108     CompactDecimalFormat* clone() const override;
0109
0110     using DecimalFormat::format;
0111
0112     /**
0113      * CompactDecimalFormat does not support parsing. This implementation
0114      * does nothing.
0115      * @param text           Unused.
0116      * @param result         Does not change.
0117      * @param parsePosition  Does not change.
0118      * @see Formattable
0119      * @stable ICU 51
0120      */
0121     void parse(const UnicodeString& text, Formattable& result,
0122                ParsePosition& parsePosition) const override;
0123
0124     /**
0125      * CompactDecimalFormat does not support parsing. This implementation
0126      * sets status to U_UNSUPPORTED_ERROR
0127      *
0128      * @param text      Unused.
0129      * @param result    Does not change.
0130      * @param status    Always set to U_UNSUPPORTED_ERROR.
0131      * @stable ICU 51
0132      */
0133     void parse(const UnicodeString& text, Formattable& result, UErrorCode& status) const override;
0134
0135 #ifndef U_HIDE_INTERNAL_API
0136     /**
0137      * Parses text from the given string as a currency amount.  Unlike
0138      * the parse() method, this method will attempt to parse a generic
0139      * currency name, searching for a match of this object's locale's
0140      * currency display names, or for a 3-letter ISO currency code.
0141      * This method will fail if this format is not a currency format,
0142      * that is, if it does not contain the currency pattern symbol
0143      * (U+00A4) in its prefix or suffix. This implementation always returns
0144      * nullptr.
0145      *
0146      * @param text the string to parse
0147      * @param pos  input-output position; on input, the position within text
0148      *             to match; must have 0 <= pos.getIndex() < text.length();
0149      *             on output, the position after the last matched character.
0150      *             If the parse fails, the position in unchanged upon output.
0151      * @return     if parse succeeds, a pointer to a newly-created CurrencyAmount
0152      *             object (owned by the caller) containing information about
0153      *             the parsed currency; if parse fails, this is nullptr.
0154      * @internal
0155      */
0156     CurrencyAmount* parseCurrency(const UnicodeString& text, ParsePosition& pos) const override;
0157 #endif  /* U_HIDE_INTERNAL_API */
0158
0159     /**
0160      * Return the class ID for this class.  This is useful only for
0161      * comparing to a return value from getDynamicClassID().  For example:
0162      * <pre>
0163      * .      Base* polymorphic_pointer = createPolymorphicObject();
0164      * .      if (polymorphic_pointer->getDynamicClassID() ==
0165      * .          Derived::getStaticClassID()) ...
0166      * </pre>
0167      * @return          The class ID for all objects of this class.
0168      * @stable ICU 51
0169      */
0170     static UClassID U_EXPORT2 getStaticClassID();
0171
0172     /**
0173      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
0174      * This method is to implement a simple version of RTTI, since not all
0175      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
0176      * clone() methods call this method.
0177      *
0178      * @return          The class ID for this object. All objects of a
0179      *                  given class have the same class ID.  Objects of
0180      *                  other classes have different class IDs.
0181      * @stable ICU 51
0182      */
0183     UClassID getDynamicClassID() const override;
0184
0185   private:
0186     CompactDecimalFormat(const Locale& inLocale, UNumberCompactStyle style, UErrorCode& status);
0187 };
0188
0189 U_NAMESPACE_END
0190
0191 #endif /* #if !UCONFIG_NO_FORMATTING */
0192
0193 #endif /* U_SHOW_CPLUSPLUS_API */
0194
0195 #endif // __COMPACT_DECIMAL_FORMAT_H__
0196 //eof