EIC code displayed by LXR master/​include/​unicode/​formattedvalue.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 10:13:05

 // © 2018 and later: Unicode, Inc. and others.
 // License & terms of use: http://www.unicode.org/copyright.html
 
 #ifndef __FORMATTEDVALUE_H__
 #define __FORMATTEDVALUE_H__
 
 #include "unicode/utypes.h"
 
 #if U_SHOW_CPLUSPLUS_API
 
 #if !UCONFIG_NO_FORMATTING
 
 #include "unicode/appendable.h"
 #include "unicode/fpositer.h"
 #include "unicode/unistr.h"
 #include "unicode/uformattedvalue.h"
 
 U_NAMESPACE_BEGIN
 
 /**
  * \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.
  */
 
 /**
  * Represents a span of a string containing a given field.
  *
  * This class differs from FieldPosition 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.
  *
  * This class is not intended for public subclassing.
  *
  * @stable ICU 64
  */
 class U_I18N_API ConstrainedFieldPosition : public UMemory {
   public:
 
     /**
      * Initializes a ConstrainedFieldPosition.
      *
      * By default, the ConstrainedFieldPosition has no iteration constraints.
      *
      * @stable ICU 64
      */
     ConstrainedFieldPosition();
 
     /** @stable ICU 64 */
     ~ConstrainedFieldPosition();
 
     /**
      * Resets this ConstrainedFieldPosition to its initial state, as if it were newly created:
      *
      * - Removes any constraints that may have been set on the instance.
      * - Resets the iteration position.
      *
      * @stable ICU 64
      */
     void reset();
 
     /**
      * Sets a constraint on the field category.
      * 
      * When this instance of ConstrainedFieldPosition is passed to FormattedValue#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:
      *
      *     ConstrainedFieldPosition cfpos;
      *     cfpos.constrainCategory(UFIELDCATEGORY_NUMBER_FORMAT);
      *     while (fmtval.nextPosition(cfpos, status)) {
      *         // handle the number-related field position
      *     }
      *
      * Changing the constraint while in the middle of iterating over a FormattedValue
      * does not generally have well-defined behavior.
      *
      * @param category The field category to fix when iterating.
      * @stable ICU 64
      */
     void constrainCategory(int32_t category);
 
     /**
      * Sets a constraint on the category and field.
      * 
      * When this instance of ConstrainedFieldPosition is passed to FormattedValue#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:
      *
      *     ConstrainedFieldPosition cfpos;
      *     cfpos.constrainField(UFIELDCATEGORY_NUMBER_FORMAT, UNUM_GROUPING_SEPARATOR_FIELD);
      *     while (fmtval.nextPosition(cfpos, status)) {
      *         // handle the grouping separator position
      *     }
      *
      * Changing the constraint while in the middle of iterating over a FormattedValue
      * does not generally have well-defined behavior.
      *
      * @param category The field category to fix when iterating.
      * @param field The field to fix when iterating.
      * @stable ICU 64
      */
     void constrainField(int32_t category, int32_t field);
 
     /**
      * Gets the field category for the current position.
      *
      * The return value is well-defined only after
      * FormattedValue#nextPosition returns true.
      *
      * @return The field category saved in the instance.
      * @stable ICU 64
      */
     inline int32_t getCategory() const {
         return fCategory;
     }
 
     /**
      * Gets the field for the current position.
      *
      * The return value is well-defined only after
      * FormattedValue#nextPosition returns true.
      *
      * @return The field saved in the instance.
      * @stable ICU 64
      */
     inline int32_t getField() const {
         return fField;
     }
 
     /**
      * Gets the INCLUSIVE start index for the current position.
      *
      * The return value is well-defined only after FormattedValue#nextPosition returns true.
      *
      * @return The start index saved in the instance.
      * @stable ICU 64
      */
     inline int32_t getStart() const {
         return fStart;
     }
 
     /**
      * Gets the EXCLUSIVE end index stored for the current position.
      *
      * The return value is well-defined only after FormattedValue#nextPosition returns true.
      *
      * @return The end index saved in the instance.
      * @stable ICU 64
      */
     inline int32_t getLimit() const {
         return fLimit;
     }
 
     ////////////////////////////////////////////////////////////////////
     //// The following methods are for FormattedValue implementers; ////
     //// most users can ignore them.                                ////
     ////////////////////////////////////////////////////////////////////
 
     /**
      * 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.
      *
      * @return The current iteration context from {@link #setInt64IterationContext}.
      * @stable ICU 64
      */
     inline int64_t getInt64IterationContext() const {
         return fContext;
     }
 
     /**
      * Sets an int64 that FormattedValue implementations may use for storage.
      *
      * Intended to be used by FormattedValue implementations.
      *
      * @param context The new iteration context.
      * @stable ICU 64
      */
     void setInt64IterationContext(int64_t context);
 
     /**
      * Determines whether a given field should be included given the
      * constraints.
      *
      * Intended to be used by FormattedValue implementations.
      *
      * @param category The category to test.
      * @param field The field to test.
      * @stable ICU 64
      */
     UBool matchesField(int32_t category, int32_t field) const;
 
     /**
      * 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 category The new field category.
      * @param field The new field.
      * @param start The new inclusive start index.
      * @param limit The new exclusive end index.
      * @stable ICU 64
      */
     void setState(
         int32_t category,
         int32_t field,
         int32_t start,
         int32_t limit);
 
   private:
     int64_t fContext = 0LL;
     int32_t fField = 0;
     int32_t fStart = 0;
     int32_t fLimit = 0;
     int32_t fCategory = UFIELD_CATEGORY_UNDEFINED;
     int8_t fConstraint = 0;
 };
 
 /**
  * An abstract formatted value: a string with associated field attributes.
  * Many formatters format to classes implementing FormattedValue.
  *
  * @stable ICU 64
  */
 class U_I18N_API FormattedValue /* not : public UObject because this is an interface/mixin class */ {
   public:
     /** @stable ICU 64 */
     virtual ~FormattedValue();
 
     /**
      * Returns the formatted string as a self-contained UnicodeString.
      *
      * If you need the string within the current scope only, consider #toTempString.
      *
      * @param status Set if an error occurs.
      * @return a UnicodeString containing the formatted string.
      *
      * @stable ICU 64
      */
     virtual UnicodeString toString(UErrorCode& status) const = 0;
 
     /**
      * Returns the formatted string as a read-only alias to memory owned by the FormattedValue.
      *
      * The return value is valid only as long as this FormattedValue is present and unchanged in
      * memory. If you need the string outside the current scope, consider #toString.
      *
      * The buffer returned by calling UnicodeString#getBuffer() on the return value is
      * guaranteed to be NUL-terminated.
      *
      * @param status Set if an error occurs.
      * @return a temporary UnicodeString containing the formatted string.
      *
      * @stable ICU 64
      */
     virtual UnicodeString toTempString(UErrorCode& status) const = 0;
 
     /**
      * Appends the formatted string to an Appendable.
      *
      * @param appendable
      *         The Appendable to which to append the string output.
      * @param status Set if an error occurs.
      * @return The same Appendable, for chaining.
      *
      * @stable ICU 64
      * @see Appendable
      */
     virtual Appendable& appendTo(Appendable& appendable, UErrorCode& status) const = 0;
 
     /**
      * Iterates over field positions in the FormattedValue. This lets you determine the position
      * of specific types of substrings, like a month or a decimal separator.
      *
      * To loop over all field positions:
      *
      *     ConstrainedFieldPosition cfpos;
      *     while (fmtval.nextPosition(cfpos, status)) {
      *         // handle the field position; get information from cfpos
      *     }
      *
      * @param cfpos
      *         The object used for iteration state. This can provide constraints to iterate over
      *         only one specific category or field;
      *         see ConstrainedFieldPosition#constrainCategory
      *         and ConstrainedFieldPosition#constrainField.
      * @param status Set if an error occurs.
      * @return true if a new occurrence of the field was found;
      *         false otherwise or if an error was set.
      *
      * @stable ICU 64
      */
     virtual UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const = 0;
 };
 
 U_NAMESPACE_END
 
 #endif /* #if !UCONFIG_NO_FORMATTING */
 
 #endif /* U_SHOW_CPLUSPLUS_API */
 
 #endif // __FORMATTEDVALUE_H__

This page was automatically generated by the 2.3.7 LXR engine. The LXR team