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 29U_NAMESPACE_BEGIN 30 31class CharString; 32class 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 */ 64class U_I18N_API Formattable : public UObject { 65public: 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 634private: 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 670inline 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 680inline const UnicodeString& Formattable::getString(void) const { 681 return *fValue.fString; 682} 683 684inline UnicodeString& Formattable::getString(void) { 685 return *fValue.fString; 686} 687 688inline int32_t Formattable::getLong(UErrorCode* status) const { 689 return getLong(*status); 690} 691 692 693U_NAMESPACE_END 694 695#endif /* #if !UCONFIG_NO_FORMATTING */ 696 697#endif //_FMTABLE 698//eof 699