tor-browser

uformattedvalue.h (12549B)

---

// © 2018 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html

#ifndef __UFORMATTEDVALUE_H__
#define __UFORMATTEDVALUE_H__

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "unicode/ufieldpositer.h"

/**
* \file
* \brief C API: Abstract operations for localized strings.
* 
* This file contains declarations for classes that deal with formatted strings. A number
* of APIs throughout ICU use these classes for expressing their localized output.
*/


/**
* All possible field categories in ICU. Every entry in this enum corresponds
* to another enum that exists in ICU.
* 
* In the APIs that take a UFieldCategory, an int32_t type is used. Field
* categories having any of the top four bits turned on are reserved as
* private-use for external APIs implementing FormattedValue. This means that
* categories 2^28 and higher or below zero (with the highest bit turned on)
* are private-use and will not be used by ICU in the future.
*
* @stable ICU 64
*/
typedef enum UFieldCategory {
   /**
    * For an undefined field category.
    * 
    * @stable ICU 64
    */
   UFIELD_CATEGORY_UNDEFINED = 0,

   /**
    * For fields in UDateFormatField (udat.h), from ICU 3.0.
    *
    * @stable ICU 64
    */
   UFIELD_CATEGORY_DATE,

   /**
    * For fields in UNumberFormatFields (unum.h), from ICU 49.
    *
    * @stable ICU 64
    */
   UFIELD_CATEGORY_NUMBER,

   /**
    * For fields in UListFormatterField (ulistformatter.h), from ICU 63.
    *
    * @stable ICU 64
    */
   UFIELD_CATEGORY_LIST,

   /**
    * For fields in URelativeDateTimeFormatterField (ureldatefmt.h), from ICU 64.
    *
    * @stable ICU 64
    */
   UFIELD_CATEGORY_RELATIVE_DATETIME,

   /**
    * Reserved for possible future fields in UDateIntervalFormatField.
    *
    * @internal
    */
   UFIELD_CATEGORY_DATE_INTERVAL,

#ifndef U_HIDE_INTERNAL_API
   /** @internal */
   UFIELD_CATEGORY_COUNT,
#endif  /* U_HIDE_INTERNAL_API */

   /**
    * Category for spans in a list.
    *
    * @stable ICU 64
    */
   UFIELD_CATEGORY_LIST_SPAN = 0x1000 + UFIELD_CATEGORY_LIST,

   /**
    * Category for spans in a date interval.
    *
    * @stable ICU 64
    */
   UFIELD_CATEGORY_DATE_INTERVAL_SPAN = 0x1000 + UFIELD_CATEGORY_DATE_INTERVAL,

   /**
    * Category for spans in a number range.
    *
    * @stable ICU 69
    */
   UFIELD_CATEGORY_NUMBER_RANGE_SPAN = 0x1000 + UFIELD_CATEGORY_NUMBER,

} UFieldCategory;


struct UConstrainedFieldPosition;
/**
* Represents a span of a string containing a given field.
*
* This struct differs from UFieldPosition in the following ways:
*
*   1. It has information on the field category.
*   2. It allows you to set constraints to use when iterating over field positions.
*   3. It is used for the newer FormattedValue APIs.
*
* @stable ICU 64
*/
typedef struct UConstrainedFieldPosition UConstrainedFieldPosition;


/**
* Creates a new UConstrainedFieldPosition.
*
* By default, the UConstrainedFieldPosition has no iteration constraints.
*
* @param ec Set if an error occurs.
* @return The new object, or NULL if an error occurs.
* @stable ICU 64
*/
U_CAPI UConstrainedFieldPosition* U_EXPORT2
ucfpos_open(UErrorCode* ec);


/**
* Resets a UConstrainedFieldPosition to its initial state, as if it were newly created.
*
* Removes any constraints that may have been set on the instance.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param ec Set if an error occurs.
* @stable ICU 64
*/
U_CAPI void U_EXPORT2
ucfpos_reset(
   UConstrainedFieldPosition* ucfpos,
   UErrorCode* ec);


/**
* Destroys a UConstrainedFieldPosition and releases its memory.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @stable ICU 64
*/
U_CAPI void U_EXPORT2
ucfpos_close(UConstrainedFieldPosition* ucfpos);


/**
* Sets a constraint on the field category.
* 
* When this instance of UConstrainedFieldPosition is passed to ufmtval_nextPosition,
* positions are skipped unless they have the given category.
*
* Any previously set constraints are cleared.
*
* For example, to loop over only the number-related fields:
*
*     UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
*     ucfpos_constrainCategory(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, ec);
*     while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
*         // handle the number-related field position
*     }
*     ucfpos_close(ucfpos);
*
* Changing the constraint while in the middle of iterating over a FormattedValue
* does not generally have well-defined behavior.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param category The field category to fix when iterating.
* @param ec Set if an error occurs.
* @stable ICU 64
*/
U_CAPI void U_EXPORT2
ucfpos_constrainCategory(
   UConstrainedFieldPosition* ucfpos,
   int32_t category,
   UErrorCode* ec);


/**
* Sets a constraint on the category and field.
* 
* When this instance of UConstrainedFieldPosition is passed to ufmtval_nextPosition,
* positions are skipped unless they have the given category and field.
*
* Any previously set constraints are cleared.
*
* For example, to loop over all grouping separators:
*
*     UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
*     ucfpos_constrainField(ucfpos, UFIELDCATEGORY_NUMBER_FORMAT, UNUM_GROUPING_SEPARATOR_FIELD, ec);
*     while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
*         // handle the grouping separator position
*     }
*     ucfpos_close(ucfpos);
*
* Changing the constraint while in the middle of iterating over a FormattedValue
* does not generally have well-defined behavior.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param category The field category to fix when iterating.
* @param field The field to fix when iterating.
* @param ec Set if an error occurs.
* @stable ICU 64
*/
U_CAPI void U_EXPORT2
ucfpos_constrainField(
   UConstrainedFieldPosition* ucfpos,
   int32_t category,
   int32_t field,
   UErrorCode* ec);


/**
* Gets the field category for the current position.
*
* If a category or field constraint was set, this function returns the constrained
* category. Otherwise, the return value is well-defined only after
* ufmtval_nextPosition returns true.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param ec Set if an error occurs.
* @return The field category saved in the instance.
* @stable ICU 64
*/
U_CAPI int32_t U_EXPORT2
ucfpos_getCategory(
   const UConstrainedFieldPosition* ucfpos,
   UErrorCode* ec);


/**
* Gets the field for the current position.
*
* If a field constraint was set, this function returns the constrained
* field. Otherwise, the return value is well-defined only after
* ufmtval_nextPosition returns true.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param ec Set if an error occurs.
* @return The field saved in the instance.
* @stable ICU 64
*/
U_CAPI int32_t U_EXPORT2
ucfpos_getField(
   const UConstrainedFieldPosition* ucfpos,
   UErrorCode* ec);


/**
* Gets the INCLUSIVE start and EXCLUSIVE end index stored for the current position.
*
* The output values are well-defined only after ufmtval_nextPosition returns true.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param pStart Set to the start index saved in the instance. Ignored if nullptr.
* @param pLimit Set to the end index saved in the instance. Ignored if nullptr.
* @param ec Set if an error occurs.
* @stable ICU 64
*/
U_CAPI void U_EXPORT2
ucfpos_getIndexes(
   const UConstrainedFieldPosition* ucfpos,
   int32_t* pStart,
   int32_t* pLimit,
   UErrorCode* ec);


/**
* Gets an int64 that FormattedValue implementations may use for storage.
*
* The initial value is zero.
*
* Users of FormattedValue should not need to call this method.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param ec Set if an error occurs.
* @return The current iteration context from ucfpos_setInt64IterationContext.
* @stable ICU 64
*/
U_CAPI int64_t U_EXPORT2
ucfpos_getInt64IterationContext(
   const UConstrainedFieldPosition* ucfpos,
   UErrorCode* ec);


/**
* Sets an int64 that FormattedValue implementations may use for storage.
*
* Intended to be used by FormattedValue implementations.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param context The new iteration context.
* @param ec Set if an error occurs.
* @stable ICU 64
*/
U_CAPI void U_EXPORT2
ucfpos_setInt64IterationContext(
   UConstrainedFieldPosition* ucfpos,
   int64_t context,
   UErrorCode* ec);


/**
* Determines whether a given field should be included given the
* constraints.
*
* Intended to be used by FormattedValue implementations.
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param category The category to test.
* @param field The field to test.
* @param ec Set if an error occurs.
* @stable ICU 64
*/
U_CAPI UBool U_EXPORT2
ucfpos_matchesField(
   const UConstrainedFieldPosition* ucfpos,
   int32_t category,
   int32_t field,
   UErrorCode* ec);


/**
* Sets new values for the primary public getters.
*
* Intended to be used by FormattedValue implementations.
*
* It is up to the implementation to ensure that the user-requested
* constraints are satisfied. This method does not check!
*
* @param ucfpos The instance of UConstrainedFieldPosition.
* @param category The new field category.
* @param field The new field.
* @param start The new inclusive start index.
* @param limit The new exclusive end index.
* @param ec Set if an error occurs.
* @stable ICU 64
*/
U_CAPI void U_EXPORT2
ucfpos_setState(
   UConstrainedFieldPosition* ucfpos,
   int32_t category,
   int32_t field,
   int32_t start,
   int32_t limit,
   UErrorCode* ec);


struct UFormattedValue;
/**
* An abstract formatted value: a string with associated field attributes.
* Many formatters format to types compatible with UFormattedValue.
*
* @stable ICU 64
*/
typedef struct UFormattedValue UFormattedValue;


/**
* Returns a pointer to the formatted string. The pointer is owned by the UFormattedValue. The
* return value is valid only as long as the UFormattedValue is present and unchanged in memory.
*
* The return value is NUL-terminated but could contain internal NULs.
*
* @param ufmtval
*         The object containing the formatted string and attributes.
* @param pLength Output variable for the length of the string. Ignored if NULL.
* @param ec Set if an error occurs.
* @return A NUL-terminated char16 string owned by the UFormattedValue.
* @stable ICU 64
*/
U_CAPI const UChar* U_EXPORT2
ufmtval_getString(
   const UFormattedValue* ufmtval,
   int32_t* pLength,
   UErrorCode* ec);


/**
* Iterates over field positions in the UFormattedValue. This lets you determine the position
* of specific types of substrings, like a month or a decimal separator.
*
* To loop over all field positions:
*
*     UConstrainedFieldPosition* ucfpos = ucfpos_open(ec);
*     while (ufmtval_nextPosition(ufmtval, ucfpos, ec)) {
*         // handle the field position; get information from ucfpos
*     }
*     ucfpos_close(ucfpos);
*
* @param ufmtval
*         The object containing the formatted string and attributes.
* @param ucfpos
*         The object used for iteration state; can provide constraints to iterate over only
*         one specific category or field;
*         see ucfpos_constrainCategory
*         and ucfpos_constrainField.
* @param ec Set if an error occurs.
* @return true if another position was found; false otherwise.
* @stable ICU 64
*/
U_CAPI UBool U_EXPORT2
ufmtval_nextPosition(
   const UFormattedValue* ufmtval,
   UConstrainedFieldPosition* ucfpos,
   UErrorCode* ec);


#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN

/**
* \class LocalUConstrainedFieldPositionPointer
* "Smart pointer" class; closes a UConstrainedFieldPosition via ucfpos_close().
* For most methods see the LocalPointerBase base class.
*
* Usage:
*
*     LocalUConstrainedFieldPositionPointer ucfpos(ucfpos_open(ec));
*     // no need to explicitly call ucfpos_close()
*
* @stable ICU 64
*/
U_DEFINE_LOCAL_OPEN_POINTER(LocalUConstrainedFieldPositionPointer,
   UConstrainedFieldPosition,
   ucfpos_close);

U_NAMESPACE_END
#endif // U_SHOW_CPLUSPLUS_API


#endif /* #if !UCONFIG_NO_FORMATTING */
#endif // __UFORMATTEDVALUE_H__