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 } UNumberFormatRoundingMode; 307 308 /** The possible number format pad positions. 309 * @stable ICU 2.0 310 */ 311 typedef enum UNumberFormatPadPosition { 312 UNUM_PAD_BEFORE_PREFIX, 313 UNUM_PAD_AFTER_PREFIX, 314 UNUM_PAD_BEFORE_SUFFIX, 315 UNUM_PAD_AFTER_SUFFIX 316 } UNumberFormatPadPosition; 317 318 /** 319 * Constants for specifying short or long format. 320 * @stable ICU 51 321 */ 322 typedef enum UNumberCompactStyle { 323 /** @stable ICU 51 */ 324 UNUM_SHORT, 325 /** @stable ICU 51 */ 326 UNUM_LONG 327 /** @stable ICU 51 */ 328 } UNumberCompactStyle; 329 330 /** 331 * Constants for specifying currency spacing 332 * @stable ICU 4.8 333 */ 334 enum UCurrencySpacing { 335 /** @stable ICU 4.8 */ 336 UNUM_CURRENCY_MATCH, 337 /** @stable ICU 4.8 */ 338 UNUM_CURRENCY_SURROUNDING_MATCH, 339 /** @stable ICU 4.8 */ 340 UNUM_CURRENCY_INSERT, 341 342 /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, 343 * it is needed for layout of DecimalFormatSymbols object. */ 344 #ifndef U_FORCE_HIDE_DEPRECATED_API 345 /** 346 * One more than the highest normal UCurrencySpacing value. 347 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 348 */ 349 UNUM_CURRENCY_SPACING_COUNT 350 #endif // U_FORCE_HIDE_DEPRECATED_API 351 }; 352 typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */ 353 354 355 /** 356 * FieldPosition and UFieldPosition selectors for format fields 357 * defined by NumberFormat and UNumberFormat. 358 * @stable ICU 49 359 */ 360 typedef enum UNumberFormatFields { 361 /** @stable ICU 49 */ 362 UNUM_INTEGER_FIELD, 363 /** @stable ICU 49 */ 364 UNUM_FRACTION_FIELD, 365 /** @stable ICU 49 */ 366 UNUM_DECIMAL_SEPARATOR_FIELD, 367 /** @stable ICU 49 */ 368 UNUM_EXPONENT_SYMBOL_FIELD, 369 /** @stable ICU 49 */ 370 UNUM_EXPONENT_SIGN_FIELD, 371 /** @stable ICU 49 */ 372 UNUM_EXPONENT_FIELD, 373 /** @stable ICU 49 */ 374 UNUM_GROUPING_SEPARATOR_FIELD, 375 /** @stable ICU 49 */ 376 UNUM_CURRENCY_FIELD, 377 /** @stable ICU 49 */ 378 UNUM_PERCENT_FIELD, 379 /** @stable ICU 49 */ 380 UNUM_PERMILL_FIELD, 381 /** @stable ICU 49 */ 382 UNUM_SIGN_FIELD, 383 /** @stable ICU 64 */ 384 UNUM_MEASURE_UNIT_FIELD, 385 /** @stable ICU 64 */ 386 UNUM_COMPACT_FIELD, 387 388 #ifndef U_HIDE_DEPRECATED_API 389 /** 390 * One more than the highest normal UNumberFormatFields value. 391 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 392 */ 393 UNUM_FIELD_COUNT = UNUM_SIGN_FIELD + 3 394 #endif /* U_HIDE_DEPRECATED_API */ 395 } UNumberFormatFields; 396 397 398 #ifndef U_HIDE_DRAFT_API 399 /** 400 * Selectors with special numeric values to use locale default minimum grouping 401 * digits for the DecimalFormat/UNumberFormat setMinimumGroupingDigits method. 402 * Do not use these constants with the [U]NumberFormatter API. 403 * 404 * @draft ICU 68 405 */ 406 typedef enum UNumberFormatMinimumGroupingDigits { 407 /** 408 * Display grouping using the default strategy for all locales. 409 * @draft ICU 68 410 */ 411 UNUM_MINIMUM_GROUPING_DIGITS_AUTO = -2, 412 /** 413 * Display grouping using locale defaults, except do not show grouping on 414 * values smaller than 10000 (such that there is a minimum of two digits 415 * before the first separator). 416 * @draft ICU 68 417 */ 418 UNUM_MINIMUM_GROUPING_DIGITS_MIN2 = -3, 419 } UNumberFormatMinimumGroupingDigits; 420 #endif // U_HIDE_DRAFT_API 421 422 /** 423 * Create and return a new UNumberFormat for formatting and parsing 424 * numbers. A UNumberFormat may be used to format numbers by calling 425 * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }. 426 * The caller must call {@link #unum_close } when done to release resources 427 * used by this object. 428 * @param style The type of number format to open: one of 429 * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, 430 * UNUM_CURRENCY_ISO, UNUM_CURRENCY_PLURAL, UNUM_SPELLOUT, 431 * UNUM_ORDINAL, UNUM_DURATION, UNUM_NUMBERING_SYSTEM, 432 * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT. 433 * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the 434 * number format is opened using the given pattern, which must conform 435 * to the syntax described in DecimalFormat or RuleBasedNumberFormat, 436 * respectively. 437 * 438 * <p><strong>NOTE::</strong> New users with are strongly encouraged to 439 * use unumf_openForSkeletonAndLocale instead of unum_open. 440 * 441 * @param pattern A pattern specifying the format to use. 442 * This parameter is ignored unless the style is 443 * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED. 444 * @param patternLength The number of characters in the pattern, or -1 445 * if null-terminated. This parameter is ignored unless the style is 446 * UNUM_PATTERN. 447 * @param locale A locale identifier to use to determine formatting 448 * and parsing conventions, or NULL to use the default locale. 449 * @param parseErr A pointer to a UParseError struct to receive the 450 * details of any parsing errors, or NULL if no parsing error details 451 * are desired. 452 * @param status A pointer to an input-output UErrorCode. 453 * @return A pointer to a newly created UNumberFormat, or NULL if an 454 * error occurred. 455 * @see unum_close 456 * @see DecimalFormat 457 * @stable ICU 2.0 458 */ 459 U_CAPI UNumberFormat* U_EXPORT2 460 unum_open( UNumberFormatStyle style, 461 const UChar* pattern, 462 int32_t patternLength, 463 const char* locale, 464 UParseError* parseErr, 465 UErrorCode* status); 466 467 468 /** 469 * Close a UNumberFormat. 470 * Once closed, a UNumberFormat may no longer be used. 471 * @param fmt The formatter to close. 472 * @stable ICU 2.0 473 */ 474 U_CAPI void U_EXPORT2 475 unum_close(UNumberFormat* fmt); 476 477 #if U_SHOW_CPLUSPLUS_API 478 479 U_NAMESPACE_BEGIN 480 481 /** 482 * \class LocalUNumberFormatPointer 483 * "Smart pointer" class, closes a UNumberFormat via unum_close(). 484 * For most methods see the LocalPointerBase base class. 485 * 486 * @see LocalPointerBase 487 * @see LocalPointer 488 * @stable ICU 4.4 489 */ 490 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close); 491 492 U_NAMESPACE_END 493 494 #endif 495 496 /** 497 * Open a copy of a UNumberFormat. 498 * This function performs a deep copy. 499 * @param fmt The format to copy 500 * @param status A pointer to an UErrorCode to receive any errors. 501 * @return A pointer to a UNumberFormat identical to fmt. 502 * @stable ICU 2.0 503 */ 504 U_CAPI UNumberFormat* U_EXPORT2 505 unum_clone(const UNumberFormat *fmt, 506 UErrorCode *status); 507 508 /** 509 * Format an integer using a UNumberFormat. 510 * The integer will be formatted according to the UNumberFormat's locale. 511 * @param fmt The formatter to use. 512 * @param number The number to format. 513 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 514 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 515 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 516 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 517 * @param resultLength The maximum size of result. 518 * @param pos A pointer to a UFieldPosition. On input, position->field 519 * is read. On output, position->beginIndex and position->endIndex indicate 520 * the beginning and ending indices of field number position->field, if such 521 * a field exists. This parameter may be NULL, in which case no field 522 * @param status A pointer to an UErrorCode to receive any errors 523 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 524 * @see unum_formatInt64 525 * @see unum_formatDouble 526 * @see unum_parse 527 * @see unum_parseInt64 528 * @see unum_parseDouble 529 * @see UFieldPosition 530 * @stable ICU 2.0 531 */ 532 U_CAPI int32_t U_EXPORT2 533 unum_format( const UNumberFormat* fmt, 534 int32_t number, 535 UChar* result, 536 int32_t resultLength, 537 UFieldPosition *pos, 538 UErrorCode* status); 539 540 /** 541 * Format an int64 using a UNumberFormat. 542 * The int64 will be formatted according to the UNumberFormat's locale. 543 * @param fmt The formatter to use. 544 * @param number The number to format. 545 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 546 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 547 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 548 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 549 * @param resultLength The maximum size of result. 550 * @param pos A pointer to a UFieldPosition. On input, position->field 551 * is read. On output, position->beginIndex and position->endIndex indicate 552 * the beginning and ending indices of field number position->field, if such 553 * a field exists. This parameter may be NULL, in which case no field 554 * @param status A pointer to an UErrorCode to receive any errors 555 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 556 * @see unum_format 557 * @see unum_formatDouble 558 * @see unum_parse 559 * @see unum_parseInt64 560 * @see unum_parseDouble 561 * @see UFieldPosition 562 * @stable ICU 2.0 563 */ 564 U_CAPI int32_t U_EXPORT2 565 unum_formatInt64(const UNumberFormat *fmt, 566 int64_t number, 567 UChar* result, 568 int32_t resultLength, 569 UFieldPosition *pos, 570 UErrorCode* status); 571 572 /** 573 * Format a double using a UNumberFormat. 574 * The double will be formatted according to the UNumberFormat's locale. 575 * @param fmt The formatter to use. 576 * @param number The number to format. 577 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 578 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 579 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 580 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 581 * @param resultLength The maximum size of result. 582 * @param pos A pointer to a UFieldPosition. On input, position->field 583 * is read. On output, position->beginIndex and position->endIndex indicate 584 * the beginning and ending indices of field number position->field, if such 585 * a field exists. This parameter may be NULL, in which case no field 586 * @param status A pointer to an UErrorCode to receive any errors 587 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 588 * @see unum_format 589 * @see unum_formatInt64 590 * @see unum_parse 591 * @see unum_parseInt64 592 * @see unum_parseDouble 593 * @see UFieldPosition 594 * @stable ICU 2.0 595 */ 596 U_CAPI int32_t U_EXPORT2 597 unum_formatDouble( const UNumberFormat* fmt, 598 double number, 599 UChar* result, 600 int32_t resultLength, 601 UFieldPosition *pos, /* 0 if ignore */ 602 UErrorCode* status); 603 604 /** 605 * Format a double using a UNumberFormat according to the UNumberFormat's locale, 606 * and initialize a UFieldPositionIterator that enumerates the subcomponents of 607 * the resulting string. 608 * 609 * @param format 610 * The formatter to use. 611 * @param number 612 * The number to format. 613 * @param result 614 * A pointer to a buffer to receive the NULL-terminated formatted 615 * number. If the formatted number fits into dest but cannot be 616 * NULL-terminated (length == resultLength) then the error code is set 617 * to U_STRING_NOT_TERMINATED_WARNING. If the formatted number doesn't 618 * fit into result then the error code is set to 619 * U_BUFFER_OVERFLOW_ERROR. 620 * @param resultLength 621 * The maximum size of result. 622 * @param fpositer 623 * A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open} 624 * (may be NULL if field position information is not needed, but in this 625 * case it's preferable to use {@link #unum_formatDouble}). Iteration 626 * information already present in the UFieldPositionIterator is deleted, 627 * and the iterator is reset to apply to the fields in the formatted 628 * string created by this function call. The field values and indexes 629 * returned by {@link #ufieldpositer_next} represent fields denoted by 630 * the UNumberFormatFields enum. Fields are not returned in a guaranteed 631 * order. Fields cannot overlap, but they may nest. For example, 1234 632 * could format as "1,234" which might consist of a grouping separator 633 * field for ',' and an integer field encompassing the entire string. 634 * @param status 635 * A pointer to an UErrorCode to receive any errors 636 * @return 637 * The total buffer size needed; if greater than resultLength, the 638 * output was truncated. 639 * @see unum_formatDouble 640 * @see unum_parse 641 * @see unum_parseDouble 642 * @see UFieldPositionIterator 643 * @see UNumberFormatFields 644 * @stable ICU 59 645 */ 646 U_CAPI int32_t U_EXPORT2 647 unum_formatDoubleForFields(const UNumberFormat* format, 648 double number, 649 UChar* result, 650 int32_t resultLength, 651 UFieldPositionIterator* fpositer, 652 UErrorCode* status); 653 654 655 /** 656 * Format a decimal number using a UNumberFormat. 657 * The number will be formatted according to the UNumberFormat's locale. 658 * The syntax of the input number is a "numeric string" 659 * as defined in the Decimal Arithmetic Specification, available at 660 * http://speleotrove.com/decimal 661 * @param fmt The formatter to use. 662 * @param number The number to format. 663 * @param length The length of the input number, or -1 if the input is nul-terminated. 664 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 665 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 666 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 667 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 668 * @param resultLength The maximum size of result. 669 * @param pos A pointer to a UFieldPosition. On input, position->field 670 * is read. On output, position->beginIndex and position->endIndex indicate 671 * the beginning and ending indices of field number position->field, if such 672 * a field exists. This parameter may be NULL, in which case it is ignored. 673 * @param status A pointer to an UErrorCode to receive any errors 674 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 675 * @see unum_format 676 * @see unum_formatInt64 677 * @see unum_parse 678 * @see unum_parseInt64 679 * @see unum_parseDouble 680 * @see UFieldPosition 681 * @stable ICU 4.4 682 */ 683 U_CAPI int32_t U_EXPORT2 684 unum_formatDecimal( const UNumberFormat* fmt, 685 const char * number, 686 int32_t length, 687 UChar* result, 688 int32_t resultLength, 689 UFieldPosition *pos, /* 0 if ignore */ 690 UErrorCode* status); 691 692 /** 693 * Format a double currency amount using a UNumberFormat. 694 * The double will be formatted according to the UNumberFormat's locale. 695 * @param fmt the formatter to use 696 * @param number the number to format 697 * @param currency the 3-letter null-terminated ISO 4217 currency code 698 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 699 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 700 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 701 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 702 * @param resultLength the maximum number of UChars to write to result 703 * @param pos a pointer to a UFieldPosition. On input, 704 * position->field is read. On output, position->beginIndex and 705 * position->endIndex indicate the beginning and ending indices of 706 * field number position->field, if such a field exists. This 707 * parameter may be NULL, in which case it is ignored. 708 * @param status a pointer to an input-output UErrorCode 709 * @return the total buffer size needed; if greater than resultLength, 710 * the output was truncated. 711 * @see unum_formatDouble 712 * @see unum_parseDoubleCurrency 713 * @see UFieldPosition 714 * @stable ICU 3.0 715 */ 716 U_CAPI int32_t U_EXPORT2 717 unum_formatDoubleCurrency(const UNumberFormat* fmt, 718 double number, 719 UChar* currency, 720 UChar* result, 721 int32_t resultLength, 722 UFieldPosition* pos, 723 UErrorCode* status); 724 725 /** 726 * Format a UFormattable into a string. 727 * @param fmt the formatter to use 728 * @param number the number to format, as a UFormattable 729 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If 730 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) 731 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number 732 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. 733 * @param resultLength the maximum number of UChars to write to result 734 * @param pos a pointer to a UFieldPosition. On input, 735 * position->field is read. On output, position->beginIndex and 736 * position->endIndex indicate the beginning and ending indices of 737 * field number position->field, if such a field exists. This 738 * parameter may be NULL, in which case it is ignored. 739 * @param status a pointer to an input-output UErrorCode 740 * @return the total buffer size needed; if greater than resultLength, 741 * the output was truncated. Will return 0 on error. 742 * @see unum_parseToUFormattable 743 * @stable ICU 52 744 */ 745 U_CAPI int32_t U_EXPORT2 746 unum_formatUFormattable(const UNumberFormat* fmt, 747 const UFormattable *number, 748 UChar *result, 749 int32_t resultLength, 750 UFieldPosition *pos, 751 UErrorCode *status); 752 753 /** 754 * Parse a string into an integer using a UNumberFormat. 755 * The string will be parsed according to the UNumberFormat's locale. 756 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 757 * and UNUM_DECIMAL_COMPACT_LONG. 758 * @param fmt The formatter to use. 759 * @param text The text to parse. 760 * @param textLength The length of text, or -1 if null-terminated. 761 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 762 * to begin parsing. If not NULL, on output the offset at which parsing ended. 763 * @param status A pointer to an UErrorCode to receive any errors 764 * @return The value of the parsed integer 765 * @see unum_parseInt64 766 * @see unum_parseDouble 767 * @see unum_format 768 * @see unum_formatInt64 769 * @see unum_formatDouble 770 * @stable ICU 2.0 771 */ 772 U_CAPI int32_t U_EXPORT2 773 unum_parse( const UNumberFormat* fmt, 774 const UChar* text, 775 int32_t textLength, 776 int32_t *parsePos /* 0 = start */, 777 UErrorCode *status); 778 779 /** 780 * Parse a string into an int64 using a UNumberFormat. 781 * The string will be parsed according to the UNumberFormat's locale. 782 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 783 * and UNUM_DECIMAL_COMPACT_LONG. 784 * @param fmt The formatter to use. 785 * @param text The text to parse. 786 * @param textLength The length of text, or -1 if null-terminated. 787 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 788 * to begin parsing. If not NULL, on output the offset at which parsing ended. 789 * @param status A pointer to an UErrorCode to receive any errors 790 * @return The value of the parsed integer 791 * @see unum_parse 792 * @see unum_parseDouble 793 * @see unum_format 794 * @see unum_formatInt64 795 * @see unum_formatDouble 796 * @stable ICU 2.8 797 */ 798 U_CAPI int64_t U_EXPORT2 799 unum_parseInt64(const UNumberFormat* fmt, 800 const UChar* text, 801 int32_t textLength, 802 int32_t *parsePos /* 0 = start */, 803 UErrorCode *status); 804 805 /** 806 * Parse a string into a double using a UNumberFormat. 807 * The string will be parsed according to the UNumberFormat's locale. 808 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 809 * and UNUM_DECIMAL_COMPACT_LONG. 810 * @param fmt The formatter to use. 811 * @param text The text to parse. 812 * @param textLength The length of text, or -1 if null-terminated. 813 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 814 * to begin parsing. If not NULL, on output the offset at which parsing ended. 815 * @param status A pointer to an UErrorCode to receive any errors 816 * @return The value of the parsed double 817 * @see unum_parse 818 * @see unum_parseInt64 819 * @see unum_format 820 * @see unum_formatInt64 821 * @see unum_formatDouble 822 * @stable ICU 2.0 823 */ 824 U_CAPI double U_EXPORT2 825 unum_parseDouble( const UNumberFormat* fmt, 826 const UChar* text, 827 int32_t textLength, 828 int32_t *parsePos /* 0 = start */, 829 UErrorCode *status); 830 831 832 /** 833 * Parse a number from a string into an unformatted numeric string using a UNumberFormat. 834 * The input string will be parsed according to the UNumberFormat's locale. 835 * The syntax of the output is a "numeric string" 836 * as defined in the Decimal Arithmetic Specification, available at 837 * http://speleotrove.com/decimal 838 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 839 * and UNUM_DECIMAL_COMPACT_LONG. 840 * @param fmt The formatter to use. 841 * @param text The text to parse. 842 * @param textLength The length of text, or -1 if null-terminated. 843 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which 844 * to begin parsing. If not NULL, on output the offset at which parsing ended. 845 * @param outBuf A (char *) buffer to receive the parsed number as a string. The output string 846 * will be nul-terminated if there is sufficient space. 847 * @param outBufLength The size of the output buffer. May be zero, in which case 848 * the outBuf pointer may be NULL, and the function will return the 849 * size of the output string. 850 * @param status A pointer to an UErrorCode to receive any errors 851 * @return the length of the output string, not including any terminating nul. 852 * @see unum_parse 853 * @see unum_parseInt64 854 * @see unum_format 855 * @see unum_formatInt64 856 * @see unum_formatDouble 857 * @stable ICU 4.4 858 */ 859 U_CAPI int32_t U_EXPORT2 860 unum_parseDecimal(const UNumberFormat* fmt, 861 const UChar* text, 862 int32_t textLength, 863 int32_t *parsePos /* 0 = start */, 864 char *outBuf, 865 int32_t outBufLength, 866 UErrorCode *status); 867 868 /** 869 * Parse a string into a double and a currency using a UNumberFormat. 870 * The string will be parsed according to the UNumberFormat's locale. 871 * @param fmt the formatter to use 872 * @param text the text to parse 873 * @param textLength the length of text, or -1 if null-terminated 874 * @param parsePos a pointer to an offset index into text at which to 875 * begin parsing. On output, *parsePos will point after the last 876 * parsed character. This parameter may be NULL, in which case parsing 877 * begins at offset 0. 878 * @param currency a pointer to the buffer to receive the parsed null- 879 * terminated currency. This buffer must have a capacity of at least 880 * 4 UChars. 881 * @param status a pointer to an input-output UErrorCode 882 * @return the parsed double 883 * @see unum_parseDouble 884 * @see unum_formatDoubleCurrency 885 * @stable ICU 3.0 886 */ 887 U_CAPI double U_EXPORT2 888 unum_parseDoubleCurrency(const UNumberFormat* fmt, 889 const UChar* text, 890 int32_t textLength, 891 int32_t* parsePos, /* 0 = start */ 892 UChar* currency, 893 UErrorCode* status); 894 895 /** 896 * Parse a UChar string into a UFormattable. 897 * Example code: 898 * \snippet test/cintltst/cnumtst.c unum_parseToUFormattable 899 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT 900 * and UNUM_DECIMAL_COMPACT_LONG. 901 * @param fmt the formatter to use 902 * @param result the UFormattable to hold the result. If NULL, a new UFormattable will be allocated (which the caller must close with ufmt_close). 903 * @param text the text to parse 904 * @param textLength the length of text, or -1 if null-terminated 905 * @param parsePos a pointer to an offset index into text at which to 906 * begin parsing. On output, *parsePos will point after the last 907 * parsed character. This parameter may be NULL in which case parsing 908 * begins at offset 0. 909 * @param status a pointer to an input-output UErrorCode 910 * @return the UFormattable. Will be ==result unless NULL was passed in for result, in which case it will be the newly opened UFormattable. 911 * @see ufmt_getType 912 * @see ufmt_close 913 * @stable ICU 52 914 */ 915 U_CAPI UFormattable* U_EXPORT2 916 unum_parseToUFormattable(const UNumberFormat* fmt, 917 UFormattable *result, 918 const UChar* text, 919 int32_t textLength, 920 int32_t* parsePos, /* 0 = start */ 921 UErrorCode* status); 922 923 /** 924 * Set the pattern used by a UNumberFormat. This can only be used 925 * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR 926 * in the status. 927 * @param format The formatter to set. 928 * @param localized true if the pattern is localized, false otherwise. 929 * @param pattern The new pattern 930 * @param patternLength The length of pattern, or -1 if null-terminated. 931 * @param parseError A pointer to UParseError to receive information 932 * about errors occurred during parsing, or NULL if no parse error 933 * information is desired. 934 * @param status A pointer to an input-output UErrorCode. 935 * @see unum_toPattern 936 * @see DecimalFormat 937 * @stable ICU 2.0 938 */ 939 U_CAPI void U_EXPORT2 940 unum_applyPattern( UNumberFormat *format, 941 UBool localized, 942 const UChar *pattern, 943 int32_t patternLength, 944 UParseError *parseError, 945 UErrorCode *status 946 ); 947 948 /** 949 * Get a locale for which decimal formatting patterns are available. 950 * A UNumberFormat in a locale returned by this function will perform the correct 951 * formatting and parsing for the locale. The results of this call are not 952 * valid for rule-based number formats. 953 * @param localeIndex The index of the desired locale. 954 * @return A locale for which number formatting patterns are available, or 0 if none. 955 * @see unum_countAvailable 956 * @stable ICU 2.0 957 */ 958 U_CAPI const char* U_EXPORT2 959 unum_getAvailable(int32_t localeIndex); 960 961 /** 962 * Determine how many locales have decimal formatting patterns available. The 963 * results of this call are not valid for rule-based number formats. 964 * This function is useful for determining the loop ending condition for 965 * calls to {@link #unum_getAvailable }. 966 * @return The number of locales for which decimal formatting patterns are available. 967 * @see unum_getAvailable 968 * @stable ICU 2.0 969 */ 970 U_CAPI int32_t U_EXPORT2 971 unum_countAvailable(void); 972 973 #if UCONFIG_HAVE_PARSEALLINPUT 974 /* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */ 975 /** 976 * @internal 977 */ 978 typedef enum UNumberFormatAttributeValue { 979 #ifndef U_HIDE_INTERNAL_API 980 /** @internal */ 981 UNUM_NO = 0, 982 /** @internal */ 983 UNUM_YES = 1, 984 /** @internal */ 985 UNUM_MAYBE = 2 986 #else 987 /** @internal */ 988 UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN 989 #endif /* U_HIDE_INTERNAL_API */ 990 } UNumberFormatAttributeValue; 991 #endif 992 993 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */ 994 typedef enum UNumberFormatAttribute { 995 /** Parse integers only */ 996 UNUM_PARSE_INT_ONLY, 997 /** Use grouping separator */ 998 UNUM_GROUPING_USED, 999 /** Always show decimal point */ 1000 UNUM_DECIMAL_ALWAYS_SHOWN, 1001 /** Maximum integer digits */ 1002 UNUM_MAX_INTEGER_DIGITS, 1003 /** Minimum integer digits */ 1004 UNUM_MIN_INTEGER_DIGITS, 1005 /** Integer digits */ 1006 UNUM_INTEGER_DIGITS, 1007 /** Maximum fraction digits */ 1008 UNUM_MAX_FRACTION_DIGITS, 1009 /** Minimum fraction digits */ 1010 UNUM_MIN_FRACTION_DIGITS, 1011 /** Fraction digits */ 1012 UNUM_FRACTION_DIGITS, 1013 /** Multiplier */ 1014 UNUM_MULTIPLIER, 1015 /** Grouping size */ 1016 UNUM_GROUPING_SIZE, 1017 /** Rounding Mode */ 1018 UNUM_ROUNDING_MODE, 1019 /** Rounding increment */ 1020 UNUM_ROUNDING_INCREMENT, 1021 /** The width to which the output of <code>format()</code> is padded. */ 1022 UNUM_FORMAT_WIDTH, 1023 /** The position at which padding will take place. */ 1024 UNUM_PADDING_POSITION, 1025 /** Secondary grouping size */ 1026 UNUM_SECONDARY_GROUPING_SIZE, 1027 /** Use significant digits 1028 * @stable ICU 3.0 */ 1029 UNUM_SIGNIFICANT_DIGITS_USED, 1030 /** Minimum significant digits 1031 * @stable ICU 3.0 */ 1032 UNUM_MIN_SIGNIFICANT_DIGITS, 1033 /** Maximum significant digits 1034 * @stable ICU 3.0 */ 1035 UNUM_MAX_SIGNIFICANT_DIGITS, 1036 /** Lenient parse mode used by rule-based formats. 1037 * @stable ICU 3.0 1038 */ 1039 UNUM_LENIENT_PARSE, 1040 #if UCONFIG_HAVE_PARSEALLINPUT 1041 /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic). 1042 * This is an internal ICU API. Do not use. 1043 * @internal 1044 */ 1045 UNUM_PARSE_ALL_INPUT = 20, 1046 #endif 1047 /** 1048 * Scale, which adjusts the position of the 1049 * decimal point when formatting. Amounts will be multiplied by 10 ^ (scale) 1050 * before they are formatted. The default value for the scale is 0 ( no adjustment ). 1051 * 1052 * <p>Example: setting the scale to 3, 123 formats as "123,000" 1053 * <p>Example: setting the scale to -4, 123 formats as "0.0123" 1054 * 1055 * This setting is analogous to getMultiplierScale() and setMultiplierScale() in decimfmt.h. 1056 * 1057 * @stable ICU 51 */ 1058 UNUM_SCALE = 21, 1059 1060 /** 1061 * Minimum grouping digits; most commonly set to 2 to print "1000" instead of "1,000". 1062 * See DecimalFormat::getMinimumGroupingDigits(). 1063 * 1064 * For better control over grouping strategies, use UNumberFormatter. 1065 * 1066 * @stable ICU 64 1067 */ 1068 UNUM_MINIMUM_GROUPING_DIGITS = 22, 1069 1070 /** 1071 * if this attribute is set to 0, it is set to UNUM_CURRENCY_STANDARD purpose, 1072 * otherwise it is UNUM_CURRENCY_CASH purpose 1073 * Default: 0 (UNUM_CURRENCY_STANDARD purpose) 1074 * @stable ICU 54 1075 */ 1076 UNUM_CURRENCY_USAGE = 23, 1077 1078 #ifndef U_HIDE_INTERNAL_API 1079 /** One below the first bitfield-boolean item. 1080 * All items after this one are stored in boolean form. 1081 * @internal */ 1082 UNUM_MAX_NONBOOLEAN_ATTRIBUTE = 0x0FFF, 1083 #endif /* U_HIDE_INTERNAL_API */ 1084 1085 /** If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating. 1086 * For example, formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing. 1087 * Default: 0 (not set) 1088 * @stable ICU 50 1089 */ 1090 UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS = 0x1000, 1091 /** 1092 * 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. 1093 * Has no effect on formatting. 1094 * Default: 0 (unset) 1095 * @stable ICU 50 1096 */ 1097 UNUM_PARSE_NO_EXPONENT = 0x1001, 1098 1099 /** 1100 * if this attribute is set to 1, specifies that, if the pattern contains a 1101 * decimal mark the input is required to have one. If this attribute is set to 0, 1102 * specifies that input does not have to contain a decimal mark. 1103 * Has no effect on formatting. 1104 * Default: 0 (unset) 1105 * @stable ICU 54 1106 */ 1107 UNUM_PARSE_DECIMAL_MARK_REQUIRED = 0x1002, 1108 1109 /** 1110 * Parsing: if set to 1, parsing is sensitive to case (lowercase/uppercase). 1111 * 1112 * @stable ICU 64 1113 */ 1114 UNUM_PARSE_CASE_SENSITIVE = 0x1003, 1115 1116 /** 1117 * Formatting: if set to 1, whether to show the plus sign on non-negative numbers. 1118 * 1119 * For better control over sign display, use UNumberFormatter. 1120 * 1121 * @stable ICU 64 1122 */ 1123 UNUM_SIGN_ALWAYS_SHOWN = 0x1004, 1124 1125 #ifndef U_HIDE_INTERNAL_API 1126 /** Limit of boolean attributes. (value should 1127 * not depend on U_HIDE conditionals) 1128 * @internal */ 1129 UNUM_LIMIT_BOOLEAN_ATTRIBUTE = 0x1005, 1130 #endif /* U_HIDE_INTERNAL_API */ 1131 1132 } UNumberFormatAttribute; 1133 1134 /** 1135 * Get a numeric attribute associated with a UNumberFormat. 1136 * An example of a numeric attribute is the number of integer digits a formatter will produce. 1137 * @param fmt The formatter to query. 1138 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 1139 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 1140 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 1141 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE, 1142 * UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS. 1143 * @return The value of attr. 1144 * @see unum_setAttribute 1145 * @see unum_getDoubleAttribute 1146 * @see unum_setDoubleAttribute 1147 * @see unum_getTextAttribute 1148 * @see unum_setTextAttribute 1149 * @stable ICU 2.0 1150 */ 1151 U_CAPI int32_t U_EXPORT2 1152 unum_getAttribute(const UNumberFormat* fmt, 1153 UNumberFormatAttribute attr); 1154 1155 /** 1156 * Set a numeric attribute associated with a UNumberFormat. 1157 * An example of a numeric attribute is the number of integer digits a formatter will produce. If the 1158 * formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand 1159 * the lenient-parse attribute. 1160 * @param fmt The formatter to set. 1161 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 1162 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 1163 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 1164 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE, 1165 * UNUM_LENIENT_PARSE, UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS. 1166 * @param newValue The new value of attr. 1167 * @see unum_getAttribute 1168 * @see unum_getDoubleAttribute 1169 * @see unum_setDoubleAttribute 1170 * @see unum_getTextAttribute 1171 * @see unum_setTextAttribute 1172 * @stable ICU 2.0 1173 */ 1174 U_CAPI void U_EXPORT2 1175 unum_setAttribute( UNumberFormat* fmt, 1176 UNumberFormatAttribute attr, 1177 int32_t newValue); 1178 1179 1180 /** 1181 * Get a numeric attribute associated with a UNumberFormat. 1182 * An example of a numeric attribute is the number of integer digits a formatter will produce. 1183 * If the formatter does not understand the attribute, -1 is returned. 1184 * @param fmt The formatter to query. 1185 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT. 1186 * @return The value of attr. 1187 * @see unum_getAttribute 1188 * @see unum_setAttribute 1189 * @see unum_setDoubleAttribute 1190 * @see unum_getTextAttribute 1191 * @see unum_setTextAttribute 1192 * @stable ICU 2.0 1193 */ 1194 U_CAPI double U_EXPORT2 1195 unum_getDoubleAttribute(const UNumberFormat* fmt, 1196 UNumberFormatAttribute attr); 1197 1198 /** 1199 * Set a numeric attribute associated with a UNumberFormat. 1200 * An example of a numeric attribute is the number of integer digits a formatter will produce. 1201 * If the formatter does not understand the attribute, this call is ignored. 1202 * @param fmt The formatter to set. 1203 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT. 1204 * @param newValue The new value of attr. 1205 * @see unum_getAttribute 1206 * @see unum_setAttribute 1207 * @see unum_getDoubleAttribute 1208 * @see unum_getTextAttribute 1209 * @see unum_setTextAttribute 1210 * @stable ICU 2.0 1211 */ 1212 U_CAPI void U_EXPORT2 1213 unum_setDoubleAttribute( UNumberFormat* fmt, 1214 UNumberFormatAttribute attr, 1215 double newValue); 1216 1217 /** The possible UNumberFormat text attributes @stable ICU 2.0*/ 1218 typedef enum UNumberFormatTextAttribute { 1219 /** Positive prefix */ 1220 UNUM_POSITIVE_PREFIX, 1221 /** Positive suffix */ 1222 UNUM_POSITIVE_SUFFIX, 1223 /** Negative prefix */ 1224 UNUM_NEGATIVE_PREFIX, 1225 /** Negative suffix */ 1226 UNUM_NEGATIVE_SUFFIX, 1227 /** The character used to pad to the format width. */ 1228 UNUM_PADDING_CHARACTER, 1229 /** The ISO currency code */ 1230 UNUM_CURRENCY_CODE, 1231 /** 1232 * The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:", 1233 * "%spellout-ordinal-masculine-plural:", "%spellout-ordinal-feminine:", or 1234 * "%spellout-ordinal-neuter:". The available public rulesets can be listed using 1235 * unum_getTextAttribute with UNUM_PUBLIC_RULESETS. This is only available with 1236 * rule-based formatters. 1237 * @stable ICU 3.0 1238 */ 1239 UNUM_DEFAULT_RULESET, 1240 /** 1241 * The public rule sets. This is only available with rule-based formatters. 1242 * This is a read-only attribute. The public rulesets are returned as a 1243 * single string, with each ruleset name delimited by ';' (semicolon). See the 1244 * CLDR LDML spec for more information about RBNF rulesets: 1245 * http://www.unicode.org/reports/tr35/tr35-numbers.html#Rule-Based_Number_Formatting 1246 * @stable ICU 3.0 1247 */ 1248 UNUM_PUBLIC_RULESETS 1249 } UNumberFormatTextAttribute; 1250 1251 /** 1252 * Get a text attribute associated with a UNumberFormat. 1253 * An example of a text attribute is the suffix for positive numbers. If the formatter 1254 * does not understand the attribute, U_UNSUPPORTED_ERROR is returned as the status. 1255 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS. 1256 * @param fmt The formatter to query. 1257 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 1258 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 1259 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS. 1260 * @param result A pointer to a buffer to receive the attribute. 1261 * @param resultLength The maximum size of result. 1262 * @param status A pointer to an UErrorCode to receive any errors 1263 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 1264 * @see unum_setTextAttribute 1265 * @see unum_getAttribute 1266 * @see unum_setAttribute 1267 * @stable ICU 2.0 1268 */ 1269 U_CAPI int32_t U_EXPORT2 1270 unum_getTextAttribute( const UNumberFormat* fmt, 1271 UNumberFormatTextAttribute tag, 1272 UChar* result, 1273 int32_t resultLength, 1274 UErrorCode* status); 1275 1276 /** 1277 * Set a text attribute associated with a UNumberFormat. 1278 * An example of a text attribute is the suffix for positive numbers. Rule-based formatters 1279 * only understand UNUM_DEFAULT_RULESET. 1280 * @param fmt The formatter to set. 1281 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 1282 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 1283 * or UNUM_DEFAULT_RULESET. 1284 * @param newValue The new value of attr. 1285 * @param newValueLength The length of newValue, or -1 if null-terminated. 1286 * @param status A pointer to an UErrorCode to receive any errors 1287 * @see unum_getTextAttribute 1288 * @see unum_getAttribute 1289 * @see unum_setAttribute 1290 * @stable ICU 2.0 1291 */ 1292 U_CAPI void U_EXPORT2 1293 unum_setTextAttribute( UNumberFormat* fmt, 1294 UNumberFormatTextAttribute tag, 1295 const UChar* newValue, 1296 int32_t newValueLength, 1297 UErrorCode *status); 1298 1299 /** 1300 * Extract the pattern from a UNumberFormat. The pattern will follow 1301 * the DecimalFormat pattern syntax. 1302 * @param fmt The formatter to query. 1303 * @param isPatternLocalized true if the pattern should be localized, 1304 * false otherwise. This is ignored if the formatter is a rule-based 1305 * formatter. 1306 * @param result A pointer to a buffer to receive the pattern. 1307 * @param resultLength The maximum size of result. 1308 * @param status A pointer to an input-output UErrorCode. 1309 * @return The total buffer size needed; if greater than resultLength, 1310 * the output was truncated. 1311 * @see unum_applyPattern 1312 * @see DecimalFormat 1313 * @stable ICU 2.0 1314 */ 1315 U_CAPI int32_t U_EXPORT2 1316 unum_toPattern( const UNumberFormat* fmt, 1317 UBool isPatternLocalized, 1318 UChar* result, 1319 int32_t resultLength, 1320 UErrorCode* status); 1321 1322 1323 /** 1324 * Constants for specifying a number format symbol. 1325 * @stable ICU 2.0 1326 */ 1327 typedef enum UNumberFormatSymbol { 1328 /** The decimal separator */ 1329 UNUM_DECIMAL_SEPARATOR_SYMBOL = 0, 1330 /** The grouping separator */ 1331 UNUM_GROUPING_SEPARATOR_SYMBOL = 1, 1332 /** The pattern separator */ 1333 UNUM_PATTERN_SEPARATOR_SYMBOL = 2, 1334 /** The percent sign */ 1335 UNUM_PERCENT_SYMBOL = 3, 1336 /** Zero*/ 1337 UNUM_ZERO_DIGIT_SYMBOL = 4, 1338 /** Character representing a digit in the pattern */ 1339 UNUM_DIGIT_SYMBOL = 5, 1340 /** The minus sign */ 1341 UNUM_MINUS_SIGN_SYMBOL = 6, 1342 /** The plus sign */ 1343 UNUM_PLUS_SIGN_SYMBOL = 7, 1344 /** The currency symbol */ 1345 UNUM_CURRENCY_SYMBOL = 8, 1346 /** The international currency symbol */ 1347 UNUM_INTL_CURRENCY_SYMBOL = 9, 1348 /** The monetary separator */ 1349 UNUM_MONETARY_SEPARATOR_SYMBOL = 10, 1350 /** The exponential symbol */ 1351 UNUM_EXPONENTIAL_SYMBOL = 11, 1352 /** Per mill symbol */ 1353 UNUM_PERMILL_SYMBOL = 12, 1354 /** Escape padding character */ 1355 UNUM_PAD_ESCAPE_SYMBOL = 13, 1356 /** Infinity symbol */ 1357 UNUM_INFINITY_SYMBOL = 14, 1358 /** Nan symbol */ 1359 UNUM_NAN_SYMBOL = 15, 1360 /** Significant digit symbol 1361 * @stable ICU 3.0 */ 1362 UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16, 1363 /** The monetary grouping separator 1364 * @stable ICU 3.6 1365 */ 1366 UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17, 1367 /** One 1368 * @stable ICU 4.6 1369 */ 1370 UNUM_ONE_DIGIT_SYMBOL = 18, 1371 /** Two 1372 * @stable ICU 4.6 1373 */ 1374 UNUM_TWO_DIGIT_SYMBOL = 19, 1375 /** Three 1376 * @stable ICU 4.6 1377 */ 1378 UNUM_THREE_DIGIT_SYMBOL = 20, 1379 /** Four 1380 * @stable ICU 4.6 1381 */ 1382 UNUM_FOUR_DIGIT_SYMBOL = 21, 1383 /** Five 1384 * @stable ICU 4.6 1385 */ 1386 UNUM_FIVE_DIGIT_SYMBOL = 22, 1387 /** Six 1388 * @stable ICU 4.6 1389 */ 1390 UNUM_SIX_DIGIT_SYMBOL = 23, 1391 /** Seven 1392 * @stable ICU 4.6 1393 */ 1394 UNUM_SEVEN_DIGIT_SYMBOL = 24, 1395 /** Eight 1396 * @stable ICU 4.6 1397 */ 1398 UNUM_EIGHT_DIGIT_SYMBOL = 25, 1399 /** Nine 1400 * @stable ICU 4.6 1401 */ 1402 UNUM_NINE_DIGIT_SYMBOL = 26, 1403 1404 /** Multiplication sign 1405 * @stable ICU 54 1406 */ 1407 UNUM_EXPONENT_MULTIPLICATION_SYMBOL = 27, 1408 1409 #ifndef U_HIDE_DEPRECATED_API 1410 /** 1411 * One more than the highest normal UNumberFormatSymbol value. 1412 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 1413 */ 1414 UNUM_FORMAT_SYMBOL_COUNT = 28 1415 #endif /* U_HIDE_DEPRECATED_API */ 1416 } UNumberFormatSymbol; 1417 1418 /** 1419 * Get a symbol associated with a UNumberFormat. 1420 * A UNumberFormat uses symbols to represent the special locale-dependent 1421 * characters in a number, for example the percent sign. This API is not 1422 * supported for rule-based formatters. 1423 * @param fmt The formatter to query. 1424 * @param symbol The UNumberFormatSymbol constant for the symbol to get 1425 * @param buffer The string buffer that will receive the symbol string; 1426 * if it is NULL, then only the length of the symbol is returned 1427 * @param size The size of the string buffer 1428 * @param status A pointer to an UErrorCode to receive any errors 1429 * @return The length of the symbol; the buffer is not modified if 1430 * <code>length>=size</code> 1431 * @see unum_setSymbol 1432 * @stable ICU 2.0 1433 */ 1434 U_CAPI int32_t U_EXPORT2 1435 unum_getSymbol(const UNumberFormat *fmt, 1436 UNumberFormatSymbol symbol, 1437 UChar *buffer, 1438 int32_t size, 1439 UErrorCode *status); 1440 1441 /** 1442 * Set a symbol associated with a UNumberFormat. 1443 * A UNumberFormat uses symbols to represent the special locale-dependent 1444 * characters in a number, for example the percent sign. This API is not 1445 * supported for rule-based formatters. 1446 * @param fmt The formatter to set. 1447 * @param symbol The UNumberFormatSymbol constant for the symbol to set 1448 * @param value The string to set the symbol to 1449 * @param length The length of the string, or -1 for a zero-terminated string 1450 * @param status A pointer to an UErrorCode to receive any errors. 1451 * @see unum_getSymbol 1452 * @stable ICU 2.0 1453 */ 1454 U_CAPI void U_EXPORT2 1455 unum_setSymbol(UNumberFormat *fmt, 1456 UNumberFormatSymbol symbol, 1457 const UChar *value, 1458 int32_t length, 1459 UErrorCode *status); 1460 1461 1462 /** 1463 * Get the locale for this number format object. 1464 * You can choose between valid and actual locale. 1465 * @param fmt The formatter to get the locale from 1466 * @param type type of the locale we're looking for (valid or actual) 1467 * @param status error code for the operation 1468 * @return the locale name 1469 * @stable ICU 2.8 1470 */ 1471 U_CAPI const char* U_EXPORT2 1472 unum_getLocaleByType(const UNumberFormat *fmt, 1473 ULocDataLocaleType type, 1474 UErrorCode* status); 1475 1476 /** 1477 * Set a particular UDisplayContext value in the formatter, such as 1478 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. 1479 * @param fmt The formatter for which to set a UDisplayContext value. 1480 * @param value The UDisplayContext value to set. 1481 * @param status A pointer to an UErrorCode to receive any errors 1482 * @stable ICU 53 1483 */ 1484 U_CAPI void U_EXPORT2 1485 unum_setContext(UNumberFormat* fmt, UDisplayContext value, UErrorCode* status); 1486 1487 /** 1488 * Get the formatter's UDisplayContext value for the specified UDisplayContextType, 1489 * such as UDISPCTX_TYPE_CAPITALIZATION. 1490 * @param fmt The formatter to query. 1491 * @param type The UDisplayContextType whose value to return 1492 * @param status A pointer to an UErrorCode to receive any errors 1493 * @return The UDisplayContextValue for the specified type. 1494 * @stable ICU 53 1495 */ 1496 U_CAPI UDisplayContext U_EXPORT2 1497 unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode* status); 1498 1499 #endif /* #if !UCONFIG_NO_FORMATTING */ 1500 1501 #endif 1502