icuSources/i18n/unicode/uformattedvalue.h

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