Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/choicfmt.h
$ cat -n /usr/include/unicode/choicfmt.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) 1997-2013, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ******************************************************************************** 8 * 9 * File CHOICFMT.H 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 02/19/97 aliu Converted from java. 15 * 03/20/97 helena Finished first cut of implementation and got rid 16 * of nextDouble/previousDouble and replaced with 17 * boolean array. 18 * 4/10/97 aliu Clean up. Modified to work on AIX. 19 * 8/6/97 nos Removed overloaded constructor, member var 'buffer'. 20 * 07/22/98 stephen Removed operator!= (implemented in Format) 21 ******************************************************************************** 22 */ 23 24 #ifndef CHOICFMT_H 25 #define CHOICFMT_H 26 27 #include "unicode/utypes.h" 28 29 #if U_SHOW_CPLUSPLUS_API 30 31 /** 32 * \file 33 * \brief C++ API: Choice Format. 34 */ 35 36 #if !UCONFIG_NO_FORMATTING 37 38 #include "unicode/fieldpos.h" 39 #include "unicode/format.h" 40 #include "unicode/messagepattern.h" 41 #include "unicode/numfmt.h" 42 #include "unicode/unistr.h" 43 44 #ifndef U_HIDE_DEPRECATED_API 45 46 U_NAMESPACE_BEGIN 47 48 class MessageFormat; 49 50 /** 51 * ChoiceFormat converts between ranges of numeric values and strings for those ranges. 52 * The strings must conform to the MessageFormat pattern syntax. 53 * 54 * <p><em><code>ChoiceFormat</code> is probably not what you need. 55 * Please use <code>MessageFormat</code> 56 * with <code>plural</code> arguments for proper plural selection, 57 * and <code>select</code> arguments for simple selection among a fixed set of choices!</em></p> 58 * 59 * <p>A <code>ChoiceFormat</code> splits 60 * the real number line \htmlonly<code>-∞</code> to 61 * <code>+∞</code>\endhtmlonly into two 62 * or more contiguous ranges. Each range is mapped to a 63 * string.</p> 64 * 65 * <p><code>ChoiceFormat</code> was originally intended 66 * for displaying grammatically correct 67 * plurals such as "There is one file." vs. "There are 2 files." 68 * <em>However,</em> plural rules for many languages 69 * are too complex for the capabilities of ChoiceFormat, 70 * and its requirement of specifying the precise rules for each message 71 * is unmanageable for translators.</p> 72 * 73 * <p>There are two methods of defining a <code>ChoiceFormat</code>; both 74 * are equivalent. The first is by using a string pattern. This is the 75 * preferred method in most cases. The second method is through direct 76 * specification of the arrays that logically make up the 77 * <code>ChoiceFormat</code>.</p> 78 * 79 * <p>Note: Typically, choice formatting is done (if done at all) via <code>MessageFormat</code> 80 * with a <code>choice</code> argument type, 81 * rather than using a stand-alone <code>ChoiceFormat</code>.</p> 82 * 83 * <h5>Patterns and Their Interpretation</h5> 84 * 85 * <p>The pattern string defines the range boundaries and the strings for each number range. 86 * Syntax: 87 * <pre> 88 * choiceStyle = number separator message ('|' number separator message)* 89 * number = normal_number | ['-'] \htmlonly∞\endhtmlonly (U+221E, infinity) 90 * normal_number = double value (unlocalized ASCII string) 91 * separator = less_than | less_than_or_equal 92 * less_than = '<' 93 * less_than_or_equal = '#' | \htmlonly≤\endhtmlonly (U+2264) 94 * message: see {@link MessageFormat} 95 * </pre> 96 * Pattern_White_Space between syntax elements is ignored, except 97 * around each range's sub-message.</p> 98 * 99 * <p>Each numeric sub-range extends from the current range's number 100 * to the next range's number. 101 * The number itself is included in its range if a <code>less_than_or_equal</code> sign is used, 102 * and excluded from its range (and instead included in the previous range) 103 * if a <code>less_than</code> sign is used.</p> 104 * 105 * <p>When a <code>ChoiceFormat</code> is constructed from 106 * arrays of numbers, closure flags and strings, 107 * they are interpreted just like 108 * the sequence of <code>(number separator string)</code> in an equivalent pattern string. 109 * <code>closure[i]==true</code> corresponds to a <code>less_than</code> separator sign. 110 * The equivalent pattern string will be constructed automatically.</p> 111 * 112 * <p>During formatting, a number is mapped to the first range 113 * where the number is not greater than the range's upper limit. 114 * That range's message string is returned. A NaN maps to the very first range.</p> 115 * 116 * <p>During parsing, a range is selected for the longest match of 117 * any range's message. That range's number is returned, ignoring the separator/closure. 118 * Only a simple string match is performed, without parsing of arguments that 119 * might be specified in the message strings.</p> 120 * 121 * <p>Note that the first range's number is ignored in formatting 122 * but may be returned from parsing.</p> 123 * 124 * <h5>Examples</h5> 125 * 126 * <p>Here is an example of two arrays that map the number 127 * <code>1..7</code> to the English day of the week abbreviations 128 * <code>Sun..Sat</code>. No closures array is given; this is the same as 129 * specifying all closures to be <code>false</code>.</p> 130 * 131 * <pre> {1,2,3,4,5,6,7}, 132 * {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}</pre> 133 * 134 * <p>Here is an example that maps the ranges [-Inf, 1), [1, 1], and (1, 135 * +Inf] to three strings. That is, the number line is split into three 136 * ranges: x < 1.0, x = 1.0, and x > 1.0. 137 * (The round parentheses in the notation above indicate an exclusive boundary, 138 * like the turned bracket in European notation: [-Inf, 1) == [-Inf, 1[ )</p> 139 * 140 * <pre> {0, 1, 1}, 141 * {false, false, true}, 142 * {"no files", "one file", "many files"}</pre> 143 * 144 * <p>Here is an example that shows formatting and parsing: </p> 145 * 146 * \code 147 * #include <unicode/choicfmt.h> 148 * #include <unicode/unistr.h> 149 * #include <iostream.h> 150 * 151 * int main(int argc, char *argv[]) { 152 * double limits[] = {1,2,3,4,5,6,7}; 153 * UnicodeString monthNames[] = { 154 * "Sun","Mon","Tue","Wed","Thu","Fri","Sat"}; 155 * ChoiceFormat fmt(limits, monthNames, 7); 156 * UnicodeString str; 157 * char buf[256]; 158 * for (double x = 1.0; x <= 8.0; x += 1.0) { 159 * fmt.format(x, str); 160 * str.extract(0, str.length(), buf, 256, ""); 161 * str.truncate(0); 162 * cout << x << " -> " 163 * << buf << endl; 164 * } 165 * cout << endl; 166 * return 0; 167 * } 168 * \endcode 169 * 170 * <p><em>User subclasses are not supported.</em> While clients may write 171 * subclasses, such code will not necessarily work and will not be 172 * guaranteed to work stably from release to release. 173 * 174 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 175 */ 176 class U_I18N_API ChoiceFormat: public NumberFormat { 177 public: 178 /** 179 * Constructs a new ChoiceFormat from the pattern string. 180 * 181 * @param pattern Pattern used to construct object. 182 * @param status Output param to receive success code. If the 183 * pattern cannot be parsed, set to failure code. 184 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 185 */ 186 ChoiceFormat(const UnicodeString& pattern, 187 UErrorCode& status); 188 189 190 /** 191 * Constructs a new ChoiceFormat with the given limits and message strings. 192 * All closure flags default to <code>false</code>, 193 * equivalent to <code>less_than_or_equal</code> separators. 194 * 195 * Copies the limits and formats instead of adopting them. 196 * 197 * @param limits Array of limit values. 198 * @param formats Array of formats. 199 * @param count Size of 'limits' and 'formats' arrays. 200 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 201 */ 202 ChoiceFormat(const double* limits, 203 const UnicodeString* formats, 204 int32_t count ); 205 206 /** 207 * Constructs a new ChoiceFormat with the given limits, closure flags and message strings. 208 * 209 * Copies the limits and formats instead of adopting them. 210 * 211 * @param limits Array of limit values 212 * @param closures Array of booleans specifying whether each 213 * element of 'limits' is open or closed. If false, then the 214 * corresponding limit number is a member of its range. 215 * If true, then the limit number belongs to the previous range it. 216 * @param formats Array of formats 217 * @param count Size of 'limits', 'closures', and 'formats' arrays 218 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 219 */ 220 ChoiceFormat(const double* limits, 221 const UBool* closures, 222 const UnicodeString* formats, 223 int32_t count); 224 225 /** 226 * Copy constructor. 227 * 228 * @param that ChoiceFormat object to be copied from 229 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 230 */ 231 ChoiceFormat(const ChoiceFormat& that); 232 233 /** 234 * Assignment operator. 235 * 236 * @param that ChoiceFormat object to be copied 237 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 238 */ 239 const ChoiceFormat& operator=(const ChoiceFormat& that); 240 241 /** 242 * Destructor. 243 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 244 */ 245 virtual ~ChoiceFormat(); 246 247 /** 248 * Clones this Format object. The caller owns the 249 * result and must delete it when done. 250 * 251 * @return a copy of this object 252 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 253 */ 254 virtual ChoiceFormat* clone() const override; 255 256 /** 257 * Returns true if the given Format objects are semantically equal. 258 * Objects of different subclasses are considered unequal. 259 * 260 * @param other ChoiceFormat object to be compared 261 * @return true if other is the same as this. 262 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 263 */ 264 virtual bool operator==(const Format& other) const override; 265 266 /** 267 * Sets the pattern. 268 * @param pattern The pattern to be applied. 269 * @param status Output param set to success/failure code on 270 * exit. If the pattern is invalid, this will be 271 * set to a failure result. 272 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 273 */ 274 virtual void applyPattern(const UnicodeString& pattern, 275 UErrorCode& status); 276 277 /** 278 * Sets the pattern. 279 * @param pattern The pattern to be applied. 280 * @param parseError Struct to receive information on position 281 * of error if an error is encountered 282 * @param status Output param set to success/failure code on 283 * exit. If the pattern is invalid, this will be 284 * set to a failure result. 285 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 286 */ 287 virtual void applyPattern(const UnicodeString& pattern, 288 UParseError& parseError, 289 UErrorCode& status); 290 /** 291 * Gets the pattern. 292 * 293 * @param pattern Output param which will receive the pattern 294 * Previous contents are deleted. 295 * @return A reference to 'pattern' 296 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 297 */ 298 virtual UnicodeString& toPattern(UnicodeString &pattern) const; 299 300 /** 301 * Sets the choices to be used in formatting. 302 * For details see the constructor with the same parameter list. 303 * 304 * @param limitsToCopy Contains the top value that you want 305 * parsed with that format,and should be in 306 * ascending sorted order. When formatting X, 307 * the choice will be the i, where limit[i] 308 * <= X < limit[i+1]. 309 * @param formatsToCopy The format strings you want to use for each limit. 310 * @param count The size of the above arrays. 311 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 312 */ 313 virtual void setChoices(const double* limitsToCopy, 314 const UnicodeString* formatsToCopy, 315 int32_t count ); 316 317 /** 318 * Sets the choices to be used in formatting. 319 * For details see the constructor with the same parameter list. 320 * 321 * @param limits Array of limits 322 * @param closures Array of limit booleans 323 * @param formats Array of format string 324 * @param count The size of the above arrays 325 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 326 */ 327 virtual void setChoices(const double* limits, 328 const UBool* closures, 329 const UnicodeString* formats, 330 int32_t count); 331 332 /** 333 * Returns nullptr and 0. 334 * Before ICU 4.8, this used to return the choice limits array. 335 * 336 * @param count Will be set to 0. 337 * @return nullptr 338 * @deprecated ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern. 339 */ 340 virtual const double* getLimits(int32_t& count) const; 341 342 /** 343 * Returns nullptr and 0. 344 * Before ICU 4.8, this used to return the limit booleans array. 345 * 346 * @param count Will be set to 0. 347 * @return nullptr 348 * @deprecated ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern. 349 */ 350 virtual const UBool* getClosures(int32_t& count) const; 351 352 /** 353 * Returns nullptr and 0. 354 * Before ICU 4.8, this used to return the array of choice strings. 355 * 356 * @param count Will be set to 0. 357 * @return nullptr 358 * @deprecated ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern. 359 */ 360 virtual const UnicodeString* getFormats(int32_t& count) const; 361 362 363 using NumberFormat::format; 364 365 /** 366 * Formats a double number using this object's choices. 367 * 368 * @param number The value to be formatted. 369 * @param appendTo Output parameter to receive result. 370 * Result is appended to existing contents. 371 * @param pos On input: an alignment field, if desired. 372 * On output: the offsets of the alignment field. 373 * @return Reference to 'appendTo' parameter. 374 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 375 */ 376 virtual UnicodeString& format(double number, 377 UnicodeString& appendTo, 378 FieldPosition& pos) const override; 379 /** 380 * Formats an int32_t number using this object's choices. 381 * 382 * @param number The value to be formatted. 383 * @param appendTo Output parameter to receive result. 384 * Result is appended to existing contents. 385 * @param pos On input: an alignment field, if desired. 386 * On output: the offsets of the alignment field. 387 * @return Reference to 'appendTo' parameter. 388 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 389 */ 390 virtual UnicodeString& format(int32_t number, 391 UnicodeString& appendTo, 392 FieldPosition& pos) const override; 393 394 /** 395 * Formats an int64_t number using this object's choices. 396 * 397 * @param number The value to be formatted. 398 * @param appendTo Output parameter to receive result. 399 * Result is appended to existing contents. 400 * @param pos On input: an alignment field, if desired. 401 * On output: the offsets of the alignment field. 402 * @return Reference to 'appendTo' parameter. 403 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 404 */ 405 virtual UnicodeString& format(int64_t number, 406 UnicodeString& appendTo, 407 FieldPosition& pos) const override; 408 409 /** 410 * Formats an array of objects using this object's choices. 411 * 412 * @param objs The array of objects to be formatted. 413 * @param cnt The size of objs. 414 * @param appendTo Output parameter to receive result. 415 * Result is appended to existing contents. 416 * @param pos On input: an alignment field, if desired. 417 * On output: the offsets of the alignment field. 418 * @param success Output param set to success/failure code on 419 * exit. 420 * @return Reference to 'appendTo' parameter. 421 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 422 */ 423 virtual UnicodeString& format(const Formattable* objs, 424 int32_t cnt, 425 UnicodeString& appendTo, 426 FieldPosition& pos, 427 UErrorCode& success) const; 428 429 using NumberFormat::parse; 430 431 /** 432 * Looks for the longest match of any message string on the input text and, 433 * if there is a match, sets the result object to the corresponding range's number. 434 * 435 * If no string matches, then the parsePosition is unchanged. 436 * 437 * @param text The text to be parsed. 438 * @param result Formattable to be set to the parse result. 439 * If parse fails, return contents are undefined. 440 * @param parsePosition The position to start parsing at on input. 441 * On output, moved to after the last successfully 442 * parse character. On parse failure, does not change. 443 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 444 */ 445 virtual void parse(const UnicodeString& text, 446 Formattable& result, 447 ParsePosition& parsePosition) const override; 448 449 /** 450 * Returns a unique class ID POLYMORPHICALLY. Part of ICU's "poor man's RTTI". 451 * 452 * @return The class ID for this object. All objects of a 453 * given class have the same class ID. Objects of 454 * other classes have different class IDs. 455 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 456 */ 457 virtual UClassID getDynamicClassID(void) const override; 458 459 /** 460 * Returns the class ID for this class. This is useful only for 461 * comparing to a return value from getDynamicClassID(). For example: 462 * <pre> 463 * . Base* polymorphic_pointer = createPolymorphicObject(); 464 * . if (polymorphic_pointer->getDynamicClassID() == 465 * . Derived::getStaticClassID()) ... 466 * </pre> 467 * @return The class ID for all objects of this class. 468 * @deprecated ICU 49 Use MessageFormat instead, with plural and select arguments. 469 */ 470 static UClassID U_EXPORT2 getStaticClassID(void); 471 472 private: 473 /** 474 * Converts a double value to a string. 475 * @param value the double number to be converted. 476 * @param string the result string. 477 * @return the converted string. 478 */ 479 static UnicodeString& dtos(double value, UnicodeString& string); 480 481 ChoiceFormat() = delete; // default constructor not implemented 482 483 /** 484 * Construct a new ChoiceFormat with the limits and the corresponding formats 485 * based on the pattern. 486 * 487 * @param newPattern Pattern used to construct object. 488 * @param parseError Struct to receive information on position 489 * of error if an error is encountered. 490 * @param status Output param to receive success code. If the 491 * pattern cannot be parsed, set to failure code. 492 */ 493 ChoiceFormat(const UnicodeString& newPattern, 494 UParseError& parseError, 495 UErrorCode& status); 496 497 friend class MessageFormat; 498 499 virtual void setChoices(const double* limits, 500 const UBool* closures, 501 const UnicodeString* formats, 502 int32_t count, 503 UErrorCode &errorCode); 504 505 /** 506 * Finds the ChoiceFormat sub-message for the given number. 507 * @param pattern A MessagePattern. 508 * @param partIndex the index of the first ChoiceFormat argument style part. 509 * @param number a number to be mapped to one of the ChoiceFormat argument's intervals 510 * @return the sub-message start part index. 511 */ 512 static int32_t findSubMessage(const MessagePattern &pattern, int32_t partIndex, double number); 513 514 static double parseArgument( 515 const MessagePattern &pattern, int32_t partIndex, 516 const UnicodeString &source, ParsePosition &pos); 517 518 /** 519 * Matches the pattern string from the end of the partIndex to 520 * the beginning of the limitPartIndex, 521 * including all syntax except SKIP_SYNTAX, 522 * against the source string starting at sourceOffset. 523 * If they match, returns the length of the source string match. 524 * Otherwise returns -1. 525 */ 526 static int32_t matchStringUntilLimitPart( 527 const MessagePattern &pattern, int32_t partIndex, int32_t limitPartIndex, 528 const UnicodeString &source, int32_t sourceOffset); 529 530 /** 531 * Some of the ChoiceFormat constructors do not have a UErrorCode parameter. 532 * We need _some_ way to provide one for the MessagePattern constructor. 533 * Alternatively, the MessagePattern could be a pointer field, but that is 534 * not nice either. 535 */ 536 UErrorCode constructorErrorCode; 537 538 /** 539 * The MessagePattern which contains the parsed structure of the pattern string. 540 * 541 * Starting with ICU 4.8, the MessagePattern contains a sequence of 542 * numeric/selector/message parts corresponding to the parsed pattern. 543 * For details see the MessagePattern class API docs. 544 */ 545 MessagePattern msgPattern; 546 547 /** 548 * Docs & fields from before ICU 4.8, before MessagePattern was used. 549 * Commented out, and left only for explanation of semantics. 550 * -------- 551 * Each ChoiceFormat divides the range -Inf..+Inf into fCount 552 * intervals. The intervals are: 553 * 554 * 0: fChoiceLimits[0]..fChoiceLimits[1] 555 * 1: fChoiceLimits[1]..fChoiceLimits[2] 556 * ... 557 * fCount-2: fChoiceLimits[fCount-2]..fChoiceLimits[fCount-1] 558 * fCount-1: fChoiceLimits[fCount-1]..+Inf 559 * 560 * Interval 0 is special; during formatting (mapping numbers to 561 * strings), it also contains all numbers less than 562 * fChoiceLimits[0], as well as NaN values. 563 * 564 * Interval i maps to and from string fChoiceFormats[i]. When 565 * parsing (mapping strings to numbers), then intervals map to 566 * their lower limit, that is, interval i maps to fChoiceLimit[i]. 567 * 568 * The intervals may be closed, half open, or open. This affects 569 * formatting but does not affect parsing. Interval i is affected 570 * by fClosures[i] and fClosures[i+1]. If fClosures[i] 571 * is false, then the value fChoiceLimits[i] is in interval i. 572 * That is, intervals i and i are: 573 * 574 * i-1: ... x < fChoiceLimits[i] 575 * i: fChoiceLimits[i] <= x ... 576 * 577 * If fClosures[i] is true, then the value fChoiceLimits[i] is 578 * in interval i-1. That is, intervals i-1 and i are: 579 * 580 * i-1: ... x <= fChoiceLimits[i] 581 * i: fChoiceLimits[i] < x ... 582 * 583 * Because of the nature of interval 0, fClosures[0] has no 584 * effect. 585 */ 586 // double* fChoiceLimits; 587 // UBool* fClosures; 588 // UnicodeString* fChoiceFormats; 589 // int32_t fCount; 590 }; 591 592 593 U_NAMESPACE_END 594 595 #endif // U_HIDE_DEPRECATED_API 596 #endif /* #if !UCONFIG_NO_FORMATTING */ 597 598 #endif /* U_SHOW_CPLUSPLUS_API */ 599 600 #endif // CHOICFMT_H 601 //eof
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
