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