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