icuSources/i18n/unicode/fmtable.h

   1 /*
   2 ********************************************************************************
   3 *   Copyright (C) 1997-2004, 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
  21 #if !UCONFIG_NO_FORMATTING
  22
  23 U_NAMESPACE_BEGIN
  24
  25 /**
  26  * Formattable objects can be passed to the Format class or
  27  * its subclasses for formatting.  Formattable is a thin wrapper
  28  * class which interconverts between the primitive numeric types
  29  * (double, long, etc.) as well as UDate and UnicodeString.
  30  *
  31  * <p>Internally, a Formattable object is a union of primitive types.
  32  * As such, it can only store one flavor of data at a time.  To
  33  * determine what flavor of data it contains, use the getType method.
  34  *
  35  * <p>As of ICU 3.0, Formattable may also wrap a UObject pointer,
  36  * which it owns.  This allows an instance of any ICU class to be
  37  * encapsulated in a Formattable.  For legacy reasons and for
  38  * efficiency, primitive numeric types are still stored directly
  39  * within a Formattable.
  40  *
  41  * <p>The Formattable class is not suitable for subclassing.
  42  */
  43 class U_I18N_API Formattable : public UObject {
  44 public:
  45     /**
  46      * This enum is only used to let callers distinguish between
  47      * the Formattable(UDate) constructor and the Formattable(double)
  48      * constructor; the compiler cannot distinguish the signatures,
  49      * since UDate is currently typedefed to be either double or long.
  50      * If UDate is changed later to be a bonafide class
  51      * or struct, then we no longer need this enum.
  52      * @stable ICU 2.4
  53      */
  54     enum ISDATE { kIsDate };
  55
  56     /**
  57      * Default constructor
  58      * @stable ICU 2.4
  59      */
  60     Formattable(); // Type kLong, value 0
  61
  62     /**
  63      * Creates a Formattable object with a UDate instance.
  64      * @param d the UDate instance.
  65      * @param flag the flag to indicate this is a date. Always set it to kIsDate
  66      * @stable ICU 2.0
  67      */
  68     Formattable(UDate d, ISDATE flag);
  69
  70     /**
  71      * Creates a Formattable object with a double number.
  72      * @param d the double number.
  73      * @stable ICU 2.0
  74      */
  75     Formattable(double d);
  76
  77     /**
  78      * Creates a Formattable object with a long number.
  79      * @param l the long number.
  80      * @stable ICU 2.0
  81      */
  82     Formattable(int32_t l);
  83
  84     /**
  85      * Creates a Formattable object with an int64_t number
  86      * @param ll the int64_t number.
  87      * @draft ICU 2.8
  88      */
  89     Formattable(int64_t ll);
  90
  91     /**
  92      * Creates a Formattable object with a char string pointer.
  93      * Assumes that the char string is null terminated.
  94      * @param strToCopy the char string.
  95      * @stable ICU 2.0
  96      */
  97     Formattable(const char* strToCopy);
  98
  99     /**
 100      * Creates a Formattable object with a UnicodeString object to copy from.
 101      * @param strToCopy the UnicodeString string.
 102      * @stable ICU 2.0
 103      */
 104     Formattable(const UnicodeString& strToCopy);
 105
 106     /**
 107      * Creates a Formattable object with a UnicodeString object to adopt from.
 108      * @param strToAdopt the UnicodeString string.
 109      * @stable ICU 2.0
 110      */
 111     Formattable(UnicodeString* strToAdopt);
 112
 113     /**
 114      * Creates a Formattable object with an array of Formattable objects.
 115      * @param arrayToCopy the Formattable object array.
 116      * @param count the array count.
 117      * @stable ICU 2.0
 118      */
 119     Formattable(const Formattable* arrayToCopy, int32_t count);
 120
 121     /**
 122      * Creates a Formattable object that adopts the given UObject.
 123      * @param objectToAdopt the UObject to set this object to
 124      * @draft ICU 3.0
 125      */
 126     Formattable(UObject* objectToAdopt);
 127
 128     /**
 129      * Copy constructor.
 130      * @stable ICU 2.0
 131      */
 132     Formattable(const Formattable&);
 133
 134     /**
 135      * Assignment operator.
 136      * @param rhs   The Formattable object to copy into this object.
 137      * @stable ICU 2.0
 138      */
 139     Formattable&    operator=(const Formattable &rhs);
 140
 141     /**
 142      * Equality comparison.
 143      * @param other    the object to be compared with.
 144      * @return        TRUE if other are equal to this, FALSE otherwise.
 145      * @stable ICU 2.0
 146      */
 147     UBool          operator==(const Formattable &other) const;
 148
 149     /**
 150      * Equality operator.
 151      * @param other    the object to be compared with.
 152      * @return        TRUE if other are unequal to this, FALSE otherwise.
 153      * @stable ICU 2.0
 154      */
 155     UBool          operator!=(const Formattable& other) const
 156       { return !operator==(other); }
 157
 158     /**
 159      * Destructor.
 160      * @stable ICU 2.0
 161      */
 162     virtual         ~Formattable();
 163
 164     /**
 165      * Clone this object.
 166      * Clones can be used concurrently in multiple threads.
 167      * If an error occurs, then NULL is returned.
 168      * The caller must delete the clone.
 169      *
 170      * @return a clone of this object
 171      *
 172      * @see getDynamicClassID
 173      * @draft ICU 2.8
 174      */
 175     Formattable *clone() const;
 176
 177     /**
 178      * Selector for flavor of data type contained within a
 179      * Formattable object.  Formattable is a union of several
 180      * different types, and at any time contains exactly one type.
 181      * @stable ICU 2.4
 182      */
 183     enum Type {
 184         /**
 185          * Selector indicating a UDate value.  Use getDate to retrieve
 186          * the value.
 187          * @stable ICU 2.4
 188          */
 189         kDate,
 190
 191         /**
 192          * Selector indicating a double value.  Use getDouble to
 193          * retrieve the value.
 194          * @stable ICU 2.4
 195          */
 196         kDouble,
 197
 198         /**
 199          * Selector indicating a 32-bit integer value.  Use getLong to
 200          * retrieve the value.
 201          * @stable ICU 2.4
 202          */
 203         kLong,
 204
 205         /**
 206          * Selector indicating a UnicodeString value.  Use getString
 207          * to retrieve the value.
 208          * @stable ICU 2.4
 209          */
 210         kString,
 211
 212         /**
 213          * Selector indicating an array of Formattables.  Use getArray
 214          * to retrieve the value.
 215          * @stable ICU 2.4
 216          */
 217         kArray,
 218
 219         /**
 220          * Selector indicating a 64-bit integer value.  Use getInt64
 221          * to retrieve the value.
 222          * @draft ICU 2.8
 223          */
 224         kInt64,
 225
 226         /**
 227          * Selector indicating a UObject value.  Use getObject to
 228          * retrieve the value.
 229          * @draft ICU 3.0
 230          */
 231         kObject
 232    };
 233
 234     /**
 235      * Gets the data type of this Formattable object.
 236      * @return    the data type of this Formattable object.
 237      * @stable ICU 2.0
 238      */
 239     Type            getType(void) const;
 240
 241     /**
 242      * Returns TRUE if the data type of this Formattable object
 243      * is kDouble, kLong, or kInt64.
 244      * @return TRUE if this is a pure numeric object
 245      * @draft ICU 3.0
 246      */
 247     UBool           isNumeric() const;
 248
 249     /**
 250      * Gets the double value of this object. If this object is not of type
 251      * kDouble then the result is undefined.
 252      * @return    the double value of this object.
 253      * @stable ICU 2.0
 254      */
 255     double          getDouble(void) const { return fValue.fDouble; }
 256
 257     /**
 258      * Gets the double value of this object. If this object is of type
 259      * long or int64 then a casting conversion is peformed, with
 260      * possible loss of precision.  If the type is kObject and the
 261      * object is a Measure, then the result of
 262      * getNumber().getDouble(status) is returned.  If this object is
 263      * neither a numeric type nor a Measure, then 0 is returned and
 264      * the status is set to U_INVALID_FORMAT_ERROR.
 265      * @param status the error code
 266      * @return the double value of this object.
 267      * @draft ICU 3.0
 268      */
 269     double          getDouble(UErrorCode& status) const;
 270
 271     /**
 272      * Gets the long value of this object. If this object is not of type
 273      * kLong then the result is undefined.
 274      * @return    the long value of this object.
 275      * @stable ICU 2.0
 276      */
 277     int32_t         getLong(void) const { return (int32_t)fValue.fInt64; }
 278
 279     /**
 280      * Gets the long value of this object. If the magnitude is too
 281      * large to fit in a long, then the maximum or minimum long value,
 282      * as appropriate, is returned and the status is set to
 283      * U_INVALID_FORMAT_ERROR.  If this object is of type kInt64 and
 284      * it fits within a long, then no precision is lost.  If it is of
 285      * type kDouble, then a casting conversion is peformed, with
 286      * truncation of any fractional part.  If the type is kObject and
 287      * the object is a Measure, then the result of
 288      * getNumber().getLong(status) is returned.  If this object is
 289      * neither a numeric type nor a Measure, then 0 is returned and
 290      * the status is set to U_INVALID_FORMAT_ERROR.
 291      * @param status the error code
 292      * @return    the long value of this object.
 293      * @draft ICU 3.0
 294      */
 295     int32_t         getLong(UErrorCode& status) const;
 296
 297     /**
 298      * Gets the int64 value of this object. If this object is not of type
 299      * kInt64 then the result is undefined.
 300      * @return    the int64 value of this object.
 301      * @draft ICU 2.8
 302      */
 303     int64_t         getInt64(void) const { return fValue.fInt64; }
 304
 305     /**
 306      * Gets the int64 value of this object. If this object is of type
 307      * kDouble and the magnitude is too large to fit in an int64, then
 308      * the maximum or minimum int64 value, as appropriate, is returned
 309      * and the status is set to U_INVALID_FORMAT_ERROR.  If the
 310      * magnitude fits in an int64, then a casting conversion is
 311      * peformed, with truncation of any fractional part.  If the type
 312      * is kObject and the object is a Measure, then the result of
 313      * getNumber().getDouble(status) is returned.  If this object is
 314      * neither a numeric type nor a Measure, then 0 is returned and
 315      * the status is set to U_INVALID_FORMAT_ERROR.
 316      * @param status the error code
 317      * @return    the int64 value of this object.
 318      * @draft ICU 3.0
 319      */
 320     int64_t         getInt64(UErrorCode& status) const;
 321
 322     /**
 323      * Gets the Date value of this object. If this object is not of type
 324      * kDate then the result is undefined.
 325      * @return    the Date value of this object.
 326      * @stable ICU 2.0
 327      */
 328     UDate           getDate() const { return fValue.fDate; }
 329
 330     /**
 331      * Gets the Date value of this object.  If the type is not a date,
 332      * status is set to U_INVALID_FORMAT_ERROR and the return value is
 333      * undefined.
 334      * @param status the error code.
 335      * @return    the Date value of this object.
 336      * @draft ICU 3.0
 337      */
 338      UDate          getDate(UErrorCode& status) const;
 339
 340     /**
 341      * Gets the string value of this object. If this object is not of type
 342      * kString then the result is undefined.
 343      * @param result    Output param to receive the Date value of this object.
 344      * @return          A reference to 'result'.
 345      * @stable ICU 2.0
 346      */
 347     UnicodeString&  getString(UnicodeString& result) const
 348       { result=*fValue.fString; return result; }
 349
 350     /**
 351      * Gets the string value of this object. If the type is not a
 352      * string, status is set to U_INVALID_FORMAT_ERROR and a bogus
 353      * string is returned.
 354      * @param result    Output param to receive the Date value of this object.
 355      * @param status    the error code.
 356      * @return          A reference to 'result'.
 357      * @draft ICU 3.0
 358      */
 359     UnicodeString&  getString(UnicodeString& result, UErrorCode& status) const;
 360
 361     /**
 362      * Gets a const reference to the string value of this object. If
 363      * this object is not of type kString then the result is
 364      * undefined.
 365      * @return   a const reference to the string value of this object.
 366      * @stable ICU 2.0
 367      */
 368     inline const UnicodeString& getString(void) const;
 369
 370     /**
 371      * Gets a const reference to the string value of this object.  If
 372      * the type is not a string, status is set to
 373      * U_INVALID_FORMAT_ERROR and the result is a bogus string.
 374      * @param status    the error code.
 375      * @return   a const reference to the string value of this object.
 376      * @draft ICU 3.0
 377      */
 378     const UnicodeString& getString(UErrorCode& status) const;
 379
 380     /**
 381      * Gets a reference to the string value of this object. If this
 382      * object is not of type kString then the result is undefined.
 383      * @return   a reference to the string value of this object.
 384      * @stable ICU 2.0
 385      */
 386     inline UnicodeString& getString(void);
 387
 388     /**
 389      * Gets a reference to the string value of this object. If the
 390      * type is not a string, status is set to U_INVALID_FORMAT_ERROR
 391      * and the result is a bogus string.
 392      * @param status    the error code.
 393      * @return   a reference to the string value of this object.
 394      * @draft ICU 3.0
 395      */
 396     UnicodeString& getString(UErrorCode& status);
 397
 398     /**
 399      * Gets the array value and count of this object. If this object
 400      * is not of type kArray then the result is undefined.
 401      * @param count    fill-in with the count of this object.
 402      * @return         the array value of this object.
 403      * @stable ICU 2.0
 404      */
 405     const Formattable* getArray(int32_t& count) const
 406       { count=fValue.fArrayAndCount.fCount; return fValue.fArrayAndCount.fArray; }
 407
 408     /**
 409      * Gets the array value and count of this object. If the type is
 410      * not an array, status is set to U_INVALID_FORMAT_ERROR, count is
 411      * set to 0, and the result is NULL.
 412      * @param count    fill-in with the count of this object.
 413      * @param status the error code.
 414      * @return         the array value of this object.
 415      * @draft ICU 3.0
 416      */
 417     const Formattable* getArray(int32_t& count, UErrorCode& status) const;
 418
 419     /**
 420      * Accesses the specified element in the array value of this
 421      * Formattable object. If this object is not of type kArray then
 422      * the result is undefined.
 423      * @param index the specified index.
 424      * @return the accessed element in the array.
 425      * @stable ICU 2.0
 426      */
 427     Formattable&    operator[](int32_t index) { return fValue.fArrayAndCount.fArray[index]; }
 428
 429     /**
 430      * Returns a pointer to the UObject contained within this
 431      * formattable, or NULL if this object does not contain a UObject.
 432      * @return a UObject pointer, or NULL
 433      * @draft ICU 3.0
 434      */
 435     const UObject*  getObject() const;
 436
 437     /**
 438      * Sets the double value of this object and changes the type to
 439      * kDouble.
 440      * @param d    the new double value to be set.
 441      * @stable ICU 2.0
 442      */
 443     void            setDouble(double d);
 444
 445     /**
 446      * Sets the long value of this object and changes the type to
 447      * kLong.
 448      * @param l    the new long value to be set.
 449      * @stable ICU 2.0
 450      */
 451     void            setLong(int32_t l);
 452
 453     /**
 454      * Sets the int64 value of this object and changes the type to
 455      * kInt64.
 456      * @param ll    the new int64 value to be set.
 457      * @draft ICU 2.8
 458      */
 459     void            setInt64(int64_t ll);
 460
 461     /**
 462      * Sets the Date value of this object and changes the type to
 463      * kDate.
 464      * @param d    the new Date value to be set.
 465      * @stable ICU 2.0
 466      */
 467     void            setDate(UDate d);
 468
 469     /**
 470      * Sets the string value of this object and changes the type to
 471      * kString.
 472      * @param stringToCopy    the new string value to be set.
 473      * @stable ICU 2.0
 474      */
 475     void            setString(const UnicodeString& stringToCopy);
 476
 477     /**
 478      * Sets the array value and count of this object and changes the
 479      * type to kArray.
 480      * @param array    the array value.
 481      * @param count    the number of array elements to be copied.
 482      * @stable ICU 2.0
 483      */
 484     void            setArray(const Formattable* array, int32_t count);
 485
 486     /**
 487      * Sets and adopts the string value and count of this object and
 488      * changes the type to kArray.
 489      * @param stringToAdopt    the new string value to be adopted.
 490      * @stable ICU 2.0
 491      */
 492     void            adoptString(UnicodeString* stringToAdopt);
 493
 494     /**
 495      * Sets and adopts the array value and count of this object and
 496      * changes the type to kArray.
 497      * @stable ICU 2.0
 498      */
 499     void            adoptArray(Formattable* array, int32_t count);
 500
 501     /**
 502      * Sets and adopts the UObject value of this object and changes
 503      * the type to kObject.  After this call, the caller must not
 504      * delete the given object.
 505      * @param objectToAdopt the UObject value to be adopted
 506      * @draft ICU 3.0
 507      */
 508     void            adoptObject(UObject* objectToAdopt);
 509
 510     /**
 511      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 512      *
 513      * @stable ICU 2.2
 514      */
 515     virtual UClassID getDynamicClassID() const;
 516
 517     /**
 518      * ICU "poor man's RTTI", returns a UClassID for this class.
 519      *
 520      * @stable ICU 2.2
 521      */
 522     static UClassID U_EXPORT2 getStaticClassID();
 523
 524     /**
 525      * Deprecated variant of getLong(UErrorCode&).
 526      * @param status the error code
 527      * @return the long value of this object.
 528      * @deprecated ICU 3.0 use getLong(UErrorCode&) instead
 529      */
 530     inline int32_t getLong(UErrorCode* status) const;
 531
 532 private:
 533     /**
 534      * Cleans up the memory for unwanted values.  For example, the adopted
 535      * string or array objects.
 536      */
 537     void            dispose(void);
 538
 539     /**
 540      * Creates a new Formattable array and copies the values from the specified
 541      * original.
 542      * @param array the original array
 543      * @param count the original array count
 544      * @return the new Formattable array.
 545      */
 546     static Formattable* createArrayCopy(const Formattable* array, int32_t count);
 547
 548     UnicodeString* getBogus() const;
 549
 550     union {
 551         UObject*        fObject;
 552         UnicodeString*  fString;
 553         double          fDouble;
 554         int64_t         fInt64;
 555         UDate           fDate;
 556         struct {
 557           Formattable*  fArray;
 558           int32_t       fCount;
 559         }               fArrayAndCount;
 560     } fValue;
 561
 562     Type                fType;
 563     UnicodeString       fBogus; // Bogus string when it's needed.
 564 };
 565
 566 inline Formattable*
 567 Formattable::createArrayCopy(const Formattable* array, int32_t count)
 568 {
 569     Formattable *result = new Formattable[count];
 570     for (int32_t i=0; i<count; ++i) result[i] = array[i]; // Don't memcpy!
 571     return result;
 572 }
 573
 574 inline UDate Formattable::getDate(UErrorCode& status) const {
 575     if (fType != kDate) {
 576         if (U_SUCCESS(status)) {
 577             status = U_INVALID_FORMAT_ERROR;
 578         }
 579         return 0;
 580     }
 581     return fValue.fDate;
 582 }
 583
 584 inline const UnicodeString& Formattable::getString(void) const {
 585     return *fValue.fString;
 586 }
 587
 588 inline UnicodeString& Formattable::getString(void) {
 589     return *fValue.fString;
 590 }
 591
 592 inline int32_t Formattable::getLong(UErrorCode* status) const {
 593     return getLong(*status);
 594 }
 595
 596 U_NAMESPACE_END
 597
 598 #endif /* #if !UCONFIG_NO_FORMATTING */
 599
 600 #endif //_FMTABLE
 601 //eof
 602