1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4********************************************************************************
5* Copyright (C) 1997-2014, International Business Machines
6* Corporation and others. All Rights Reserved.
7********************************************************************************
8*
9* File FMTABLE.H
10*
11* Modification History:
12*
13* Date Name Description
14* 02/29/97 aliu Creation.
15********************************************************************************
16*/
17#ifndef FMTABLE_H
18#define FMTABLE_H
19
20#include "unicode/utypes.h"
21
22#if U_SHOW_CPLUSPLUS_API
23
24/**
25 * \file
26 * \brief C++ API: Formattable is a thin wrapper for primitive types used for formatting and parsing
27 */
28
29#if !UCONFIG_NO_FORMATTING
30
31#include "unicode/unistr.h"
32#include "unicode/stringpiece.h"
33#include "unicode/uformattable.h"
34
35U_NAMESPACE_BEGIN
36
37class CharString;
38namespace number {
39namespace impl {
40class DecimalQuantity;
41}
42}
43
44/**
45 * Formattable objects can be passed to the Format class or
46 * its subclasses for formatting. Formattable is a thin wrapper
47 * class which interconverts between the primitive numeric types
48 * (double, long, etc.) as well as UDate and UnicodeString.
49 *
50 * <p>Internally, a Formattable object is a union of primitive types.
51 * As such, it can only store one flavor of data at a time. To
52 * determine what flavor of data it contains, use the getType method.
53 *
54 * <p>As of ICU 3.0, Formattable may also wrap a UObject pointer,
55 * which it owns. This allows an instance of any ICU class to be
56 * encapsulated in a Formattable. For legacy reasons and for
57 * efficiency, primitive numeric types are still stored directly
58 * within a Formattable.
59 *
60 * <p>The Formattable class is not suitable for subclassing.
61 *
62 * <p>See UFormattable for a C wrapper.
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 or 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(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, or kInt64
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, 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(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 /**
600 * Convert the UFormattable to a Formattable. Internally, this is a reinterpret_cast.
601 * @param fmt a valid UFormattable
602 * @return the UFormattable as a Formattable object pointer. This is an alias to the original
603 * UFormattable, and so is only valid while the original argument remains in scope.
604 * @stable ICU 52
605 */
606 static inline Formattable *fromUFormattable(UFormattable *fmt);
607
608 /**
609 * Convert the const UFormattable to a const Formattable. Internally, this is a reinterpret_cast.
610 * @param fmt a valid UFormattable
611 * @return the UFormattable as a Formattable object pointer. This is an alias to the original
612 * UFormattable, and so is only valid while the original argument remains in scope.
613 * @stable ICU 52
614 */
615 static inline const Formattable *fromUFormattable(const UFormattable *fmt);
616
617 /**
618 * Convert this object pointer to a UFormattable.
619 * @return this object as a UFormattable pointer. This is an alias to this object,
620 * and so is only valid while this object remains in scope.
621 * @stable ICU 52
622 */
623 inline UFormattable *toUFormattable();
624
625 /**
626 * Convert this object pointer to a UFormattable.
627 * @return this object as a UFormattable pointer. This is an alias to this object,
628 * and so is only valid while this object remains in scope.
629 * @stable ICU 52
630 */
631 inline const UFormattable *toUFormattable() const;
632
633#ifndef U_HIDE_DEPRECATED_API
634 /**
635 * Deprecated variant of getLong(UErrorCode&).
636 * @param status the error code
637 * @return the long value of this object.
638 * @deprecated ICU 3.0 use getLong(UErrorCode&) instead
639 */
640 inline int32_t getLong(UErrorCode* status) const;
641#endif /* U_HIDE_DEPRECATED_API */
642
643#ifndef U_HIDE_INTERNAL_API
644 /**
645 * Internal function, do not use.
646 * TODO: figure out how to make this be non-public.
647 * NumberFormat::format(Formattable, ...
648 * needs to get at the DecimalQuantity, if it exists, for
649 * big decimal formatting.
650 * @internal
651 */
652 number::impl::DecimalQuantity *getDecimalQuantity() const { return fDecimalQuantity;}
653
654 /**
655 * Export the value of this Formattable to a DecimalQuantity.
656 * @internal
657 */
658 void populateDecimalQuantity(number::impl::DecimalQuantity& output, UErrorCode& status) const;
659
660 /**
661 * Adopt, and set value from, a DecimalQuantity
662 * Internal Function, do not use.
663 * @param dq the DecimalQuantity to be adopted
664 * @internal
665 */
666 void adoptDecimalQuantity(number::impl::DecimalQuantity *dq);
667
668 /**
669 * Internal function to return the CharString pointer.
670 * @param status error code
671 * @return pointer to the CharString - may become invalid if the object is modified
672 * @internal
673 */
674 CharString *internalGetCharString(UErrorCode &status);
675
676#endif /* U_HIDE_INTERNAL_API */
677
678private:
679 /**
680 * Cleans up the memory for unwanted values. For example, the adopted
681 * string or array objects.
682 */
683 void dispose(void);
684
685 /**
686 * Common initialization, for use by constructors.
687 */
688 void init();
689
690 UnicodeString* getBogus() const;
691
692 union {
693 UObject* fObject;
694 UnicodeString* fString;
695 double fDouble;
696 int64_t fInt64;
697 UDate fDate;
698 struct {
699 Formattable* fArray;
700 int32_t fCount;
701 } fArrayAndCount;
702 } fValue;
703
704 CharString *fDecimalStr;
705
706 number::impl::DecimalQuantity *fDecimalQuantity;
707
708 Type fType;
709 UnicodeString fBogus; // Bogus string when it's needed.
710};
711
712inline UDate Formattable::getDate(UErrorCode& status) const {
713 if (fType != kDate) {
714 if (U_SUCCESS(status)) {
715 status = U_INVALID_FORMAT_ERROR;
716 }
717 return 0;
718 }
719 return fValue.fDate;
720}
721
722inline const UnicodeString& Formattable::getString(void) const {
723 return *fValue.fString;
724}
725
726inline UnicodeString& Formattable::getString(void) {
727 return *fValue.fString;
728}
729
730#ifndef U_HIDE_DEPRECATED_API
731inline int32_t Formattable::getLong(UErrorCode* status) const {
732 return getLong(*status);
733}
734#endif /* U_HIDE_DEPRECATED_API */
735
736inline UFormattable* Formattable::toUFormattable() {
737 return reinterpret_cast<UFormattable*>(this);
738}
739
740inline const UFormattable* Formattable::toUFormattable() const {
741 return reinterpret_cast<const UFormattable*>(this);
742}
743
744inline Formattable* Formattable::fromUFormattable(UFormattable *fmt) {
745 return reinterpret_cast<Formattable *>(fmt);
746}
747
748inline const Formattable* Formattable::fromUFormattable(const UFormattable *fmt) {
749 return reinterpret_cast<const Formattable *>(fmt);
750}
751
752U_NAMESPACE_END
753
754#endif /* #if !UCONFIG_NO_FORMATTING */
755
756#endif /* U_SHOW_CPLUSPLUS_API */
757
758#endif //_FMTABLE
759//eof
760