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  * <p><strong>IMPORTANT:</strong> 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  * <hr/>
  38  *
  39  * The CompactDecimalFormat produces abbreviated numbers, suitable for display in
  40  * environments will limited real estate. For example, 'Hits: 1.2B' instead of
  41  * 'Hits: 1,200,000,000'. The format will be appropriate for the given language,
  42  * such as "1,2 Mrd." for German.
  43  * <p>
  44  * For numbers under 1000 trillion (under 10^15, such as 123,456,789,012,345),
  45  * the result will be short for supported languages. However, the result may
  46  * sometimes exceed 7 characters, such as when there are combining marks or thin
  47  * characters. In such cases, the visual width in fonts should still be short.
  48  * <p>
  49  * By default, there are 3 significant digits. After creation, if more than
  50  * three significant digits are set (with setMaximumSignificantDigits), or if a
  51  * fixed number of digits are set (with setMaximumIntegerDigits or
  52  * setMaximumFractionDigits), then result may be wider.
  53  * <p>
  54  * At this time, parsing is not supported, and will produce a U_UNSUPPORTED_ERROR.
  55  * Resetting the pattern prefixes or suffixes is not supported; the method calls
  56  * are ignored.
  57  * <p>
  58  * @stable ICU 51
  59  */
  60 class U_I18N_API CompactDecimalFormat : public DecimalFormat {
  61 public:
  62
  63      /**
  64       * Returns a compact decimal instance for specified locale.
  65      * <p>
  66      * <strong>NOTE:</strong> New users are strongly encouraged to use
  67      * {@link NumberFormatter} instead of NumberFormat.
  68       * @param inLocale the given locale.
  69       * @param style whether to use short or long style.
  70       * @param status error code returned  here.
  71       * @stable ICU 51
  72       */
  73      static CompactDecimalFormat* U_EXPORT2 createInstance(
  74           const Locale& inLocale, UNumberCompactStyle style, UErrorCode& status);
  75
  76     /**
  77      * Copy constructor.
  78      *
  79      * @param source    the DecimalFormat object to be copied from.
  80      * @stable ICU 51
  81       */
  82     CompactDecimalFormat(const CompactDecimalFormat& source);
  83
  84     /**
  85      * Destructor.
  86      * @stable ICU 51
  87      */
  88     virtual ~CompactDecimalFormat();
  89
  90     /**
  91      * Assignment operator.
  92      *
  93      * @param rhs    the DecimalFormat object to be copied.
  94      * @stable ICU 51
  95      */
  96     CompactDecimalFormat& operator=(const CompactDecimalFormat& rhs);
  97
  98     /**
  99      * Clone this Format object polymorphically. The caller owns the
 100      * result and should delete it when done.
 101      *
 102      * @return    a polymorphic copy of this CompactDecimalFormat.
 103      * @stable ICU 51
 104      */
 105     virtual Format* clone() const;
 106
 107     /**
 108      * Return TRUE if the given Format objects are semantically equal.
 109      * Objects of different subclasses are considered unequal.
 110      *
 111      * @param other    the object to be compared with.
 112      * @return         TRUE if the given Format objects are semantically equal.
 113      * @stable ICU 51
 114      */
 115     virtual UBool operator==(const Format& other) const;
 116
 117
 118     using DecimalFormat::format;
 119
 120     /**
 121      * Format a double or long number using base-10 representation.
 122      *
 123      * @param number    The value to be formatted.
 124      * @param appendTo  Output parameter to receive result.
 125      *                  Result is appended to existing contents.
 126      * @param pos       On input: an alignment field, if desired.
 127      *                  On output: the offsets of the alignment field.
 128      * @return          Reference to 'appendTo' parameter.
 129      * @stable ICU 51
 130      */
 131     virtual UnicodeString& format(double number,
 132                                   UnicodeString& appendTo,
 133                                   FieldPosition& pos) const;
 134
 135     /**
 136      * Format a double or long number using base-10 representation.
 137      *
 138      * @param number    The value to be formatted.
 139      * @param appendTo  Output parameter to receive result.
 140      *                  Result is appended to existing contents.
 141      * @param pos       On input: an alignment field, if desired.
 142      *                  On output: the offsets of the alignment field.
 143      * @param status
 144      * @return          Reference to 'appendTo' parameter.
 145      * @internal
 146      */
 147     virtual UnicodeString& format(double number,
 148                                   UnicodeString& appendTo,
 149                                   FieldPosition& pos,
 150                                   UErrorCode &status) const;
 151
 152     /**
 153      * Format a double or long number using base-10 representation.
 154      * Currently sets status to U_UNSUPPORTED_ERROR.
 155      *
 156      * @param number    The value to be formatted.
 157      * @param appendTo  Output parameter to receive result.
 158      *                  Result is appended to existing contents.
 159      * @param posIter   On return, can be used to iterate over positions
 160      *                  of fields generated by this format call.
 161      *                  Can be NULL.
 162      * @param status    Output param filled with success/failure status.
 163      * @return          Reference to 'appendTo' parameter.
 164      * @internal
 165      */
 166     virtual UnicodeString& format(double number,
 167                                   UnicodeString& appendTo,
 168                                   FieldPositionIterator* posIter,
 169                                   UErrorCode& status) const;
 170
 171     /**
 172      * Format a long number using base-10 representation.
 173      *
 174      * @param number    The value to be formatted.
 175      * @param appendTo  Output parameter to receive result.
 176      *                  Result is appended to existing contents.
 177      * @param pos       On input: an alignment field, if desired.
 178      *                  On output: the offsets of the alignment field.
 179      * @return          Reference to 'appendTo' parameter.
 180      * @stable ICU 56
 181      */
 182     virtual UnicodeString& format(int32_t number,
 183                                   UnicodeString& appendTo,
 184                                   FieldPosition& pos) const;
 185
 186     /**
 187      * Format a long number using base-10 representation.
 188      *
 189      * @param number    The value to be formatted.
 190      * @param appendTo  Output parameter to receive result.
 191      *                  Result is appended to existing contents.
 192      * @param pos       On input: an alignment field, if desired.
 193      *                  On output: the offsets of the alignment field.
 194      * @return          Reference to 'appendTo' parameter.
 195      * @internal
 196      */
 197     virtual UnicodeString& format(int32_t number,
 198                                   UnicodeString& appendTo,
 199                                   FieldPosition& pos,
 200                                   UErrorCode &status) const;
 201
 202     /**
 203      * Format a long number using base-10 representation.
 204      * Currently sets status to U_UNSUPPORTED_ERROR
 205      *
 206      * @param number    The value to be formatted.
 207      * @param appendTo  Output parameter to receive result.
 208      *                  Result is appended to existing contents.
 209      * @param posIter   On return, can be used to iterate over positions
 210      *                  of fields generated by this format call.
 211      *                  Can be NULL.
 212      * @param status    Output param filled with success/failure status.
 213      * @return          Reference to 'appendTo' parameter.
 214      * @internal
 215      */
 216     virtual UnicodeString& format(int32_t number,
 217                                   UnicodeString& appendTo,
 218                                   FieldPositionIterator* posIter,
 219                                   UErrorCode& status) const;
 220
 221     /**
 222      * Format an int64 number using base-10 representation.
 223      *
 224      * @param number    The value to be formatted.
 225      * @param appendTo  Output parameter to receive result.
 226      *                  Result is appended to existing contents.
 227      * @param pos       On input: an alignment field, if desired.
 228      *                  On output: the offsets of the alignment field.
 229      * @return          Reference to 'appendTo' parameter.
 230      * @stable ICU 51
 231      */
 232     virtual UnicodeString& format(int64_t number,
 233                                   UnicodeString& appendTo,
 234                                   FieldPosition& pos) const;
 235
 236     /**
 237      * Format an int64 number using base-10 representation.
 238      *
 239      * @param number    The value to be formatted.
 240      * @param appendTo  Output parameter to receive result.
 241      *                  Result is appended to existing contents.
 242      * @param pos       On input: an alignment field, if desired.
 243      *                  On output: the offsets of the alignment field.
 244      * @return          Reference to 'appendTo' parameter.
 245      * @internal
 246      */
 247     virtual UnicodeString& format(int64_t number,
 248                                   UnicodeString& appendTo,
 249                                   FieldPosition& pos,
 250                                   UErrorCode &status) const;
 251
 252     /**
 253      * Format an int64 number using base-10 representation.
 254      * Currently sets status to U_UNSUPPORTED_ERROR
 255      *
 256      * @param number    The value to be formatted.
 257      * @param appendTo  Output parameter to receive result.
 258      *                  Result is appended to existing contents.
 259      * @param posIter   On return, can be used to iterate over positions
 260      *                  of fields generated by this format call.
 261      *                  Can be NULL.
 262      * @param status    Output param filled with success/failure status.
 263      * @return          Reference to 'appendTo' parameter.
 264      * @internal
 265      */
 266     virtual UnicodeString& format(int64_t number,
 267                                   UnicodeString& appendTo,
 268                                   FieldPositionIterator* posIter,
 269                                   UErrorCode& status) const;
 270
 271     /**
 272      * Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR
 273      * The syntax of the unformatted number is a "numeric string"
 274      * as defined in the Decimal Arithmetic Specification, available at
 275      * http://speleotrove.com/decimal
 276      *
 277      * @param number    The unformatted number, as a string.
 278      * @param appendTo  Output parameter to receive result.
 279      *                  Result is appended to existing contents.
 280      * @param posIter   On return, can be used to iterate over positions
 281      *                  of fields generated by this format call.
 282      *                  Can be NULL.
 283      * @param status    Output param filled with success/failure status.
 284      * @return          Reference to 'appendTo' parameter.
 285      * @internal
 286      */
 287     virtual UnicodeString& format(StringPiece number,
 288                                   UnicodeString& appendTo,
 289                                   FieldPositionIterator* posIter,
 290                                   UErrorCode& status) const;
 291
 292     /**
 293      * Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR
 294      * The number is a DigitList wrapper onto a floating point decimal number.
 295      * The default implementation in NumberFormat converts the decimal number
 296      * to a double and formats that.
 297      *
 298      * @param number    The number, a DigitList format Decimal Floating Point.
 299      * @param appendTo  Output parameter to receive result.
 300      *                  Result is appended to existing contents.
 301      * @param posIter   On return, can be used to iterate over positions
 302      *                  of fields generated by this format call.
 303      * @param status    Output param filled with success/failure status.
 304      * @return          Reference to 'appendTo' parameter.
 305      * @internal
 306      */
 307     virtual UnicodeString& format(const DigitList &number,
 308                                   UnicodeString& appendTo,
 309                                   FieldPositionIterator* posIter,
 310                                   UErrorCode& status) const;
 311
 312     /**
 313      * Format a decimal number. Currently sets status to U_UNSUPPORTED_ERROR.
 314      * The number is a DigitList wrapper onto a floating point decimal number.
 315      * The default implementation in NumberFormat converts the decimal number
 316      * to a double and formats that.
 317      *
 318      * @param number    The number, a DigitList format Decimal Floating Point.
 319      * @param appendTo  Output parameter to receive result.
 320      *                  Result is appended to existing contents.
 321      * @param pos       On input: an alignment field, if desired.
 322      *                  On output: the offsets of the alignment field.
 323      * @param status    Output param filled with success/failure status.
 324      * @return          Reference to 'appendTo' parameter.
 325      * @internal
 326      */
 327     virtual UnicodeString& format(const DigitList &number,
 328                                   UnicodeString& appendTo,
 329                                   FieldPosition& pos,
 330                                   UErrorCode& status) const;
 331
 332    /**
 333     * CompactDecimalFormat does not support parsing. This implementation
 334     * does nothing.
 335     * @param text           Unused.
 336     * @param result         Does not change.
 337     * @param parsePosition  Does not change.
 338     * @see Formattable
 339     * @stable ICU 51
 340     */
 341     virtual void parse(const UnicodeString& text,
 342                        Formattable& result,
 343                        ParsePosition& parsePosition) const;
 344
 345     /**
 346      * CompactDecimalFormat does not support parsing. This implementation
 347      * sets status to U_UNSUPPORTED_ERROR
 348      *
 349      * @param text      Unused.
 350      * @param result    Does not change.
 351      * @param status    Always set to U_UNSUPPORTED_ERROR.
 352      * @stable ICU 51
 353      */
 354     virtual void parse(const UnicodeString& text,
 355                        Formattable& result,
 356                        UErrorCode& status) const;
 357
 358     /**
 359      * Parses text from the given string as a currency amount.  Unlike
 360      * the parse() method, this method will attempt to parse a generic
 361      * currency name, searching for a match of this object's locale's
 362      * currency display names, or for a 3-letter ISO currency code.
 363      * This method will fail if this format is not a currency format,
 364      * that is, if it does not contain the currency pattern symbol
 365      * (U+00A4) in its prefix or suffix. This implementation always returns
 366      * NULL.
 367      *
 368      * @param text the string to parse
 369      * @param pos  input-output position; on input, the position within text
 370      *             to match; must have 0 <= pos.getIndex() < text.length();
 371      *             on output, the position after the last matched character.
 372      *             If the parse fails, the position in unchanged upon output.
 373      * @return     if parse succeeds, a pointer to a newly-created CurrencyAmount
 374      *             object (owned by the caller) containing information about
 375      *             the parsed currency; if parse fails, this is NULL.
 376      * @internal
 377      */
 378     virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
 379                                           ParsePosition& pos) const;
 380
 381     /**
 382      * Return the class ID for this class.  This is useful only for
 383      * comparing to a return value from getDynamicClassID().  For example:
 384      * <pre>
 385      * .      Base* polymorphic_pointer = createPolymorphicObject();
 386      * .      if (polymorphic_pointer->getDynamicClassID() ==
 387      * .          Derived::getStaticClassID()) ...
 388      * </pre>
 389      * @return          The class ID for all objects of this class.
 390      * @stable ICU 51
 391      */
 392     static UClassID U_EXPORT2 getStaticClassID();
 393
 394     /**
 395      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
 396      * This method is to implement a simple version of RTTI, since not all
 397      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
 398      * clone() methods call this method.
 399      *
 400      * @return          The class ID for this object. All objects of a
 401      *                  given class have the same class ID.  Objects of
 402      *                  other classes have different class IDs.
 403      * @stable ICU 51
 404      */
 405     virtual UClassID getDynamicClassID() const;
 406
 407 private:
 408
 409     const UHashtable* _unitsByVariant;
 410     const double* _divisors;
 411     PluralRules* _pluralRules;
 412
 413     // Default constructor not implemented.
 414     CompactDecimalFormat(const DecimalFormat &, const UHashtable* unitsByVariant, const double* divisors, PluralRules* pluralRules);
 415
 416     UBool eqHelper(const CompactDecimalFormat& that) const;
 417 };
 418
 419 U_NAMESPACE_END
 420 #endif // U_SHOW_CPLUSPLUS_API
 421
 422 #endif /* #if !UCONFIG_NO_FORMATTING */
 423
 424 #endif // __COMPACT_DECIMAL_FORMAT_H__
 425 //eof