1 // © 2018 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 4 #ifndef __UFORMATTEDVALUE_H__ 5 #define __UFORMATTEDVALUE_H__ 6 7 #include "unicode/utypes.h" 8 9 #if !UCONFIG_NO_FORMATTING 10 11 #include "unicode/ufieldpositer.h" 12 13 /** 14 * \file 15 * \brief C API: Abstract operations for localized strings. 16 * 17 * This file contains declarations for classes that deal with formatted strings. A number 18 * of APIs throughout ICU use these classes for expressing their localized output. 19 */ 20 21 22 /** 23 * All possible field categories in ICU. Every entry in this enum corresponds 24 * to another enum that exists in ICU. 25 * 26 * In the APIs that take a UFieldCategory, an int32_t type is used. Field 27 * categories having any of the top four bits turned on are reserved as 28 * private-use for external APIs implementing FormattedValue. This means that 29 * categories 2^28 and higher or below zero (with the highest bit turned on) 30 * are private-use and will not be used by ICU in the future. 31 * 32 * @stable ICU 64 33 */ 34 typedef enum UFieldCategory { 35 /** 36 * For an undefined field category. 37 * 38 * @stable ICU 64 39 */ 40 UFIELD_CATEGORY_UNDEFINED = 0, 41 42 /** 43 * For fields in UDateFormatField (udat.h), from ICU 3.0. 44 * 45 * @stable ICU 64 46 */ 47 UFIELD_CATEGORY_DATE, 48 49 /** 50 * For fields in UNumberFormatFields (unum.h), from ICU 49. 51 * 52 * @stable ICU 64 53 */ 54 UFIELD_CATEGORY_NUMBER, 55 56 /** 57 * For fields in UListFormatterField (ulistformatter.h), from ICU 63. 58 * 59 * @stable ICU 64 60 */ 61 UFIELD_CATEGORY_LIST, 62 63 /** 64 * For fields in URelativeDateTimeFormatterField (ureldatefmt.h), from ICU 64. 65 * 66 * @stable ICU 64 67 */ 68 UFIELD_CATEGORY_RELATIVE_DATETIME, 69 70 /** 71 * Reserved for possible future fields in UDateIntervalFormatField. 72 * 73 * @internal 74 */ 75 UFIELD_CATEGORY_DATE_INTERVAL, 76 77 #ifndef U_HIDE_INTERNAL_API 78 /** @internal */ 79 UFIELD_CATEGORY_COUNT, 80 #endif /* U_HIDE_INTERNAL_API */ 81 82 /** 83 * Category for spans in a list. 84 * 85 * @stable ICU 64 86 */ 87 UFIELD_CATEGORY_LIST_SPAN = 0x1000 + UFIELD_CATEGORY_LIST, 88 89 /** 90 * Category for spans in a date interval. 91 * 92 * @stable ICU 64 93 */ 94 UFIELD_CATEGORY_DATE_INTERVAL_SPAN = 0x1000 + UFIELD_CATEGORY_DATE_INTERVAL, 95 96 #ifndef U_HIDE_DRAFT_API 97 /** 98 * Category for spans in a number range. 99 * 100 * @draft ICU 69 101 */ 102 UFIELD_CATEGORY_NUMBER_RANGE_SPAN = 0x1000 + UFIELD_CATEGORY_NUMBER, 103 #endif // U_HIDE_DRAFT_API 104 105 } UFieldCategory; 106 107 108 struct UConstrainedFieldPosition; 109 /** 110 * Represents a span of a string containing a given field. 111 * 112 * This struct differs from UFieldPosition in the following ways: 113 * 114 * 1. It has information on the field category. 115 * 2. It allows you to set constraints to use when iterating over field positions. 116 * 3. It is used for the newer FormattedValue APIs. 117 * 118 * @stable ICU 64 119 */ 120 typedef struct UConstrainedFieldPosition UConstrainedFieldPosition; 121 122 123 /** 124 * Creates a new UConstrainedFieldPosition. 125 * 126 * By default, the UConstrainedFieldPosition has no iteration constraints. 127 * 128 * @param ec Set if an error occurs. 129 * @return The new object, or NULL if an error occurs. 130 * @stable ICU 64 131 */ 132 U_CAPI UConstrainedFieldPosition* U_EXPORT2 133 ucfpos_open(UErrorCode* ec); 134 135 136 /** 137 * Resets a UConstrainedFieldPosition to its initial state, as if it were newly created. 138 * 139 * Removes any constraints that may have been set on the instance. 140 * 141 * @param ucfpos The instance of UConstrainedFieldPosition. 142 * @param ec Set if an error occurs. 143 * @stable ICU 64 144 */ 145 U_CAPI void U_EXPORT2 146 ucfpos_reset( 147 UConstrainedFieldPosition* ucfpos, 148 UErrorCode* ec); 149 150 151 /** 152 * Destroys a UConstrainedFieldPosition and releases its memory. 153 * 154 * @param ucfpos The instance of UConstrainedFieldPosition. 155 * @stable ICU 64 156 */ 157 U_CAPI void U_EXPORT2 158 ucfpos_close(UConstrainedFieldPosition* ucfpos); 159 160 161 /** 162 * Sets a constraint on the field category. 163 * 164 * When this instance of UConstrainedFieldPosition is passed to ufmtval_nextPosition, 165 * positions are skipped unless they have the given category. 166 * 167 * Any previously set constraints are cleared. 168 * 169 * For example, to loop over only the number-related fields: 170 * 171 * UConstrainedFieldPosition* ucfpos = ucfpos_open(ec); 172 * ucfpos_constrainCategory(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, ec); 173 * while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) { 174 * // handle the number-related field position 175 * } 176 * ucfpos_close(ucfpos); 177 * 178 * Changing the constraint while in the middle of iterating over a FormattedValue 179 * does not generally have well-defined behavior. 180 * 181 * @param ucfpos The instance of UConstrainedFieldPosition. 182 * @param category The field category to fix when iterating. 183 * @param ec Set if an error occurs. 184 * @stable ICU 64 185 */ 186 U_CAPI void U_EXPORT2 187 ucfpos_constrainCategory( 188 UConstrainedFieldPosition* ucfpos, 189 int32_t category, 190 UErrorCode* ec); 191 192 193 /** 194 * Sets a constraint on the category and field. 195 * 196 * When this instance of UConstrainedFieldPosition is passed to ufmtval_nextPosition, 197 * positions are skipped unless they have the given category and field. 198 * 199 * Any previously set constraints are cleared. 200 * 201 * For example, to loop over all grouping separators: 202 * 203 * UConstrainedFieldPosition* ucfpos = ucfpos_open(ec); 204 * ucfpos_constrainField(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, UNUM_GROUPING_SEPARATOR_FIELD, ec); 205 * while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) { 206 * // handle the grouping separator position 207 * } 208 * ucfpos_close(ucfpos); 209 * 210 * Changing the constraint while in the middle of iterating over a FormattedValue 211 * does not generally have well-defined behavior. 212 * 213 * @param ucfpos The instance of UConstrainedFieldPosition. 214 * @param category The field category to fix when iterating. 215 * @param field The field to fix when iterating. 216 * @param ec Set if an error occurs. 217 * @stable ICU 64 218 */ 219 U_CAPI void U_EXPORT2 220 ucfpos_constrainField( 221 UConstrainedFieldPosition* ucfpos, 222 int32_t category, 223 int32_t field, 224 UErrorCode* ec); 225 226 227 /** 228 * Gets the field category for the current position. 229 * 230 * If a category or field constraint was set, this function returns the constrained 231 * category. Otherwise, the return value is well-defined only after 232 * ufmtval_nextPosition returns true. 233 * 234 * @param ucfpos The instance of UConstrainedFieldPosition. 235 * @param ec Set if an error occurs. 236 * @return The field category saved in the instance. 237 * @stable ICU 64 238 */ 239 U_CAPI int32_t U_EXPORT2 240 ucfpos_getCategory( 241 const UConstrainedFieldPosition* ucfpos, 242 UErrorCode* ec); 243 244 245 /** 246 * Gets the field for the current position. 247 * 248 * If a field constraint was set, this function returns the constrained 249 * field. Otherwise, the return value is well-defined only after 250 * ufmtval_nextPosition returns true. 251 * 252 * @param ucfpos The instance of UConstrainedFieldPosition. 253 * @param ec Set if an error occurs. 254 * @return The field saved in the instance. 255 * @stable ICU 64 256 */ 257 U_CAPI int32_t U_EXPORT2 258 ucfpos_getField( 259 const UConstrainedFieldPosition* ucfpos, 260 UErrorCode* ec); 261 262 263 /** 264 * Gets the INCLUSIVE start and EXCLUSIVE end index stored for the current position. 265 * 266 * The output values are well-defined only after ufmtval_nextPosition returns true. 267 * 268 * @param ucfpos The instance of UConstrainedFieldPosition. 269 * @param pStart Set to the start index saved in the instance. Ignored if nullptr. 270 * @param pLimit Set to the end index saved in the instance. Ignored if nullptr. 271 * @param ec Set if an error occurs. 272 * @stable ICU 64 273 */ 274 U_CAPI void U_EXPORT2 275 ucfpos_getIndexes( 276 const UConstrainedFieldPosition* ucfpos, 277 int32_t* pStart, 278 int32_t* pLimit, 279 UErrorCode* ec); 280 281 282 /** 283 * Gets an int64 that FormattedValue implementations may use for storage. 284 * 285 * The initial value is zero. 286 * 287 * Users of FormattedValue should not need to call this method. 288 * 289 * @param ucfpos The instance of UConstrainedFieldPosition. 290 * @param ec Set if an error occurs. 291 * @return The current iteration context from ucfpos_setInt64IterationContext. 292 * @stable ICU 64 293 */ 294 U_CAPI int64_t U_EXPORT2 295 ucfpos_getInt64IterationContext( 296 const UConstrainedFieldPosition* ucfpos, 297 UErrorCode* ec); 298 299 300 /** 301 * Sets an int64 that FormattedValue implementations may use for storage. 302 * 303 * Intended to be used by FormattedValue implementations. 304 * 305 * @param ucfpos The instance of UConstrainedFieldPosition. 306 * @param context The new iteration context. 307 * @param ec Set if an error occurs. 308 * @stable ICU 64 309 */ 310 U_CAPI void U_EXPORT2 311 ucfpos_setInt64IterationContext( 312 UConstrainedFieldPosition* ucfpos, 313 int64_t context, 314 UErrorCode* ec); 315 316 317 /** 318 * Determines whether a given field should be included given the 319 * constraints. 320 * 321 * Intended to be used by FormattedValue implementations. 322 * 323 * @param ucfpos The instance of UConstrainedFieldPosition. 324 * @param category The category to test. 325 * @param field The field to test. 326 * @param ec Set if an error occurs. 327 * @stable ICU 64 328 */ 329 U_CAPI UBool U_EXPORT2 330 ucfpos_matchesField( 331 const UConstrainedFieldPosition* ucfpos, 332 int32_t category, 333 int32_t field, 334 UErrorCode* ec); 335 336 337 /** 338 * Sets new values for the primary public getters. 339 * 340 * Intended to be used by FormattedValue implementations. 341 * 342 * It is up to the implementation to ensure that the user-requested 343 * constraints are satisfied. This method does not check! 344 * 345 * @param ucfpos The instance of UConstrainedFieldPosition. 346 * @param category The new field category. 347 * @param field The new field. 348 * @param start The new inclusive start index. 349 * @param limit The new exclusive end index. 350 * @param ec Set if an error occurs. 351 * @stable ICU 64 352 */ 353 U_CAPI void U_EXPORT2 354 ucfpos_setState( 355 UConstrainedFieldPosition* ucfpos, 356 int32_t category, 357 int32_t field, 358 int32_t start, 359 int32_t limit, 360 UErrorCode* ec); 361 362 363 struct UFormattedValue; 364 /** 365 * An abstract formatted value: a string with associated field attributes. 366 * Many formatters format to types compatible with UFormattedValue. 367 * 368 * @stable ICU 64 369 */ 370 typedef struct UFormattedValue UFormattedValue; 371 372 373 /** 374 * Returns a pointer to the formatted string. The pointer is owned by the UFormattedValue. The 375 * return value is valid only as long as the UFormattedValue is present and unchanged in memory. 376 * 377 * The return value is NUL-terminated but could contain internal NULs. 378 * 379 * @param ufmtval 380 * The object containing the formatted string and attributes. 381 * @param pLength Output variable for the length of the string. Ignored if NULL. 382 * @param ec Set if an error occurs. 383 * @return A NUL-terminated char16 string owned by the UFormattedValue. 384 * @stable ICU 64 385 */ 386 U_CAPI const UChar* U_EXPORT2 387 ufmtval_getString( 388 const UFormattedValue* ufmtval, 389 int32_t* pLength, 390 UErrorCode* ec); 391 392 393 /** 394 * Iterates over field positions in the UFormattedValue. This lets you determine the position 395 * of specific types of substrings, like a month or a decimal separator. 396 * 397 * To loop over all field positions: 398 * 399 * UConstrainedFieldPosition* ucfpos = ucfpos_open(ec); 400 * while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) { 401 * // handle the field position; get information from ucfpos 402 * } 403 * ucfpos_close(ucfpos); 404 * 405 * @param ufmtval 406 * The object containing the formatted string and attributes. 407 * @param ucfpos 408 * The object used for iteration state; can provide constraints to iterate over only 409 * one specific category or field; 410 * see ucfpos_constrainCategory 411 * and ucfpos_constrainField. 412 * @param ec Set if an error occurs. 413 * @return true if another position was found; false otherwise. 414 * @stable ICU 64 415 */ 416 U_CAPI UBool U_EXPORT2 417 ufmtval_nextPosition( 418 const UFormattedValue* ufmtval, 419 UConstrainedFieldPosition* ucfpos, 420 UErrorCode* ec); 421 422 423 #if U_SHOW_CPLUSPLUS_API 424 U_NAMESPACE_BEGIN 425 426 /** 427 * \class LocalUConstrainedFieldPositionPointer 428 * "Smart pointer" class; closes a UConstrainedFieldPosition via ucfpos_close(). 429 * For most methods see the LocalPointerBase base class. 430 * 431 * Usage: 432 * 433 * LocalUConstrainedFieldPositionPointer ucfpos(ucfpos_open(ec)); 434 * // no need to explicitly call ucfpos_close() 435 * 436 * @stable ICU 64 437 */ 438 U_DEFINE_LOCAL_OPEN_POINTER(LocalUConstrainedFieldPositionPointer, 439 UConstrainedFieldPosition, 440 ucfpos_close); 441 442 U_NAMESPACE_END 443 #endif // U_SHOW_CPLUSPLUS_API 444 445 446 #endif /* #if !UCONFIG_NO_FORMATTING */ 447 #endif // __UFORMATTEDVALUE_H__ 448