icuSources/i18n/unicode/compactdecimalformat.h

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