1 /* 2 ******************************************************************************* 3 * Copyright (C) 1997-2011, International Business Machines Corporation and others. 4 * All Rights Reserved. 5 * Modification History: 6 * 7 * Date Name Description 8 * 06/24/99 helena Integrated Alan's NF enhancements and Java2 bug fixes 9 ******************************************************************************* 10 */ 11 12 #ifndef _UNUM 13 #define _UNUM 14 15 #include "unicode/utypes.h" 16 17 #if !UCONFIG_NO_FORMATTING 18 19 #include "unicode/localpointer.h" 20 #include "unicode/uloc.h" 21 #include "unicode/umisc.h" 22 #include "unicode/parseerr.h" 23 /** 24 * \file 25 * \brief C API: NumberFormat 26 * 27 * <h2> Number Format C API </h2> 28 * 29 * Number Format C API Provides functions for 30 * formatting and parsing a number. Also provides methods for 31 * determining which locales have number formats, and what their names 32 * are. 33 * <P> 34 * UNumberFormat helps you to format and parse numbers for any locale. 35 * Your code can be completely independent of the locale conventions 36 * for decimal points, thousands-separators, or even the particular 37 * decimal digits used, or whether the number format is even decimal. 38 * There are different number format styles like decimal, currency, 39 * percent and spellout. 40 * <P> 41 * To format a number for the current Locale, use one of the static 42 * factory methods: 43 * <pre> 44 * \code 45 * UChar myString[20]; 46 * double myNumber = 7.0; 47 * UErrorCode status = U_ZERO_ERROR; 48 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status); 49 * unum_formatDouble(nf, myNumber, myString, 20, NULL, &status); 50 * printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*) 51 * \endcode 52 * </pre> 53 * If you are formatting multiple numbers, it is more efficient to get 54 * the format and use it multiple times so that the system doesn't 55 * have to fetch the information about the local language and country 56 * conventions multiple times. 57 * <pre> 58 * \code 59 * uint32_t i, resultlength, reslenneeded; 60 * UErrorCode status = U_ZERO_ERROR; 61 * UFieldPosition pos; 62 * uint32_t a[] = { 123, 3333, -1234567 }; 63 * const uint32_t a_len = sizeof(a) / sizeof(a[0]); 64 * UNumberFormat* nf; 65 * UChar* result = NULL; 66 * 67 * nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status); 68 * for (i = 0; i < a_len; i++) { 69 * resultlength=0; 70 * reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status); 71 * result = NULL; 72 * if(status==U_BUFFER_OVERFLOW_ERROR){ 73 * status=U_ZERO_ERROR; 74 * resultlength=reslenneeded+1; 75 * result=(UChar*)malloc(sizeof(UChar) * resultlength); 76 * unum_format(nf, a[i], result, resultlength, &pos, &status); 77 * } 78 * printf( " Example 2: %s\n", austrdup(result)); 79 * free(result); 80 * } 81 * \endcode 82 * </pre> 83 * To format a number for a different Locale, specify it in the 84 * call to unum_open(). 85 * <pre> 86 * \code 87 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, "fr_FR", NULL, &success) 88 * \endcode 89 * </pre> 90 * You can use a NumberFormat API unum_parse() to parse. 91 * <pre> 92 * \code 93 * UErrorCode status = U_ZERO_ERROR; 94 * int32_t pos=0; 95 * int32_t num; 96 * num = unum_parse(nf, str, u_strlen(str), &pos, &status); 97 * \endcode 98 * </pre> 99 * Use UNUM_DECIMAL to get the normal number format for that country. 100 * There are other static options available. Use UNUM_CURRENCY 101 * to get the currency number format for that country. Use UNUM_PERCENT 102 * to get a format for displaying percentages. With this format, a 103 * fraction from 0.53 is displayed as 53%. 104 * <P> 105 * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat 106 * formatter. The pattern must conform to the syntax defined for those 107 * formatters. 108 * <P> 109 * You can also control the display of numbers with such function as 110 * unum_getAttribues() and unum_setAtributes(), which let you set the 111 * miminum fraction digits, grouping, etc. 112 * @see UNumberFormatAttributes for more details 113 * <P> 114 * You can also use forms of the parse and format methods with 115 * ParsePosition and UFieldPosition to allow you to: 116 * <ul type=round> 117 * <li>(a) progressively parse through pieces of a string. 118 * <li>(b) align the decimal point and other areas. 119 * </ul> 120 * <p> 121 * It is also possible to change or set the symbols used for a particular 122 * locale like the currency symbol, the grouping seperator , monetary seperator 123 * etc by making use of functions unum_setSymbols() and unum_getSymbols(). 124 */ 125 126 /** A number formatter. 127 * For usage in C programs. 128 * @stable ICU 2.0 129 */ 130 typedef void* UNumberFormat; 131 132 /** The possible number format styles. 133 * @stable ICU 2.0 134 */ 135 typedef enum UNumberFormatStyle { 136 /** 137 * Decimal format defined by a pattern string. 138 * @stable ICU 3.0 139 */ 140 UNUM_PATTERN_DECIMAL=0, 141 /** 142 * Decimal format ("normal" style). 143 * @stable ICU 2.0 144 */ 145 UNUM_DECIMAL=1, 146 /** 147 * Currency format with a currency symbol, e.g., "$1.00". 148 * @stable ICU 2.0 149 */ 150 UNUM_CURRENCY, 151 /** 152 * Percent format 153 * @stable ICU 2.0 154 */ 155 UNUM_PERCENT, 156 /** 157 * Scientific format 158 * @stable ICU 2.1 159 */ 160 UNUM_SCIENTIFIC, 161 /** 162 * Spellout rule-based format 163 * @stable ICU 2.0 164 */ 165 UNUM_SPELLOUT, 166 /** 167 * Ordinal rule-based format 168 * @stable ICU 3.0 169 */ 170 UNUM_ORDINAL, 171 /** 172 * Duration rule-based format 173 * @stable ICU 3.0 174 */ 175 UNUM_DURATION, 176 /** 177 * Numbering system rule-based format 178 * @stable ICU 4.2 179 */ 180 UNUM_NUMBERING_SYSTEM, 181 /** 182 * Rule-based format defined by a pattern string. 183 * @stable ICU 3.0 184 */ 185 UNUM_PATTERN_RULEBASED, 186 /** 187 * Currency format with an ISO currency code, e.g., "USD1.00". 188 * @draft ICU 4.8 189 */ 190 UNUM_CURRENCY_ISO, 191 /** 192 * Currency format with a pluralized currency name, 193 * e.g., "1.00 US dollar" and "3.00 US dollars". 194 * @draft ICU 4.8 195 */ 196 UNUM_CURRENCY_PLURAL, 197 /** 198 * One more than the highest number format style constant. 199 * @draft ICU 4.8 200 */ 201 UNUM_FORMAT_STYLE_COUNT, 202 /** 203 * Default format 204 * @stable ICU 2.0 205 */ 206 UNUM_DEFAULT = UNUM_DECIMAL, 207 /** 208 * Alias for UNUM_PATTERN_DECIMAL 209 * @stable ICU 3.0 210 */ 211 UNUM_IGNORE = UNUM_PATTERN_DECIMAL 212 } UNumberFormatStyle; 213 214 /** The possible number format rounding modes. 215 * @stable ICU 2.0 216 */ 217 typedef enum UNumberFormatRoundingMode { 218 UNUM_ROUND_CEILING, 219 UNUM_ROUND_FLOOR, 220 UNUM_ROUND_DOWN, 221 UNUM_ROUND_UP, 222 /** 223 * Half-even rounding, misspelled name 224 * @deprecated, ICU 3.8 225 */ 226 UNUM_FOUND_HALFEVEN, 227 UNUM_ROUND_HALFDOWN, 228 UNUM_ROUND_HALFUP, 229 /** 230 * ROUND_UNNECESSARY reports an error if formatted result is not exact. 231 * @draft ICU 4.8 232 */ 233 UNUM_ROUND_UNNECESSARY, 234 /** 235 * Half-even rounding 236 * @stable, ICU 3.8 237 */ 238 UNUM_ROUND_HALFEVEN = UNUM_FOUND_HALFEVEN 239 } UNumberFormatRoundingMode; 240 241 /** The possible number format pad positions. 242 * @stable ICU 2.0 243 */ 244 typedef enum UNumberFormatPadPosition { 245 UNUM_PAD_BEFORE_PREFIX, 246 UNUM_PAD_AFTER_PREFIX, 247 UNUM_PAD_BEFORE_SUFFIX, 248 UNUM_PAD_AFTER_SUFFIX 249 } UNumberFormatPadPosition; 250 251 /** 252 * Constants for specifying currency spacing 253 * @draft ICU 4.8 254 */ 255 enum UCurrencySpacing { 256 UNUM_CURRENCY_MATCH, 257 UNUM_CURRENCY_SURROUNDING_MATCH, 258 UNUM_CURRENCY_INSERT, 259 UNUM_CURRENCY_SPACING_COUNT 260 }; 261 typedef enum UCurrencySpacing UCurrencySpacing; /**< @draft ICU 4.8 */ 262 263 /** 264 * Create and return a new UNumberFormat for formatting and parsing 265 * numbers. A UNumberFormat may be used to format numbers by calling 266 * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }. 267 * The caller must call {@link #unum_close } when done to release resources 268 * used by this object. 269 * @param style The type of number format to open: one of 270 * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT, 271 * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT. 272 * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the 273 * number format is opened using the given pattern, which must conform 274 * to the syntax described in DecimalFormat or RuleBasedNumberFormat, 275 * respectively. 276 * @param pattern A pattern specifying the format to use. 277 * This parameter is ignored unless the style is 278 * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED. 279 * @param patternLength The number of characters in the pattern, or -1 280 * if null-terminated. This parameter is ignored unless the style is 281 * UNUM_PATTERN. 282 * @param locale A locale identifier to use to determine formatting 283 * and parsing conventions, or NULL to use the default locale. 284 * @param parseErr A pointer to a UParseError struct to receive the 285 * details of any parsing errors, or NULL if no parsing error details 286 * are desired. 287 * @param status A pointer to an input-output UErrorCode. 288 * @return A pointer to a newly created UNumberFormat, or NULL if an 289 * error occurred. 290 * @see unum_close 291 * @see DecimalFormat 292 * @stable ICU 2.0 293 */ 294 U_STABLE UNumberFormat* U_EXPORT2 295 unum_open( UNumberFormatStyle style, 296 const UChar* pattern, 297 int32_t patternLength, 298 const char* locale, 299 UParseError* parseErr, 300 UErrorCode* status); 301 302 303 /** 304 * Close a UNumberFormat. 305 * Once closed, a UNumberFormat may no longer be used. 306 * @param fmt The formatter to close. 307 * @stable ICU 2.0 308 */ 309 U_STABLE void U_EXPORT2 310 unum_close(UNumberFormat* fmt); 311 312 #if U_SHOW_CPLUSPLUS_API 313 314 U_NAMESPACE_BEGIN 315 316 /** 317 * \class LocalUNumberFormatPointer 318 * "Smart pointer" class, closes a UNumberFormat via unum_close(). 319 * For most methods see the LocalPointerBase base class. 320 * 321 * @see LocalPointerBase 322 * @see LocalPointer 323 * @stable ICU 4.4 324 */ 325 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close); 326 327 U_NAMESPACE_END 328 329 #endif 330 331 /** 332 * Open a copy of a UNumberFormat. 333 * This function performs a deep copy. 334 * @param fmt The format to copy 335 * @param status A pointer to an UErrorCode to receive any errors. 336 * @return A pointer to a UNumberFormat identical to fmt. 337 * @stable ICU 2.0 338 */ 339 U_STABLE UNumberFormat* U_EXPORT2 340 unum_clone(const UNumberFormat *fmt, 341 UErrorCode *status); 342 343 /** 344 * Format an integer using a UNumberFormat. 345 * The integer will be formatted according to the UNumberFormat's locale. 346 * @param fmt The formatter to use. 347 * @param number The number to format. 348 * @param result A pointer to a buffer to receive the formatted number. 349 * @param resultLength The maximum size of result. 350 * @param pos A pointer to a UFieldPosition. On input, position->field 351 * is read. On output, position->beginIndex and position->endIndex indicate 352 * the beginning and ending indices of field number position->field, if such 353 * a field exists. This parameter may be NULL, in which case no field 354 * @param status A pointer to an UErrorCode to receive any errors 355 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 356 * @see unum_formatInt64 357 * @see unum_formatDouble 358 * @see unum_parse 359 * @see unum_parseInt64 360 * @see unum_parseDouble 361 * @see UFieldPosition 362 * @stable ICU 2.0 363 */ 364 U_STABLE int32_t U_EXPORT2 365 unum_format( const UNumberFormat* fmt, 366 int32_t number, 367 UChar* result, 368 int32_t resultLength, 369 UFieldPosition *pos, 370 UErrorCode* status); 371 372 /** 373 * Format an int64 using a UNumberFormat. 374 * The int64 will be formatted according to the UNumberFormat's locale. 375 * @param fmt The formatter to use. 376 * @param number The number to format. 377 * @param result A pointer to a buffer to receive the formatted number. 378 * @param resultLength The maximum size of result. 379 * @param pos A pointer to a UFieldPosition. On input, position->field 380 * is read. On output, position->beginIndex and position->endIndex indicate 381 * the beginning and ending indices of field number position->field, if such 382 * a field exists. This parameter may be NULL, in which case no field 383 * @param status A pointer to an UErrorCode to receive any errors 384 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 385 * @see unum_format 386 * @see unum_formatDouble 387 * @see unum_parse 388 * @see unum_parseInt64 389 * @see unum_parseDouble 390 * @see UFieldPosition 391 * @stable ICU 2.0 392 */ 393 U_STABLE int32_t U_EXPORT2 394 unum_formatInt64(const UNumberFormat *fmt, 395 int64_t number, 396 UChar* result, 397 int32_t resultLength, 398 UFieldPosition *pos, 399 UErrorCode* status); 400 401 /** 402 * Format a double using a UNumberFormat. 403 * The double will be formatted according to the UNumberFormat's locale. 404 * @param fmt The formatter to use. 405 * @param number The number to format. 406 * @param result A pointer to a buffer to receive the formatted number. 407 * @param resultLength The maximum size of result. 408 * @param pos A pointer to a UFieldPosition. On input, position->field 409 * is read. On output, position->beginIndex and position->endIndex indicate 410 * the beginning and ending indices of field number position->field, if such 411 * a field exists. This parameter may be NULL, in which case no field 412 * @param status A pointer to an UErrorCode to receive any errors 413 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 414 * @see unum_format 415 * @see unum_formatInt64 416 * @see unum_parse 417 * @see unum_parseInt64 418 * @see unum_parseDouble 419 * @see UFieldPosition 420 * @stable ICU 2.0 421 */ 422 U_STABLE int32_t U_EXPORT2 423 unum_formatDouble( const UNumberFormat* fmt, 424 double number, 425 UChar* result, 426 int32_t resultLength, 427 UFieldPosition *pos, /* 0 if ignore */ 428 UErrorCode* status); 429 430 /** 431 * Format a decimal number using a UNumberFormat. 432 * The number will be formatted according to the UNumberFormat's locale. 433 * The syntax of the input number is a "numeric string" 434 * as defined in the Decimal Arithmetic Specification, available at 435 * http://speleotrove.com/decimal 436 * @param fmt The formatter to use. 437 * @param number The number to format. 438 * @param length The length of the input number, or -1 if the input is nul-terminated. 439 * @param result A pointer to a buffer to receive the formatted number. 440 * @param resultLength The maximum size of result. 441 * @param pos A pointer to a UFieldPosition. On input, position->field 442 * is read. On output, position->beginIndex and position->endIndex indicate 443 * the beginning and ending indices of field number position->field, if such 444 * a field exists. This parameter may be NULL, in which case it is ignored. 445 * @param status A pointer to an UErrorCode to receive any errors 446 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 447 * @see unum_format 448 * @see unum_formatInt64 449 * @see unum_parse 450 * @see unum_parseInt64 451 * @see unum_parseDouble 452 * @see UFieldPosition 453 * @stable ICU 4.4 454 */ 455 U_STABLE int32_t U_EXPORT2 456 unum_formatDecimal( const UNumberFormat* fmt, 457 const char * number, 458 int32_t length, 459 UChar* result, 460 int32_t resultLength, 461 UFieldPosition *pos, /* 0 if ignore */ 462 UErrorCode* status); 463 464 /** 465 * Format a double currency amount using a UNumberFormat. 466 * The double will be formatted according to the UNumberFormat's locale. 467 * @param fmt the formatter to use 468 * @param number the number to format 469 * @param currency the 3-letter null-terminated ISO 4217 currency code 470 * @param result a pointer to the buffer to receive the formatted number 471 * @param resultLength the maximum number of UChars to write to result 472 * @param pos a pointer to a UFieldPosition. On input, 473 * position->field is read. On output, position->beginIndex and 474 * position->endIndex indicate the beginning and ending indices of 475 * field number position->field, if such a field exists. This 476 * parameter may be NULL, in which case it is ignored. 477 * @param status a pointer to an input-output UErrorCode 478 * @return the total buffer size needed; if greater than resultLength, 479 * the output was truncated. 480 * @see unum_formatDouble 481 * @see unum_parseDoubleCurrency 482 * @see UFieldPosition 483 * @stable ICU 3.0 484 */ 485 U_STABLE int32_t U_EXPORT2 486 unum_formatDoubleCurrency(const UNumberFormat* fmt, 487 double number, 488 UChar* currency, 489 UChar* result, 490 int32_t resultLength, 491 UFieldPosition* pos, /* ignored if 0 */ 492 UErrorCode* status); 493 494 /** 495 * Parse a string into an integer using a UNumberFormat. 496 * The string will be parsed according to the UNumberFormat's locale. 497 * @param fmt The formatter to use. 498 * @param text The text to parse. 499 * @param textLength The length of text, or -1 if null-terminated. 500 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 501 * to begin parsing. If not 0, on output the offset at which parsing ended. 502 * @param status A pointer to an UErrorCode to receive any errors 503 * @return The value of the parsed integer 504 * @see unum_parseInt64 505 * @see unum_parseDouble 506 * @see unum_format 507 * @see unum_formatInt64 508 * @see unum_formatDouble 509 * @stable ICU 2.0 510 */ 511 U_STABLE int32_t U_EXPORT2 512 unum_parse( const UNumberFormat* fmt, 513 const UChar* text, 514 int32_t textLength, 515 int32_t *parsePos /* 0 = start */, 516 UErrorCode *status); 517 518 /** 519 * Parse a string into an int64 using a UNumberFormat. 520 * The string will be parsed according to the UNumberFormat's locale. 521 * @param fmt The formatter to use. 522 * @param text The text to parse. 523 * @param textLength The length of text, or -1 if null-terminated. 524 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 525 * to begin parsing. If not 0, on output the offset at which parsing ended. 526 * @param status A pointer to an UErrorCode to receive any errors 527 * @return The value of the parsed integer 528 * @see unum_parse 529 * @see unum_parseDouble 530 * @see unum_format 531 * @see unum_formatInt64 532 * @see unum_formatDouble 533 * @stable ICU 2.8 534 */ 535 U_STABLE int64_t U_EXPORT2 536 unum_parseInt64(const UNumberFormat* fmt, 537 const UChar* text, 538 int32_t textLength, 539 int32_t *parsePos /* 0 = start */, 540 UErrorCode *status); 541 542 /** 543 * Parse a string into a double using a UNumberFormat. 544 * The string will be parsed according to the UNumberFormat's locale. 545 * @param fmt The formatter to use. 546 * @param text The text to parse. 547 * @param textLength The length of text, or -1 if null-terminated. 548 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 549 * to begin parsing. If not 0, on output the offset at which parsing ended. 550 * @param status A pointer to an UErrorCode to receive any errors 551 * @return The value of the parsed double 552 * @see unum_parse 553 * @see unum_parseInt64 554 * @see unum_format 555 * @see unum_formatInt64 556 * @see unum_formatDouble 557 * @stable ICU 2.0 558 */ 559 U_STABLE double U_EXPORT2 560 unum_parseDouble( const UNumberFormat* fmt, 561 const UChar* text, 562 int32_t textLength, 563 int32_t *parsePos /* 0 = start */, 564 UErrorCode *status); 565 566 567 /** 568 * Parse a number from a string into an unformatted numeric string using a UNumberFormat. 569 * The input string will be parsed according to the UNumberFormat's locale. 570 * The syntax of the output is a "numeric string" 571 * as defined in the Decimal Arithmetic Specification, available at 572 * http://speleotrove.com/decimal 573 * @param fmt The formatter to use. 574 * @param text The text to parse. 575 * @param textLength The length of text, or -1 if null-terminated. 576 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 577 * to begin parsing. If not 0, on output the offset at which parsing ended. 578 * @param outBuf A (char *) buffer to receive the parsed number as a string. The output string 579 * will be nul-terminated if there is sufficient space. 580 * @param outBufLength The size of the output buffer. May be zero, in which case 581 * the outBuf pointer may be NULL, and the function will return the 582 * size of the output string. 583 * @param status A pointer to an UErrorCode to receive any errors 584 * @return the length of the output string, not including any terminating nul. 585 * @see unum_parse 586 * @see unum_parseInt64 587 * @see unum_format 588 * @see unum_formatInt64 589 * @see unum_formatDouble 590 * @stable ICU 4.4 591 */ 592 U_STABLE int32_t U_EXPORT2 593 unum_parseDecimal(const UNumberFormat* fmt, 594 const UChar* text, 595 int32_t textLength, 596 int32_t *parsePos /* 0 = start */, 597 char *outBuf, 598 int32_t outBufLength, 599 UErrorCode *status); 600 601 /** 602 * Parse a string into a double and a currency using a UNumberFormat. 603 * The string will be parsed according to the UNumberFormat's locale. 604 * @param fmt the formatter to use 605 * @param text the text to parse 606 * @param textLength the length of text, or -1 if null-terminated 607 * @param parsePos a pointer to an offset index into text at which to 608 * begin parsing. On output, *parsePos will point after the last 609 * parsed character. This parameter may be 0, in which case parsing 610 * begins at offset 0. 611 * @param currency a pointer to the buffer to receive the parsed null- 612 * terminated currency. This buffer must have a capacity of at least 613 * 4 UChars. 614 * @param status a pointer to an input-output UErrorCode 615 * @return the parsed double 616 * @see unum_parseDouble 617 * @see unum_formatDoubleCurrency 618 * @stable ICU 3.0 619 */ 620 U_STABLE double U_EXPORT2 621 unum_parseDoubleCurrency(const UNumberFormat* fmt, 622 const UChar* text, 623 int32_t textLength, 624 int32_t* parsePos, /* 0 = start */ 625 UChar* currency, 626 UErrorCode* status); 627 628 /** 629 * Set the pattern used by a UNumberFormat. This can only be used 630 * on a DecimalFormat, other formats return U_ILLEGAL_ARGUMENT_ERROR 631 * in the status. 632 * @param format The formatter to set. 633 * @param localized TRUE if the pattern is localized, FALSE otherwise. 634 * @param pattern The new pattern 635 * @param patternLength The length of pattern, or -1 if null-terminated. 636 * @param parseError A pointer to UParseError to recieve information 637 * about errors occurred during parsing, or NULL if no parse error 638 * information is desired. 639 * @param status A pointer to an input-output UErrorCode. 640 * @see unum_toPattern 641 * @see DecimalFormat 642 * @stable ICU 2.0 643 */ 644 U_STABLE void U_EXPORT2 645 unum_applyPattern( UNumberFormat *format, 646 UBool localized, 647 const UChar *pattern, 648 int32_t patternLength, 649 UParseError *parseError, 650 UErrorCode *status 651 ); 652 653 /** 654 * Get a locale for which decimal formatting patterns are available. 655 * A UNumberFormat in a locale returned by this function will perform the correct 656 * formatting and parsing for the locale. The results of this call are not 657 * valid for rule-based number formats. 658 * @param localeIndex The index of the desired locale. 659 * @return A locale for which number formatting patterns are available, or 0 if none. 660 * @see unum_countAvailable 661 * @stable ICU 2.0 662 */ 663 U_STABLE const char* U_EXPORT2 664 unum_getAvailable(int32_t localeIndex); 665 666 /** 667 * Determine how many locales have decimal formatting patterns available. The 668 * results of this call are not valid for rule-based number formats. 669 * This function is useful for determining the loop ending condition for 670 * calls to {@link #unum_getAvailable }. 671 * @return The number of locales for which decimal formatting patterns are available. 672 * @see unum_getAvailable 673 * @stable ICU 2.0 674 */ 675 U_STABLE int32_t U_EXPORT2 676 unum_countAvailable(void); 677 678 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */ 679 typedef enum UNumberFormatAttribute { 680 /** Parse integers only */ 681 UNUM_PARSE_INT_ONLY, 682 /** Use grouping separator */ 683 UNUM_GROUPING_USED, 684 /** Always show decimal point */ 685 UNUM_DECIMAL_ALWAYS_SHOWN, 686 /** Maximum integer digits */ 687 UNUM_MAX_INTEGER_DIGITS, 688 /** Minimum integer digits */ 689 UNUM_MIN_INTEGER_DIGITS, 690 /** Integer digits */ 691 UNUM_INTEGER_DIGITS, 692 /** Maximum fraction digits */ 693 UNUM_MAX_FRACTION_DIGITS, 694 /** Minimum fraction digits */ 695 UNUM_MIN_FRACTION_DIGITS, 696 /** Fraction digits */ 697 UNUM_FRACTION_DIGITS, 698 /** Multiplier */ 699 UNUM_MULTIPLIER, 700 /** Grouping size */ 701 UNUM_GROUPING_SIZE, 702 /** Rounding Mode */ 703 UNUM_ROUNDING_MODE, 704 /** Rounding increment */ 705 UNUM_ROUNDING_INCREMENT, 706 /** The width to which the output of <code>format()</code> is padded. */ 707 UNUM_FORMAT_WIDTH, 708 /** The position at which padding will take place. */ 709 UNUM_PADDING_POSITION, 710 /** Secondary grouping size */ 711 UNUM_SECONDARY_GROUPING_SIZE, 712 /** Use significant digits 713 * @stable ICU 3.0 */ 714 UNUM_SIGNIFICANT_DIGITS_USED, 715 /** Minimum significant digits 716 * @stable ICU 3.0 */ 717 UNUM_MIN_SIGNIFICANT_DIGITS, 718 /** Maximum significant digits 719 * @stable ICU 3.0 */ 720 UNUM_MAX_SIGNIFICANT_DIGITS, 721 /** Lenient parse mode used by rule-based formats. 722 * @stable ICU 3.0 723 */ 724 UNUM_LENIENT_PARSE 725 } UNumberFormatAttribute; 726 727 /** 728 * Get a numeric attribute associated with a UNumberFormat. 729 * An example of a numeric attribute is the number of integer digits a formatter will produce. 730 * @param fmt The formatter to query. 731 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 732 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 733 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 734 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE. 735 * @return The value of attr. 736 * @see unum_setAttribute 737 * @see unum_getDoubleAttribute 738 * @see unum_setDoubleAttribute 739 * @see unum_getTextAttribute 740 * @see unum_setTextAttribute 741 * @stable ICU 2.0 742 */ 743 U_STABLE int32_t U_EXPORT2 744 unum_getAttribute(const UNumberFormat* fmt, 745 UNumberFormatAttribute attr); 746 747 /** 748 * Set a numeric attribute associated with a UNumberFormat. 749 * An example of a numeric attribute is the number of integer digits a formatter will produce. If the 750 * formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand 751 * the lenient-parse attribute. 752 * @param fmt The formatter to set. 753 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 754 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 755 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 756 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE, 757 * or UNUM_LENIENT_PARSE. 758 * @param newValue The new value of attr. 759 * @see unum_getAttribute 760 * @see unum_getDoubleAttribute 761 * @see unum_setDoubleAttribute 762 * @see unum_getTextAttribute 763 * @see unum_setTextAttribute 764 * @stable ICU 2.0 765 */ 766 U_STABLE void U_EXPORT2 767 unum_setAttribute( UNumberFormat* fmt, 768 UNumberFormatAttribute attr, 769 int32_t newValue); 770 771 772 /** 773 * Get a numeric attribute associated with a UNumberFormat. 774 * An example of a numeric attribute is the number of integer digits a formatter will produce. 775 * If the formatter does not understand the attribute, -1 is returned. 776 * @param fmt The formatter to query. 777 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT. 778 * @return The value of attr. 779 * @see unum_getAttribute 780 * @see unum_setAttribute 781 * @see unum_setDoubleAttribute 782 * @see unum_getTextAttribute 783 * @see unum_setTextAttribute 784 * @stable ICU 2.0 785 */ 786 U_STABLE double U_EXPORT2 787 unum_getDoubleAttribute(const UNumberFormat* fmt, 788 UNumberFormatAttribute attr); 789 790 /** 791 * Set a numeric attribute associated with a UNumberFormat. 792 * An example of a numeric attribute is the number of integer digits a formatter will produce. 793 * If the formatter does not understand the attribute, this call is ignored. 794 * @param fmt The formatter to set. 795 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT. 796 * @param newValue The new value of attr. 797 * @see unum_getAttribute 798 * @see unum_setAttribute 799 * @see unum_getDoubleAttribute 800 * @see unum_getTextAttribute 801 * @see unum_setTextAttribute 802 * @stable ICU 2.0 803 */ 804 U_STABLE void U_EXPORT2 805 unum_setDoubleAttribute( UNumberFormat* fmt, 806 UNumberFormatAttribute attr, 807 double newValue); 808 809 /** The possible UNumberFormat text attributes @stable ICU 2.0*/ 810 typedef enum UNumberFormatTextAttribute { 811 /** Positive prefix */ 812 UNUM_POSITIVE_PREFIX, 813 /** Positive suffix */ 814 UNUM_POSITIVE_SUFFIX, 815 /** Negative prefix */ 816 UNUM_NEGATIVE_PREFIX, 817 /** Negative suffix */ 818 UNUM_NEGATIVE_SUFFIX, 819 /** The character used to pad to the format width. */ 820 UNUM_PADDING_CHARACTER, 821 /** The ISO currency code */ 822 UNUM_CURRENCY_CODE, 823 /** 824 * The default rule set. This is only available with rule-based formatters. 825 * @stable ICU 3.0 826 */ 827 UNUM_DEFAULT_RULESET, 828 /** 829 * The public rule sets. This is only available with rule-based formatters. 830 * This is a read-only attribute. The public rulesets are returned as a 831 * single string, with each ruleset name delimited by ';' (semicolon). 832 * @stable ICU 3.0 833 */ 834 UNUM_PUBLIC_RULESETS 835 } UNumberFormatTextAttribute; 836 837 /** 838 * Get a text attribute associated with a UNumberFormat. 839 * An example of a text attribute is the suffix for positive numbers. If the formatter 840 * does not understand the attributre, U_UNSUPPORTED_ERROR is returned as the status. 841 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS. 842 * @param fmt The formatter to query. 843 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 844 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 845 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS. 846 * @param result A pointer to a buffer to receive the attribute. 847 * @param resultLength The maximum size of result. 848 * @param status A pointer to an UErrorCode to receive any errors 849 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 850 * @see unum_setTextAttribute 851 * @see unum_getAttribute 852 * @see unum_setAttribute 853 * @stable ICU 2.0 854 */ 855 U_STABLE int32_t U_EXPORT2 856 unum_getTextAttribute( const UNumberFormat* fmt, 857 UNumberFormatTextAttribute tag, 858 UChar* result, 859 int32_t resultLength, 860 UErrorCode* status); 861 862 /** 863 * Set a text attribute associated with a UNumberFormat. 864 * An example of a text attribute is the suffix for positive numbers. Rule-based formatters 865 * only understand UNUM_DEFAULT_RULESET. 866 * @param fmt The formatter to set. 867 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 868 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 869 * or UNUM_DEFAULT_RULESET. 870 * @param newValue The new value of attr. 871 * @param newValueLength The length of newValue, or -1 if null-terminated. 872 * @param status A pointer to an UErrorCode to receive any errors 873 * @see unum_getTextAttribute 874 * @see unum_getAttribute 875 * @see unum_setAttribute 876 * @stable ICU 2.0 877 */ 878 U_STABLE void U_EXPORT2 879 unum_setTextAttribute( UNumberFormat* fmt, 880 UNumberFormatTextAttribute tag, 881 const UChar* newValue, 882 int32_t newValueLength, 883 UErrorCode *status); 884 885 /** 886 * Extract the pattern from a UNumberFormat. The pattern will follow 887 * the DecimalFormat pattern syntax. 888 * @param fmt The formatter to query. 889 * @param isPatternLocalized TRUE if the pattern should be localized, 890 * FALSE otherwise. This is ignored if the formatter is a rule-based 891 * formatter. 892 * @param result A pointer to a buffer to receive the pattern. 893 * @param resultLength The maximum size of result. 894 * @param status A pointer to an input-output UErrorCode. 895 * @return The total buffer size needed; if greater than resultLength, 896 * the output was truncated. 897 * @see unum_applyPattern 898 * @see DecimalFormat 899 * @stable ICU 2.0 900 */ 901 U_STABLE int32_t U_EXPORT2 902 unum_toPattern( const UNumberFormat* fmt, 903 UBool isPatternLocalized, 904 UChar* result, 905 int32_t resultLength, 906 UErrorCode* status); 907 908 909 /** 910 * Constants for specifying a number format symbol. 911 * @stable ICU 2.0 912 */ 913 typedef enum UNumberFormatSymbol { 914 /** The decimal separator */ 915 UNUM_DECIMAL_SEPARATOR_SYMBOL = 0, 916 /** The grouping separator */ 917 UNUM_GROUPING_SEPARATOR_SYMBOL = 1, 918 /** The pattern separator */ 919 UNUM_PATTERN_SEPARATOR_SYMBOL = 2, 920 /** The percent sign */ 921 UNUM_PERCENT_SYMBOL = 3, 922 /** Zero*/ 923 UNUM_ZERO_DIGIT_SYMBOL = 4, 924 /** Character representing a digit in the pattern */ 925 UNUM_DIGIT_SYMBOL = 5, 926 /** The minus sign */ 927 UNUM_MINUS_SIGN_SYMBOL = 6, 928 /** The plus sign */ 929 UNUM_PLUS_SIGN_SYMBOL = 7, 930 /** The currency symbol */ 931 UNUM_CURRENCY_SYMBOL = 8, 932 /** The international currency symbol */ 933 UNUM_INTL_CURRENCY_SYMBOL = 9, 934 /** The monetary separator */ 935 UNUM_MONETARY_SEPARATOR_SYMBOL = 10, 936 /** The exponential symbol */ 937 UNUM_EXPONENTIAL_SYMBOL = 11, 938 /** Per mill symbol */ 939 UNUM_PERMILL_SYMBOL = 12, 940 /** Escape padding character */ 941 UNUM_PAD_ESCAPE_SYMBOL = 13, 942 /** Infinity symbol */ 943 UNUM_INFINITY_SYMBOL = 14, 944 /** Nan symbol */ 945 UNUM_NAN_SYMBOL = 15, 946 /** Significant digit symbol 947 * @stable ICU 3.0 */ 948 UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16, 949 /** The monetary grouping separator 950 * @stable ICU 3.6 951 */ 952 UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17, 953 /** One 954 * @draft ICU 4.6 955 */ 956 UNUM_ONE_DIGIT_SYMBOL = 18, 957 /** Two 958 * @draft ICU 4.6 959 */ 960 UNUM_TWO_DIGIT_SYMBOL = 19, 961 /** Three 962 * @draft ICU 4.6 963 */ 964 UNUM_THREE_DIGIT_SYMBOL = 20, 965 /** Four 966 * @draft ICU 4.6 967 */ 968 UNUM_FOUR_DIGIT_SYMBOL = 21, 969 /** Five 970 * @draft ICU 4.6 971 */ 972 UNUM_FIVE_DIGIT_SYMBOL = 22, 973 /** Six 974 * @draft ICU 4.6 975 */ 976 UNUM_SIX_DIGIT_SYMBOL = 23, 977 /** Seven 978 * @draft ICU 4.6 979 */ 980 UNUM_SEVEN_DIGIT_SYMBOL = 24, 981 /** Eight 982 * @draft ICU 4.6 983 */ 984 UNUM_EIGHT_DIGIT_SYMBOL = 25, 985 /** Nine 986 * @draft ICU 4.6 987 */ 988 UNUM_NINE_DIGIT_SYMBOL = 26, 989 /** count symbol constants */ 990 UNUM_FORMAT_SYMBOL_COUNT = 27 991 } UNumberFormatSymbol; 992 993 /** 994 * Get a symbol associated with a UNumberFormat. 995 * A UNumberFormat uses symbols to represent the special locale-dependent 996 * characters in a number, for example the percent sign. This API is not 997 * supported for rule-based formatters. 998 * @param fmt The formatter to query. 999 * @param symbol The UNumberFormatSymbol constant for the symbol to get 1000 * @param buffer The string buffer that will receive the symbol string; 1001 * if it is NULL, then only the length of the symbol is returned 1002 * @param size The size of the string buffer 1003 * @param status A pointer to an UErrorCode to receive any errors 1004 * @return The length of the symbol; the buffer is not modified if 1005 * <code>length>=size</code> 1006 * @see unum_setSymbol 1007 * @stable ICU 2.0 1008 */ 1009 U_STABLE int32_t U_EXPORT2 1010 unum_getSymbol(const UNumberFormat *fmt, 1011 UNumberFormatSymbol symbol, 1012 UChar *buffer, 1013 int32_t size, 1014 UErrorCode *status); 1015 1016 /** 1017 * Set a symbol associated with a UNumberFormat. 1018 * A UNumberFormat uses symbols to represent the special locale-dependent 1019 * characters in a number, for example the percent sign. This API is not 1020 * supported for rule-based formatters. 1021 * @param fmt The formatter to set. 1022 * @param symbol The UNumberFormatSymbol constant for the symbol to set 1023 * @param value The string to set the symbol to 1024 * @param length The length of the string, or -1 for a zero-terminated string 1025 * @param status A pointer to an UErrorCode to receive any errors. 1026 * @see unum_getSymbol 1027 * @stable ICU 2.0 1028 */ 1029 U_STABLE void U_EXPORT2 1030 unum_setSymbol(UNumberFormat *fmt, 1031 UNumberFormatSymbol symbol, 1032 const UChar *value, 1033 int32_t length, 1034 UErrorCode *status); 1035 1036 1037 /** 1038 * Get the locale for this number format object. 1039 * You can choose between valid and actual locale. 1040 * @param fmt The formatter to get the locale from 1041 * @param type type of the locale we're looking for (valid or actual) 1042 * @param status error code for the operation 1043 * @return the locale name 1044 * @stable ICU 2.8 1045 */ 1046 U_STABLE const char* U_EXPORT2 1047 unum_getLocaleByType(const UNumberFormat *fmt, 1048 ULocDataLocaleType type, 1049 UErrorCode* status); 1050 1051 #endif /* #if !UCONFIG_NO_FORMATTING */ 1052 1053 #endif 1054