jpayne@69: // © 2018 and later: Unicode, Inc. and others.
jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69: 
jpayne@69: #ifndef __UFORMATTEDVALUE_H__
jpayne@69: #define __UFORMATTEDVALUE_H__
jpayne@69: 
jpayne@69: #include "unicode/utypes.h"
jpayne@69: 
jpayne@69: #if !UCONFIG_NO_FORMATTING
jpayne@69: 
jpayne@69: #include "unicode/ufieldpositer.h"
jpayne@69: 
jpayne@69: /**
jpayne@69:  * \file
jpayne@69:  * \brief C API: Abstract operations for localized strings.
jpayne@69:  * 
jpayne@69:  * This file contains declarations for classes that deal with formatted strings. A number
jpayne@69:  * of APIs throughout ICU use these classes for expressing their localized output.
jpayne@69:  */
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * All possible field categories in ICU. Every entry in this enum corresponds
jpayne@69:  * to another enum that exists in ICU.
jpayne@69:  * 
jpayne@69:  * In the APIs that take a UFieldCategory, an int32_t type is used. Field
jpayne@69:  * categories having any of the top four bits turned on are reserved as
jpayne@69:  * private-use for external APIs implementing FormattedValue. This means that
jpayne@69:  * categories 2^28 and higher or below zero (with the highest bit turned on)
jpayne@69:  * are private-use and will not be used by ICU in the future.
jpayne@69:  *
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: typedef enum UFieldCategory {
jpayne@69:     /**
jpayne@69:      * For an undefined field category.
jpayne@69:      * 
jpayne@69:      * @stable ICU 64
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_UNDEFINED = 0,
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * For fields in UDateFormatField (udat.h), from ICU 3.0.
jpayne@69:      *
jpayne@69:      * @stable ICU 64
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_DATE,
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * For fields in UNumberFormatFields (unum.h), from ICU 49.
jpayne@69:      *
jpayne@69:      * @stable ICU 64
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_NUMBER,
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * For fields in UListFormatterField (ulistformatter.h), from ICU 63.
jpayne@69:      *
jpayne@69:      * @stable ICU 64
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_LIST,
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * For fields in URelativeDateTimeFormatterField (ureldatefmt.h), from ICU 64.
jpayne@69:      *
jpayne@69:      * @stable ICU 64
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_RELATIVE_DATETIME,
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Reserved for possible future fields in UDateIntervalFormatField.
jpayne@69:      *
jpayne@69:      * @internal
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_DATE_INTERVAL,
jpayne@69: 
jpayne@69: #ifndef U_HIDE_INTERNAL_API
jpayne@69:     /** @internal */
jpayne@69:     UFIELD_CATEGORY_COUNT,
jpayne@69: #endif  /* U_HIDE_INTERNAL_API */
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Category for spans in a list.
jpayne@69:      *
jpayne@69:      * @stable ICU 64
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_LIST_SPAN = 0x1000 + UFIELD_CATEGORY_LIST,
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Category for spans in a date interval.
jpayne@69:      *
jpayne@69:      * @stable ICU 64
jpayne@69:      */
jpayne@69:     UFIELD_CATEGORY_DATE_INTERVAL_SPAN = 0x1000 + UFIELD_CATEGORY_DATE_INTERVAL,
jpayne@69: 
jpayne@69: } UFieldCategory;
jpayne@69: 
jpayne@69: 
jpayne@69: struct UConstrainedFieldPosition;
jpayne@69: /**
jpayne@69:  * Represents a span of a string containing a given field.
jpayne@69:  *
jpayne@69:  * This struct differs from UFieldPosition in the following ways:
jpayne@69:  *
jpayne@69:  *   1. It has information on the field category.
jpayne@69:  *   2. It allows you to set constraints to use when iterating over field positions.
jpayne@69:  *   3. It is used for the newer FormattedValue APIs.
jpayne@69:  *
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: typedef struct UConstrainedFieldPosition UConstrainedFieldPosition;
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Creates a new UConstrainedFieldPosition.
jpayne@69:  *
jpayne@69:  * By default, the UConstrainedFieldPosition has no iteration constraints.
jpayne@69:  *
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @return The new object, or NULL if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE UConstrainedFieldPosition* U_EXPORT2
jpayne@69: ucfpos_open(UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Resets a UConstrainedFieldPosition to its initial state, as if it were newly created.
jpayne@69:  *
jpayne@69:  * Removes any constraints that may have been set on the instance.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ucfpos_reset(
jpayne@69:     UConstrainedFieldPosition* ucfpos,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Destroys a UConstrainedFieldPosition and releases its memory.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ucfpos_close(UConstrainedFieldPosition* ucfpos);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Sets a constraint on the field category.
jpayne@69:  * 
jpayne@69:  * When this instance of UConstrainedFieldPosition is passed to ufmtval_nextPosition,
jpayne@69:  * positions are skipped unless they have the given category.
jpayne@69:  *
jpayne@69:  * Any previously set constraints are cleared.
jpayne@69:  *
jpayne@69:  * For example, to loop over only the number-related fields:
jpayne@69:  *
jpayne@69:  *     UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
jpayne@69:  *     ucfpos_constrainCategory(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, ec);
jpayne@69:  *     while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
jpayne@69:  *         // handle the number-related field position
jpayne@69:  *     }
jpayne@69:  *     ucfpos_close(ucfpos);
jpayne@69:  *
jpayne@69:  * Changing the constraint while in the middle of iterating over a FormattedValue
jpayne@69:  * does not generally have well-defined behavior.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param category The field category to fix when iterating.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ucfpos_constrainCategory(
jpayne@69:     UConstrainedFieldPosition* ucfpos,
jpayne@69:     int32_t category,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Sets a constraint on the category and field.
jpayne@69:  * 
jpayne@69:  * When this instance of UConstrainedFieldPosition is passed to ufmtval_nextPosition,
jpayne@69:  * positions are skipped unless they have the given category and field.
jpayne@69:  *
jpayne@69:  * Any previously set constraints are cleared.
jpayne@69:  *
jpayne@69:  * For example, to loop over all grouping separators:
jpayne@69:  *
jpayne@69:  *     UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
jpayne@69:  *     ucfpos_constrainField(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, UNUM_GROUPING_SEPARATOR_FIELD, ec);
jpayne@69:  *     while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
jpayne@69:  *         // handle the grouping separator position
jpayne@69:  *     }
jpayne@69:  *     ucfpos_close(ucfpos);
jpayne@69:  *
jpayne@69:  * Changing the constraint while in the middle of iterating over a FormattedValue
jpayne@69:  * does not generally have well-defined behavior.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param category The field category to fix when iterating.
jpayne@69:  * @param field The field to fix when iterating.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ucfpos_constrainField(
jpayne@69:     UConstrainedFieldPosition* ucfpos,
jpayne@69:     int32_t category,
jpayne@69:     int32_t field,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Gets the field category for the current position.
jpayne@69:  *
jpayne@69:  * If a category or field constraint was set, this function returns the constrained
jpayne@69:  * category. Otherwise, the return value is well-defined only after
jpayne@69:  * ufmtval_nextPosition returns TRUE.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @return The field category saved in the instance.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ucfpos_getCategory(
jpayne@69:     const UConstrainedFieldPosition* ucfpos,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Gets the field for the current position.
jpayne@69:  *
jpayne@69:  * If a field constraint was set, this function returns the constrained
jpayne@69:  * field. Otherwise, the return value is well-defined only after
jpayne@69:  * ufmtval_nextPosition returns TRUE.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @return The field saved in the instance.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE int32_t U_EXPORT2
jpayne@69: ucfpos_getField(
jpayne@69:     const UConstrainedFieldPosition* ucfpos,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Gets the INCLUSIVE start and EXCLUSIVE end index stored for the current position.
jpayne@69:  *
jpayne@69:  * The output values are well-defined only after ufmtval_nextPosition returns TRUE.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param pStart Set to the start index saved in the instance. Ignored if nullptr.
jpayne@69:  * @param pLimit Set to the end index saved in the instance. Ignored if nullptr.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ucfpos_getIndexes(
jpayne@69:     const UConstrainedFieldPosition* ucfpos,
jpayne@69:     int32_t* pStart,
jpayne@69:     int32_t* pLimit,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Gets an int64 that FormattedValue implementations may use for storage.
jpayne@69:  *
jpayne@69:  * The initial value is zero.
jpayne@69:  *
jpayne@69:  * Users of FormattedValue should not need to call this method.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @return The current iteration context from ucfpos_setInt64IterationContext.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE int64_t U_EXPORT2
jpayne@69: ucfpos_getInt64IterationContext(
jpayne@69:     const UConstrainedFieldPosition* ucfpos,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Sets an int64 that FormattedValue implementations may use for storage.
jpayne@69:  *
jpayne@69:  * Intended to be used by FormattedValue implementations.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param context The new iteration context.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ucfpos_setInt64IterationContext(
jpayne@69:     UConstrainedFieldPosition* ucfpos,
jpayne@69:     int64_t context,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Determines whether a given field should be included given the
jpayne@69:  * constraints.
jpayne@69:  *
jpayne@69:  * Intended to be used by FormattedValue implementations.
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param category The category to test.
jpayne@69:  * @param field The field to test.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE UBool U_EXPORT2
jpayne@69: ucfpos_matchesField(
jpayne@69:     const UConstrainedFieldPosition* ucfpos,
jpayne@69:     int32_t category,
jpayne@69:     int32_t field,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Sets new values for the primary public getters.
jpayne@69:  *
jpayne@69:  * Intended to be used by FormattedValue implementations.
jpayne@69:  *
jpayne@69:  * It is up to the implementation to ensure that the user-requested
jpayne@69:  * constraints are satisfied. This method does not check!
jpayne@69:  *
jpayne@69:  * @param ucfpos The instance of UConstrainedFieldPosition.
jpayne@69:  * @param category The new field category.
jpayne@69:  * @param field The new field.
jpayne@69:  * @param start The new inclusive start index.
jpayne@69:  * @param limit The new exclusive end index.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE void U_EXPORT2
jpayne@69: ucfpos_setState(
jpayne@69:     UConstrainedFieldPosition* ucfpos,
jpayne@69:     int32_t category,
jpayne@69:     int32_t field,
jpayne@69:     int32_t start,
jpayne@69:     int32_t limit,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: struct UFormattedValue;
jpayne@69: /**
jpayne@69:  * An abstract formatted value: a string with associated field attributes.
jpayne@69:  * Many formatters format to types compatible with UFormattedValue.
jpayne@69:  *
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: typedef struct UFormattedValue UFormattedValue;
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Returns a pointer to the formatted string. The pointer is owned by the UFormattedValue. The
jpayne@69:  * return value is valid only as long as the UFormattedValue is present and unchanged in memory.
jpayne@69:  *
jpayne@69:  * The return value is NUL-terminated but could contain internal NULs.
jpayne@69:  *
jpayne@69:  * @param ufmtval
jpayne@69:  *         The object containing the formatted string and attributes.
jpayne@69:  * @param pLength Output variable for the length of the string. Ignored if NULL.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @return A NUL-terminated char16 string owned by the UFormattedValue.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE const UChar* U_EXPORT2
jpayne@69: ufmtval_getString(
jpayne@69:     const UFormattedValue* ufmtval,
jpayne@69:     int32_t* pLength,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Iterates over field positions in the UFormattedValue. This lets you determine the position
jpayne@69:  * of specific types of substrings, like a month or a decimal separator.
jpayne@69:  *
jpayne@69:  * To loop over all field positions:
jpayne@69:  *
jpayne@69:  *     UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
jpayne@69:  *     while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
jpayne@69:  *         // handle the field position; get information from ucfpos
jpayne@69:  *     }
jpayne@69:  *     ucfpos_close(ucfpos);
jpayne@69:  *
jpayne@69:  * @param ufmtval
jpayne@69:  *         The object containing the formatted string and attributes.
jpayne@69:  * @param ucfpos
jpayne@69:  *         The object used for iteration state; can provide constraints to iterate over only
jpayne@69:  *         one specific category or field;
jpayne@69:  *         see ucfpos_constrainCategory
jpayne@69:  *         and ucfpos_constrainField.
jpayne@69:  * @param ec Set if an error occurs.
jpayne@69:  * @return TRUE if another position was found; FALSE otherwise.
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_STABLE UBool U_EXPORT2
jpayne@69: ufmtval_nextPosition(
jpayne@69:     const UFormattedValue* ufmtval,
jpayne@69:     UConstrainedFieldPosition* ucfpos,
jpayne@69:     UErrorCode* ec);
jpayne@69: 
jpayne@69: 
jpayne@69: #if U_SHOW_CPLUSPLUS_API
jpayne@69: U_NAMESPACE_BEGIN
jpayne@69: 
jpayne@69: /**
jpayne@69:  * \class LocalUConstrainedFieldPositionPointer
jpayne@69:  * "Smart pointer" class; closes a UConstrainedFieldPosition via ucfpos_close().
jpayne@69:  * For most methods see the LocalPointerBase base class.
jpayne@69:  *
jpayne@69:  * Usage:
jpayne@69:  *
jpayne@69:  *     LocalUConstrainedFieldPositionPointer ucfpos(ucfpos_open(ec));
jpayne@69:  *     // no need to explicitly call ucfpos_close()
jpayne@69:  *
jpayne@69:  * @stable ICU 64
jpayne@69:  */
jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUConstrainedFieldPositionPointer,
jpayne@69:     UConstrainedFieldPosition,
jpayne@69:     ucfpos_close);
jpayne@69: 
jpayne@69: U_NAMESPACE_END
jpayne@69: #endif // U_SHOW_CPLUSPLUS_API
jpayne@69: 
jpayne@69: 
jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69: #endif // __UFORMATTEDVALUE_H__