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 */
getDouble(void)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 */
getLong(void)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 */
getInt64(void)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 */
getDate()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 */
getString(UnicodeString & result)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 */
getArray(int32_t & count)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
getDate(UErrorCode & status)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
getString(void)573 inline const UnicodeString& Formattable::getString(void) const {
574 return *fValue.fString;
575 }
576
getString(void)577 inline UnicodeString& Formattable::getString(void) {
578 return *fValue.fString;
579 }
580
getLong(UErrorCode * status)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