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