Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/formattedvalue.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2018 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3
jpayne@69 4 #ifndef __FORMATTEDVALUE_H__
jpayne@69 5 #define __FORMATTEDVALUE_H__
jpayne@69 6
jpayne@69 7 #include "unicode/utypes.h"
jpayne@69 8
jpayne@69 9 #if U_SHOW_CPLUSPLUS_API
jpayne@69 10
jpayne@69 11 #if !UCONFIG_NO_FORMATTING
jpayne@69 12
jpayne@69 13 #include "unicode/appendable.h"
jpayne@69 14 #include "unicode/fpositer.h"
jpayne@69 15 #include "unicode/unistr.h"
jpayne@69 16 #include "unicode/uformattedvalue.h"
jpayne@69 17
jpayne@69 18 U_NAMESPACE_BEGIN
jpayne@69 19
jpayne@69 20 /**
jpayne@69 21 * \file
jpayne@69 22 * \brief C++ API: Abstract operations for localized strings.
jpayne@69 23 *
jpayne@69 24 * This file contains declarations for classes that deal with formatted strings. A number
jpayne@69 25 * of APIs throughout ICU use these classes for expressing their localized output.
jpayne@69 26 */
jpayne@69 27
jpayne@69 28 /**
jpayne@69 29 * Represents a span of a string containing a given field.
jpayne@69 30 *
jpayne@69 31 * This class differs from FieldPosition in the following ways:
jpayne@69 32 *
jpayne@69 33 * 1. It has information on the field category.
jpayne@69 34 * 2. It allows you to set constraints to use when iterating over field positions.
jpayne@69 35 * 3. It is used for the newer FormattedValue APIs.
jpayne@69 36 *
jpayne@69 37 * This class is not intended for public subclassing.
jpayne@69 38 *
jpayne@69 39 * @stable ICU 64
jpayne@69 40 */
jpayne@69 41 class U_I18N_API ConstrainedFieldPosition : public UMemory {
jpayne@69 42 public:
jpayne@69 43
jpayne@69 44 /**
jpayne@69 45 * Initializes a ConstrainedFieldPosition.
jpayne@69 46 *
jpayne@69 47 * By default, the ConstrainedFieldPosition has no iteration constraints.
jpayne@69 48 *
jpayne@69 49 * @stable ICU 64
jpayne@69 50 */
jpayne@69 51 ConstrainedFieldPosition();
jpayne@69 52
jpayne@69 53 /** @stable ICU 64 */
jpayne@69 54 ~ConstrainedFieldPosition();
jpayne@69 55
jpayne@69 56 /**
jpayne@69 57 * Resets this ConstrainedFieldPosition to its initial state, as if it were newly created:
jpayne@69 58 *
jpayne@69 59 * - Removes any constraints that may have been set on the instance.
jpayne@69 60 * - Resets the iteration position.
jpayne@69 61 *
jpayne@69 62 * @stable ICU 64
jpayne@69 63 */
jpayne@69 64 void reset();
jpayne@69 65
jpayne@69 66 /**
jpayne@69 67 * Sets a constraint on the field category.
jpayne@69 68 *
jpayne@69 69 * When this instance of ConstrainedFieldPosition is passed to FormattedValue#nextPosition,
jpayne@69 70 * positions are skipped unless they have the given category.
jpayne@69 71 *
jpayne@69 72 * Any previously set constraints are cleared.
jpayne@69 73 *
jpayne@69 74 * For example, to loop over only the number-related fields:
jpayne@69 75 *
jpayne@69 76 * ConstrainedFieldPosition cfpos;
jpayne@69 77 * cfpos.constrainCategory(UFIELDCATEGORY_NUMBER_FORMAT);
jpayne@69 78 * while (fmtval.nextPosition(cfpos, status)) {
jpayne@69 79 * // handle the number-related field position
jpayne@69 80 * }
jpayne@69 81 *
jpayne@69 82 * Changing the constraint while in the middle of iterating over a FormattedValue
jpayne@69 83 * does not generally have well-defined behavior.
jpayne@69 84 *
jpayne@69 85 * @param category The field category to fix when iterating.
jpayne@69 86 * @stable ICU 64
jpayne@69 87 */
jpayne@69 88 void constrainCategory(int32_t category);
jpayne@69 89
jpayne@69 90 /**
jpayne@69 91 * Sets a constraint on the category and field.
jpayne@69 92 *
jpayne@69 93 * When this instance of ConstrainedFieldPosition is passed to FormattedValue#nextPosition,
jpayne@69 94 * positions are skipped unless they have the given category and field.
jpayne@69 95 *
jpayne@69 96 * Any previously set constraints are cleared.
jpayne@69 97 *
jpayne@69 98 * For example, to loop over all grouping separators:
jpayne@69 99 *
jpayne@69 100 * ConstrainedFieldPosition cfpos;
jpayne@69 101 * cfpos.constrainField(UFIELDCATEGORY_NUMBER_FORMAT, UNUM_GROUPING_SEPARATOR_FIELD);
jpayne@69 102 * while (fmtval.nextPosition(cfpos, status)) {
jpayne@69 103 * // handle the grouping separator position
jpayne@69 104 * }
jpayne@69 105 *
jpayne@69 106 * Changing the constraint while in the middle of iterating over a FormattedValue
jpayne@69 107 * does not generally have well-defined behavior.
jpayne@69 108 *
jpayne@69 109 * @param category The field category to fix when iterating.
jpayne@69 110 * @param field The field to fix when iterating.
jpayne@69 111 * @stable ICU 64
jpayne@69 112 */
jpayne@69 113 void constrainField(int32_t category, int32_t field);
jpayne@69 114
jpayne@69 115 /**
jpayne@69 116 * Gets the field category for the current position.
jpayne@69 117 *
jpayne@69 118 * The return value is well-defined only after
jpayne@69 119 * FormattedValue#nextPosition returns TRUE.
jpayne@69 120 *
jpayne@69 121 * @return The field category saved in the instance.
jpayne@69 122 * @stable ICU 64
jpayne@69 123 */
jpayne@69 124 inline int32_t getCategory() const {
jpayne@69 125 return fCategory;
jpayne@69 126 }
jpayne@69 127
jpayne@69 128 /**
jpayne@69 129 * Gets the field for the current position.
jpayne@69 130 *
jpayne@69 131 * The return value is well-defined only after
jpayne@69 132 * FormattedValue#nextPosition returns TRUE.
jpayne@69 133 *
jpayne@69 134 * @return The field saved in the instance.
jpayne@69 135 * @stable ICU 64
jpayne@69 136 */
jpayne@69 137 inline int32_t getField() const {
jpayne@69 138 return fField;
jpayne@69 139 }
jpayne@69 140
jpayne@69 141 /**
jpayne@69 142 * Gets the INCLUSIVE start index for the current position.
jpayne@69 143 *
jpayne@69 144 * The return value is well-defined only after FormattedValue#nextPosition returns TRUE.
jpayne@69 145 *
jpayne@69 146 * @return The start index saved in the instance.
jpayne@69 147 * @stable ICU 64
jpayne@69 148 */
jpayne@69 149 inline int32_t getStart() const {
jpayne@69 150 return fStart;
jpayne@69 151 }
jpayne@69 152
jpayne@69 153 /**
jpayne@69 154 * Gets the EXCLUSIVE end index stored for the current position.
jpayne@69 155 *
jpayne@69 156 * The return value is well-defined only after FormattedValue#nextPosition returns TRUE.
jpayne@69 157 *
jpayne@69 158 * @return The end index saved in the instance.
jpayne@69 159 * @stable ICU 64
jpayne@69 160 */
jpayne@69 161 inline int32_t getLimit() const {
jpayne@69 162 return fLimit;
jpayne@69 163 }
jpayne@69 164
jpayne@69 165 ////////////////////////////////////////////////////////////////////
jpayne@69 166 //// The following methods are for FormattedValue implementers; ////
jpayne@69 167 //// most users can ignore them. ////
jpayne@69 168 ////////////////////////////////////////////////////////////////////
jpayne@69 169
jpayne@69 170 /**
jpayne@69 171 * Gets an int64 that FormattedValue implementations may use for storage.
jpayne@69 172 *
jpayne@69 173 * The initial value is zero.
jpayne@69 174 *
jpayne@69 175 * Users of FormattedValue should not need to call this method.
jpayne@69 176 *
jpayne@69 177 * @return The current iteration context from {@link #setInt64IterationContext}.
jpayne@69 178 * @stable ICU 64
jpayne@69 179 */
jpayne@69 180 inline int64_t getInt64IterationContext() const {
jpayne@69 181 return fContext;
jpayne@69 182 }
jpayne@69 183
jpayne@69 184 /**
jpayne@69 185 * Sets an int64 that FormattedValue implementations may use for storage.
jpayne@69 186 *
jpayne@69 187 * Intended to be used by FormattedValue implementations.
jpayne@69 188 *
jpayne@69 189 * @param context The new iteration context.
jpayne@69 190 * @stable ICU 64
jpayne@69 191 */
jpayne@69 192 void setInt64IterationContext(int64_t context);
jpayne@69 193
jpayne@69 194 /**
jpayne@69 195 * Determines whether a given field should be included given the
jpayne@69 196 * constraints.
jpayne@69 197 *
jpayne@69 198 * Intended to be used by FormattedValue implementations.
jpayne@69 199 *
jpayne@69 200 * @param category The category to test.
jpayne@69 201 * @param field The field to test.
jpayne@69 202 * @stable ICU 64
jpayne@69 203 */
jpayne@69 204 UBool matchesField(int32_t category, int32_t field) const;
jpayne@69 205
jpayne@69 206 /**
jpayne@69 207 * Sets new values for the primary public getters.
jpayne@69 208 *
jpayne@69 209 * Intended to be used by FormattedValue implementations.
jpayne@69 210 *
jpayne@69 211 * It is up to the implementation to ensure that the user-requested
jpayne@69 212 * constraints are satisfied. This method does not check!
jpayne@69 213 *
jpayne@69 214 * @param category The new field category.
jpayne@69 215 * @param field The new field.
jpayne@69 216 * @param start The new inclusive start index.
jpayne@69 217 * @param limit The new exclusive end index.
jpayne@69 218 * @stable ICU 64
jpayne@69 219 */
jpayne@69 220 void setState(
jpayne@69 221 int32_t category,
jpayne@69 222 int32_t field,
jpayne@69 223 int32_t start,
jpayne@69 224 int32_t limit);
jpayne@69 225
jpayne@69 226 private:
jpayne@69 227 int64_t fContext = 0LL;
jpayne@69 228 int32_t fField = 0;
jpayne@69 229 int32_t fStart = 0;
jpayne@69 230 int32_t fLimit = 0;
jpayne@69 231 int32_t fCategory = UFIELD_CATEGORY_UNDEFINED;
jpayne@69 232 int8_t fConstraint = 0;
jpayne@69 233 };
jpayne@69 234
jpayne@69 235 /**
jpayne@69 236 * An abstract formatted value: a string with associated field attributes.
jpayne@69 237 * Many formatters format to classes implementing FormattedValue.
jpayne@69 238 *
jpayne@69 239 * @stable ICU 64
jpayne@69 240 */
jpayne@69 241 class U_I18N_API FormattedValue /* not : public UObject because this is an interface/mixin class */ {
jpayne@69 242 public:
jpayne@69 243 /** @stable ICU 64 */
jpayne@69 244 virtual ~FormattedValue();
jpayne@69 245
jpayne@69 246 /**
jpayne@69 247 * Returns the formatted string as a self-contained UnicodeString.
jpayne@69 248 *
jpayne@69 249 * If you need the string within the current scope only, consider #toTempString.
jpayne@69 250 *
jpayne@69 251 * @param status Set if an error occurs.
jpayne@69 252 * @return a UnicodeString containing the formatted string.
jpayne@69 253 *
jpayne@69 254 * @stable ICU 64
jpayne@69 255 */
jpayne@69 256 virtual UnicodeString toString(UErrorCode& status) const = 0;
jpayne@69 257
jpayne@69 258 /**
jpayne@69 259 * Returns the formatted string as a read-only alias to memory owned by the FormattedValue.
jpayne@69 260 *
jpayne@69 261 * The return value is valid only as long as this FormattedValue is present and unchanged in
jpayne@69 262 * memory. If you need the string outside the current scope, consider #toString.
jpayne@69 263 *
jpayne@69 264 * The buffer returned by calling UnicodeString#getBuffer() on the return value is
jpayne@69 265 * guaranteed to be NUL-terminated.
jpayne@69 266 *
jpayne@69 267 * @param status Set if an error occurs.
jpayne@69 268 * @return a temporary UnicodeString containing the formatted string.
jpayne@69 269 *
jpayne@69 270 * @stable ICU 64
jpayne@69 271 */
jpayne@69 272 virtual UnicodeString toTempString(UErrorCode& status) const = 0;
jpayne@69 273
jpayne@69 274 /**
jpayne@69 275 * Appends the formatted string to an Appendable.
jpayne@69 276 *
jpayne@69 277 * @param appendable
jpayne@69 278 * The Appendable to which to append the string output.
jpayne@69 279 * @param status Set if an error occurs.
jpayne@69 280 * @return The same Appendable, for chaining.
jpayne@69 281 *
jpayne@69 282 * @stable ICU 64
jpayne@69 283 * @see Appendable
jpayne@69 284 */
jpayne@69 285 virtual Appendable& appendTo(Appendable& appendable, UErrorCode& status) const = 0;
jpayne@69 286
jpayne@69 287 /**
jpayne@69 288 * Iterates over field positions in the FormattedValue. This lets you determine the position
jpayne@69 289 * of specific types of substrings, like a month or a decimal separator.
jpayne@69 290 *
jpayne@69 291 * To loop over all field positions:
jpayne@69 292 *
jpayne@69 293 * ConstrainedFieldPosition cfpos;
jpayne@69 294 * while (fmtval.nextPosition(cfpos, status)) {
jpayne@69 295 * // handle the field position; get information from cfpos
jpayne@69 296 * }
jpayne@69 297 *
jpayne@69 298 * @param cfpos
jpayne@69 299 * The object used for iteration state. This can provide constraints to iterate over
jpayne@69 300 * only one specific category or field;
jpayne@69 301 * see ConstrainedFieldPosition#constrainCategory
jpayne@69 302 * and ConstrainedFieldPosition#constrainField.
jpayne@69 303 * @param status Set if an error occurs.
jpayne@69 304 * @return TRUE if a new occurrence of the field was found;
jpayne@69 305 * FALSE otherwise or if an error was set.
jpayne@69 306 *
jpayne@69 307 * @stable ICU 64
jpayne@69 308 */
jpayne@69 309 virtual UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const = 0;
jpayne@69 310 };
jpayne@69 311
jpayne@69 312 U_NAMESPACE_END
jpayne@69 313
jpayne@69 314 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 315
jpayne@69 316 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 317
jpayne@69 318 #endif // __FORMATTEDVALUE_H__