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