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
35 U_NAMESPACE_BEGIN
36
37 class CharString;
38
39 namespace number::impl {
40 class DecimalQuantity;
41 }
42
43 /**
44 * Formattable objects can be passed to the Format class or
45 * its subclasses for formatting. Formattable is a thin wrapper
46 * class which interconverts between the primitive numeric types
47 * (double, long, etc.) as well as UDate and UnicodeString.
48 *
49 * <p>Internally, a Formattable object is a union of primitive types.
50 * As such, it can only store one flavor of data at a time. To
51 * determine what flavor of data it contains, use the getType method.
52 *
53 * <p>As of ICU 3.0, Formattable may also wrap a UObject pointer,
54 * which it owns. This allows an instance of any ICU class to be
55 * encapsulated in a Formattable. For legacy reasons and for
56 * efficiency, primitive numeric types are still stored directly
57 * within a Formattable.
58 *
59 * <p>The Formattable class is not suitable for subclassing.
60 *
61 * <p>See UFormattable for a C wrapper.
62 */
63 class U_I18N_API Formattable : public UObject {
64 public:
65 /**
66 * This enum is only used to let callers distinguish between
67 * the Formattable(UDate) constructor and the Formattable(double)
68 * constructor; the compiler cannot distinguish the signatures,
69 * since UDate is currently typedefed to be either double or long.
70 * If UDate is changed later to be a bonafide class
71 * or struct, then we no longer need this enum.
72 * @stable ICU 2.4
73 */
74 enum ISDATE { kIsDate };
75
76 /**
77 * Default constructor
78 * @stable ICU 2.4
79 */
80 Formattable(); // Type kLong, value 0
81
82 /**
83 * Creates a Formattable object with a UDate instance.
84 * @param d the UDate instance.
85 * @param flag the flag to indicate this is a date. Always set it to kIsDate
86 * @stable ICU 2.0
87 */
88 Formattable(UDate d, ISDATE flag);
89
90 /**
91 * Creates a Formattable object with a double number.
92 * @param d the double number.
93 * @stable ICU 2.0
94 */
95 Formattable(double d);
96
97 /**
98 * Creates a Formattable object with a long number.
99 * @param l the long number.
100 * @stable ICU 2.0
101 */
102 Formattable(int32_t l);
103
104 /**
105 * Creates a Formattable object with an int64_t number
106 * @param ll the int64_t number.
107 * @stable ICU 2.8
108 */
109 Formattable(int64_t ll);
110
111 #if !UCONFIG_NO_CONVERSION
112 /**
113 * Creates a Formattable object with a char string pointer.
114 * Assumes that the char string is null terminated.
115 * @param strToCopy the char string.
116 * @stable ICU 2.0
117 */
118 Formattable(const char* strToCopy);
119 #endif
120
121 /**
122 * Creates a Formattable object of an appropriate numeric type from a
123 * a decimal number in string form. The Formattable will retain the
124 * full precision of the input in decimal format, even when it exceeds
125 * what can be represented by a double or int64_t.
126 *
127 * @param number the unformatted (not localized) string representation
128 * of the Decimal number.
129 * @param status the error code. Possible errors include U_INVALID_FORMAT_ERROR
130 * if the format of the string does not conform to that of a
131 * decimal number.
132 * @stable ICU 4.4
133 */
134 Formattable(StringPiece number, UErrorCode &status);
135
136 /**
137 * Creates a Formattable object with a UnicodeString object to copy from.
138 * @param strToCopy the UnicodeString string.
139 * @stable ICU 2.0
140 */
141 Formattable(const UnicodeString& strToCopy);
142
143 /**
144 * Creates a Formattable object with a UnicodeString object to adopt from.
145 * @param strToAdopt the UnicodeString string.
146 * @stable ICU 2.0
147 */
148 Formattable(UnicodeString* strToAdopt);
149
150 /**
151 * Creates a Formattable object with an array of Formattable objects.
152 * @param arrayToCopy the Formattable object array.
153 * @param count the array count.
154 * @stable ICU 2.0
155 */
156 Formattable(const Formattable* arrayToCopy, int32_t count);
157
158 /**
159 * Creates a Formattable object that adopts the given UObject.
160 * @param objectToAdopt the UObject to set this object to
161 * @stable ICU 3.0
162 */
163 Formattable(UObject* objectToAdopt);
164
165 /**
166 * Copy constructor.
167 * @stable ICU 2.0
168 */
169 Formattable(const Formattable&);
170
171 /**
172 * Assignment operator.
173 * @param rhs The Formattable object to copy into this object.
174 * @stable ICU 2.0
175 */
176 Formattable& operator=(const Formattable &rhs);
177
178 /**
179 * Equality comparison.
180 * @param other the object to be compared with.
181 * @return true if other are equal to this, false otherwise.
182 * @stable ICU 2.0
183 */
184 bool operator==(const Formattable &other) const;
185
186 /**
187 * Equality operator.
188 * @param other the object to be compared with.
189 * @return true if other are unequal to this, false otherwise.
190 * @stable ICU 2.0
191 */
192 bool operator!=(const Formattable& other) const
193 { return !operator==(other); }
194
195 /**
196 * Destructor.
197 * @stable ICU 2.0
198 */
199 virtual ~Formattable();
200
201 /**
202 * Clone this object.
203 * Clones can be used concurrently in multiple threads.
204 * If an error occurs, then nullptr is returned.
205 * The caller must delete the clone.
206 *
207 * @return a clone of this object
208 *
209 * @see getDynamicClassID
210 * @stable ICU 2.8
211 */
212 Formattable *clone() const;
213
214 /**
215 * Selector for flavor of data type contained within a
216 * Formattable object. Formattable is a union of several
217 * different types, and at any time contains exactly one type.
218 * @stable ICU 2.4
219 */
220 enum Type {
221 /**
222 * Selector indicating a UDate value. Use getDate to retrieve
223 * the value.
224 * @stable ICU 2.4
225 */
226 kDate,
227
228 /**
229 * Selector indicating a double value. Use getDouble to
230 * retrieve the value.
231 * @stable ICU 2.4
232 */
233 kDouble,
234
235 /**
236 * Selector indicating a 32-bit integer value. Use getLong to
237 * retrieve the value.
238 * @stable ICU 2.4
239 */
240 kLong,
241
242 /**
243 * Selector indicating a UnicodeString value. Use getString
244 * to retrieve the value.
245 * @stable ICU 2.4
246 */
247 kString,
248
249 /**
250 * Selector indicating an array of Formattables. Use getArray
251 * to retrieve the value.
252 * @stable ICU 2.4
253 */
254 kArray,
255
256 /**
257 * Selector indicating a 64-bit integer value. Use getInt64
258 * to retrieve the value.
259 * @stable ICU 2.8
260 */
261 kInt64,
262
263 /**
264 * Selector indicating a UObject value. Use getObject to
265 * retrieve the value.
266 * @stable ICU 3.0
267 */
268 kObject
269 };
270
271 /**
272 * Gets the data type of this Formattable object.
273 * @return the data type of this Formattable object.
274 * @stable ICU 2.0
275 */
276 Type getType() const;
277
278 /**
279 * Returns true if the data type of this Formattable object
280 * is kDouble, kLong, or kInt64
281 * @return true if this is a pure numeric object
282 * @stable ICU 3.0
283 */
284 UBool isNumeric() const;
285
286 /**
287 * Gets the double value of this object. If this object is not of type
288 * kDouble then the result is undefined.
289 * @return the double value of this object.
290 * @stable ICU 2.0
291 */
getDouble()292 double getDouble() const { return fValue.fDouble; }
293
294 /**
295 * Gets the double value of this object. If this object is of type
296 * long, int64 or Decimal Number then a conversion is performed, with
297 * possible loss of precision. If the type is kObject and the
298 * object is a Measure, then the result of
299 * getNumber().getDouble(status) is returned. If this object is
300 * neither a numeric type nor a Measure, then 0 is returned and
301 * the status is set to U_INVALID_FORMAT_ERROR.
302 * @param status the error code
303 * @return the double value of this object.
304 * @stable ICU 3.0
305 */
306 double getDouble(UErrorCode& status) const;
307
308 /**
309 * Gets the long value of this object. If this object is not of type
310 * kLong then the result is undefined.
311 * @return the long value of this object.
312 * @stable ICU 2.0
313 */
getLong()314 int32_t getLong() const { return (int32_t)fValue.fInt64; }
315
316 /**
317 * Gets the long value of this object. If the magnitude is too
318 * large to fit in a long, then the maximum or minimum long value,
319 * as appropriate, is returned and the status is set to
320 * U_INVALID_FORMAT_ERROR. If this object is of type kInt64 and
321 * it fits within a long, then no precision is lost. If it is of
322 * type kDouble, then a conversion is performed, with
323 * truncation of any fractional part. If the type is kObject and
324 * the object is a Measure, then the result of
325 * getNumber().getLong(status) is returned. If this object is
326 * neither a numeric type nor a Measure, then 0 is returned and
327 * the status is set to U_INVALID_FORMAT_ERROR.
328 * @param status the error code
329 * @return the long value of this object.
330 * @stable ICU 3.0
331 */
332 int32_t getLong(UErrorCode& status) const;
333
334 /**
335 * Gets the int64 value of this object. If this object is not of type
336 * kInt64 then the result is undefined.
337 * @return the int64 value of this object.
338 * @stable ICU 2.8
339 */
getInt64()340 int64_t getInt64() const { return fValue.fInt64; }
341
342 /**
343 * Gets the int64 value of this object. If this object is of a numeric
344 * type and the magnitude is too large to fit in an int64, then
345 * the maximum or minimum int64 value, as appropriate, is returned
346 * and the status is set to U_INVALID_FORMAT_ERROR. If the
347 * magnitude fits in an int64, then a casting conversion is
348 * performed, with truncation of any fractional part. If the type
349 * is kObject and the object is a Measure, then the result of
350 * getNumber().getDouble(status) is returned. If this object is
351 * neither a numeric type nor a Measure, then 0 is returned and
352 * the status is set to U_INVALID_FORMAT_ERROR.
353 * @param status the error code
354 * @return the int64 value of this object.
355 * @stable ICU 3.0
356 */
357 int64_t getInt64(UErrorCode& status) const;
358
359 /**
360 * Gets the Date value of this object. If this object is not of type
361 * kDate then the result is undefined.
362 * @return the Date value of this object.
363 * @stable ICU 2.0
364 */
getDate()365 UDate getDate() const { return fValue.fDate; }
366
367 /**
368 * Gets the Date value of this object. If the type is not a date,
369 * status is set to U_INVALID_FORMAT_ERROR and the return value is
370 * undefined.
371 * @param status the error code.
372 * @return the Date value of this object.
373 * @stable ICU 3.0
374 */
375 UDate getDate(UErrorCode& status) const;
376
377 /**
378 * Gets the string value of this object. If this object is not of type
379 * kString then the result is undefined.
380 * @param result Output param to receive the Date value of this object.
381 * @return A reference to 'result'.
382 * @stable ICU 2.0
383 */
getString(UnicodeString & result)384 UnicodeString& getString(UnicodeString& result) const
385 { result=*fValue.fString; return result; }
386
387 /**
388 * Gets the string value of this object. If the type is not a
389 * string, status is set to U_INVALID_FORMAT_ERROR and a bogus
390 * string is returned.
391 * @param result Output param to receive the Date value of this object.
392 * @param status the error code.
393 * @return A reference to 'result'.
394 * @stable ICU 3.0
395 */
396 UnicodeString& getString(UnicodeString& result, UErrorCode& status) const;
397
398 /**
399 * Gets a const reference to the string value of this object. If
400 * this object is not of type kString then the result is
401 * undefined.
402 * @return a const reference to the string value of this object.
403 * @stable ICU 2.0
404 */
405 inline const UnicodeString& getString() const;
406
407 /**
408 * Gets a const reference to the string value of this object. If
409 * the type is not a string, status is set to
410 * U_INVALID_FORMAT_ERROR and the result is a bogus string.
411 * @param status the error code.
412 * @return a const reference to the string value of this object.
413 * @stable ICU 3.0
414 */
415 const UnicodeString& getString(UErrorCode& status) const;
416
417 /**
418 * Gets a reference to the string value of this object. If this
419 * object is not of type kString then the result is undefined.
420 * @return a reference to the string value of this object.
421 * @stable ICU 2.0
422 */
423 inline UnicodeString& getString();
424
425 /**
426 * Gets a reference to the string value of this object. If the
427 * type is not a string, status is set to U_INVALID_FORMAT_ERROR
428 * and the result is a bogus string.
429 * @param status the error code.
430 * @return a reference to the string value of this object.
431 * @stable ICU 3.0
432 */
433 UnicodeString& getString(UErrorCode& status);
434
435 /**
436 * Gets the array value and count of this object. If this object
437 * is not of type kArray then the result is undefined.
438 * @param count fill-in with the count of this object.
439 * @return the array value of this object.
440 * @stable ICU 2.0
441 */
getArray(int32_t & count)442 const Formattable* getArray(int32_t& count) const
443 { count=fValue.fArrayAndCount.fCount; return fValue.fArrayAndCount.fArray; }
444
445 /**
446 * Gets the array value and count of this object. If the type is
447 * not an array, status is set to U_INVALID_FORMAT_ERROR, count is
448 * set to 0, and the result is nullptr.
449 * @param count fill-in with the count of this object.
450 * @param status the error code.
451 * @return the array value of this object.
452 * @stable ICU 3.0
453 */
454 const Formattable* getArray(int32_t& count, UErrorCode& status) const;
455
456 /**
457 * Accesses the specified element in the array value of this
458 * Formattable object. If this object is not of type kArray then
459 * the result is undefined.
460 * @param index the specified index.
461 * @return the accessed element in the array.
462 * @stable ICU 2.0
463 */
464 Formattable& operator[](int32_t index) { return fValue.fArrayAndCount.fArray[index]; }
465
466 /**
467 * Returns a pointer to the UObject contained within this
468 * formattable, or nullptr if this object does not contain a UObject.
469 * @return a UObject pointer, or nullptr
470 * @stable ICU 3.0
471 */
472 const UObject* getObject() const;
473
474 /**
475 * Returns a numeric string representation of the number contained within this
476 * formattable, or nullptr if this object does not contain numeric type.
477 * For values obtained by parsing, the returned decimal number retains
478 * the full precision and range of the original input, unconstrained by
479 * the limits of a double floating point or a 64 bit int.
480 *
481 * This function is not thread safe, and therefore is not declared const,
482 * even though it is logically const.
483 *
484 * Possible errors include U_MEMORY_ALLOCATION_ERROR, and
485 * U_INVALID_STATE if the formattable object has not been set to
486 * a numeric type.
487 *
488 * @param status the error code.
489 * @return the unformatted string representation of a number.
490 * @stable ICU 4.4
491 */
492 StringPiece getDecimalNumber(UErrorCode &status);
493
494 /**
495 * Sets the double value of this object and changes the type to
496 * kDouble.
497 * @param d the new double value to be set.
498 * @stable ICU 2.0
499 */
500 void setDouble(double d);
501
502 /**
503 * Sets the long value of this object and changes the type to
504 * kLong.
505 * @param l the new long value to be set.
506 * @stable ICU 2.0
507 */
508 void setLong(int32_t l);
509
510 /**
511 * Sets the int64 value of this object and changes the type to
512 * kInt64.
513 * @param ll the new int64 value to be set.
514 * @stable ICU 2.8
515 */
516 void setInt64(int64_t ll);
517
518 /**
519 * Sets the Date value of this object and changes the type to
520 * kDate.
521 * @param d the new Date value to be set.
522 * @stable ICU 2.0
523 */
524 void setDate(UDate d);
525
526 /**
527 * Sets the string value of this object and changes the type to
528 * kString.
529 * @param stringToCopy the new string value to be set.
530 * @stable ICU 2.0
531 */
532 void setString(const UnicodeString& stringToCopy);
533
534 /**
535 * Sets the array value and count of this object and changes the
536 * type to kArray.
537 * @param array the array value.
538 * @param count the number of array elements to be copied.
539 * @stable ICU 2.0
540 */
541 void setArray(const Formattable* array, int32_t count);
542
543 /**
544 * Sets and adopts the string value and count of this object and
545 * changes the type to kArray.
546 * @param stringToAdopt the new string value to be adopted.
547 * @stable ICU 2.0
548 */
549 void adoptString(UnicodeString* stringToAdopt);
550
551 /**
552 * Sets and adopts the array value and count of this object and
553 * changes the type to kArray.
554 * @stable ICU 2.0
555 */
556 void adoptArray(Formattable* array, int32_t count);
557
558 /**
559 * Sets and adopts the UObject value of this object and changes
560 * the type to kObject. After this call, the caller must not
561 * delete the given object.
562 * @param objectToAdopt the UObject value to be adopted
563 * @stable ICU 3.0
564 */
565 void adoptObject(UObject* objectToAdopt);
566
567 /**
568 * Sets the the numeric value from a decimal number string, and changes
569 * the type to to a numeric type appropriate for the number.
570 * The syntax of the number is a "numeric string"
571 * as defined in the Decimal Arithmetic Specification, available at
572 * http://speleotrove.com/decimal
573 * The full precision and range of the input number will be retained,
574 * even when it exceeds what can be represented by a double or an int64.
575 *
576 * @param numberString a string representation of the unformatted decimal number.
577 * @param status the error code. Set to U_INVALID_FORMAT_ERROR if the
578 * incoming string is not a valid decimal number.
579 * @stable ICU 4.4
580 */
581 void setDecimalNumber(StringPiece numberString,
582 UErrorCode &status);
583
584 /**
585 * ICU "poor man's RTTI", returns a UClassID for the actual class.
586 *
587 * @stable ICU 2.2
588 */
589 virtual UClassID getDynamicClassID() const override;
590
591 /**
592 * ICU "poor man's RTTI", returns a UClassID for this class.
593 *
594 * @stable ICU 2.2
595 */
596 static UClassID U_EXPORT2 getStaticClassID();
597
598 /**
599 * Convert the UFormattable to a Formattable. Internally, this is a reinterpret_cast.
600 * @param fmt a valid UFormattable
601 * @return the UFormattable as a Formattable object pointer. This is an alias to the original
602 * UFormattable, and so is only valid while the original argument remains in scope.
603 * @stable ICU 52
604 */
605 static inline Formattable *fromUFormattable(UFormattable *fmt);
606
607 /**
608 * Convert the const UFormattable to a const Formattable. Internally, this is a reinterpret_cast.
609 * @param fmt a valid UFormattable
610 * @return the UFormattable as a Formattable object pointer. This is an alias to the original
611 * UFormattable, and so is only valid while the original argument remains in scope.
612 * @stable ICU 52
613 */
614 static inline const Formattable *fromUFormattable(const UFormattable *fmt);
615
616 /**
617 * Convert this object pointer to a UFormattable.
618 * @return this object as a UFormattable pointer. This is an alias to this object,
619 * and so is only valid while this object remains in scope.
620 * @stable ICU 52
621 */
622 inline UFormattable *toUFormattable();
623
624 /**
625 * Convert this object pointer to a UFormattable.
626 * @return this object as a UFormattable pointer. This is an alias to this object,
627 * and so is only valid while this object remains in scope.
628 * @stable ICU 52
629 */
630 inline const UFormattable *toUFormattable() const;
631
632 #ifndef U_HIDE_DEPRECATED_API
633 /**
634 * Deprecated variant of getLong(UErrorCode&).
635 * @param status the error code
636 * @return the long value of this object.
637 * @deprecated ICU 3.0 use getLong(UErrorCode&) instead
638 */
639 inline int32_t getLong(UErrorCode* status) const;
640 #endif /* U_HIDE_DEPRECATED_API */
641
642 #ifndef U_HIDE_INTERNAL_API
643 /**
644 * Internal function, do not use.
645 * TODO: figure out how to make this be non-public.
646 * NumberFormat::format(Formattable, ...
647 * needs to get at the DecimalQuantity, if it exists, for
648 * big decimal formatting.
649 * @internal
650 */
getDecimalQuantity()651 number::impl::DecimalQuantity *getDecimalQuantity() const { return fDecimalQuantity;}
652
653 /**
654 * Export the value of this Formattable to a DecimalQuantity.
655 * @internal
656 */
657 void populateDecimalQuantity(number::impl::DecimalQuantity& output, UErrorCode& status) const;
658
659 /**
660 * Adopt, and set value from, a DecimalQuantity
661 * Internal Function, do not use.
662 * @param dq the DecimalQuantity to be adopted
663 * @internal
664 */
665 void adoptDecimalQuantity(number::impl::DecimalQuantity *dq);
666
667 /**
668 * Internal function to return the CharString pointer.
669 * @param status error code
670 * @return pointer to the CharString - may become invalid if the object is modified
671 * @internal
672 */
673 CharString *internalGetCharString(UErrorCode &status);
674
675 #endif /* U_HIDE_INTERNAL_API */
676
677 private:
678 /**
679 * Cleans up the memory for unwanted values. For example, the adopted
680 * string or array objects.
681 */
682 void dispose();
683
684 /**
685 * Common initialization, for use by constructors.
686 */
687 void init();
688
689 UnicodeString* getBogus() const;
690
691 union {
692 UObject* fObject;
693 UnicodeString* fString;
694 double fDouble;
695 int64_t fInt64;
696 UDate fDate;
697 struct {
698 Formattable* fArray;
699 int32_t fCount;
700 } fArrayAndCount;
701 } fValue;
702
703 CharString *fDecimalStr;
704
705 number::impl::DecimalQuantity *fDecimalQuantity;
706
707 Type fType;
708 UnicodeString fBogus; // Bogus string when it's needed.
709 };
710
getDate(UErrorCode & status)711 inline UDate Formattable::getDate(UErrorCode& status) const {
712 if (fType != kDate) {
713 if (U_SUCCESS(status)) {
714 status = U_INVALID_FORMAT_ERROR;
715 }
716 return 0;
717 }
718 return fValue.fDate;
719 }
720
getString()721 inline const UnicodeString& Formattable::getString() const {
722 return *fValue.fString;
723 }
724
getString()725 inline UnicodeString& Formattable::getString() {
726 return *fValue.fString;
727 }
728
729 #ifndef U_HIDE_DEPRECATED_API
getLong(UErrorCode * status)730 inline int32_t Formattable::getLong(UErrorCode* status) const {
731 return getLong(*status);
732 }
733 #endif /* U_HIDE_DEPRECATED_API */
734
toUFormattable()735 inline UFormattable* Formattable::toUFormattable() {
736 return reinterpret_cast<UFormattable*>(this);
737 }
738
toUFormattable()739 inline const UFormattable* Formattable::toUFormattable() const {
740 return reinterpret_cast<const UFormattable*>(this);
741 }
742
fromUFormattable(UFormattable * fmt)743 inline Formattable* Formattable::fromUFormattable(UFormattable *fmt) {
744 return reinterpret_cast<Formattable *>(fmt);
745 }
746
fromUFormattable(const UFormattable * fmt)747 inline const Formattable* Formattable::fromUFormattable(const UFormattable *fmt) {
748 return reinterpret_cast<const Formattable *>(fmt);
749 }
750
751 U_NAMESPACE_END
752
753 #endif /* #if !UCONFIG_NO_FORMATTING */
754
755 #endif /* U_SHOW_CPLUSPLUS_API */
756
757 #endif //_FMTABLE
758 //eof
759