OLD | NEW |
1 /* | 1 /* |
2 ******************************************************************************** | 2 ******************************************************************************** |
3 * Copyright (C) 2013, International Business Machines Corporation and others. | 3 * Copyright (C) 2013-2014, International Business Machines Corporation and other
s. |
4 * All Rights Reserved. | 4 * All Rights Reserved. |
5 ******************************************************************************** | 5 ******************************************************************************** |
6 * | 6 * |
7 * File UFORMATTABLE.H | 7 * File UFORMATTABLE.H |
8 * | 8 * |
9 * Modification History: | 9 * Modification History: |
10 * | 10 * |
11 * Date Name Description | 11 * Date Name Description |
12 * 2013 Jun 7 srl New | 12 * 2013 Jun 7 srl New |
13 ******************************************************************************** | 13 ******************************************************************************** |
(...skipping 11 matching lines...) Expand all Loading... |
25 * See {@link unum_parseToUFormattable} for example code. | 25 * See {@link unum_parseToUFormattable} for example code. |
26 */ | 26 */ |
27 | 27 |
28 #ifndef UFORMATTABLE_H | 28 #ifndef UFORMATTABLE_H |
29 #define UFORMATTABLE_H | 29 #define UFORMATTABLE_H |
30 | 30 |
31 #include "unicode/utypes.h" | 31 #include "unicode/utypes.h" |
32 | 32 |
33 #if !UCONFIG_NO_FORMATTING | 33 #if !UCONFIG_NO_FORMATTING |
34 | 34 |
35 #ifndef U_HIDE_DRAFT_API | |
36 | |
37 #include "unicode/localpointer.h" | 35 #include "unicode/localpointer.h" |
38 | 36 |
39 /** | 37 /** |
40 * Enum designating the type of a UFormattable instance. | 38 * Enum designating the type of a UFormattable instance. |
41 * Practically, this indicates which of the getters would return without convers
ion | 39 * Practically, this indicates which of the getters would return without convers
ion |
42 * or error. | 40 * or error. |
43 * @see icu::Formattable::Type | 41 * @see icu::Formattable::Type |
44 * @draft ICU 52 | 42 * @stable ICU 52 |
45 */ | 43 */ |
46 typedef enum UFormattableType { | 44 typedef enum UFormattableType { |
47 UFMT_DATE = 0, /**< ufmt_getDate() will return without conversion. @see ufmt_g
etDate*/ | 45 UFMT_DATE = 0, /**< ufmt_getDate() will return without conversion. @see ufmt_g
etDate*/ |
48 UFMT_DOUBLE, /**< ufmt_getDouble() will return without conversion. @see ufm
t_getDouble*/ | 46 UFMT_DOUBLE, /**< ufmt_getDouble() will return without conversion. @see ufm
t_getDouble*/ |
49 UFMT_LONG, /**< ufmt_getLong() will return without conversion. @see ufmt_g
etLong */ | 47 UFMT_LONG, /**< ufmt_getLong() will return without conversion. @see ufmt_g
etLong */ |
50 UFMT_STRING, /**< ufmt_getUChars() will return without conversion. @see ufm
t_getUChars*/ | 48 UFMT_STRING, /**< ufmt_getUChars() will return without conversion. @see ufm
t_getUChars*/ |
51 UFMT_ARRAY, /**< ufmt_countArray() and ufmt_getArray() will return the valu
e. @see ufmt_getArrayItemByIndex */ | 49 UFMT_ARRAY, /**< ufmt_countArray() and ufmt_getArray() will return the valu
e. @see ufmt_getArrayItemByIndex */ |
52 UFMT_INT64, /**< ufmt_getInt64() will return without conversion. @see ufmt_
getInt64 */ | 50 UFMT_INT64, /**< ufmt_getInt64() will return without conversion. @see ufmt_
getInt64 */ |
53 UFMT_OBJECT, /**< ufmt_getObject() will return without conversion. @see ufm
t_getObject*/ | 51 UFMT_OBJECT, /**< ufmt_getObject() will return without conversion. @see ufm
t_getObject*/ |
54 UFMT_COUNT /**< Count of defined UFormattableType values */ | 52 UFMT_COUNT /**< Count of defined UFormattableType values */ |
55 } UFormattableType; | 53 } UFormattableType; |
56 | 54 |
57 | 55 |
58 /** | 56 /** |
59 * Opaque type representing various types of data which may be used for formatti
ng | 57 * Opaque type representing various types of data which may be used for formatti
ng |
60 * and parsing operations. | 58 * and parsing operations. |
61 * @see icu::Formattable | 59 * @see icu::Formattable |
62 * @draft ICU 52 | 60 * @stable ICU 52 |
63 */ | 61 */ |
64 typedef void *UFormattable; | 62 typedef void *UFormattable; |
65 | 63 |
66 /** | 64 /** |
67 * Initialize a UFormattable, to type UNUM_LONG, value 0 | 65 * Initialize a UFormattable, to type UNUM_LONG, value 0 |
68 * may return error if memory allocation failed. | 66 * may return error if memory allocation failed. |
69 * parameter status error code. | 67 * parameter status error code. |
70 * See {@link unum_parseToUFormattable} for example code. | 68 * See {@link unum_parseToUFormattable} for example code. |
71 * @draft ICU 52 | 69 * @stable ICU 52 |
72 * @return the new UFormattable | 70 * @return the new UFormattable |
73 * @see ufmt_close | 71 * @see ufmt_close |
74 * @see icu::Formattable::Formattable() | 72 * @see icu::Formattable::Formattable() |
75 */ | 73 */ |
76 U_DRAFT UFormattable* U_EXPORT2 | 74 U_STABLE UFormattable* U_EXPORT2 |
77 ufmt_open(UErrorCode* status); | 75 ufmt_open(UErrorCode* status); |
78 | 76 |
79 /** | 77 /** |
80 * Cleanup any additional memory allocated by this UFormattable. | 78 * Cleanup any additional memory allocated by this UFormattable. |
81 * @param fmt the formatter | 79 * @param fmt the formatter |
82 * @draft ICU 52 | 80 * @stable ICU 52 |
83 * @see ufmt_open | 81 * @see ufmt_open |
84 */ | 82 */ |
85 U_DRAFT void U_EXPORT2 | 83 U_STABLE void U_EXPORT2 |
86 ufmt_close(UFormattable* fmt); | 84 ufmt_close(UFormattable* fmt); |
87 | 85 |
88 #if U_SHOW_CPLUSPLUS_API | 86 #if U_SHOW_CPLUSPLUS_API |
89 | 87 |
90 U_NAMESPACE_BEGIN | 88 U_NAMESPACE_BEGIN |
91 | 89 |
92 /** | 90 /** |
93 * \class LocalUFormattablePointer | 91 * \class LocalUFormattablePointer |
94 * "Smart pointer" class, closes a UFormattable via ufmt_close(). | 92 * "Smart pointer" class, closes a UFormattable via ufmt_close(). |
95 * For most methods see the LocalPointerBase base class. | 93 * For most methods see the LocalPointerBase base class. |
96 * | 94 * |
97 * @see LocalPointerBase | 95 * @see LocalPointerBase |
98 * @see LocalPointer | 96 * @see LocalPointer |
99 * @draft ICU 52 | 97 * @stable ICU 52 |
100 */ | 98 */ |
101 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattablePointer, UFormattable, ufmt_close); | 99 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattablePointer, UFormattable, ufmt_close); |
102 | 100 |
103 U_NAMESPACE_END | 101 U_NAMESPACE_END |
104 | 102 |
105 #endif | 103 #endif |
106 | 104 |
107 /** | 105 /** |
108 * Return the type of this object | 106 * Return the type of this object |
109 * @param fmt the UFormattable object | 107 * @param fmt the UFormattable object |
110 * @param status status code - U_ILLEGAL_ARGUMENT_ERROR is returned if the UForm
attable contains data not supported by | 108 * @param status status code - U_ILLEGAL_ARGUMENT_ERROR is returned if the UForm
attable contains data not supported by |
111 * the API | 109 * the API |
112 * @return the value as a UFormattableType | 110 * @return the value as a UFormattableType |
113 * @see ufmt_isNumeric | 111 * @see ufmt_isNumeric |
114 * @see icu::Formattable::getType() const | 112 * @see icu::Formattable::getType() const |
115 * @draft ICU 52 | 113 * @stable ICU 52 |
116 */ | 114 */ |
117 U_DRAFT UFormattableType U_EXPORT2 | 115 U_STABLE UFormattableType U_EXPORT2 |
118 ufmt_getType(const UFormattable* fmt, UErrorCode *status); | 116 ufmt_getType(const UFormattable* fmt, UErrorCode *status); |
119 | 117 |
120 /** | 118 /** |
121 * Return whether the object is numeric. | 119 * Return whether the object is numeric. |
122 * @param fmt the UFormattable object | 120 * @param fmt the UFormattable object |
123 * @return true if the object is a double, long, or int64 value, else false. | 121 * @return true if the object is a double, long, or int64 value, else false. |
124 * @see ufmt_getType | 122 * @see ufmt_getType |
125 * @see icu::Formattable::isNumeric() const | 123 * @see icu::Formattable::isNumeric() const |
126 * @draft ICU 52 | 124 * @stable ICU 52 |
127 */ | 125 */ |
128 U_DRAFT UBool U_EXPORT2 | 126 U_STABLE UBool U_EXPORT2 |
129 ufmt_isNumeric(const UFormattable* fmt); | 127 ufmt_isNumeric(const UFormattable* fmt); |
130 | 128 |
131 /** | 129 /** |
132 * Gets the UDate value of this object. If the type is not of type UFMT_DATE, | 130 * Gets the UDate value of this object. If the type is not of type UFMT_DATE, |
133 * status is set to U_INVALID_FORMAT_ERROR and the return value is | 131 * status is set to U_INVALID_FORMAT_ERROR and the return value is |
134 * undefined. | 132 * undefined. |
135 * @param fmt the UFormattable object | 133 * @param fmt the UFormattable object |
136 * @param status the error code - any conversion or format errors | 134 * @param status the error code - any conversion or format errors |
137 * @return the value | 135 * @return the value |
138 * @draft ICU 52 | 136 * @stable ICU 52 |
139 * @see icu::Formattable::getDate(UErrorCode&) const | 137 * @see icu::Formattable::getDate(UErrorCode&) const |
140 */ | 138 */ |
141 U_DRAFT UDate U_EXPORT2 | 139 U_STABLE UDate U_EXPORT2 |
142 ufmt_getDate(const UFormattable* fmt, UErrorCode *status); | 140 ufmt_getDate(const UFormattable* fmt, UErrorCode *status); |
143 | 141 |
144 /** | 142 /** |
145 * Gets the double value of this object. If the type is not a UFMT_DOUBLE, or | 143 * Gets the double value of this object. If the type is not a UFMT_DOUBLE, or |
146 * if there are additional significant digits than fit in a double type, | 144 * if there are additional significant digits than fit in a double type, |
147 * a conversion is performed with possible loss of precision. | 145 * a conversion is performed with possible loss of precision. |
148 * If the type is UFMT_OBJECT and the | 146 * If the type is UFMT_OBJECT and the |
149 * object is a Measure, then the result of | 147 * object is a Measure, then the result of |
150 * getNumber().getDouble(status) is returned. If this object is | 148 * getNumber().getDouble(status) is returned. If this object is |
151 * neither a numeric type nor a Measure, then 0 is returned and | 149 * neither a numeric type nor a Measure, then 0 is returned and |
152 * the status is set to U_INVALID_FORMAT_ERROR. | 150 * the status is set to U_INVALID_FORMAT_ERROR. |
153 * @param fmt the UFormattable object | 151 * @param fmt the UFormattable object |
154 * @param status the error code - any conversion or format errors | 152 * @param status the error code - any conversion or format errors |
155 * @return the value | 153 * @return the value |
156 * @draft ICU 52 | 154 * @stable ICU 52 |
157 * @see icu::Formattable::getDouble(UErrorCode&) const | 155 * @see icu::Formattable::getDouble(UErrorCode&) const |
158 */ | 156 */ |
159 U_DRAFT double U_EXPORT2 | 157 U_STABLE double U_EXPORT2 |
160 ufmt_getDouble(UFormattable* fmt, UErrorCode *status); | 158 ufmt_getDouble(UFormattable* fmt, UErrorCode *status); |
161 | 159 |
162 /** | 160 /** |
163 * Gets the long (int32_t) value of this object. If the magnitude is too | 161 * Gets the long (int32_t) value of this object. If the magnitude is too |
164 * large to fit in a long, then the maximum or minimum long value, | 162 * large to fit in a long, then the maximum or minimum long value, |
165 * as appropriate, is returned and the status is set to | 163 * as appropriate, is returned and the status is set to |
166 * U_INVALID_FORMAT_ERROR. If this object is of type UFMT_INT64 and | 164 * U_INVALID_FORMAT_ERROR. If this object is of type UFMT_INT64 and |
167 * it fits within a long, then no precision is lost. If it is of | 165 * it fits within a long, then no precision is lost. If it is of |
168 * type kDouble or kDecimalNumber, then a conversion is peformed, with | 166 * type kDouble or kDecimalNumber, then a conversion is peformed, with |
169 * truncation of any fractional part. If the type is UFMT_OBJECT and | 167 * truncation of any fractional part. If the type is UFMT_OBJECT and |
170 * the object is a Measure, then the result of | 168 * the object is a Measure, then the result of |
171 * getNumber().getLong(status) is returned. If this object is | 169 * getNumber().getLong(status) is returned. If this object is |
172 * neither a numeric type nor a Measure, then 0 is returned and | 170 * neither a numeric type nor a Measure, then 0 is returned and |
173 * the status is set to U_INVALID_FORMAT_ERROR. | 171 * the status is set to U_INVALID_FORMAT_ERROR. |
174 * @param fmt the UFormattable object | 172 * @param fmt the UFormattable object |
175 * @param status the error code - any conversion or format errors | 173 * @param status the error code - any conversion or format errors |
176 * @return the value | 174 * @return the value |
177 * @draft ICU 52 | 175 * @stable ICU 52 |
178 * @see icu::Formattable::getLong(UErrorCode&) const | 176 * @see icu::Formattable::getLong(UErrorCode&) const |
179 */ | 177 */ |
180 U_DRAFT int32_t U_EXPORT2 | 178 U_STABLE int32_t U_EXPORT2 |
181 ufmt_getLong(UFormattable* fmt, UErrorCode *status); | 179 ufmt_getLong(UFormattable* fmt, UErrorCode *status); |
182 | 180 |
183 | 181 |
184 /** | 182 /** |
185 * Gets the int64_t value of this object. If this object is of a numeric | 183 * Gets the int64_t value of this object. If this object is of a numeric |
186 * type and the magnitude is too large to fit in an int64, then | 184 * type and the magnitude is too large to fit in an int64, then |
187 * the maximum or minimum int64 value, as appropriate, is returned | 185 * the maximum or minimum int64 value, as appropriate, is returned |
188 * and the status is set to U_INVALID_FORMAT_ERROR. If the | 186 * and the status is set to U_INVALID_FORMAT_ERROR. If the |
189 * magnitude fits in an int64, then a casting conversion is | 187 * magnitude fits in an int64, then a casting conversion is |
190 * peformed, with truncation of any fractional part. If the type | 188 * peformed, with truncation of any fractional part. If the type |
191 * is UFMT_OBJECT and the object is a Measure, then the result of | 189 * is UFMT_OBJECT and the object is a Measure, then the result of |
192 * getNumber().getDouble(status) is returned. If this object is | 190 * getNumber().getDouble(status) is returned. If this object is |
193 * neither a numeric type nor a Measure, then 0 is returned and | 191 * neither a numeric type nor a Measure, then 0 is returned and |
194 * the status is set to U_INVALID_FORMAT_ERROR. | 192 * the status is set to U_INVALID_FORMAT_ERROR. |
195 * @param fmt the UFormattable object | 193 * @param fmt the UFormattable object |
196 * @param status the error code - any conversion or format errors | 194 * @param status the error code - any conversion or format errors |
197 * @return the value | 195 * @return the value |
198 * @draft ICU 52 | 196 * @stable ICU 52 |
199 * @see icu::Formattable::getInt64(UErrorCode&) const | 197 * @see icu::Formattable::getInt64(UErrorCode&) const |
200 */ | 198 */ |
201 U_DRAFT int64_t U_EXPORT2 | 199 U_STABLE int64_t U_EXPORT2 |
202 ufmt_getInt64(UFormattable* fmt, UErrorCode *status); | 200 ufmt_getInt64(UFormattable* fmt, UErrorCode *status); |
203 | 201 |
204 /** | 202 /** |
205 * Returns a pointer to the UObject contained within this | 203 * Returns a pointer to the UObject contained within this |
206 * formattable (as a const void*), or NULL if this object | 204 * formattable (as a const void*), or NULL if this object |
207 * is not of type UFMT_OBJECT. | 205 * is not of type UFMT_OBJECT. |
208 * @param fmt the UFormattable object | 206 * @param fmt the UFormattable object |
209 * @param status the error code - any conversion or format errors | 207 * @param status the error code - any conversion or format errors |
210 * @return the value as a const void*. It is a polymorphic C++ object. | 208 * @return the value as a const void*. It is a polymorphic C++ object. |
211 * @draft ICU 52 | 209 * @stable ICU 52 |
212 * @see icu::Formattable::getObject() const | 210 * @see icu::Formattable::getObject() const |
213 */ | 211 */ |
214 U_DRAFT const void *U_EXPORT2 | 212 U_STABLE const void *U_EXPORT2 |
215 ufmt_getObject(const UFormattable* fmt, UErrorCode *status); | 213 ufmt_getObject(const UFormattable* fmt, UErrorCode *status); |
216 | 214 |
217 /** | 215 /** |
218 * Gets the string value of this object as a UChar string. If the type is not a | 216 * Gets the string value of this object as a UChar string. If the type is not a |
219 * string, status is set to U_INVALID_FORMAT_ERROR and a NULL pointer is returne
d. | 217 * string, status is set to U_INVALID_FORMAT_ERROR and a NULL pointer is returne
d. |
220 * This function is not thread safe and may modify the UFormattable if need be t
o terminate the string. | 218 * This function is not thread safe and may modify the UFormattable if need be t
o terminate the string. |
221 * The returned pointer is not valid if any other functions are called on this U
Formattable, or if the UFormattable is closed. | 219 * The returned pointer is not valid if any other functions are called on this U
Formattable, or if the UFormattable is closed. |
222 * @param fmt the UFormattable object | 220 * @param fmt the UFormattable object |
223 * @param status the error code - any conversion or format errors | 221 * @param status the error code - any conversion or format errors |
224 * @param len if non null, contains the string length on return | 222 * @param len if non null, contains the string length on return |
225 * @return the null terminated string value - must not be referenced after any o
ther functions are called on this UFormattable. | 223 * @return the null terminated string value - must not be referenced after any o
ther functions are called on this UFormattable. |
226 * @draft ICU 52 | 224 * @stable ICU 52 |
227 * @see icu::Formattable::getString(UnicodeString&)const | 225 * @see icu::Formattable::getString(UnicodeString&)const |
228 */ | 226 */ |
229 U_DRAFT const UChar* U_EXPORT2 | 227 U_STABLE const UChar* U_EXPORT2 |
230 ufmt_getUChars(UFormattable* fmt, int32_t *len, UErrorCode *status); | 228 ufmt_getUChars(UFormattable* fmt, int32_t *len, UErrorCode *status); |
231 | 229 |
232 /** | 230 /** |
233 * Get the number of array objects contained, if an array type UFMT_ARRAY | 231 * Get the number of array objects contained, if an array type UFMT_ARRAY |
234 * @param fmt the UFormattable object | 232 * @param fmt the UFormattable object |
235 * @param status the error code - any conversion or format errors. U_ILLEGAL_ARG
UMENT_ERROR if not an array type. | 233 * @param status the error code - any conversion or format errors. U_ILLEGAL_ARG
UMENT_ERROR if not an array type. |
236 * @return the number of array objects or undefined if not an array type | 234 * @return the number of array objects or undefined if not an array type |
237 * @draft ICU 52 | 235 * @stable ICU 52 |
238 * @see ufmt_getArrayItemByIndex | 236 * @see ufmt_getArrayItemByIndex |
239 */ | 237 */ |
240 U_DRAFT int32_t U_EXPORT2 | 238 U_STABLE int32_t U_EXPORT2 |
241 ufmt_getArrayLength(const UFormattable* fmt, UErrorCode *status); | 239 ufmt_getArrayLength(const UFormattable* fmt, UErrorCode *status); |
242 | 240 |
243 /** | 241 /** |
244 * Get the specified value from the array of UFormattables. Invalid if the objec
t is not an array type UFMT_ARRAY | 242 * Get the specified value from the array of UFormattables. Invalid if the objec
t is not an array type UFMT_ARRAY |
245 * @param fmt the UFormattable object | 243 * @param fmt the UFormattable object |
246 * @param n the number of the array to return (0 based). | 244 * @param n the number of the array to return (0 based). |
247 * @param status the error code - any conversion or format errors. Returns an er
ror if n is out of bounds. | 245 * @param status the error code - any conversion or format errors. Returns an er
ror if n is out of bounds. |
248 * @return the nth array value, only valid while the containing UFormattable is
valid. NULL if not an array. | 246 * @return the nth array value, only valid while the containing UFormattable is
valid. NULL if not an array. |
249 * @draft ICU 52 | 247 * @stable ICU 52 |
250 * @see icu::Formattable::getArray(int32_t&, UErrorCode&) const | 248 * @see icu::Formattable::getArray(int32_t&, UErrorCode&) const |
251 */ | 249 */ |
252 U_DRAFT UFormattable * U_EXPORT2 | 250 U_STABLE UFormattable * U_EXPORT2 |
253 ufmt_getArrayItemByIndex(UFormattable* fmt, int32_t n, UErrorCode *status); | 251 ufmt_getArrayItemByIndex(UFormattable* fmt, int32_t n, UErrorCode *status); |
254 | 252 |
255 /** | 253 /** |
256 * Returns a numeric string representation of the number contained within this | 254 * Returns a numeric string representation of the number contained within this |
257 * formattable, or NULL if this object does not contain numeric type. | 255 * formattable, or NULL if this object does not contain numeric type. |
258 * For values obtained by parsing, the returned decimal number retains | 256 * For values obtained by parsing, the returned decimal number retains |
259 * the full precision and range of the original input, unconstrained by | 257 * the full precision and range of the original input, unconstrained by |
260 * the limits of a double floating point or a 64 bit int. | 258 * the limits of a double floating point or a 64 bit int. |
261 * | 259 * |
262 * This function is not thread safe, and therfore is not declared const, | 260 * This function is not thread safe, and therfore is not declared const, |
263 * even though it is logically const. | 261 * even though it is logically const. |
264 * The resulting buffer is owned by the UFormattable and is invalid if any other
functions are | 262 * The resulting buffer is owned by the UFormattable and is invalid if any other
functions are |
265 * called on the UFormattable. | 263 * called on the UFormattable. |
266 * | 264 * |
267 * Possible errors include U_MEMORY_ALLOCATION_ERROR, and | 265 * Possible errors include U_MEMORY_ALLOCATION_ERROR, and |
268 * U_INVALID_STATE if the formattable object has not been set to | 266 * U_INVALID_STATE if the formattable object has not been set to |
269 * a numeric type. | 267 * a numeric type. |
270 * @param fmt the UFormattable object | 268 * @param fmt the UFormattable object |
271 * @param len if non-null, on exit contains the string length (not including the
terminating null) | 269 * @param len if non-null, on exit contains the string length (not including the
terminating null) |
272 * @param status the error code | 270 * @param status the error code |
273 * @return the character buffer as a NULL terminated string, which is owned by t
he object and must not be accessed if any other functions are called on this obj
ect. | 271 * @return the character buffer as a NULL terminated string, which is owned by t
he object and must not be accessed if any other functions are called on this obj
ect. |
274 * @draft ICU 52 | 272 * @stable ICU 52 |
275 * @see icu::Formattable::getDecimalNumber(UErrorCode&) | 273 * @see icu::Formattable::getDecimalNumber(UErrorCode&) |
276 */ | 274 */ |
277 U_DRAFT const char * U_EXPORT2 | 275 U_STABLE const char * U_EXPORT2 |
278 ufmt_getDecNumChars(UFormattable *fmt, int32_t *len, UErrorCode *status); | 276 ufmt_getDecNumChars(UFormattable *fmt, int32_t *len, UErrorCode *status); |
279 #endif /* U_HIDE_DRAFT_API */ | |
280 | 277 |
281 #endif | 278 #endif |
282 | 279 |
283 #endif | 280 #endif |
OLD | NEW |