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 592
