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