icuSources/i18n/unicode/compactdecimalformat.h

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