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