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-2015, International Business Machines Corporation and others. 6 * All Rights Reserved. 7 * Modification History: 8 * 9 * Date Name Description 10 * 06/24/99 helena Integrated Alan's NF enhancements and Java2 bug fixes 11 ******************************************************************************* 12 */ 13 14 #ifndef _UNUM 15 #define _UNUM 16 17 #include "unicode/utypes.h" 18 19 #if !UCONFIG_NO_FORMATTING 20 21 #include "unicode/uloc.h" 22 #include "unicode/ucurr.h" 23 #include "unicode/umisc.h" 24 #include "unicode/parseerr.h" 25 #include "unicode/uformattable.h" 26 #include "unicode/udisplaycontext.h" 27 #include "unicode/ufieldpositer.h" 28 29 #if U_SHOW_CPLUSPLUS_API 30 #include "unicode/localpointer.h" 31 #endif // U_SHOW_CPLUSPLUS_API 32 33 /** 34 * \file 35 * \brief C API: Compatibility APIs for number formatting. 36 * 37 * <h2> Number Format C API </h2> 38 * 39 * <p><strong>IMPORTANT:</strong> New users with are strongly encouraged to 40 * see if unumberformatter.h fits their use case. Although not deprecated, 41 * this header is provided for backwards compatibility only. 42 * 43 * Number Format C API Provides functions for 44 * formatting and parsing a number. Also provides methods for 45 * determining which locales have number formats, and what their names 46 * are. 47 * <P> 48 * UNumberFormat helps you to format and parse numbers for any locale. 49 * Your code can be completely independent of the locale conventions 50 * for decimal points, thousands-separators, or even the particular 51 * decimal digits used, or whether the number format is even decimal. 52 * There are different number format styles like decimal, currency, 53 * percent and spellout. 54 * <P> 55 * To format a number for the current Locale, use one of the static 56 * factory methods: 57 * <pre> 58 * \code 59 * UChar myString[20]; 60 * double myNumber = 7.0; 61 * UErrorCode status = U_ZERO_ERROR; 62 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status); 63 * unum_formatDouble(nf, myNumber, myString, 20, NULL, &status); 64 * printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*) 65 * \endcode 66 * </pre> 67 * If you are formatting multiple numbers, it is more efficient to get 68 * the format and use it multiple times so that the system doesn't 69 * have to fetch the information about the local language and country 70 * conventions multiple times. 71 * <pre> 72 * \code 73 * uint32_t i, resultlength, reslenneeded; 74 * UErrorCode status = U_ZERO_ERROR; 75 * UFieldPosition pos; 76 * uint32_t a[] = { 123, 3333, -1234567 }; 77 * const uint32_t a_len = sizeof(a) / sizeof(a[0]); 78 * UNumberFormat* nf; 79 * UChar* result = NULL; 80 * 81 * nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status); 82 * for (i = 0; i < a_len; i++) { 83 * resultlength=0; 84 * reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status); 85 * result = NULL; 86 * if(status==U_BUFFER_OVERFLOW_ERROR){ 87 * status=U_ZERO_ERROR; 88 * resultlength=reslenneeded+1; 89 * result=(UChar*)malloc(sizeof(UChar) * resultlength); 90 * unum_format(nf, a[i], result, resultlength, &pos, &status); 91 * } 92 * printf( " Example 2: %s\n", austrdup(result)); 93 * free(result); 94 * } 95 * \endcode 96 * </pre> 97 * To format a number for a different Locale, specify it in the 98 * call to unum_open(). 99 * <pre> 100 * \code 101 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, "fr_FR", NULL, &success) 102 * \endcode 103 * </pre> 104 * You can use a NumberFormat API unum_parse() to parse. 105 * <pre> 106 * \code 107 * UErrorCode status = U_ZERO_ERROR; 108 * int32_t pos=0; 109 * int32_t num; 110 * num = unum_parse(nf, str, u_strlen(str), &pos, &status); 111 * \endcode 112 * </pre> 113 * Use UNUM_DECIMAL to get the normal number format for that country. 114 * There are other static options available. Use UNUM_CURRENCY 115 * to get the currency number format for that country. Use UNUM_PERCENT 116 * to get a format for displaying percentages. With this format, a 117 * fraction from 0.53 is displayed as 53%. 118 * <P> 119 * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat 120 * formatter. The pattern must conform to the syntax defined for those 121 * formatters. 122 * <P> 123 * You can also control the display of numbers with such function as 124 * unum_getAttributes() and unum_setAttributes(), which let you set the 125 * minimum fraction digits, grouping, etc. 126 * @see UNumberFormatAttributes for more details 127 * <P> 128 * You can also use forms of the parse and format methods with 129 * ParsePosition and UFieldPosition to allow you to: 130 * <ul type=round> 131 * <li>(a) progressively parse through pieces of a string. 132 * <li>(b) align the decimal point and other areas. 133 * </ul> 134 * <p> 135 * It is also possible to change or set the symbols used for a particular 136 * locale like the currency symbol, the grouping separator , monetary separator 137 * etc by making use of functions unum_setSymbols() and unum_getSymbols(). 138 */ 139 140 /** A number formatter. 141 * For usage in C programs. 142 * @stable ICU 2.0 143 */ 144 typedef void* UNumberFormat; 145 146 /** The possible number format styles. 147 * @stable ICU 2.0 148 */ 149 typedef enum UNumberFormatStyle { 150 /** 151 * Decimal format defined by a pattern string. 152 * @stable ICU 3.0 153 */ 154 UNUM_PATTERN_DECIMAL=0, 155 /** 156 * Decimal format ("normal" style). 157 * @stable ICU 2.0 158 */ 159 UNUM_DECIMAL=1, 160 /** 161 * Currency format (generic). 162 * Defaults to UNUM_CURRENCY_STANDARD style 163 * (using currency symbol, e.g., "$1.00", with non-accounting 164 * style for negative values e.g. using minus sign). 165 * The specific style may be specified using the -cf- locale key. 166 * @stable ICU 2.0 167 */ 168 UNUM_CURRENCY=2, 169 /** 170 * Percent format 171 * @stable ICU 2.0 172 */ 173 UNUM_PERCENT=3, 174 /** 175 * Scientific format 176 * @stable ICU 2.1 177 */ 178 UNUM_SCIENTIFIC=4, 179 /** 180 * Spellout rule-based format. The default ruleset can be specified/changed using 181 * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets 182 * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS. 183 * @stable ICU 2.0 184 */ 185 UNUM_SPELLOUT=5, 186 /** 187 * Ordinal rule-based format . The default ruleset can be specified/changed using 188 * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets 189 * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS. 190 * @stable ICU 3.0 191 */ 192 UNUM_ORDINAL=6, 193 /** 194 * Duration rule-based format 195 * @stable ICU 3.0 196 */ 197 UNUM_DURATION=7, 198 /** 199 * Numbering system rule-based format 200 * @stable ICU 4.2 201 */ 202 UNUM_NUMBERING_SYSTEM=8, 203 /** 204 * Rule-based format defined by a pattern string. 205 * @stable ICU 3.0 206 */ 207 UNUM_PATTERN_RULEBASED=9, 208 /** 209 * Currency format with an ISO currency code, e.g., "USD1.00". 210 * @stable ICU 4.8 211 */ 212 UNUM_CURRENCY_ISO=10, 213 /** 214 * Currency format with a pluralized currency name, 215 * e.g., "1.00 US dollar" and "3.00 US dollars". 216 * @stable ICU 4.8 217 */ 218 UNUM_CURRENCY_PLURAL=11, 219 /** 220 * Currency format for accounting, e.g., "($3.00)" for 221 * negative currency amount instead of "-$3.00" ({@link #UNUM_CURRENCY}). 222 * Overrides any style specified using -cf- key in locale. 223 * @stable ICU 53 224 */ 225 UNUM_CURRENCY_ACCOUNTING=12, 226 /** 227 * Currency format with a currency symbol given CASH usage, e.g., 228 * "NT$3" instead of "NT$3.23". 229 * @stable ICU 54 230 */ 231 UNUM_CASH_CURRENCY=13, 232 /** 233 * Decimal format expressed using compact notation 234 * (short form, corresponds to UNumberCompactStyle=UNUM_SHORT) 235 * e.g. "23K", "45B" 236 * @stable ICU 56 237 */ 238 UNUM_DECIMAL_COMPACT_SHORT=14, 239 /** 240 * Decimal format expressed using compact notation 241 * (long form, corresponds to UNumberCompactStyle=UNUM_LONG) 242 * e.g. "23 thousand", "45 billion" 243 * @stable ICU 56 244 */ 245 UNUM_DECIMAL_COMPACT_LONG=15, 246 /** 247 * Currency format with a currency symbol, e.g., "$1.00", 248 * using non-accounting style for negative values (e.g. minus sign). 249 * Overrides any style specified using -cf- key in locale. 250 * @stable ICU 56 251 */ 252 UNUM_CURRENCY_STANDARD=16, 253 254 #ifndef U_HIDE_DEPRECATED_API 255 /** 256 * One more than the highest normal UNumberFormatStyle value. 257 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 258 */ 259 UNUM_FORMAT_STYLE_COUNT=17, 260 #endif /* U_HIDE_DEPRECATED_API */ 261 262 /** 263 * Default format 264 * @stable ICU 2.0 265 */ 266 UNUM_DEFAULT = UNUM_DECIMAL, 267 /** 268 * Alias for UNUM_PATTERN_DECIMAL 269 * @stable ICU 3.0 270 */ 271 UNUM_IGNORE = UNUM_PATTERN_DECIMAL 272 } UNumberFormatStyle; 273 274 /** The possible number format rounding modes. 275 * 276 * <p> 277 * For more detail on rounding modes, see: 278 * https://unicode-org.github.io/icu/userguide/format_parse/numbers/rounding-modes 279 * 280 * @stable ICU 2.0 281 */ 282 typedef enum UNumberFormatRoundingMode { 283 UNUM_ROUND_CEILING, 284 UNUM_ROUND_FLOOR, 285 UNUM_ROUND_DOWN, 286 UNUM_ROUND_UP, 287 /** 288 * Half-even rounding 289 * @stable, ICU 3.8 290 */ 291 UNUM_ROUND_HALFEVEN, 292 #ifndef U_HIDE_DEPRECATED_API 293 /** 294 * Half-even rounding, misspelled name 295 * @deprecated, ICU 3.8 296 */ 297 UNUM_FOUND_HALFEVEN = UNUM_ROUND_HALFEVEN, 298 #endif /* U_HIDE_DEPRECATED_API */ 299 UNUM_ROUND_HALFDOWN = UNUM_ROUND_HALFEVEN + 1, 300 UNUM_ROUND_HALFUP, 301 /** 302 * ROUND_UNNECESSARY reports an error if formatted result is not exact. 303 * @stable ICU 4.8 304 */ 305 UNUM_ROUND_UNNECESSARY, 306 #ifndef U_HIDE_DRAFT_API 307 /** 308 * Rounds ties toward the odd number. 309 * @draft ICU 69 310 */ 311 UNUM_ROUND_HALF_ODD, 312 /** 313 * Rounds ties toward +∞. 314 * @draft ICU 69 315 */ 316 UNUM_ROUND_HALF_CEILING, 317 /** 318 * Rounds ties toward -∞. 319 * @draft ICU 69 320 */ 321 UNUM_ROUND_HALF_FLOOR, 322 #endif // U_HIDE_DRAFT_API 323 } UNumberFormatRoundingMode; 324 325 /** The possible number format pad positions. 326 * @stable ICU 2.0 327 */ 328 typedef enum UNumberFormatPadPosition { 329 UNUM_PAD_BEFORE_PREFIX, 330 UNUM_PAD_AFTER_PREFIX, 331 UNUM_PAD_BEFORE_SUFFIX, 332 UNUM_PAD_AFTER_SUFFIX 333 } UNumberFormatPadPosition; 334 335 /** 336 * Constants for specifying short or long format. 337 * @stable ICU 51 338 */ 339 typedef enum UNumberCompactStyle { 340 /** @stable ICU 51 */ 341 UNUM_SHORT, 342 /** @stable ICU 51 */ 343 UNUM_LONG 344 /** @stable ICU 51 */ 345 } UNumberCompactStyle; 346 347 /** 348 * Constants for specifying currency spacing 349 * @stable ICU 4.8 350 */ 351 enum UCurrencySpacing { 352 /** @stable ICU 4.8 */ 353 UNUM_CURRENCY_MATCH, 354 /** @stable ICU 4.8 */ 355 UNUM_CURRENCY_SURROUNDING_MATCH, 356 /** @stable ICU 4.8 */ 357 UNUM_CURRENCY_INSERT, 358 359 /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, 360 * it is needed for layout of DecimalFormatSymbols object. */ 361 #ifndef U_FORCE_HIDE_DEPRECATED_API 362 /** 363 * One more than the highest normal UCurrencySpacing value. 364 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 365 */ 366 UNUM_CURRENCY_SPACING_COUNT 367 #endif // U_FORCE_HIDE_DEPRECATED_API 368 }; 369 typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */ 370 371 372 /** 373 * FieldPosition and UFieldPosition selectors for format fields 374 * defined by NumberFormat and UNumberFormat. 375 * @stable ICU 49 376 */ 377 typedef enum UNumberFormatFields { 378 /** @stable ICU 49 */ 379 UNUM_INTEGER_FIELD, 380 /** @stable ICU 49 */ 381 UNUM_FRACTION_FIELD, 382 /** @stable ICU 49 */ 383 UNUM_DECIMAL_SEPARATOR_FIELD, 384 /** @stable ICU 49 */ 385 UNUM_EXPONENT_SYMBOL_FIELD, 386 /** @stable ICU 49 */ 387 UNUM_EXPONENT_SIGN_FIELD, 388 /** @stable ICU 49 */ 389 UNUM_EXPONENT_FIELD, 390 /** @stable ICU 49 */ 391 UNUM_GROUPING_SEPARATOR_FIELD, 392 /** @stable ICU 49 */ 393 UNUM_CURRENCY_FIELD, 394 /** @stable ICU 49 */ 395 UNUM_PERCENT_FIELD, 396 /** @stable ICU 49 */ 397 UNUM_PERMILL_FIELD, 398 /** @stable ICU 49 */ 399 UNUM_SIGN_FIELD, 400 /** @stable ICU 64 */ 401 UNUM_MEASURE_UNIT_FIELD, 402 /** @stable ICU 64 */ 403 UNUM_COMPACT_FIELD, 404 405 #ifndef U_HIDE_DEPRECATED_API 406 /** 407 * One more than the highest normal UNumberFormatFields value. 408 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 409 */ 410 UNUM_FIELD_COUNT = UNUM_SIGN_FIELD + 3 411 #endif /* U_HIDE_DEPRECATED_API */ 412 } UNumberFormatFields; 413 414 415 /** 416 * Selectors with special numeric values to use locale default minimum grouping 417 * digits for the DecimalFormat/UNumberFormat setMinimumGroupingDigits method. 418 * Do not use these constants with the [U]NumberFormatter API. 419 * 420 * @stable ICU 68 421 */ 422 typedef enum UNumberFormatMinimumGroupingDigits { 423 /** 424 * Display grouping using the default strategy for all locales. 425 * @stable ICU 68 426 */ 427 UNUM_MINIMUM_GROUPING_DIGITS_AUTO = -2, 428 /** 429 * Display grouping using locale defaults, except do not show grouping on 430 * values smaller than 10000 (such that there is a minimum of two digits 431 * before the first separator). 432 * @stable ICU 68 433 */ 434 UNUM_MINIMUM_GROUPING_DIGITS_MIN2 = -3, 435 } UNumberFormatMinimumGroupingDigits; 436 437 /** 438 * Create and return a new UNumberFormat for formatting and parsing 439 * numbers. A UNumberFormat may be used to format numbers by calling 440 * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }. 441 * The caller must call {@link #unum_close } when done to release resources 442 * used by this object. 443 * @param style The type of number format to open: one of 444 * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, 445 * UNUM_CURRENCY_ISO, UNUM_CURRENCY_PLURAL, UNUM_SPELLOUT, 446 * UNUM_ORDINAL, UNUM_DURATION, UNUM_NUMBERING_SYSTEM, 447 * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT. 448 * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the 449 * number format is opened using the given pattern, which must conform 450 * to the syntax described in DecimalFormat or RuleBasedNumberFormat, 451 * respectively. 452 * 453 * <p><strong>NOTE::</strong> New users with are strongly encouraged to 454 * use unumf_openForSkeletonAndLocale instead of unum_open. 455 * 456 * @param pattern A pattern specifying the format to use. 457 * This parameter is ignored unless the style is 458 * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED. 459 * @param patternLength The number of characters in the pattern, or -1 460 * if null-terminated. This parameter is ignored unless the style is 461 * UNUM_PATTERN. 462 * @param locale A locale identifier to use to determine formatting 463 * and parsing conventions, or NULL to use the default locale. 464 * @param parseErr A pointer to a UParseError struct to receive the 465 * details of any parsing errors, or NULL if no parsing error details 466 * are desired. 467 * @param status A pointer to an input-output UErrorCode. 468 * @return A pointer to a newly created UNumberFormat, or NULL if an 469 * error occurred. 470 * @see unum_close 471 * @see DecimalFormat 472 * @stable ICU 2.0 473 */ 474 U_CAPI UNumberFormat* U_EXPORT2 475 unum_open( UNumberFormatStyle style, 476 const UChar* pattern, 477 int32_t patternLength, 478 const char* locale, 479 UParseError* parseErr, 480 UErrorCode* status); 481 482 483 /** 484 * Close a UNumberFormat. 485 * Once closed, a UNumberFormat may no longer be used. 486 * @param fmt The formatter to close. 487 * @stable ICU 2.0 488 */ 489 U_CAPI void U_EXPORT2 490 unum_close(UNumberFormat* fmt); 491 492 #if U_SHOW_CPLUSPLUS_API 493 494 U_NAMESPACE_BEGIN 495 496 /** 497 * \class LocalUNumberFormatPointer 498 * "Smart pointer" class, closes a UNumberFormat via unum_close(). 499 * For most methods see the LocalPointerBase base class. 500 * 501 * @see LocalPointerBase 502 * @see LocalPointer 503 * @stable ICU 4.4 504 */ 505 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close); 506 507 U_NAMESPACE_END 508 509 #endif 510 511 /** 512 * Open a copy of a UNumberFormat. 513 * This function performs a deep copy. 514 * @param fmt The format to copy 515 * @param status A pointer to an UErrorCode to receive any errors. 516 * @return A pointer to a UNumberFormat identical to fmt. 517 * @stable ICU 2.0 518 */ 519 U_CAPI UNumberFormat* U_EXPORT2 520 unum_clone(const UNumberFormat *fmt, 521 UErrorCode *status); 522 523 /** 524 * Format an integer using a UNumberFormat. 525 * The integer will be formatted according to the UNumberFormat's locale. 526 * @param fmt The formatter to use. 527 * @param number The number to format. 528 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 529 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 530 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 531 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 532 * @param resultLength The maximum size of result. 533 * @param pos A pointer to a UFieldPosition. On input, position->field 534 * is read. On output, position->beginIndex and position->endIndex indicate 535 * the beginning and ending indices of field number position->field, if such 536 * a field exists. This parameter may be NULL, in which case no field 537 * @param status A pointer to an UErrorCode to receive any errors 538 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 539 * @see unum_formatInt64 540 * @see unum_formatDouble 541 * @see unum_parse 542 * @see unum_parseInt64 543 * @see unum_parseDouble 544 * @see UFieldPosition 545 * @stable ICU 2.0 546 */ 547 U_CAPI int32_t U_EXPORT2 548 unum_format( const UNumberFormat* fmt, 549 int32_t number, 550 UChar* result, 551 int32_t resultLength, 552 UFieldPosition *pos, 553 UErrorCode* status); 554 555 /** 556 * Format an int64 using a UNumberFormat. 557 * The int64 will be formatted according to the UNumberFormat's locale. 558 * @param fmt The formatter to use. 559 * @param number The number to format. 560 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 561 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 562 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 563 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 564 * @param resultLength The maximum size of result. 565 * @param pos A pointer to a UFieldPosition. On input, position->field 566 * is read. On output, position->beginIndex and position->endIndex indicate 567 * the beginning and ending indices of field number position->field, if such 568 * a field exists. This parameter may be NULL, in which case no field 569 * @param status A pointer to an UErrorCode to receive any errors 570 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 571 * @see unum_format 572 * @see unum_formatDouble 573 * @see unum_parse 574 * @see unum_parseInt64 575 * @see unum_parseDouble 576 * @see UFieldPosition 577 * @stable ICU 2.0 578 */ 579 U_CAPI int32_t U_EXPORT2 580 unum_formatInt64(const UNumberFormat *fmt, 581 int64_t number, 582 UChar* result, 583 int32_t resultLength, 584 UFieldPosition *pos, 585 UErrorCode* status); 586 587 /** 588 * Format a double using a UNumberFormat. 589 * The double will be formatted according to the UNumberFormat's locale. 590 * @param fmt The formatter to use. 591 * @param number The number to format. 592 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 593 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 594 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 595 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 596 * @param resultLength The maximum size of result. 597 * @param pos A pointer to a UFieldPosition. On input, position->field 598 * is read. On output, position->beginIndex and position->endIndex indicate 599 * the beginning and ending indices of field number position->field, if such 600 * a field exists. This parameter may be NULL, in which case no field 601 * @param status A pointer to an UErrorCode to receive any errors 602 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 603 * @see unum_format 604 * @see unum_formatInt64 605 * @see unum_parse 606 * @see unum_parseInt64 607 * @see unum_parseDouble 608 * @see UFieldPosition 609 * @stable ICU 2.0 610 */ 611 U_CAPI int32_t U_EXPORT2 612 unum_formatDouble( const UNumberFormat* fmt, 613 double number, 614 UChar* result, 615 int32_t resultLength, 616 UFieldPosition *pos, /* 0 if ignore */ 617 UErrorCode* status); 618 619 /** 620 * Format a double using a UNumberFormat according to the UNumberFormat's locale, 621 * and initialize a UFieldPositionIterator that enumerates the subcomponents of 622 * the resulting string. 623 * 624 * @param format 625 * The formatter to use. 626 * @param number 627 * The number to format. 628 * @param result 629 * A pointer to a buffer to receive the NULL-terminated formatted 630 * number. If the formatted number fits into dest but cannot be 631 * NULL-terminated (length == resultLength) then the error code is set 632 * to U_STRING_NOT_TERMINATED_WARNING. If the formatted number doesn't 633 * fit into result then the error code is set to 634 * U_BUFFER_OVERFLOW_ERROR. 635 * @param resultLength 636 * The maximum size of result. 637 * @param fpositer 638 * A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open} 639 * (may be NULL if field position information is not needed, but in this 640 * case it's preferable to use {@link #unum_formatDouble}). Iteration 641 * information already present in the UFieldPositionIterator is deleted, 642 * and the iterator is reset to apply to the fields in the formatted 643 * string created by this function call. The field values and indexes 644 * returned by {@link #ufieldpositer_next} represent fields denoted by 645 * the UNumberFormatFields enum. Fields are not returned in a guaranteed 646 * order. Fields cannot overlap, but they may nest. For example, 1234 647 * could format as "1,234" which might consist of a grouping separator 648 * field for ',' and an integer field encompassing the entire string. 649 * @param status 650 * A pointer to an UErrorCode to receive any errors 651 * @return 652 * The total buffer size needed; if greater than resultLength, the 653 * output was truncated. 654 * @see unum_formatDouble 655 * @see unum_parse 656 * @see unum_parseDouble 657 * @see UFieldPositionIterator 658 * @see UNumberFormatFields 659 * @stable ICU 59 660 */ 661 U_CAPI int32_t U_EXPORT2 662 unum_formatDoubleForFields(const UNumberFormat* format, 663 double number, 664 UChar* result, 665 int32_t resultLength, 666 UFieldPositionIterator* fpositer, 667 UErrorCode* status); 668 669 670 /** 671 * Format a decimal number using a UNumberFormat. 672 * The number will be formatted according to the UNumberFormat's locale. 673 * The syntax of the input number is a "numeric string" 674 * as defined in the Decimal Arithmetic Specification, available at 675 * http://speleotrove.com/decimal 676 * @param fmt The formatter to use. 677 * @param number The number to format. 678 * @param length The length of the input number, or -1 if the input is nul-terminated. 679 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 680 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 681 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 682 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 683 * @param resultLength The maximum size of result. 684 * @param pos A pointer to a UFieldPosition. On input, position->field 685 * is read. On output, position->beginIndex and position->endIndex indicate 686 * the beginning and ending indices of field number position->field, if such 687 * a field exists. This parameter may be NULL, in which case it is ignored. 688 * @param status A pointer to an UErrorCode to receive any errors 689 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 690 * @see unum_format 691 * @see unum_formatInt64 692 * @see unum_parse 693 * @see unum_parseInt64 694 * @see unum_parseDouble 695 * @see UFieldPosition 696 * @stable ICU 4.4 697 */ 698 U_CAPI int32_t U_EXPORT2 699 unum_formatDecimal( const UNumberFormat* fmt, 700 const char * number, 701 int32_t length, 702 UChar* result, 703 int32_t resultLength, 704 UFieldPosition *pos, /* 0 if ignore */ 705 UErrorCode* status); 706 707 /** 708 * Format a double currency amount using a UNumberFormat. 709 * The double will be formatted according to the UNumberFormat's locale. 710 * 711 * To format an exact decimal value with a currency, use 712 * `unum_setTextAttribute(UNUM_CURRENCY_CODE, ...)` followed by unum_formatDecimal. 713 * Your UNumberFormat must be created with the UNUM_CURRENCY style. Alternatively, 714 * consider using unumf_openForSkeletonAndLocale. 715 * 716 * @param fmt the formatter to use 717 * @param number the number to format 718 * @param currency the 3-letter null-terminated ISO 4217 currency code 719 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 720 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 721 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 722 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 723 * @param resultLength the maximum number of UChars to write to result 724 * @param pos a pointer to a UFieldPosition. On input, 725 * position->field is read. On output, position->beginIndex and 726 * position->endIndex indicate the beginning and ending indices of 727 * field number position->field, if such a field exists. This 728 * parameter may be NULL, in which case it is ignored. 729 * @param status a pointer to an input-output UErrorCode 730 * @return the total buffer size needed; if greater than resultLength, 731 * the output was truncated. 732 * @see unum_formatDouble 733 * @see unum_parseDoubleCurrency 734 * @see UFieldPosition 735 * @stable ICU 3.0 736 */ 737 U_CAPI int32_t U_EXPORT2 738 unum_formatDoubleCurrency(const UNumberFormat* fmt, 739 double number, 740 UChar* currency, 741 UChar* result, 742 int32_t resultLength, 743 UFieldPosition* pos, 744 UErrorCode* status); 745 746 /** 747 * Format a UFormattable into a string. 748 * @param fmt the formatter to use 749 * @param number the number to format, as a UFormattable 750 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 751 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 752 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 753 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 754 * @param resultLength the maximum number of UChars to write to result 755 * @param pos a pointer to a UFieldPosition. On input, 756 * position->field is read. On output, position->beginIndex and 757 * position->endIndex indicate the beginning and ending indices of 758 * field number position->field, if such a field exists. This 759 * parameter may be NULL, in which case it is ignored. 760 * @param status a pointer to an input-output UErrorCode 761 * @return the total buffer size needed; if greater than resultLength, 762 * the output was truncated. Will return 0 on error. 763 * @see unum_parseToUFormattable 764 * @stable ICU 52 765 */ 766 U_CAPI int32_t U_EXPORT2 767 unum_formatUFormattable(const UNumberFormat* fmt, 768 const UFormattable *number, 769 UChar *result, 770 int32_t resultLength, 771 UFieldPosition *pos, 772 UErrorCode *status); 773 774 /** 775 * Parse a string into an integer using a UNumberFormat. 776 * The string will be parsed according to the UNumberFormat's locale. 777 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 778 * and UNUM_DECIMAL_COMPACT_LONG. 779 * @param fmt The formatter to use. 780 * @param text The text to parse. 781 * @param textLength The length of text, or -1 if null-terminated. 782 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 783 * to begin parsing. If not NULL, on output the offset at which parsing ended. 784 * @param status A pointer to an UErrorCode to receive any errors 785 * @return The value of the parsed integer 786 * @see unum_parseInt64 787 * @see unum_parseDouble 788 * @see unum_format 789 * @see unum_formatInt64 790 * @see unum_formatDouble 791 * @stable ICU 2.0 792 */ 793 U_CAPI int32_t U_EXPORT2 794 unum_parse( const UNumberFormat* fmt, 795 const UChar* text, 796 int32_t textLength, 797 int32_t *parsePos /* 0 = start */, 798 UErrorCode *status); 799 800 /** 801 * Parse a string into an int64 using a UNumberFormat. 802 * The string will be parsed according to the UNumberFormat's locale. 803 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 804 * and UNUM_DECIMAL_COMPACT_LONG. 805 * @param fmt The formatter to use. 806 * @param text The text to parse. 807 * @param textLength The length of text, or -1 if null-terminated. 808 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 809 * to begin parsing. If not NULL, on output the offset at which parsing ended. 810 * @param status A pointer to an UErrorCode to receive any errors 811 * @return The value of the parsed integer 812 * @see unum_parse 813 * @see unum_parseDouble 814 * @see unum_format 815 * @see unum_formatInt64 816 * @see unum_formatDouble 817 * @stable ICU 2.8 818 */ 819 U_CAPI int64_t U_EXPORT2 820 unum_parseInt64(const UNumberFormat* fmt, 821 const UChar* text, 822 int32_t textLength, 823 int32_t *parsePos /* 0 = start */, 824 UErrorCode *status); 825 826 /** 827 * Parse a string into a double using a UNumberFormat. 828 * The string will be parsed according to the UNumberFormat's locale. 829 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 830 * and UNUM_DECIMAL_COMPACT_LONG. 831 * @param fmt The formatter to use. 832 * @param text The text to parse. 833 * @param textLength The length of text, or -1 if null-terminated. 834 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 835 * to begin parsing. If not NULL, on output the offset at which parsing ended. 836 * @param status A pointer to an UErrorCode to receive any errors 837 * @return The value of the parsed double 838 * @see unum_parse 839 * @see unum_parseInt64 840 * @see unum_format 841 * @see unum_formatInt64 842 * @see unum_formatDouble 843 * @stable ICU 2.0 844 */ 845 U_CAPI double U_EXPORT2 846 unum_parseDouble( const UNumberFormat* fmt, 847 const UChar* text, 848 int32_t textLength, 849 int32_t *parsePos /* 0 = start */, 850 UErrorCode *status); 851 852 853 /** 854 * Parse a number from a string into an unformatted numeric string using a UNumberFormat. 855 * The input string will be parsed according to the UNumberFormat's locale. 856 * The syntax of the output is a "numeric string" 857 * as defined in the Decimal Arithmetic Specification, available at 858 * http://speleotrove.com/decimal 859 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 860 * and UNUM_DECIMAL_COMPACT_LONG. 861 * @param fmt The formatter to use. 862 * @param text The text to parse. 863 * @param textLength The length of text, or -1 if null-terminated. 864 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 865 * to begin parsing. If not NULL, on output the offset at which parsing ended. 866 * @param outBuf A (char *) buffer to receive the parsed number as a string. The output string 867 * will be nul-terminated if there is sufficient space. 868 * @param outBufLength The size of the output buffer. May be zero, in which case 869 * the outBuf pointer may be NULL, and the function will return the 870 * size of the output string. 871 * @param status A pointer to an UErrorCode to receive any errors 872 * @return the length of the output string, not including any terminating nul. 873 * @see unum_parse 874 * @see unum_parseInt64 875 * @see unum_format 876 * @see unum_formatInt64 877 * @see unum_formatDouble 878 * @stable ICU 4.4 879 */ 880 U_CAPI int32_t U_EXPORT2 881 unum_parseDecimal(const UNumberFormat* fmt, 882 const UChar* text, 883 int32_t textLength, 884 int32_t *parsePos /* 0 = start */, 885 char *outBuf, 886 int32_t outBufLength, 887 UErrorCode *status); 888 889 /** 890 * Parse a string into a double and a currency using a UNumberFormat. 891 * The string will be parsed according to the UNumberFormat's locale. 892 * @param fmt the formatter to use 893 * @param text the text to parse 894 * @param textLength the length of text, or -1 if null-terminated 895 * @param parsePos a pointer to an offset index into text at which to 896 * begin parsing. On output, *parsePos will point after the last 897 * parsed character. This parameter may be NULL, in which case parsing 898 * begins at offset 0. 899 * @param currency a pointer to the buffer to receive the parsed null- 900 * terminated currency. This buffer must have a capacity of at least 901 * 4 UChars. 902 * @param status a pointer to an input-output UErrorCode 903 * @return the parsed double 904 * @see unum_parseDouble 905 * @see unum_formatDoubleCurrency 906 * @stable ICU 3.0 907 */ 908 U_CAPI double U_EXPORT2 909 unum_parseDoubleCurrency(const UNumberFormat* fmt, 910 const UChar* text, 911 int32_t textLength, 912 int32_t* parsePos, /* 0 = start */ 913 UChar* currency, 914 UErrorCode* status); 915 916 /** 917 * Parse a UChar string into a UFormattable. 918 * Example code: 919 * \snippet test/cintltst/cnumtst.c unum_parseToUFormattable 920 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 921 * and UNUM_DECIMAL_COMPACT_LONG. 922 * @param fmt the formatter to use 923 * @param result the UFormattable to hold the result. If NULL, a new UFormattable will be allocated (which the caller must close with ufmt_close). 924 * @param text the text to parse 925 * @param textLength the length of text, or -1 if null-terminated 926 * @param parsePos a pointer to an offset index into text at which to 927 * begin parsing. On output, *parsePos will point after the last 928 * parsed character. This parameter may be NULL in which case parsing 929 * begins at offset 0. 930 * @param status a pointer to an input-output UErrorCode 931 * @return the UFormattable. Will be ==result unless NULL was passed in for result, in which case it will be the newly opened UFormattable. 932 * @see ufmt_getType 933 * @see ufmt_close 934 * @stable ICU 52 935 */ 936 U_CAPI UFormattable* U_EXPORT2 937 unum_parseToUFormattable(const UNumberFormat* fmt, 938 UFormattable *result, 939 const UChar* text, 940 int32_t textLength, 941 int32_t* parsePos, /* 0 = start */ 942 UErrorCode* status); 943 944 /** 945 * Set the pattern used by a UNumberFormat. This can only be used 946 * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR 947 * in the status. 948 * @param format The formatter to set. 949 * @param localized true if the pattern is localized, false otherwise. 950 * @param pattern The new pattern 951 * @param patternLength The length of pattern, or -1 if null-terminated. 952 * @param parseError A pointer to UParseError to receive information 953 * about errors occurred during parsing, or NULL if no parse error 954 * information is desired. 955 * @param status A pointer to an input-output UErrorCode. 956 * @see unum_toPattern 957 * @see DecimalFormat 958 * @stable ICU 2.0 959 */ 960 U_CAPI void U_EXPORT2 961 unum_applyPattern( UNumberFormat *format, 962 UBool localized, 963 const UChar *pattern, 964 int32_t patternLength, 965 UParseError *parseError, 966 UErrorCode *status 967 ); 968 969 /** 970 * Get a locale for which decimal formatting patterns are available. 971 * A UNumberFormat in a locale returned by this function will perform the correct 972 * formatting and parsing for the locale. The results of this call are not 973 * valid for rule-based number formats. 974 * @param localeIndex The index of the desired locale. 975 * @return A locale for which number formatting patterns are available, or 0 if none. 976 * @see unum_countAvailable 977 * @stable ICU 2.0 978 */ 979 U_CAPI const char* U_EXPORT2 980 unum_getAvailable(int32_t localeIndex); 981 982 /** 983 * Determine how many locales have decimal formatting patterns available. The 984 * results of this call are not valid for rule-based number formats. 985 * This function is useful for determining the loop ending condition for 986 * calls to {@link #unum_getAvailable }. 987 * @return The number of locales for which decimal formatting patterns are available. 988 * @see unum_getAvailable 989 * @stable ICU 2.0 990 */ 991 U_CAPI int32_t U_EXPORT2 992 unum_countAvailable(void); 993 994 #if UCONFIG_HAVE_PARSEALLINPUT 995 /* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */ 996 /** 997 * @internal 998 */ 999 typedef enum UNumberFormatAttributeValue { 1000 #ifndef U_HIDE_INTERNAL_API 1001 /** @internal */ 1002 UNUM_NO = 0, 1003 /** @internal */ 1004 UNUM_YES = 1, 1005 /** @internal */ 1006 UNUM_MAYBE = 2 1007 #else 1008 /** @internal */ 1009 UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN 1010 #endif /* U_HIDE_INTERNAL_API */ 1011 } UNumberFormatAttributeValue; 1012 #endif 1013 1014 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */ 1015 typedef enum UNumberFormatAttribute { 1016 /** Parse integers only */ 1017 UNUM_PARSE_INT_ONLY, 1018 /** Use grouping separator */ 1019 UNUM_GROUPING_USED, 1020 /** Always show decimal point */ 1021 UNUM_DECIMAL_ALWAYS_SHOWN, 1022 /** Maximum integer digits */ 1023 UNUM_MAX_INTEGER_DIGITS, 1024 /** Minimum integer digits */ 1025 UNUM_MIN_INTEGER_DIGITS, 1026 /** Integer digits */ 1027 UNUM_INTEGER_DIGITS, 1028 /** Maximum fraction digits */ 1029 UNUM_MAX_FRACTION_DIGITS, 1030 /** Minimum fraction digits */ 1031 UNUM_MIN_FRACTION_DIGITS, 1032 /** Fraction digits */ 1033 UNUM_FRACTION_DIGITS, 1034 /** Multiplier */ 1035 UNUM_MULTIPLIER, 1036 /** Grouping size */ 1037 UNUM_GROUPING_SIZE, 1038 /** Rounding Mode */ 1039 UNUM_ROUNDING_MODE, 1040 /** Rounding increment */ 1041 UNUM_ROUNDING_INCREMENT, 1042 /** The width to which the output of <code>format()</code> is padded. */ 1043 UNUM_FORMAT_WIDTH, 1044 /** The position at which padding will take place. */ 1045 UNUM_PADDING_POSITION, 1046 /** Secondary grouping size */ 1047 UNUM_SECONDARY_GROUPING_SIZE, 1048 /** Use significant digits 1049 * @stable ICU 3.0 */ 1050 UNUM_SIGNIFICANT_DIGITS_USED, 1051 /** Minimum significant digits 1052 * @stable ICU 3.0 */ 1053 UNUM_MIN_SIGNIFICANT_DIGITS, 1054 /** Maximum significant digits 1055 * @stable ICU 3.0 */ 1056 UNUM_MAX_SIGNIFICANT_DIGITS, 1057 /** Lenient parse mode used by rule-based formats. 1058 * @stable ICU 3.0 1059 */ 1060 UNUM_LENIENT_PARSE, 1061 #if UCONFIG_HAVE_PARSEALLINPUT 1062 /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic). 1063 * This is an internal ICU API. Do not use. 1064 * @internal 1065 */ 1066 UNUM_PARSE_ALL_INPUT = 20, 1067 #endif 1068 /** 1069 * Scale, which adjusts the position of the 1070 * decimal point when formatting. Amounts will be multiplied by 10 ^ (scale) 1071 * before they are formatted. The default value for the scale is 0 ( no adjustment ). 1072 * 1073 * <p>Example: setting the scale to 3, 123 formats as "123,000" 1074 * <p>Example: setting the scale to -4, 123 formats as "0.0123" 1075 * 1076 * This setting is analogous to getMultiplierScale() and setMultiplierScale() in decimfmt.h. 1077 * 1078 * @stable ICU 51 */ 1079 UNUM_SCALE = 21, 1080 1081 /** 1082 * Minimum grouping digits; most commonly set to 2 to print "1000" instead of "1,000". 1083 * See DecimalFormat::getMinimumGroupingDigits(). 1084 * 1085 * For better control over grouping strategies, use UNumberFormatter. 1086 * 1087 * @stable ICU 64 1088 */ 1089 UNUM_MINIMUM_GROUPING_DIGITS = 22, 1090 1091 /** 1092 * if this attribute is set to 0, it is set to UNUM_CURRENCY_STANDARD purpose, 1093 * otherwise it is UNUM_CASH_CURRENCY purpose 1094 * Default: 0 (UNUM_CURRENCY_STANDARD purpose) 1095 * @stable ICU 54 1096 */ 1097 UNUM_CURRENCY_USAGE = 23, 1098 1099 #ifndef U_HIDE_INTERNAL_API 1100 /** One below the first bitfield-boolean item. 1101 * All items after this one are stored in boolean form. 1102 * @internal */ 1103 UNUM_MAX_NONBOOLEAN_ATTRIBUTE = 0x0FFF, 1104 #endif /* U_HIDE_INTERNAL_API */ 1105 1106 /** If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating. 1107 * For example, formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing. 1108 * Default: 0 (not set) 1109 * @stable ICU 50 1110 */ 1111 UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS = 0x1000, 1112 /** 1113 * if this attribute is set to 1, specifies that, if the pattern doesn't contain an exponent, the exponent will not be parsed. If the pattern does contain an exponent, this attribute has no effect. 1114 * Has no effect on formatting. 1115 * Default: 0 (unset) 1116 * @stable ICU 50 1117 */ 1118 UNUM_PARSE_NO_EXPONENT = 0x1001, 1119 1120 /** 1121 * if this attribute is set to 1, specifies that, if the pattern contains a 1122 * decimal mark the input is required to have one. If this attribute is set to 0, 1123 * specifies that input does not have to contain a decimal mark. 1124 * Has no effect on formatting. 1125 * Default: 0 (unset) 1126 * @stable ICU 54 1127 */ 1128 UNUM_PARSE_DECIMAL_MARK_REQUIRED = 0x1002, 1129 1130 /** 1131 * Parsing: if set to 1, parsing is sensitive to case (lowercase/uppercase). 1132 * 1133 * @stable ICU 64 1134 */ 1135 UNUM_PARSE_CASE_SENSITIVE = 0x1003, 1136 1137 /** 1138 * Formatting: if set to 1, whether to show the plus sign on non-negative numbers. 1139 * 1140 * For better control over sign display, use UNumberFormatter. 1141 * 1142 * @stable ICU 64 1143 */ 1144 UNUM_SIGN_ALWAYS_SHOWN = 0x1004, 1145 1146 #ifndef U_HIDE_INTERNAL_API 1147 /** Limit of boolean attributes. (value should 1148 * not depend on U_HIDE conditionals) 1149 * @internal */ 1150 UNUM_LIMIT_BOOLEAN_ATTRIBUTE = 0x1005, 1151 #endif /* U_HIDE_INTERNAL_API */ 1152 1153 } UNumberFormatAttribute; 1154 1155 /** 1156 * Get a numeric attribute associated with a UNumberFormat. 1157 * An example of a numeric attribute is the number of integer digits a formatter will produce. 1158 * @param fmt The formatter to query. 1159 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 1160 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 1161 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 1162 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE, 1163 * UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS. 1164 * @return The value of attr. 1165 * @see unum_setAttribute 1166 * @see unum_getDoubleAttribute 1167 * @see unum_setDoubleAttribute 1168 * @see unum_getTextAttribute 1169 * @see unum_setTextAttribute 1170 * @stable ICU 2.0 1171 */ 1172 U_CAPI int32_t U_EXPORT2 1173 unum_getAttribute(const UNumberFormat* fmt, 1174 UNumberFormatAttribute attr); 1175 1176 /** 1177 * Set a numeric attribute associated with a UNumberFormat. 1178 * An example of a numeric attribute is the number of integer digits a formatter will produce. If the 1179 * formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand 1180 * the lenient-parse attribute. 1181 * @param fmt The formatter to set. 1182 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 1183 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 1184 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 1185 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE, 1186 * UNUM_LENIENT_PARSE, UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS. 1187 * @param newValue The new value of attr. 1188 * @see unum_getAttribute 1189 * @see unum_getDoubleAttribute 1190 * @see unum_setDoubleAttribute 1191 * @see unum_getTextAttribute 1192 * @see unum_setTextAttribute 1193 * @stable ICU 2.0 1194 */ 1195 U_CAPI void U_EXPORT2 1196 unum_setAttribute( UNumberFormat* fmt, 1197 UNumberFormatAttribute attr, 1198 int32_t newValue); 1199 1200 1201 /** 1202 * Get a numeric attribute associated with a UNumberFormat. 1203 * An example of a numeric attribute is the number of integer digits a formatter will produce. 1204 * If the formatter does not understand the attribute, -1 is returned. 1205 * @param fmt The formatter to query. 1206 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT. 1207 * @return The value of attr. 1208 * @see unum_getAttribute 1209 * @see unum_setAttribute 1210 * @see unum_setDoubleAttribute 1211 * @see unum_getTextAttribute 1212 * @see unum_setTextAttribute 1213 * @stable ICU 2.0 1214 */ 1215 U_CAPI double U_EXPORT2 1216 unum_getDoubleAttribute(const UNumberFormat* fmt, 1217 UNumberFormatAttribute attr); 1218 1219 /** 1220 * Set a numeric attribute associated with a UNumberFormat. 1221 * An example of a numeric attribute is the number of integer digits a formatter will produce. 1222 * If the formatter does not understand the attribute, this call is ignored. 1223 * @param fmt The formatter to set. 1224 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT. 1225 * @param newValue The new value of attr. 1226 * @see unum_getAttribute 1227 * @see unum_setAttribute 1228 * @see unum_getDoubleAttribute 1229 * @see unum_getTextAttribute 1230 * @see unum_setTextAttribute 1231 * @stable ICU 2.0 1232 */ 1233 U_CAPI void U_EXPORT2 1234 unum_setDoubleAttribute( UNumberFormat* fmt, 1235 UNumberFormatAttribute attr, 1236 double newValue); 1237 1238 /** The possible UNumberFormat text attributes @stable ICU 2.0*/ 1239 typedef enum UNumberFormatTextAttribute { 1240 /** Positive prefix */ 1241 UNUM_POSITIVE_PREFIX, 1242 /** Positive suffix */ 1243 UNUM_POSITIVE_SUFFIX, 1244 /** Negative prefix */ 1245 UNUM_NEGATIVE_PREFIX, 1246 /** Negative suffix */ 1247 UNUM_NEGATIVE_SUFFIX, 1248 /** The character used to pad to the format width. */ 1249 UNUM_PADDING_CHARACTER, 1250 /** The ISO currency code */ 1251 UNUM_CURRENCY_CODE, 1252 /** 1253 * The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:", 1254 * "%spellout-ordinal-masculine-plural:", "%spellout-ordinal-feminine:", or 1255 * "%spellout-ordinal-neuter:". The available public rulesets can be listed using 1256 * unum_getTextAttribute with UNUM_PUBLIC_RULESETS. This is only available with 1257 * rule-based formatters. 1258 * @stable ICU 3.0 1259 */ 1260 UNUM_DEFAULT_RULESET, 1261 /** 1262 * The public rule sets. This is only available with rule-based formatters. 1263 * This is a read-only attribute. The public rulesets are returned as a 1264 * single string, with each ruleset name delimited by ';' (semicolon). See the 1265 * CLDR LDML spec for more information about RBNF rulesets: 1266 * http://www.unicode.org/reports/tr35/tr35-numbers.html#Rule-Based_Number_Formatting 1267 * @stable ICU 3.0 1268 */ 1269 UNUM_PUBLIC_RULESETS 1270 } UNumberFormatTextAttribute; 1271 1272 /** 1273 * Get a text attribute associated with a UNumberFormat. 1274 * An example of a text attribute is the suffix for positive numbers. If the formatter 1275 * does not understand the attribute, U_UNSUPPORTED_ERROR is returned as the status. 1276 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS. 1277 * @param fmt The formatter to query. 1278 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 1279 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 1280 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS. 1281 * @param result A pointer to a buffer to receive the attribute. 1282 * @param resultLength The maximum size of result. 1283 * @param status A pointer to an UErrorCode to receive any errors 1284 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 1285 * @see unum_setTextAttribute 1286 * @see unum_getAttribute 1287 * @see unum_setAttribute 1288 * @stable ICU 2.0 1289 */ 1290 U_CAPI int32_t U_EXPORT2 1291 unum_getTextAttribute( const UNumberFormat* fmt, 1292 UNumberFormatTextAttribute tag, 1293 UChar* result, 1294 int32_t resultLength, 1295 UErrorCode* status); 1296 1297 /** 1298 * Set a text attribute associated with a UNumberFormat. 1299 * An example of a text attribute is the suffix for positive numbers. Rule-based formatters 1300 * only understand UNUM_DEFAULT_RULESET. 1301 * @param fmt The formatter to set. 1302 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 1303 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 1304 * or UNUM_DEFAULT_RULESET. 1305 * @param newValue The new value of attr. 1306 * @param newValueLength The length of newValue, or -1 if null-terminated. 1307 * @param status A pointer to an UErrorCode to receive any errors 1308 * @see unum_getTextAttribute 1309 * @see unum_getAttribute 1310 * @see unum_setAttribute 1311 * @stable ICU 2.0 1312 */ 1313 U_CAPI void U_EXPORT2 1314 unum_setTextAttribute( UNumberFormat* fmt, 1315 UNumberFormatTextAttribute tag, 1316 const UChar* newValue, 1317 int32_t newValueLength, 1318 UErrorCode *status); 1319 1320 /** 1321 * Extract the pattern from a UNumberFormat. The pattern will follow 1322 * the DecimalFormat pattern syntax. 1323 * @param fmt The formatter to query. 1324 * @param isPatternLocalized true if the pattern should be localized, 1325 * false otherwise. This is ignored if the formatter is a rule-based 1326 * formatter. 1327 * @param result A pointer to a buffer to receive the pattern. 1328 * @param resultLength The maximum size of result. 1329 * @param status A pointer to an input-output UErrorCode. 1330 * @return The total buffer size needed; if greater than resultLength, 1331 * the output was truncated. 1332 * @see unum_applyPattern 1333 * @see DecimalFormat 1334 * @stable ICU 2.0 1335 */ 1336 U_CAPI int32_t U_EXPORT2 1337 unum_toPattern( const UNumberFormat* fmt, 1338 UBool isPatternLocalized, 1339 UChar* result, 1340 int32_t resultLength, 1341 UErrorCode* status); 1342 1343 1344 /** 1345 * Constants for specifying a number format symbol. 1346 * @stable ICU 2.0 1347 */ 1348 typedef enum UNumberFormatSymbol { 1349 /** The decimal separator */ 1350 UNUM_DECIMAL_SEPARATOR_SYMBOL = 0, 1351 /** The grouping separator */ 1352 UNUM_GROUPING_SEPARATOR_SYMBOL = 1, 1353 /** The pattern separator */ 1354 UNUM_PATTERN_SEPARATOR_SYMBOL = 2, 1355 /** The percent sign */ 1356 UNUM_PERCENT_SYMBOL = 3, 1357 /** Zero*/ 1358 UNUM_ZERO_DIGIT_SYMBOL = 4, 1359 /** Character representing a digit in the pattern */ 1360 UNUM_DIGIT_SYMBOL = 5, 1361 /** The minus sign */ 1362 UNUM_MINUS_SIGN_SYMBOL = 6, 1363 /** The plus sign */ 1364 UNUM_PLUS_SIGN_SYMBOL = 7, 1365 /** The currency symbol */ 1366 UNUM_CURRENCY_SYMBOL = 8, 1367 /** The international currency symbol */ 1368 UNUM_INTL_CURRENCY_SYMBOL = 9, 1369 /** The monetary separator */ 1370 UNUM_MONETARY_SEPARATOR_SYMBOL = 10, 1371 /** The exponential symbol */ 1372 UNUM_EXPONENTIAL_SYMBOL = 11, 1373 /** Per mill symbol */ 1374 UNUM_PERMILL_SYMBOL = 12, 1375 /** Escape padding character */ 1376 UNUM_PAD_ESCAPE_SYMBOL = 13, 1377 /** Infinity symbol */ 1378 UNUM_INFINITY_SYMBOL = 14, 1379 /** Nan symbol */ 1380 UNUM_NAN_SYMBOL = 15, 1381 /** Significant digit symbol 1382 * @stable ICU 3.0 */ 1383 UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16, 1384 /** The monetary grouping separator 1385 * @stable ICU 3.6 1386 */ 1387 UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17, 1388 /** One 1389 * @stable ICU 4.6 1390 */ 1391 UNUM_ONE_DIGIT_SYMBOL = 18, 1392 /** Two 1393 * @stable ICU 4.6 1394 */ 1395 UNUM_TWO_DIGIT_SYMBOL = 19, 1396 /** Three 1397 * @stable ICU 4.6 1398 */ 1399 UNUM_THREE_DIGIT_SYMBOL = 20, 1400 /** Four 1401 * @stable ICU 4.6 1402 */ 1403 UNUM_FOUR_DIGIT_SYMBOL = 21, 1404 /** Five 1405 * @stable ICU 4.6 1406 */ 1407 UNUM_FIVE_DIGIT_SYMBOL = 22, 1408 /** Six 1409 * @stable ICU 4.6 1410 */ 1411 UNUM_SIX_DIGIT_SYMBOL = 23, 1412 /** Seven 1413 * @stable ICU 4.6 1414 */ 1415 UNUM_SEVEN_DIGIT_SYMBOL = 24, 1416 /** Eight 1417 * @stable ICU 4.6 1418 */ 1419 UNUM_EIGHT_DIGIT_SYMBOL = 25, 1420 /** Nine 1421 * @stable ICU 4.6 1422 */ 1423 UNUM_NINE_DIGIT_SYMBOL = 26, 1424 1425 /** Multiplication sign 1426 * @stable ICU 54 1427 */ 1428 UNUM_EXPONENT_MULTIPLICATION_SYMBOL = 27, 1429 1430 #ifndef U_HIDE_INTERNAL_API 1431 /** Approximately sign. 1432 * @internal 1433 */ 1434 UNUM_APPROXIMATELY_SIGN_SYMBOL = 28, 1435 #endif 1436 1437 #ifndef U_HIDE_DEPRECATED_API 1438 /** 1439 * One more than the highest normal UNumberFormatSymbol value. 1440 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 1441 */ 1442 UNUM_FORMAT_SYMBOL_COUNT = 29 1443 #endif /* U_HIDE_DEPRECATED_API */ 1444 } UNumberFormatSymbol; 1445 1446 /** 1447 * Get a symbol associated with a UNumberFormat. 1448 * A UNumberFormat uses symbols to represent the special locale-dependent 1449 * characters in a number, for example the percent sign. This API is not 1450 * supported for rule-based formatters. 1451 * @param fmt The formatter to query. 1452 * @param symbol The UNumberFormatSymbol constant for the symbol to get 1453 * @param buffer The string buffer that will receive the symbol string; 1454 * if it is NULL, then only the length of the symbol is returned 1455 * @param size The size of the string buffer 1456 * @param status A pointer to an UErrorCode to receive any errors 1457 * @return The length of the symbol; the buffer is not modified if 1458 * <code>length>=size</code> 1459 * @see unum_setSymbol 1460 * @stable ICU 2.0 1461 */ 1462 U_CAPI int32_t U_EXPORT2 1463 unum_getSymbol(const UNumberFormat *fmt, 1464 UNumberFormatSymbol symbol, 1465 UChar *buffer, 1466 int32_t size, 1467 UErrorCode *status); 1468 1469 /** 1470 * Set a symbol associated with a UNumberFormat. 1471 * A UNumberFormat uses symbols to represent the special locale-dependent 1472 * characters in a number, for example the percent sign. This API is not 1473 * supported for rule-based formatters. 1474 * @param fmt The formatter to set. 1475 * @param symbol The UNumberFormatSymbol constant for the symbol to set 1476 * @param value The string to set the symbol to 1477 * @param length The length of the string, or -1 for a zero-terminated string 1478 * @param status A pointer to an UErrorCode to receive any errors. 1479 * @see unum_getSymbol 1480 * @stable ICU 2.0 1481 */ 1482 U_CAPI void U_EXPORT2 1483 unum_setSymbol(UNumberFormat *fmt, 1484 UNumberFormatSymbol symbol, 1485 const UChar *value, 1486 int32_t length, 1487 UErrorCode *status); 1488 1489 1490 /** 1491 * Get the locale for this number format object. 1492 * You can choose between valid and actual locale. 1493 * @param fmt The formatter to get the locale from 1494 * @param type type of the locale we're looking for (valid or actual) 1495 * @param status error code for the operation 1496 * @return the locale name 1497 * @stable ICU 2.8 1498 */ 1499 U_CAPI const char* U_EXPORT2 1500 unum_getLocaleByType(const UNumberFormat *fmt, 1501 ULocDataLocaleType type, 1502 UErrorCode* status); 1503 1504 /** 1505 * Set a particular UDisplayContext value in the formatter, such as 1506 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. 1507 * @param fmt The formatter for which to set a UDisplayContext value. 1508 * @param value The UDisplayContext value to set. 1509 * @param status A pointer to an UErrorCode to receive any errors 1510 * @stable ICU 53 1511 */ 1512 U_CAPI void U_EXPORT2 1513 unum_setContext(UNumberFormat* fmt, UDisplayContext value, UErrorCode* status); 1514 1515 /** 1516 * Get the formatter's UDisplayContext value for the specified UDisplayContextType, 1517 * such as UDISPCTX_TYPE_CAPITALIZATION. 1518 * @param fmt The formatter to query. 1519 * @param type The UDisplayContextType whose value to return 1520 * @param status A pointer to an UErrorCode to receive any errors 1521 * @return The UDisplayContextValue for the specified type. 1522 * @stable ICU 53 1523 */ 1524 U_CAPI UDisplayContext U_EXPORT2 1525 unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode* status); 1526 1527 #endif /* #if !UCONFIG_NO_FORMATTING */ 1528 1529 #endif 1530