1 // © 2018 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 4 #ifndef __UNUMBERFORMATTER_H__ 5 #define __UNUMBERFORMATTER_H__ 6 7 #include "unicode/utypes.h" 8 9 #if !UCONFIG_NO_FORMATTING 10 11 #include "unicode/parseerr.h" 12 #include "unicode/ufieldpositer.h" 13 #include "unicode/umisc.h" 14 #include "unicode/uformattedvalue.h" 15 16 17 /** 18 * \file 19 * \brief C-compatible API for localized number formatting; not recommended for C++. 20 * 21 * This is the C-compatible version of the NumberFormatter API introduced in ICU 60. C++ users should 22 * include unicode/numberformatter.h and use the proper C++ APIs. 23 * 24 * The C API accepts a number skeleton string for specifying the settings for formatting, which covers a 25 * very large subset of all possible number formatting features. For more information on number skeleton 26 * strings, see unicode/numberformatter.h. 27 * 28 * When using UNumberFormatter, which is treated as immutable, the results are exported to a mutable 29 * UFormattedNumber object, which you subsequently use for populating your string buffer or iterating over 30 * the fields. 31 * 32 * Example code: 33 * <pre> 34 * // Setup: 35 * UErrorCode ec = U_ZERO_ERROR; 36 * UNumberFormatter* uformatter = unumf_openForSkeletonAndLocale(u"precision-integer", -1, "en", &ec); 37 * UFormattedNumber* uresult = unumf_openResult(&ec); 38 * if (U_FAILURE(ec)) { return; } 39 * 40 * // Format a double: 41 * unumf_formatDouble(uformatter, 5142.3, uresult, &ec); 42 * if (U_FAILURE(ec)) { return; } 43 * 44 * // Export the string to a malloc'd buffer: 45 * int32_t len = unumf_resultToString(uresult, NULL, 0, &ec); 46 * // at this point, ec == U_BUFFER_OVERFLOW_ERROR 47 * ec = U_ZERO_ERROR; 48 * UChar* buffer = (UChar*) malloc((len+1)*sizeof(UChar)); 49 * unumf_resultToString(uresult, buffer, len+1, &ec); 50 * if (U_FAILURE(ec)) { return; } 51 * // buffer should equal "5,142" 52 * 53 * // Cleanup: 54 * unumf_close(uformatter); 55 * unumf_closeResult(uresult); 56 * free(buffer); 57 * </pre> 58 * 59 * If you are a C++ user linking against the C libraries, you can use the LocalPointer versions of these 60 * APIs. The following example uses LocalPointer with the decimal number and field position APIs: 61 * 62 * <pre> 63 * // Setup: 64 * LocalUNumberFormatterPointer uformatter(unumf_openForSkeletonAndLocale(u"percent", -1, "en", &ec)); 65 * LocalUFormattedNumberPointer uresult(unumf_openResult(&ec)); 66 * if (U_FAILURE(ec)) { return; } 67 * 68 * // Format a decimal number: 69 * unumf_formatDecimal(uformatter.getAlias(), "9.87E-3", -1, uresult.getAlias(), &ec); 70 * if (U_FAILURE(ec)) { return; } 71 * 72 * // Get the location of the percent sign: 73 * UFieldPosition ufpos = {UNUM_PERCENT_FIELD, 0, 0}; 74 * unumf_resultNextFieldPosition(uresult.getAlias(), &ufpos, &ec); 75 * // ufpos should contain beginIndex=7 and endIndex=8 since the string is "0.00987%" 76 * 77 * // No need to do any cleanup since we are using LocalPointer. 78 * </pre> 79 */ 80 81 /** 82 * An enum declaring how to render units, including currencies. Example outputs when formatting 123 USD and 123 83 * meters in <em>en-CA</em>: 84 * 85 * <p> 86 * <ul> 87 * <li>NARROW*: "$123.00" and "123 m" 88 * <li>SHORT: "US$ 123.00" and "123 m" 89 * <li>FULL_NAME: "123.00 US dollars" and "123 meters" 90 * <li>ISO_CODE: "USD 123.00" and undefined behavior 91 * <li>HIDDEN: "123.00" and "123" 92 * </ul> 93 * 94 * <p> 95 * This enum is similar to {@link UMeasureFormatWidth}. 96 * 97 * @stable ICU 60 98 */ 99 typedef enum UNumberUnitWidth { 100 /** 101 * Print an abbreviated version of the unit name. Similar to SHORT, but always use the shortest available 102 * abbreviation or symbol. This option can be used when the context hints at the identity of the unit. For more 103 * information on the difference between NARROW and SHORT, see SHORT. 104 * 105 * <p> 106 * In CLDR, this option corresponds to the "Narrow" format for measure units and the "¤¤¤¤¤" placeholder for 107 * currencies. 108 * 109 * @stable ICU 60 110 */ 111 UNUM_UNIT_WIDTH_NARROW, 112 113 /** 114 * Print an abbreviated version of the unit name. Similar to NARROW, but use a slightly wider abbreviation or 115 * symbol when there may be ambiguity. This is the default behavior. 116 * 117 * <p> 118 * For example, in <em>es-US</em>, the SHORT form for Fahrenheit is "{0} °F", but the NARROW form is "{0}°", 119 * since Fahrenheit is the customary unit for temperature in that locale. 120 * 121 * <p> 122 * In CLDR, this option corresponds to the "Short" format for measure units and the "¤" placeholder for 123 * currencies. 124 * 125 * @stable ICU 60 126 */ 127 UNUM_UNIT_WIDTH_SHORT, 128 129 /** 130 * Print the full name of the unit, without any abbreviations. 131 * 132 * <p> 133 * In CLDR, this option corresponds to the default format for measure units and the "¤¤¤" placeholder for 134 * currencies. 135 * 136 * @stable ICU 60 137 */ 138 UNUM_UNIT_WIDTH_FULL_NAME, 139 140 /** 141 * Use the three-digit ISO XXX code in place of the symbol for displaying currencies. The behavior of this 142 * option is currently undefined for use with measure units. 143 * 144 * <p> 145 * In CLDR, this option corresponds to the "¤¤" placeholder for currencies. 146 * 147 * @stable ICU 60 148 */ 149 UNUM_UNIT_WIDTH_ISO_CODE, 150 151 #ifndef U_HIDE_DRAFT_API 152 /** 153 * Use the formal variant of the currency symbol; for example, "NT$" for the New Taiwan 154 * dollar in zh-TW. 155 * 156 * <p> 157 * Behavior of this option with non-currency units is not defined at this time. 158 * 159 * @draft ICU 68 160 */ 161 UNUM_UNIT_WIDTH_FORMAL, 162 163 /** 164 * Use the alternate variant of the currency symbol; for example, "TL" for the Turkish 165 * lira (TRY). 166 * 167 * <p> 168 * Behavior of this option with non-currency units is not defined at this time. 169 * 170 * @draft ICU 68 171 */ 172 UNUM_UNIT_WIDTH_VARIANT, 173 #endif // U_HIDE_DRAFT_API 174 175 /** 176 * Format the number according to the specified unit, but do not display the unit. For currencies, apply 177 * monetary symbols and formats as with SHORT, but omit the currency symbol. For measure units, the behavior is 178 * equivalent to not specifying the unit at all. 179 * 180 * @stable ICU 60 181 */ 182 UNUM_UNIT_WIDTH_HIDDEN, 183 184 /** 185 * One more than the highest UNumberUnitWidth value. 186 * 187 * @internal ICU 60: The numeric value may change over time; see ICU ticket #12420. 188 */ 189 UNUM_UNIT_WIDTH_COUNT 190 } UNumberUnitWidth; 191 192 /** 193 * An enum declaring the strategy for when and how to display grouping separators (i.e., the 194 * separator, often a comma or period, after every 2-3 powers of ten). The choices are several 195 * pre-built strategies for different use cases that employ locale data whenever possible. Example 196 * outputs for 1234 and 1234567 in <em>en-IN</em>: 197 * 198 * <ul> 199 * <li>OFF: 1234 and 12345 200 * <li>MIN2: 1234 and 12,34,567 201 * <li>AUTO: 1,234 and 12,34,567 202 * <li>ON_ALIGNED: 1,234 and 12,34,567 203 * <li>THOUSANDS: 1,234 and 1,234,567 204 * </ul> 205 * 206 * <p> 207 * The default is AUTO, which displays grouping separators unless the locale data says that grouping 208 * is not customary. To force grouping for all numbers greater than 1000 consistently across locales, 209 * use ON_ALIGNED. On the other hand, to display grouping less frequently than the default, use MIN2 210 * or OFF. See the docs of each option for details. 211 * 212 * <p> 213 * Note: This enum specifies the strategy for grouping sizes. To set which character to use as the 214 * grouping separator, use the "symbols" setter. 215 * 216 * @stable ICU 63 217 */ 218 typedef enum UNumberGroupingStrategy { 219 /** 220 * Do not display grouping separators in any locale. 221 * 222 * @stable ICU 61 223 */ 224 UNUM_GROUPING_OFF, 225 226 /** 227 * Display grouping using locale defaults, except do not show grouping on values smaller than 228 * 10000 (such that there is a <em>minimum of two digits</em> before the first separator). 229 * 230 * <p> 231 * Note that locales may restrict grouping separators to be displayed only on 1 million or 232 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency). 233 * 234 * <p> 235 * Locale data is used to determine whether to separate larger numbers into groups of 2 236 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas). 237 * 238 * @stable ICU 61 239 */ 240 UNUM_GROUPING_MIN2, 241 242 /** 243 * Display grouping using the default strategy for all locales. This is the default behavior. 244 * 245 * <p> 246 * Note that locales may restrict grouping separators to be displayed only on 1 million or 247 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency). 248 * 249 * <p> 250 * Locale data is used to determine whether to separate larger numbers into groups of 2 251 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas). 252 * 253 * @stable ICU 61 254 */ 255 UNUM_GROUPING_AUTO, 256 257 /** 258 * Always display the grouping separator on values of at least 1000. 259 * 260 * <p> 261 * This option ignores the locale data that restricts or disables grouping, described in MIN2 and 262 * AUTO. This option may be useful to normalize the alignment of numbers, such as in a 263 * spreadsheet. 264 * 265 * <p> 266 * Locale data is used to determine whether to separate larger numbers into groups of 2 267 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas). 268 * 269 * @stable ICU 61 270 */ 271 UNUM_GROUPING_ON_ALIGNED, 272 273 /** 274 * Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater. Do not use 275 * locale data for determining the grouping strategy. 276 * 277 * @stable ICU 61 278 */ 279 UNUM_GROUPING_THOUSANDS 280 281 #ifndef U_HIDE_INTERNAL_API 282 , 283 /** 284 * One more than the highest UNumberGroupingStrategy value. 285 * 286 * @internal ICU 62: The numeric value may change over time; see ICU ticket #12420. 287 */ 288 UNUM_GROUPING_COUNT 289 #endif /* U_HIDE_INTERNAL_API */ 290 291 } UNumberGroupingStrategy; 292 293 /** 294 * An enum declaring how to denote positive and negative numbers. Example outputs when formatting 295 * 123, 0, and -123 in <em>en-US</em>: 296 * 297 * <ul> 298 * <li>AUTO: "123", "0", and "-123" 299 * <li>ALWAYS: "+123", "+0", and "-123" 300 * <li>NEVER: "123", "0", and "123" 301 * <li>ACCOUNTING: "$123", "$0", and "($123)" 302 * <li>ACCOUNTING_ALWAYS: "+$123", "+$0", and "($123)" 303 * <li>EXCEPT_ZERO: "+123", "0", and "-123" 304 * <li>ACCOUNTING_EXCEPT_ZERO: "+$123", "$0", and "($123)" 305 * </ul> 306 * 307 * <p> 308 * The exact format, including the position and the code point of the sign, differ by locale. 309 * 310 * @stable ICU 60 311 */ 312 typedef enum UNumberSignDisplay { 313 /** 314 * Show the minus sign on negative numbers, and do not show the sign on positive numbers. This is the default 315 * behavior. 316 * 317 * @stable ICU 60 318 */ 319 UNUM_SIGN_AUTO, 320 321 /** 322 * Show the minus sign on negative numbers and the plus sign on positive numbers, including zero. 323 * To hide the sign on zero, see {@link UNUM_SIGN_EXCEPT_ZERO}. 324 * 325 * @stable ICU 60 326 */ 327 UNUM_SIGN_ALWAYS, 328 329 /** 330 * Do not show the sign on positive or negative numbers. 331 * 332 * @stable ICU 60 333 */ 334 UNUM_SIGN_NEVER, 335 336 /** 337 * Use the locale-dependent accounting format on negative numbers, and do not show the sign on positive numbers. 338 * 339 * <p> 340 * The accounting format is defined in CLDR and varies by locale; in many Western locales, the format is a pair 341 * of parentheses around the number. 342 * 343 * <p> 344 * Note: Since CLDR defines the accounting format in the monetary context only, this option falls back to the 345 * AUTO sign display strategy when formatting without a currency unit. This limitation may be lifted in the 346 * future. 347 * 348 * @stable ICU 60 349 */ 350 UNUM_SIGN_ACCOUNTING, 351 352 /** 353 * Use the locale-dependent accounting format on negative numbers, and show the plus sign on 354 * positive numbers, including zero. For more information on the accounting format, see the 355 * ACCOUNTING sign display strategy. To hide the sign on zero, see 356 * {@link UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO}. 357 * 358 * @stable ICU 60 359 */ 360 UNUM_SIGN_ACCOUNTING_ALWAYS, 361 362 /** 363 * Show the minus sign on negative numbers and the plus sign on positive numbers. Do not show a 364 * sign on zero, numbers that round to zero, or NaN. 365 * 366 * @stable ICU 61 367 */ 368 UNUM_SIGN_EXCEPT_ZERO, 369 370 /** 371 * Use the locale-dependent accounting format on negative numbers, and show the plus sign on 372 * positive numbers. Do not show a sign on zero, numbers that round to zero, or NaN. For more 373 * information on the accounting format, see the ACCOUNTING sign display strategy. 374 * 375 * @stable ICU 61 376 */ 377 UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO, 378 379 /** 380 * One more than the highest UNumberSignDisplay value. 381 * 382 * @internal ICU 60: The numeric value may change over time; see ICU ticket #12420. 383 */ 384 UNUM_SIGN_COUNT 385 } UNumberSignDisplay; 386 387 /** 388 * An enum declaring how to render the decimal separator. 389 * 390 * <p> 391 * <ul> 392 * <li>UNUM_DECIMAL_SEPARATOR_AUTO: "1", "1.1" 393 * <li>UNUM_DECIMAL_SEPARATOR_ALWAYS: "1.", "1.1" 394 * </ul> 395 * 396 * @stable ICU 60 397 */ 398 typedef enum UNumberDecimalSeparatorDisplay { 399 /** 400 * Show the decimal separator when there are one or more digits to display after the separator, and do not show 401 * it otherwise. This is the default behavior. 402 * 403 * @stable ICU 60 404 */ 405 UNUM_DECIMAL_SEPARATOR_AUTO, 406 407 /** 408 * Always show the decimal separator, even if there are no digits to display after the separator. 409 * 410 * @stable ICU 60 411 */ 412 UNUM_DECIMAL_SEPARATOR_ALWAYS, 413 414 /** 415 * One more than the highest UNumberDecimalSeparatorDisplay value. 416 * 417 * @internal ICU 60: The numeric value may change over time; see ICU ticket #12420. 418 */ 419 UNUM_DECIMAL_SEPARATOR_COUNT 420 } UNumberDecimalSeparatorDisplay; 421 422 struct UNumberFormatter; 423 /** 424 * C-compatible version of icu::number::LocalizedNumberFormatter. 425 * 426 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 427 * 428 * @stable ICU 62 429 */ 430 typedef struct UNumberFormatter UNumberFormatter; 431 432 struct UFormattedNumber; 433 /** 434 * C-compatible version of icu::number::FormattedNumber. 435 * 436 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 437 * 438 * @stable ICU 62 439 */ 440 typedef struct UFormattedNumber UFormattedNumber; 441 442 443 /** 444 * Creates a new UNumberFormatter for the given skeleton string and locale. This is currently the only 445 * method for creating a new UNumberFormatter. 446 * 447 * Objects of type UNumberFormatter returned by this method are threadsafe. 448 * 449 * For more details on skeleton strings, see the documentation in numberformatter.h. For more details on 450 * the usage of this API, see the documentation at the top of unumberformatter.h. 451 * 452 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 453 * 454 * @param skeleton The skeleton string, like u"percent precision-integer" 455 * @param skeletonLen The number of UChars in the skeleton string, or -1 if it is NUL-terminated. 456 * @param locale The NUL-terminated locale ID. 457 * @param ec Set if an error occurs. 458 * @stable ICU 62 459 */ 460 U_CAPI UNumberFormatter* U_EXPORT2 461 unumf_openForSkeletonAndLocale(const UChar* skeleton, int32_t skeletonLen, const char* locale, 462 UErrorCode* ec); 463 464 465 /** 466 * Like unumf_openForSkeletonAndLocale, but accepts a UParseError, which will be populated with the 467 * location of a skeleton syntax error if such a syntax error exists. 468 * 469 * @param skeleton The skeleton string, like u"percent precision-integer" 470 * @param skeletonLen The number of UChars in the skeleton string, or -1 if it is NUL-terminated. 471 * @param locale The NUL-terminated locale ID. 472 * @param perror A parse error struct populated if an error occurs when parsing. Can be NULL. 473 * If no error occurs, perror->offset will be set to -1. 474 * @param ec Set if an error occurs. 475 * @stable ICU 64 476 */ 477 U_CAPI UNumberFormatter* U_EXPORT2 478 unumf_openForSkeletonAndLocaleWithError( 479 const UChar* skeleton, int32_t skeletonLen, const char* locale, UParseError* perror, UErrorCode* ec); 480 481 482 /** 483 * Creates an object to hold the result of a UNumberFormatter 484 * operation. The object can be used repeatedly; it is cleared whenever 485 * passed to a format function. 486 * 487 * @param ec Set if an error occurs. 488 * @stable ICU 62 489 */ 490 U_CAPI UFormattedNumber* U_EXPORT2 491 unumf_openResult(UErrorCode* ec); 492 493 494 /** 495 * Uses a UNumberFormatter to format an integer to a UFormattedNumber. A string, field position, and other 496 * information can be retrieved from the UFormattedNumber. 497 * 498 * The UNumberFormatter can be shared between threads. Each thread should have its own local 499 * UFormattedNumber, however, for storing the result of the formatting operation. 500 * 501 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 502 * 503 * @param uformatter A formatter object created by unumf_openForSkeletonAndLocale or similar. 504 * @param value The number to be formatted. 505 * @param uresult The object that will be mutated to store the result; see unumf_openResult. 506 * @param ec Set if an error occurs. 507 * @stable ICU 62 508 */ 509 U_CAPI void U_EXPORT2 510 unumf_formatInt(const UNumberFormatter* uformatter, int64_t value, UFormattedNumber* uresult, 511 UErrorCode* ec); 512 513 514 /** 515 * Uses a UNumberFormatter to format a double to a UFormattedNumber. A string, field position, and other 516 * information can be retrieved from the UFormattedNumber. 517 * 518 * The UNumberFormatter can be shared between threads. Each thread should have its own local 519 * UFormattedNumber, however, for storing the result of the formatting operation. 520 * 521 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 522 * 523 * @param uformatter A formatter object created by unumf_openForSkeletonAndLocale or similar. 524 * @param value The number to be formatted. 525 * @param uresult The object that will be mutated to store the result; see unumf_openResult. 526 * @param ec Set if an error occurs. 527 * @stable ICU 62 528 */ 529 U_CAPI void U_EXPORT2 530 unumf_formatDouble(const UNumberFormatter* uformatter, double value, UFormattedNumber* uresult, 531 UErrorCode* ec); 532 533 534 /** 535 * Uses a UNumberFormatter to format a decimal number to a UFormattedNumber. A string, field position, and 536 * other information can be retrieved from the UFormattedNumber. 537 * 538 * The UNumberFormatter can be shared between threads. Each thread should have its own local 539 * UFormattedNumber, however, for storing the result of the formatting operation. 540 * 541 * The syntax of the unformatted number is a "numeric string" as defined in the Decimal Arithmetic 542 * Specification, available at http://speleotrove.com/decimal 543 * 544 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 545 * 546 * @param uformatter A formatter object created by unumf_openForSkeletonAndLocale or similar. 547 * @param value The numeric string to be formatted. 548 * @param valueLen The length of the numeric string, or -1 if it is NUL-terminated. 549 * @param uresult The object that will be mutated to store the result; see unumf_openResult. 550 * @param ec Set if an error occurs. 551 * @stable ICU 62 552 */ 553 U_CAPI void U_EXPORT2 554 unumf_formatDecimal(const UNumberFormatter* uformatter, const char* value, int32_t valueLen, 555 UFormattedNumber* uresult, UErrorCode* ec); 556 557 /** 558 * Returns a representation of a UFormattedNumber as a UFormattedValue, 559 * which can be subsequently passed to any API requiring that type. 560 * 561 * The returned object is owned by the UFormattedNumber and is valid 562 * only as long as the UFormattedNumber is present and unchanged in memory. 563 * 564 * You can think of this method as a cast between types. 565 * 566 * @param uresult The object containing the formatted string. 567 * @param ec Set if an error occurs. 568 * @return A UFormattedValue owned by the input object. 569 * @stable ICU 64 570 */ 571 U_CAPI const UFormattedValue* U_EXPORT2 572 unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec); 573 574 575 /** 576 * Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible. 577 * If bufferCapacity is greater than the required length, a terminating NUL is written. 578 * If bufferCapacity is less than the required length, an error code is set. 579 * 580 * Also see ufmtval_getString, which returns a NUL-terminated string: 581 * 582 * int32_t len; 583 * const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec); 584 * 585 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead. 586 * 587 * @param uresult The object containing the formatted number. 588 * @param buffer Where to save the string output. 589 * @param bufferCapacity The number of UChars available in the buffer. 590 * @param ec Set if an error occurs. 591 * @return The required length. 592 * @stable ICU 62 593 */ 594 U_CAPI int32_t U_EXPORT2 595 unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity, 596 UErrorCode* ec); 597 598 599 /** 600 * Determines the start and end indices of the next occurrence of the given <em>field</em> in the 601 * output string. This allows you to determine the locations of, for example, the integer part, 602 * fraction part, or symbols. 603 * 604 * This is a simpler but less powerful alternative to {@link ufmtval_nextPosition}. 605 * 606 * If a field occurs just once, calling this method will find that occurrence and return it. If a 607 * field occurs multiple times, this method may be called repeatedly with the following pattern: 608 * 609 * <pre> 610 * UFieldPosition ufpos = {UNUM_GROUPING_SEPARATOR_FIELD, 0, 0}; 611 * while (unumf_resultNextFieldPosition(uresult, ufpos, &ec)) { 612 * // do something with ufpos. 613 * } 614 * </pre> 615 * 616 * This method is useful if you know which field to query. If you want all available field position 617 * information, use unumf_resultGetAllFieldPositions(). 618 * 619 * NOTE: All fields of the UFieldPosition must be initialized before calling this method. 620 * 621 * @param uresult The object containing the formatted number. 622 * @param ufpos 623 * Input+output variable. On input, the "field" property determines which field to look up, 624 * and the "endIndex" property determines where to begin the search. On output, the 625 * "beginIndex" field is set to the beginning of the first occurrence of the field after the 626 * input "endIndex", and "endIndex" is set to the end of that occurrence of the field 627 * (exclusive index). If a field position is not found, the FieldPosition is not changed and 628 * the method returns false. 629 * @param ec Set if an error occurs. 630 * @stable ICU 62 631 */ 632 U_CAPI UBool U_EXPORT2 633 unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec); 634 635 636 /** 637 * Populates the given iterator with all fields in the formatted output string. This allows you to 638 * determine the locations of the integer part, fraction part, and sign. 639 * 640 * This is an alternative to the more powerful {@link ufmtval_nextPosition} API. 641 * 642 * If you need information on only one field, use {@link ufmtval_nextPosition} or 643 * {@link unumf_resultNextFieldPosition}. 644 * 645 * @param uresult The object containing the formatted number. 646 * @param ufpositer 647 * A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}. Iteration 648 * information already present in the UFieldPositionIterator is deleted, and the iterator is reset 649 * to apply to the fields in the formatted string created by this function call. The field values 650 * and indexes returned by {@link #ufieldpositer_next} represent fields denoted by 651 * the UNumberFormatFields enum. Fields are not returned in a guaranteed order. Fields cannot 652 * overlap, but they may nest. For example, 1234 could format as "1,234" which might consist of a 653 * grouping separator field for ',' and an integer field encompassing the entire string. 654 * @param ec Set if an error occurs. 655 * @stable ICU 62 656 */ 657 U_CAPI void U_EXPORT2 658 unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer, 659 UErrorCode* ec); 660 661 662 #ifndef U_HIDE_DRAFT_API 663 /** 664 * Extracts the formatted number as a "numeric string" conforming to the 665 * syntax defined in the Decimal Arithmetic Specification, available at 666 * http://speleotrove.com/decimal 667 * 668 * This endpoint is useful for obtaining the exact number being printed 669 * after scaling and rounding have been applied by the number formatter. 670 * 671 * @param uresult The input object containing the formatted number. 672 * @param dest the 8-bit char buffer into which the decimal number is placed 673 * @param destCapacity The size, in chars, of the destination buffer. May be zero 674 * for precomputing the required size. 675 * @param ec receives any error status. 676 * If U_BUFFER_OVERFLOW_ERROR: Returns number of chars for 677 * preflighting. 678 * @return Number of chars in the data. Does not include a trailing NUL. 679 * @draft ICU 68 680 */ 681 U_CAPI int32_t U_EXPORT2 682 unumf_resultToDecimalNumber( 683 const UFormattedNumber* uresult, 684 char* dest, 685 int32_t destCapacity, 686 UErrorCode* ec); 687 #endif // U_HIDE_DRAFT_API 688 689 690 /** 691 * Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale(). 692 * 693 * @param uformatter An object created by unumf_openForSkeletonAndLocale(). 694 * @stable ICU 62 695 */ 696 U_CAPI void U_EXPORT2 697 unumf_close(UNumberFormatter* uformatter); 698 699 700 /** 701 * Releases the UFormattedNumber created by unumf_openResult(). 702 * 703 * @param uresult An object created by unumf_openResult(). 704 * @stable ICU 62 705 */ 706 U_CAPI void U_EXPORT2 707 unumf_closeResult(UFormattedNumber* uresult); 708 709 710 #if U_SHOW_CPLUSPLUS_API 711 U_NAMESPACE_BEGIN 712 713 /** 714 * \class LocalUNumberFormatterPointer 715 * "Smart pointer" class; closes a UNumberFormatter via unumf_close(). 716 * For most methods see the LocalPointerBase base class. 717 * 718 * Usage: 719 * <pre> 720 * LocalUNumberFormatterPointer uformatter(unumf_openForSkeletonAndLocale(...)); 721 * // no need to explicitly call unumf_close() 722 * </pre> 723 * 724 * @see LocalPointerBase 725 * @see LocalPointer 726 * @stable ICU 62 727 */ 728 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatterPointer, UNumberFormatter, unumf_close); 729 730 /** 731 * \class LocalUFormattedNumberPointer 732 * "Smart pointer" class; closes a UFormattedNumber via unumf_closeResult(). 733 * For most methods see the LocalPointerBase base class. 734 * 735 * Usage: 736 * <pre> 737 * LocalUFormattedNumberPointer uformatter(unumf_openResult(...)); 738 * // no need to explicitly call unumf_closeResult() 739 * </pre> 740 * 741 * @see LocalPointerBase 742 * @see LocalPointer 743 * @stable ICU 62 744 */ 745 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult); 746 747 U_NAMESPACE_END 748 #endif // U_SHOW_CPLUSPLUS_API 749 750 #endif /* #if !UCONFIG_NO_FORMATTING */ 751 #endif //__UNUMBERFORMATTER_H__ 752