diff options
Diffstat (limited to 'intl/icu/source/i18n/unicode/formattedvalue.h')
| -rw-r--r-- | intl/icu/source/i18n/unicode/formattedvalue.h | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/intl/icu/source/i18n/unicode/formattedvalue.h b/intl/icu/source/i18n/unicode/formattedvalue.h new file mode 100644 index 0000000000..e7ba4ec245 --- /dev/null +++ b/intl/icu/source/i18n/unicode/formattedvalue.h @@ -0,0 +1,318 @@ +// © 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__ |