icuSources/i18n/unicode/fmtable.h

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