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