Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/simpleformatter.h
$ cat -n /usr/include/unicode/simpleformatter.h 1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ****************************************************************************** 5 * Copyright (C) 2014-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ****************************************************************************** 8 * simpleformatter.h 9 */ 10 11 #ifndef __SIMPLEFORMATTER_H__ 12 #define __SIMPLEFORMATTER_H__ 13 14 /** 15 * \file 16 * \brief C++ API: Simple formatter, minimal subset of MessageFormat. 17 */ 18 19 #include "unicode/utypes.h" 20 21 #if U_SHOW_CPLUSPLUS_API 22 23 #include "unicode/unistr.h" 24 25 U_NAMESPACE_BEGIN 26 27 // Forward declaration: 28 namespace number { 29 namespace impl { 30 class SimpleModifier; 31 } 32 } 33 34 /** 35 * Formats simple patterns like "{1} was born in {0}". 36 * Minimal subset of MessageFormat; fast, simple, minimal dependencies. 37 * Supports only numbered arguments with no type nor style parameters, 38 * and formats only string values. 39 * Quoting via ASCII apostrophe compatible with ICU MessageFormat default behavior. 40 * 41 * Factory methods set error codes for syntax errors 42 * and for too few or too many arguments/placeholders. 43 * 44 * SimpleFormatter objects are thread-safe except for assignment and applying new patterns. 45 * 46 * Example: 47 * <pre> 48 * UErrorCode errorCode = U_ZERO_ERROR; 49 * SimpleFormatter fmt("{1} '{born}' in {0}", errorCode); 50 * UnicodeString result; 51 * 52 * // Output: "paul {born} in england" 53 * fmt.format("england", "paul", result, errorCode); 54 * </pre> 55 * 56 * This class is not intended for public subclassing. 57 * 58 * @see MessageFormat 59 * @see UMessagePatternApostropheMode 60 * @stable ICU 57 61 */ 62 class U_COMMON_API SimpleFormatter final : public UMemory { 63 public: 64 /** 65 * Default constructor. 66 * @stable ICU 57 67 */ 68 SimpleFormatter() : compiledPattern((char16_t)0) {} 69 70 /** 71 * Constructs a formatter from the pattern string. 72 * 73 * @param pattern The pattern string. 74 * @param errorCode ICU error code in/out parameter. 75 * Must fulfill U_SUCCESS before the function call. 76 * Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax. 77 * @stable ICU 57 78 */ 79 SimpleFormatter(const UnicodeString& pattern, UErrorCode &errorCode) { 80 applyPattern(pattern, errorCode); 81 } 82 83 /** 84 * Constructs a formatter from the pattern string. 85 * The number of arguments checked against the given limits is the 86 * highest argument number plus one, not the number of occurrences of arguments. 87 * 88 * @param pattern The pattern string. 89 * @param min The pattern must have at least this many arguments. 90 * @param max The pattern must have at most this many arguments. 91 * @param errorCode ICU error code in/out parameter. 92 * Must fulfill U_SUCCESS before the function call. 93 * Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax and 94 * too few or too many arguments. 95 * @stable ICU 57 96 */ 97 SimpleFormatter(const UnicodeString& pattern, int32_t min, int32_t max, 98 UErrorCode &errorCode) { 99 applyPatternMinMaxArguments(pattern, min, max, errorCode); 100 } 101 102 /** 103 * Copy constructor. 104 * @stable ICU 57 105 */ 106 SimpleFormatter(const SimpleFormatter& other) 107 : compiledPattern(other.compiledPattern) {} 108 109 /** 110 * Assignment operator. 111 * @stable ICU 57 112 */ 113 SimpleFormatter &operator=(const SimpleFormatter& other); 114 115 /** 116 * Destructor. 117 * @stable ICU 57 118 */ 119 ~SimpleFormatter(); 120 121 /** 122 * Changes this object according to the new pattern. 123 * 124 * @param pattern The pattern string. 125 * @param errorCode ICU error code in/out parameter. 126 * Must fulfill U_SUCCESS before the function call. 127 * Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax. 128 * @return true if U_SUCCESS(errorCode). 129 * @stable ICU 57 130 */ 131 UBool applyPattern(const UnicodeString &pattern, UErrorCode &errorCode) { 132 return applyPatternMinMaxArguments(pattern, 0, INT32_MAX, errorCode); 133 } 134 135 /** 136 * Changes this object according to the new pattern. 137 * The number of arguments checked against the given limits is the 138 * highest argument number plus one, not the number of occurrences of arguments. 139 * 140 * @param pattern The pattern string. 141 * @param min The pattern must have at least this many arguments. 142 * @param max The pattern must have at most this many arguments. 143 * @param errorCode ICU error code in/out parameter. 144 * Must fulfill U_SUCCESS before the function call. 145 * Set to U_ILLEGAL_ARGUMENT_ERROR for bad argument syntax and 146 * too few or too many arguments. 147 * @return true if U_SUCCESS(errorCode). 148 * @stable ICU 57 149 */ 150 UBool applyPatternMinMaxArguments(const UnicodeString &pattern, 151 int32_t min, int32_t max, UErrorCode &errorCode); 152 153 /** 154 * @return The max argument number + 1. 155 * @stable ICU 57 156 */ 157 int32_t getArgumentLimit() const { 158 return getArgumentLimit(compiledPattern.getBuffer(), compiledPattern.length()); 159 } 160 161 /** 162 * Formats the given value, appending to the appendTo builder. 163 * The argument value must not be the same object as appendTo. 164 * getArgumentLimit() must be at most 1. 165 * 166 * @param value0 Value for argument {0}. 167 * @param appendTo Gets the formatted pattern and value appended. 168 * @param errorCode ICU error code in/out parameter. 169 * Must fulfill U_SUCCESS before the function call. 170 * @return appendTo 171 * @stable ICU 57 172 */ 173 UnicodeString &format( 174 const UnicodeString &value0, 175 UnicodeString &appendTo, UErrorCode &errorCode) const; 176 177 /** 178 * Formats the given values, appending to the appendTo builder. 179 * An argument value must not be the same object as appendTo. 180 * getArgumentLimit() must be at most 2. 181 * 182 * @param value0 Value for argument {0}. 183 * @param value1 Value for argument {1}. 184 * @param appendTo Gets the formatted pattern and values appended. 185 * @param errorCode ICU error code in/out parameter. 186 * Must fulfill U_SUCCESS before the function call. 187 * @return appendTo 188 * @stable ICU 57 189 */ 190 UnicodeString &format( 191 const UnicodeString &value0, 192 const UnicodeString &value1, 193 UnicodeString &appendTo, UErrorCode &errorCode) const; 194 195 /** 196 * Formats the given values, appending to the appendTo builder. 197 * An argument value must not be the same object as appendTo. 198 * getArgumentLimit() must be at most 3. 199 * 200 * @param value0 Value for argument {0}. 201 * @param value1 Value for argument {1}. 202 * @param value2 Value for argument {2}. 203 * @param appendTo Gets the formatted pattern and values appended. 204 * @param errorCode ICU error code in/out parameter. 205 * Must fulfill U_SUCCESS before the function call. 206 * @return appendTo 207 * @stable ICU 57 208 */ 209 UnicodeString &format( 210 const UnicodeString &value0, 211 const UnicodeString &value1, 212 const UnicodeString &value2, 213 UnicodeString &appendTo, UErrorCode &errorCode) const; 214 215 /** 216 * Formats the given values, appending to the appendTo string. 217 * 218 * @param values The argument values. 219 * An argument value must not be the same object as appendTo. 220 * Can be nullptr if valuesLength==getArgumentLimit()==0. 221 * @param valuesLength The length of the values array. 222 * Must be at least getArgumentLimit(). 223 * @param appendTo Gets the formatted pattern and values appended. 224 * @param offsets offsets[i] receives the offset of where 225 * values[i] replaced pattern argument {i}. 226 * Can be shorter or longer than values. Can be nullptr if offsetsLength==0. 227 * If there is no {i} in the pattern, then offsets[i] is set to -1. 228 * @param offsetsLength The length of the offsets array. 229 * @param errorCode ICU error code in/out parameter. 230 * Must fulfill U_SUCCESS before the function call. 231 * @return appendTo 232 * @stable ICU 57 233 */ 234 UnicodeString &formatAndAppend( 235 const UnicodeString *const *values, int32_t valuesLength, 236 UnicodeString &appendTo, 237 int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const; 238 239 /** 240 * Formats the given values, replacing the contents of the result string. 241 * May optimize by actually appending to the result if it is the same object 242 * as the value corresponding to the initial argument in the pattern. 243 * 244 * @param values The argument values. 245 * An argument value may be the same object as result. 246 * Can be nullptr if valuesLength==getArgumentLimit()==0. 247 * @param valuesLength The length of the values array. 248 * Must be at least getArgumentLimit(). 249 * @param result Gets its contents replaced by the formatted pattern and values. 250 * @param offsets offsets[i] receives the offset of where 251 * values[i] replaced pattern argument {i}. 252 * Can be shorter or longer than values. Can be nullptr if offsetsLength==0. 253 * If there is no {i} in the pattern, then offsets[i] is set to -1. 254 * @param offsetsLength The length of the offsets array. 255 * @param errorCode ICU error code in/out parameter. 256 * Must fulfill U_SUCCESS before the function call. 257 * @return result 258 * @stable ICU 57 259 */ 260 UnicodeString &formatAndReplace( 261 const UnicodeString *const *values, int32_t valuesLength, 262 UnicodeString &result, 263 int32_t *offsets, int32_t offsetsLength, UErrorCode &errorCode) const; 264 265 /** 266 * Returns the pattern text with none of the arguments. 267 * Like formatting with all-empty string values. 268 * @stable ICU 57 269 */ 270 UnicodeString getTextWithNoArguments() const { 271 return getTextWithNoArguments( 272 compiledPattern.getBuffer(), 273 compiledPattern.length(), 274 nullptr, 275 0); 276 } 277 278 #ifndef U_HIDE_INTERNAL_API 279 /** 280 * Returns the pattern text with none of the arguments. 281 * Like formatting with all-empty string values. 282 * 283 * TODO(ICU-20406): Replace this with an Iterator interface. 284 * 285 * @param offsets offsets[i] receives the offset of where {i} was located 286 * before it was replaced by an empty string. 287 * For example, "a{0}b{1}" produces offset 1 for i=0 and 2 for i=1. 288 * Can be nullptr if offsetsLength==0. 289 * If there is no {i} in the pattern, then offsets[i] is set to -1. 290 * @param offsetsLength The length of the offsets array. 291 * 292 * @internal 293 */ 294 UnicodeString getTextWithNoArguments(int32_t *offsets, int32_t offsetsLength) const { 295 return getTextWithNoArguments( 296 compiledPattern.getBuffer(), 297 compiledPattern.length(), 298 offsets, 299 offsetsLength); 300 } 301 #endif // U_HIDE_INTERNAL_API 302 303 private: 304 /** 305 * Binary representation of the compiled pattern. 306 * Index 0: One more than the highest argument number. 307 * Followed by zero or more arguments or literal-text segments. 308 * 309 * An argument is stored as its number, less than ARG_NUM_LIMIT. 310 * A literal-text segment is stored as its length (at least 1) offset by ARG_NUM_LIMIT, 311 * followed by that many chars. 312 */ 313 UnicodeString compiledPattern; 314 315 static inline int32_t getArgumentLimit(const char16_t *compiledPattern, 316 int32_t compiledPatternLength) { 317 return compiledPatternLength == 0 ? 0 : compiledPattern[0]; 318 } 319 320 static UnicodeString getTextWithNoArguments( 321 const char16_t *compiledPattern, 322 int32_t compiledPatternLength, 323 int32_t *offsets, 324 int32_t offsetsLength); 325 326 static UnicodeString &format( 327 const char16_t *compiledPattern, int32_t compiledPatternLength, 328 const UnicodeString *const *values, 329 UnicodeString &result, const UnicodeString *resultCopy, UBool forbidResultAsValue, 330 int32_t *offsets, int32_t offsetsLength, 331 UErrorCode &errorCode); 332 333 // Give access to internals to SimpleModifier for number formatting 334 friend class number::impl::SimpleModifier; 335 }; 336 337 U_NAMESPACE_END 338 339 #endif /* U_SHOW_CPLUSPLUS_API */ 340 341 #endif // __SIMPLEFORMATTER_H__
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
