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