icuSources/i18n/unicode/fmtable.h

   1 /*
   2 ********************************************************************************
   3 *   Copyright (C) 1997-2013, International Business Machines
   4 *   Corporation and others.  All Rights Reserved.
   5 ********************************************************************************
   6 *
   7 * File FMTABLE.H
   8 *
   9 * Modification History:
  10 *
  11 *   Date        Name        Description
  12 *   02/29/97    aliu        Creation.
  13 ********************************************************************************
  14 */
  15 #ifndef FMTABLE_H
  16 #define FMTABLE_H
  17
  18 #include "unicode/utypes.h"
  19 #include "unicode/unistr.h"
  20 #include "unicode/stringpiece.h"
  21
  22 /**
  23  * \file
  24  * \brief C++ API: Formattable is a thin wrapper for primitive numeric types.
  25  */
  26
  27 #if !UCONFIG_NO_FORMATTING
  28
  29 U_NAMESPACE_BEGIN
  30
  31 class CharString;
  32 class DigitList;
  33
  34 #ifndef U_HIDE_INTERNAL_API
  35 /**
  36  * \def UNUM_INTERNAL_STACKARRAY_SIZE
  37  * @internal
  38  */
  39 #if U_PLATFORM == U_PF_OS400
  40 #define UNUM_INTERNAL_STACKARRAY_SIZE 144
  41 #else
  42 #define UNUM_INTERNAL_STACKARRAY_SIZE 128
  43 #endif
  44 #endif  /* U_HIDE_INTERNAL_API */
  45
  46 /**
  47  * Formattable objects can be passed to the Format class or
  48  * its subclasses for formatting.  Formattable is a thin wrapper
  49  * class which interconverts between the primitive numeric types
  50  * (double, long, etc.) as well as UDate and UnicodeString.
  51  *
  52  * <p>Internally, a Formattable object is a union of primitive types.
  53  * As such, it can only store one flavor of data at a time.  To
  54  * determine what flavor of data it contains, use the getType method.
  55  *
  56  * <p>As of ICU 3.0, Formattable may also wrap a UObject pointer,
  57  * which it owns.  This allows an instance of any ICU class to be
  58  * encapsulated in a Formattable.  For legacy reasons and for
  59  * efficiency, primitive numeric types are still stored directly
  60  * within a Formattable.
  61  *
  62  * <p>The Formattable class is not suitable for subclassing.
  63  */
  64 class U_I18N_API Formattable : public UObject {
  65 public:
  66     /**
  67      * This enum is only used to let callers distinguish between
  68      * the Formattable(UDate) constructor and the Formattable(double)
  69      * constructor; the compiler cannot distinguish the signatures,
  70      * since UDate is currently typedefed to be either double or long.
  71      * If UDate is changed later to be a bonafide class
  72      * or struct, then we no longer need this enum.
  73      * @stable ICU 2.4
  74      */
  75     enum ISDATE { kIsDate };
  76
  77     /**
  78      * Default constructor
  79      * @stable ICU 2.4
  80      */
  81     Formattable(); // Type kLong, value 0
  82
  83     /**
  84      * Creates a Formattable object with a UDate instance.
  85      * @param d the UDate instance.
  86      * @param flag the flag to indicate this is a date. Always set it to kIsDate
  87      * @stable ICU 2.0
  88      */
  89     Formattable(UDate d, ISDATE flag);
  90
  91     /**
  92      * Creates a Formattable object with a double number.
  93      * @param d the double number.
  94      * @stable ICU 2.0
  95      */
  96     Formattable(double d);
  97
  98     /**
  99      * Creates a Formattable object with a long number.
 100      * @param l the long number.
 101      * @stable ICU 2.0
 102      */
 103     Formattable(int32_t l);
 104
 105     /**
 106      * Creates a Formattable object with an int64_t number
 107      * @param ll the int64_t number.
 108      * @stable ICU 2.8
 109      */
 110     Formattable(int64_t ll);
 111
 112 #if !UCONFIG_NO_CONVERSION
 113     /**
 114      * Creates a Formattable object with a char string pointer.
 115      * Assumes that the char string is null terminated.
 116      * @param strToCopy the char string.
 117      * @stable ICU 2.0
 118      */
 119     Formattable(const char* strToCopy);
 120 #endif
 121
 122     /**
 123      * Creates a Formattable object of an appropriate numeric type from a
 124      * a decimal number in string form.  The Formattable will retain the
 125      * full precision of the input in decimal format, even when it exceeds
 126      * what can be represented by a double of int64_t.
 127      *
 128      * @param number  the unformatted (not localized) string representation
 129      *                     of the Decimal number.
 130      * @param status  the error code.  Possible errors include U_INVALID_FORMAT_ERROR
 131      *                if the format of the string does not conform to that of a
 132      *                decimal number.
 133      * @stable ICU 4.4
 134      */
 135     Formattable(const StringPiece &number, UErrorCode &status);
 136
 137     /**
 138      * Creates a Formattable object with a UnicodeString object to copy from.
 139      * @param strToCopy the UnicodeString string.
 140      * @stable ICU 2.0
 141      */
 142     Formattable(const UnicodeString& strToCopy);
 143
 144     /**
 145      * Creates a Formattable object with a UnicodeString object to adopt from.
 146      * @param strToAdopt the UnicodeString string.
 147      * @stable ICU 2.0
 148      */
 149     Formattable(UnicodeString* strToAdopt);
 150
 151     /**
 152      * Creates a Formattable object with an array of Formattable objects.
 153      * @param arrayToCopy the Formattable object array.
 154      * @param count the array count.
 155      * @stable ICU 2.0
 156      */
 157     Formattable(const Formattable* arrayToCopy, int32_t count);
 158
 159     /**
 160      * Creates a Formattable object that adopts the given UObject.
 161      * @param objectToAdopt the UObject to set this object to
 162      * @stable ICU 3.0
 163      */
 164     Formattable(UObject* objectToAdopt);
 165
 166     /**
 167      * Copy constructor.
 168      * @stable ICU 2.0
 169      */
 170     Formattable(const Formattable&);
 171
 172     /**
 173      * Assignment operator.
 174      * @param rhs   The Formattable object to copy into this object.
 175      * @stable ICU 2.0
 176      */
 177     Formattable&    operator=(const Formattable &rhs);
 178
 179     /**
 180      * Equality comparison.
 181      * @param other    the object to be compared with.
 182      * @return        TRUE if other are equal to this, FALSE otherwise.
 183      * @stable ICU 2.0
 184      */
 185     UBool          operator==(const Formattable &other) const;
 186
 187     /**
 188      * Equality operator.
 189      * @param other    the object to be compared with.
 190      * @return        TRUE if other are unequal to this, FALSE otherwise.
 191      * @stable ICU 2.0
 192      */
 193     UBool          operator!=(const Formattable& other) const
 194       { return !operator==(other); }
 195
 196     /**
 197      * Destructor.
 198      * @stable ICU 2.0
 199      */
 200     virtual         ~Formattable();
 201
 202     /**
 203      * Clone this object.
 204      * Clones can be used concurrently in multiple threads.
 205      * If an error occurs, then NULL is returned.
 206      * The caller must delete the clone.
 207      *
 208      * @return a clone of this object
 209      *
 210      * @see getDynamicClassID
 211      * @stable ICU 2.8
 212      */
 213     Formattable *clone() const;
 214
 215     /**
 216      * Selector for flavor of data type contained within a
 217      * Formattable object.  Formattable is a union of several
 218      * different types, and at any time contains exactly one type.
 219      * @stable ICU 2.4
 220      */
 221     enum Type {
 222         /**
 223          * Selector indicating a UDate value.  Use getDate to retrieve
 224          * the value.
 225          * @stable ICU 2.4
 226          */
 227         kDate,
 228
 229         /**
 230          * Selector indicating a double value.  Use getDouble to
 231          * retrieve the value.
 232          * @stable ICU 2.4
 233          */
 234         kDouble,
 235
 236         /**
 237          * Selector indicating a 32-bit integer value.  Use getLong to
 238          * retrieve the value.
 239          * @stable ICU 2.4
 240          */
 241         kLong,
 242
 243         /**
 244          * Selector indicating a UnicodeString value.  Use getString
 245          * to retrieve the value.
 246          * @stable ICU 2.4
 247          */
 248         kString,
 249
 250         /**
 251          * Selector indicating an array of Formattables.  Use getArray
 252          * to retrieve the value.
 253          * @stable ICU 2.4
 254          */
 255         kArray,
 256
 257         /**
 258          * Selector indicating a 64-bit integer value.  Use getInt64
 259          * to retrieve the value.
 260          * @stable ICU 2.8
 261          */
 262         kInt64,
 263
 264         /**
 265          * Selector indicating a UObject value.  Use getObject to
 266          * retrieve the value.
 267          * @stable ICU 3.0
 268          */
 269         kObject
 270    };
 271
 272     /**
 273      * Gets the data type of this Formattable object.
 274      * @return    the data type of this Formattable object.
 275      * @stable ICU 2.0
 276      */
 277     Type            getType(void) const;
 278
 279     /**
 280      * Returns TRUE if the data type of this Formattable object
 281      * is kDouble, kLong, kInt64 or kDecimalNumber.
 282      * @return TRUE if this is a pure numeric object
 283      * @stable ICU 3.0
 284      */
 285     UBool           isNumeric() const;
 286
 287     /**
 288      * Gets the double value of this object. If this object is not of type
 289      * kDouble then the result is undefined.
 290      * @return    the double value of this object.
 291      * @stable ICU 2.0
 292      */
 293     double          getDouble(void) const { return fValue.fDouble; }
 294
 295     /**
 296      * Gets the double value of this object. If this object is of type
 297      * long, int64 or Decimal Number then a conversion is peformed, with
 298      * possible loss of precision.  If the type is kObject and the
 299      * object is a Measure, then the result of
 300      * getNumber().getDouble(status) is returned.  If this object is
 301      * neither a numeric type nor a Measure, then 0 is returned and
 302      * the status is set to U_INVALID_FORMAT_ERROR.
 303      * @param status the error code
 304      * @return the double value of this object.
 305      * @stable ICU 3.0
 306      */
 307     double          getDouble(UErrorCode& status) const;
 308
 309     /**
 310      * Gets the long value of this object. If this object is not of type
 311      * kLong then the result is undefined.
 312      * @return    the long value of this object.
 313      * @stable ICU 2.0
 314      */
 315     int32_t         getLong(void) const { return (int32_t)fValue.fInt64; }
 316
 317     /**
 318      * Gets the long value of this object. If the magnitude is too
 319      * large to fit in a long, then the maximum or minimum long value,
 320      * as appropriate, is returned and the status is set to
 321      * U_INVALID_FORMAT_ERROR.  If this object is of type kInt64 and
 322      * it fits within a long, then no precision is lost.  If it is of
 323      * type kDouble or kDecimalNumber, then a conversion is peformed, with
 324      * truncation of any fractional part.  If the type is kObject and
 325      * the object is a Measure, then the result of
 326      * getNumber().getLong(status) is returned.  If this object is
 327      * neither a numeric type nor a Measure, then 0 is returned and
 328      * the status is set to U_INVALID_FORMAT_ERROR.
 329      * @param status the error code
 330      * @return    the long value of this object.
 331      * @stable ICU 3.0
 332      */
 333     int32_t         getLong(UErrorCode& status) const;
 334
 335     /**
 336      * Gets the int64 value of this object. If this object is not of type
 337      * kInt64 then the result is undefined.
 338      * @return    the int64 value of this object.
 339      * @stable ICU 2.8
 340      */
 341     int64_t         getInt64(void) const { return fValue.fInt64; }
 342
 343     /**
 344      * Gets the int64 value of this object. If this object is of a numeric
 345      * type and the magnitude is too large to fit in an int64, then
 346      * the maximum or minimum int64 value, as appropriate, is returned
 347      * and the status is set to U_INVALID_FORMAT_ERROR.  If the
 348      * magnitude fits in an int64, then a casting conversion is
 349      * peformed, with truncation of any fractional part.  If the type
 350      * is kObject and the object is a Measure, then the result of
 351      * getNumber().getDouble(status) is returned.  If this object is
 352      * neither a numeric type nor a Measure, then 0 is returned and
 353      * the status is set to U_INVALID_FORMAT_ERROR.
 354      * @param status the error code
 355      * @return    the int64 value of this object.
 356      * @stable ICU 3.0
 357      */
 358     int64_t         getInt64(UErrorCode& status) const;
 359
 360     /**
 361      * Gets the Date value of this object. If this object is not of type
 362      * kDate then the result is undefined.
 363      * @return    the Date value of this object.
 364      * @stable ICU 2.0
 365      */
 366     UDate           getDate() const { return fValue.fDate; }
 367
 368     /**
 369      * Gets the Date value of this object.  If the type is not a date,
 370      * status is set to U_INVALID_FORMAT_ERROR and the return value is
 371      * undefined.
 372      * @param status the error code.
 373      * @return    the Date value of this object.
 374      * @stable ICU 3.0
 375      */
 376      UDate          getDate(UErrorCode& status) const;
 377
 378     /**
 379      * Gets the string value of this object. If this object is not of type
 380      * kString then the result is undefined.
 381      * @param result    Output param to receive the Date value of this object.
 382      * @return          A reference to 'result'.
 383      * @stable ICU 2.0
 384      */
 385     UnicodeString&  getString(UnicodeString& result) const
 386       { result=*fValue.fString; return result; }
 387
 388     /**
 389      * Gets the string value of this object. If the type is not a
 390      * string, status is set to U_INVALID_FORMAT_ERROR and a bogus
 391      * string is returned.
 392      * @param result    Output param to receive the Date value of this object.
 393      * @param status    the error code.
 394      * @return          A reference to 'result'.
 395      * @stable ICU 3.0
 396      */
 397     UnicodeString&  getString(UnicodeString& result, UErrorCode& status) const;
 398
 399     /**
 400      * Gets a const reference to the string value of this object. If
 401      * this object is not of type kString then the result is
 402      * undefined.
 403      * @return   a const reference to the string value of this object.
 404      * @stable ICU 2.0
 405      */
 406     inline const UnicodeString& getString(void) const;
 407
 408     /**
 409      * Gets a const reference to the string value of this object.  If
 410      * the type is not a string, status is set to
 411      * U_INVALID_FORMAT_ERROR and the result is a bogus string.
 412      * @param status    the error code.
 413      * @return   a const reference to the string value of this object.
 414      * @stable ICU 3.0
 415      */
 416     const UnicodeString& getString(UErrorCode& status) const;
 417
 418     /**
 419      * Gets a reference to the string value of this object. If this
 420      * object is not of type kString then the result is undefined.
 421      * @return   a reference to the string value of this object.
 422      * @stable ICU 2.0
 423      */
 424     inline UnicodeString& getString(void);
 425
 426     /**
 427      * Gets a reference to the string value of this object. If the
 428      * type is not a string, status is set to U_INVALID_FORMAT_ERROR
 429      * and the result is a bogus string.
 430      * @param status    the error code.
 431      * @return   a reference to the string value of this object.
 432      * @stable ICU 3.0
 433      */
 434     UnicodeString& getString(UErrorCode& status);
 435
 436     /**
 437      * Gets the array value and count of this object. If this object
 438      * is not of type kArray then the result is undefined.
 439      * @param count    fill-in with the count of this object.
 440      * @return         the array value of this object.
 441      * @stable ICU 2.0
 442      */
 443     const Formattable* getArray(int32_t& count) const
 444       { count=fValue.fArrayAndCount.fCount; return fValue.fArrayAndCount.fArray; }
 445
 446     /**
 447      * Gets the array value and count of this object. If the type is
 448      * not an array, status is set to U_INVALID_FORMAT_ERROR, count is
 449      * set to 0, and the result is NULL.
 450      * @param count    fill-in with the count of this object.
 451      * @param status the error code.
 452      * @return         the array value of this object.
 453      * @stable ICU 3.0
 454      */
 455     const Formattable* getArray(int32_t& count, UErrorCode& status) const;
 456
 457     /**
 458      * Accesses the specified element in the array value of this
 459      * Formattable object. If this object is not of type kArray then
 460      * the result is undefined.
 461      * @param index the specified index.
 462      * @return the accessed element in the array.
 463      * @stable ICU 2.0
 464      */
 465     Formattable&    operator[](int32_t index) { return fValue.fArrayAndCount.fArray[index]; }
 466
 467     /**
 468      * Returns a pointer to the UObject contained within this
 469      * formattable, or NULL if this object does not contain a UObject.
 470      * @return a UObject pointer, or NULL
 471      * @stable ICU 3.0
 472      */
 473     const UObject*  getObject() const;
 474
 475     /**
 476      * Returns a numeric string representation of the number contained within this
 477      * formattable, or NULL if this object does not contain numeric type.
 478      * For values obtained by parsing, the returned decimal number retains
 479      * the full precision and range of the original input, unconstrained by
 480      * the limits of a double floating point or a 64 bit int.
 481      *
 482      * This function is not thread safe, and therfore is not declared const,
 483      * even though it is logically const.
 484      *
 485      * Possible errors include U_MEMORY_ALLOCATION_ERROR, and
 486      * U_INVALID_STATE if the formattable object has not been set to
 487      * a numeric type.
 488      *
 489      * @param status the error code.
 490      * @return the unformatted string representation of a number.
 491      * @stable ICU 4.4
 492      */
 493     StringPiece getDecimalNumber(UErrorCode &status);
 494
 495      /**
 496      * Sets the double value of this object and changes the type to
 497      * kDouble.
 498      * @param d    the new double value to be set.
 499      * @stable ICU 2.0
 500      */
 501     void            setDouble(double d);
 502
 503     /**
 504      * Sets the long value of this object and changes the type to
 505      * kLong.
 506      * @param l    the new long value to be set.
 507      * @stable ICU 2.0
 508      */
 509     void            setLong(int32_t l);
 510
 511     /**
 512      * Sets the int64 value of this object and changes the type to
 513      * kInt64.
 514      * @param ll    the new int64 value to be set.
 515      * @stable ICU 2.8
 516      */
 517     void            setInt64(int64_t ll);
 518
 519     /**
 520      * Sets the Date value of this object and changes the type to
 521      * kDate.
 522      * @param d    the new Date value to be set.
 523      * @stable ICU 2.0
 524      */
 525     void            setDate(UDate d);
 526
 527     /**
 528      * Sets the string value of this object and changes the type to
 529      * kString.
 530      * @param stringToCopy    the new string value to be set.
 531      * @stable ICU 2.0
 532      */
 533     void            setString(const UnicodeString& stringToCopy);
 534
 535     /**
 536      * Sets the array value and count of this object and changes the
 537      * type to kArray.
 538      * @param array    the array value.
 539      * @param count    the number of array elements to be copied.
 540      * @stable ICU 2.0
 541      */
 542     void            setArray(const Formattable* array, int32_t count);
 543
 544     /**
 545      * Sets and adopts the string value and count of this object and
 546      * changes the type to kArray.
 547      * @param stringToAdopt    the new string value to be adopted.
 548      * @stable ICU 2.0
 549      */
 550     void            adoptString(UnicodeString* stringToAdopt);
 551
 552     /**
 553      * Sets and adopts the array value and count of this object and
 554      * changes the type to kArray.
 555      * @stable ICU 2.0
 556      */
 557     void            adoptArray(Formattable* array, int32_t count);
 558
 559     /**
 560      * Sets and adopts the UObject value of this object and changes
 561      * the type to kObject.  After this call, the caller must not
 562      * delete the given object.
 563      * @param objectToAdopt the UObject value to be adopted
 564      * @stable ICU 3.0
 565      */
 566     void            adoptObject(UObject* objectToAdopt);
 567
 568     /**
 569      * Sets the the numeric value from a decimal number string, and changes
 570      * the type to to a numeric type appropriate for the number.
 571      * The syntax of the number is a "numeric string"
 572      * as defined in the Decimal Arithmetic Specification, available at
 573      * http://speleotrove.com/decimal
 574      * The full precision and range of the input number will be retained,
 575      * even when it exceeds what can be represented by a double or an int64.
 576      *
 577      * @param numberString  a string representation of the unformatted decimal number.
 578      * @param status        the error code.  Set to U_INVALID_FORMAT_ERROR if the
 579      *                      incoming string is not a valid decimal number.
 580      * @stable ICU 4.4
 581      */
 582     void             setDecimalNumber(const StringPiece &numberString,
 583                                       UErrorCode &status);
 584
 585     /**
 586      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 587      *
 588      * @stable ICU 2.2
 589      */
 590     virtual UClassID getDynamicClassID() const;
 591
 592     /**
 593      * ICU "poor man's RTTI", returns a UClassID for this class.
 594      *
 595      * @stable ICU 2.2
 596      */
 597     static UClassID U_EXPORT2 getStaticClassID();
 598
 599 #ifndef U_HIDE_DEPRECATED_API
 600     /**
 601      * Deprecated variant of getLong(UErrorCode&).
 602      * @param status the error code
 603      * @return the long value of this object.
 604      * @deprecated ICU 3.0 use getLong(UErrorCode&) instead
 605      */
 606     inline int32_t getLong(UErrorCode* status) const;
 607 #endif  /* U_HIDE_DEPRECATED_API */
 608
 609 #ifndef U_HIDE_INTERNAL_API
 610     /**
 611      * Internal function, do not use.
 612      * TODO:  figure out how to make this be non-public.
 613      *        NumberFormat::format(Formattable, ...
 614      *        needs to get at the DigitList, if it exists, for
 615      *        big decimal formatting.
 616      *  @internal
 617      */
 618     DigitList *getDigitList() const { return fDecimalNum;}
 619
 620     /**
 621      *  @internal
 622      */
 623     DigitList *getInternalDigitList();
 624
 625     /**
 626      *  Adopt, and set value from, a DigitList
 627      *     Internal Function, do not use.
 628      *  @param dl the Digit List to be adopted
 629      *  @internal
 630      */
 631     void adoptDigitList(DigitList *dl);
 632 #endif  /* U_HIDE_INTERNAL_API */
 633
 634 private:
 635     /**
 636      * Cleans up the memory for unwanted values.  For example, the adopted
 637      * string or array objects.
 638      */
 639     void            dispose(void);
 640
 641     /**
 642      * Common initialization, for use by constructors.
 643      */
 644     void            init();
 645
 646     UnicodeString* getBogus() const;
 647
 648     union {
 649         UObject*        fObject;
 650         UnicodeString*  fString;
 651         double          fDouble;
 652         int64_t         fInt64;
 653         UDate           fDate;
 654         struct {
 655           Formattable*  fArray;
 656           int32_t       fCount;
 657         }               fArrayAndCount;
 658     } fValue;
 659
 660     CharString           *fDecimalStr;
 661
 662     DigitList            *fDecimalNum;
 663
 664     char                fStackData[UNUM_INTERNAL_STACKARRAY_SIZE]; // must be big enough for DigitList
 665
 666     Type                fType;
 667     UnicodeString       fBogus; // Bogus string when it's needed.
 668 };
 669
 670 inline UDate Formattable::getDate(UErrorCode& status) const {
 671     if (fType != kDate) {
 672         if (U_SUCCESS(status)) {
 673             status = U_INVALID_FORMAT_ERROR;
 674         }
 675         return 0;
 676     }
 677     return fValue.fDate;
 678 }
 679
 680 inline const UnicodeString& Formattable::getString(void) const {
 681     return *fValue.fString;
 682 }
 683
 684 inline UnicodeString& Formattable::getString(void) {
 685     return *fValue.fString;
 686 }
 687
 688 inline int32_t Formattable::getLong(UErrorCode* status) const {
 689     return getLong(*status);
 690 }
 691
 692
 693 U_NAMESPACE_END
 694
 695 #endif /* #if !UCONFIG_NO_FORMATTING */
 696
 697 #endif //_FMTABLE
 698 //eof