1 /* 2 ******************************************************************************* 3 * Copyright (C) 1997-2012, 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_getAttributes() and unum_setAttributes(), 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 * @stable 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 * @stable ICU 4.8 195 */ 196 UNUM_CURRENCY_PLURAL, 197 /** 198 * One more than the highest number format style constant. 199 * @stable 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 224 * @stable, ICU 3.8 225 */ 226 UNUM_ROUND_HALFEVEN, 227 #ifndef U_HIDE_DEPRECATED_API 228 /** 229 * Half-even rounding, misspelled name 230 * @deprecated, ICU 3.8 231 */ 232 UNUM_FOUND_HALFEVEN = UNUM_ROUND_HALFEVEN, 233 #endif /* U_HIDE_DEPRECATED_API */ 234 UNUM_ROUND_HALFDOWN, 235 UNUM_ROUND_HALFUP, 236 /** 237 * ROUND_UNNECESSARY reports an error if formatted result is not exact. 238 * @stable ICU 4.8 239 */ 240 UNUM_ROUND_UNNECESSARY 241 } UNumberFormatRoundingMode; 242 243 /** The possible number format pad positions. 244 * @stable ICU 2.0 245 */ 246 typedef enum UNumberFormatPadPosition { 247 UNUM_PAD_BEFORE_PREFIX, 248 UNUM_PAD_AFTER_PREFIX, 249 UNUM_PAD_BEFORE_SUFFIX, 250 UNUM_PAD_AFTER_SUFFIX 251 } UNumberFormatPadPosition; 252 253 /** 254 * Constants for specifying currency spacing 255 * @stable ICU 4.8 256 */ 257 enum UCurrencySpacing { 258 /** @stable ICU 4.8 */ 259 UNUM_CURRENCY_MATCH, 260 /** @stable ICU 4.8 */ 261 UNUM_CURRENCY_SURROUNDING_MATCH, 262 /** @stable ICU 4.8 */ 263 UNUM_CURRENCY_INSERT, 264 /** @stable ICU 4.8 */ 265 UNUM_CURRENCY_SPACING_COUNT 266 }; 267 typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */ 268 269 270 /** 271 * FieldPosition and UFieldPosition selectors for format fields 272 * defined by NumberFormat and UNumberFormat. 273 * @stable ICU 49 274 */ 275 typedef enum UNumberFormatFields { 276 /** @stable ICU 49 */ 277 UNUM_INTEGER_FIELD, 278 /** @stable ICU 49 */ 279 UNUM_FRACTION_FIELD, 280 /** @stable ICU 49 */ 281 UNUM_DECIMAL_SEPARATOR_FIELD, 282 /** @stable ICU 49 */ 283 UNUM_EXPONENT_SYMBOL_FIELD, 284 /** @stable ICU 49 */ 285 UNUM_EXPONENT_SIGN_FIELD, 286 /** @stable ICU 49 */ 287 UNUM_EXPONENT_FIELD, 288 /** @stable ICU 49 */ 289 UNUM_GROUPING_SEPARATOR_FIELD, 290 /** @stable ICU 49 */ 291 UNUM_CURRENCY_FIELD, 292 /** @stable ICU 49 */ 293 UNUM_PERCENT_FIELD, 294 /** @stable ICU 49 */ 295 UNUM_PERMILL_FIELD, 296 /** @stable ICU 49 */ 297 UNUM_SIGN_FIELD, 298 /** @stable ICU 49 */ 299 UNUM_FIELD_COUNT 300 } UNumberFormatFields; 301 302 303 /** 304 * Create and return a new UNumberFormat for formatting and parsing 305 * numbers. A UNumberFormat may be used to format numbers by calling 306 * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }. 307 * The caller must call {@link #unum_close } when done to release resources 308 * used by this object. 309 * @param style The type of number format to open: one of 310 * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT, 311 * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT. 312 * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the 313 * number format is opened using the given pattern, which must conform 314 * to the syntax described in DecimalFormat or RuleBasedNumberFormat, 315 * respectively. 316 * @param pattern A pattern specifying the format to use. 317 * This parameter is ignored unless the style is 318 * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED. 319 * @param patternLength The number of characters in the pattern, or -1 320 * if null-terminated. This parameter is ignored unless the style is 321 * UNUM_PATTERN. 322 * @param locale A locale identifier to use to determine formatting 323 * and parsing conventions, or NULL to use the default locale. 324 * @param parseErr A pointer to a UParseError struct to receive the 325 * details of any parsing errors, or NULL if no parsing error details 326 * are desired. 327 * @param status A pointer to an input-output UErrorCode. 328 * @return A pointer to a newly created UNumberFormat, or NULL if an 329 * error occurred. 330 * @see unum_close 331 * @see DecimalFormat 332 * @stable ICU 2.0 333 */ 334 U_STABLE UNumberFormat* U_EXPORT2 335 unum_open( UNumberFormatStyle style, 336 const UChar* pattern, 337 int32_t patternLength, 338 const char* locale, 339 UParseError* parseErr, 340 UErrorCode* status); 341 342 343 /** 344 * Close a UNumberFormat. 345 * Once closed, a UNumberFormat may no longer be used. 346 * @param fmt The formatter to close. 347 * @stable ICU 2.0 348 */ 349 U_STABLE void U_EXPORT2 350 unum_close(UNumberFormat* fmt); 351 352 #if U_SHOW_CPLUSPLUS_API 353 354 U_NAMESPACE_BEGIN 355 356 /** 357 * \class LocalUNumberFormatPointer 358 * "Smart pointer" class, closes a UNumberFormat via unum_close(). 359 * For most methods see the LocalPointerBase base class. 360 * 361 * @see LocalPointerBase 362 * @see LocalPointer 363 * @stable ICU 4.4 364 */ 365 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close); 366 367 U_NAMESPACE_END 368 369 #endif 370 371 /** 372 * Open a copy of a UNumberFormat. 373 * This function performs a deep copy. 374 * @param fmt The format to copy 375 * @param status A pointer to an UErrorCode to receive any errors. 376 * @return A pointer to a UNumberFormat identical to fmt. 377 * @stable ICU 2.0 378 */ 379 U_STABLE UNumberFormat* U_EXPORT2 380 unum_clone(const UNumberFormat *fmt, 381 UErrorCode *status); 382 383 /** 384 * Format an integer using a UNumberFormat. 385 * The integer will be formatted according to the UNumberFormat's locale. 386 * @param fmt The formatter to use. 387 * @param number The number to format. 388 * @param result A pointer to a buffer to receive the formatted number. 389 * @param resultLength The maximum size of result. 390 * @param pos A pointer to a UFieldPosition. On input, position->field 391 * is read. On output, position->beginIndex and position->endIndex indicate 392 * the beginning and ending indices of field number position->field, if such 393 * a field exists. This parameter may be NULL, in which case no field 394 * @param status A pointer to an UErrorCode to receive any errors 395 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 396 * @see unum_formatInt64 397 * @see unum_formatDouble 398 * @see unum_parse 399 * @see unum_parseInt64 400 * @see unum_parseDouble 401 * @see UFieldPosition 402 * @stable ICU 2.0 403 */ 404 U_STABLE int32_t U_EXPORT2 405 unum_format( const UNumberFormat* fmt, 406 int32_t number, 407 UChar* result, 408 int32_t resultLength, 409 UFieldPosition *pos, 410 UErrorCode* status); 411 412 /** 413 * Format an int64 using a UNumberFormat. 414 * The int64 will be formatted according to the UNumberFormat's locale. 415 * @param fmt The formatter to use. 416 * @param number The number to format. 417 * @param result A pointer to a buffer to receive the formatted number. 418 * @param resultLength The maximum size of result. 419 * @param pos A pointer to a UFieldPosition. On input, position->field 420 * is read. On output, position->beginIndex and position->endIndex indicate 421 * the beginning and ending indices of field number position->field, if such 422 * a field exists. This parameter may be NULL, in which case no field 423 * @param status A pointer to an UErrorCode to receive any errors 424 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 425 * @see unum_format 426 * @see unum_formatDouble 427 * @see unum_parse 428 * @see unum_parseInt64 429 * @see unum_parseDouble 430 * @see UFieldPosition 431 * @stable ICU 2.0 432 */ 433 U_STABLE int32_t U_EXPORT2 434 unum_formatInt64(const UNumberFormat *fmt, 435 int64_t number, 436 UChar* result, 437 int32_t resultLength, 438 UFieldPosition *pos, 439 UErrorCode* status); 440 441 /** 442 * Format a double using a UNumberFormat. 443 * The double will be formatted according to the UNumberFormat's locale. 444 * @param fmt The formatter to use. 445 * @param number The number to format. 446 * @param result A pointer to a buffer to receive the formatted number. 447 * @param resultLength The maximum size of result. 448 * @param pos A pointer to a UFieldPosition. On input, position->field 449 * is read. On output, position->beginIndex and position->endIndex indicate 450 * the beginning and ending indices of field number position->field, if such 451 * a field exists. This parameter may be NULL, in which case no field 452 * @param status A pointer to an UErrorCode to receive any errors 453 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 454 * @see unum_format 455 * @see unum_formatInt64 456 * @see unum_parse 457 * @see unum_parseInt64 458 * @see unum_parseDouble 459 * @see UFieldPosition 460 * @stable ICU 2.0 461 */ 462 U_STABLE int32_t U_EXPORT2 463 unum_formatDouble( const UNumberFormat* fmt, 464 double number, 465 UChar* result, 466 int32_t resultLength, 467 UFieldPosition *pos, /* 0 if ignore */ 468 UErrorCode* status); 469 470 /** 471 * Format a decimal number using a UNumberFormat. 472 * The number will be formatted according to the UNumberFormat's locale. 473 * The syntax of the input number is a "numeric string" 474 * as defined in the Decimal Arithmetic Specification, available at 475 * http://speleotrove.com/decimal 476 * @param fmt The formatter to use. 477 * @param number The number to format. 478 * @param length The length of the input number, or -1 if the input is nul-terminated. 479 * @param result A pointer to a buffer to receive the formatted number. 480 * @param resultLength The maximum size of result. 481 * @param pos A pointer to a UFieldPosition. On input, position->field 482 * is read. On output, position->beginIndex and position->endIndex indicate 483 * the beginning and ending indices of field number position->field, if such 484 * a field exists. This parameter may be NULL, in which case it is ignored. 485 * @param status A pointer to an UErrorCode to receive any errors 486 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 487 * @see unum_format 488 * @see unum_formatInt64 489 * @see unum_parse 490 * @see unum_parseInt64 491 * @see unum_parseDouble 492 * @see UFieldPosition 493 * @stable ICU 4.4 494 */ 495 U_STABLE int32_t U_EXPORT2 496 unum_formatDecimal( const UNumberFormat* fmt, 497 const char * number, 498 int32_t length, 499 UChar* result, 500 int32_t resultLength, 501 UFieldPosition *pos, /* 0 if ignore */ 502 UErrorCode* status); 503 504 /** 505 * Format a double currency amount using a UNumberFormat. 506 * The double will be formatted according to the UNumberFormat's locale. 507 * @param fmt the formatter to use 508 * @param number the number to format 509 * @param currency the 3-letter null-terminated ISO 4217 currency code 510 * @param result a pointer to the buffer to receive the formatted number 511 * @param resultLength the maximum number of UChars to write to result 512 * @param pos a pointer to a UFieldPosition. On input, 513 * position->field is read. On output, position->beginIndex and 514 * position->endIndex indicate the beginning and ending indices of 515 * field number position->field, if such a field exists. This 516 * parameter may be NULL, in which case it is ignored. 517 * @param status a pointer to an input-output UErrorCode 518 * @return the total buffer size needed; if greater than resultLength, 519 * the output was truncated. 520 * @see unum_formatDouble 521 * @see unum_parseDoubleCurrency 522 * @see UFieldPosition 523 * @stable ICU 3.0 524 */ 525 U_STABLE int32_t U_EXPORT2 526 unum_formatDoubleCurrency(const UNumberFormat* fmt, 527 double number, 528 UChar* currency, 529 UChar* result, 530 int32_t resultLength, 531 UFieldPosition* pos, /* ignored if 0 */ 532 UErrorCode* status); 533 534 /** 535 * Parse a string into an integer using a UNumberFormat. 536 * The string will be parsed according to the UNumberFormat's locale. 537 * @param fmt The formatter to use. 538 * @param text The text to parse. 539 * @param textLength The length of text, or -1 if null-terminated. 540 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 541 * to begin parsing. If not 0, on output the offset at which parsing ended. 542 * @param status A pointer to an UErrorCode to receive any errors 543 * @return The value of the parsed integer 544 * @see unum_parseInt64 545 * @see unum_parseDouble 546 * @see unum_format 547 * @see unum_formatInt64 548 * @see unum_formatDouble 549 * @stable ICU 2.0 550 */ 551 U_STABLE int32_t U_EXPORT2 552 unum_parse( const UNumberFormat* fmt, 553 const UChar* text, 554 int32_t textLength, 555 int32_t *parsePos /* 0 = start */, 556 UErrorCode *status); 557 558 /** 559 * Parse a string into an int64 using a UNumberFormat. 560 * The string will be parsed according to the UNumberFormat's locale. 561 * @param fmt The formatter to use. 562 * @param text The text to parse. 563 * @param textLength The length of text, or -1 if null-terminated. 564 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 565 * to begin parsing. If not 0, on output the offset at which parsing ended. 566 * @param status A pointer to an UErrorCode to receive any errors 567 * @return The value of the parsed integer 568 * @see unum_parse 569 * @see unum_parseDouble 570 * @see unum_format 571 * @see unum_formatInt64 572 * @see unum_formatDouble 573 * @stable ICU 2.8 574 */ 575 U_STABLE int64_t U_EXPORT2 576 unum_parseInt64(const UNumberFormat* fmt, 577 const UChar* text, 578 int32_t textLength, 579 int32_t *parsePos /* 0 = start */, 580 UErrorCode *status); 581 582 /** 583 * Parse a string into a double using a UNumberFormat. 584 * The string will be parsed according to the UNumberFormat's locale. 585 * @param fmt The formatter to use. 586 * @param text The text to parse. 587 * @param textLength The length of text, or -1 if null-terminated. 588 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 589 * to begin parsing. If not 0, on output the offset at which parsing ended. 590 * @param status A pointer to an UErrorCode to receive any errors 591 * @return The value of the parsed double 592 * @see unum_parse 593 * @see unum_parseInt64 594 * @see unum_format 595 * @see unum_formatInt64 596 * @see unum_formatDouble 597 * @stable ICU 2.0 598 */ 599 U_STABLE double U_EXPORT2 600 unum_parseDouble( const UNumberFormat* fmt, 601 const UChar* text, 602 int32_t textLength, 603 int32_t *parsePos /* 0 = start */, 604 UErrorCode *status); 605 606 607 /** 608 * Parse a number from a string into an unformatted numeric string using a UNumberFormat. 609 * The input string will be parsed according to the UNumberFormat's locale. 610 * The syntax of the output is a "numeric string" 611 * as defined in the Decimal Arithmetic Specification, available at 612 * http://speleotrove.com/decimal 613 * @param fmt The formatter to use. 614 * @param text The text to parse. 615 * @param textLength The length of text, or -1 if null-terminated. 616 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 617 * to begin parsing. If not 0, on output the offset at which parsing ended. 618 * @param outBuf A (char *) buffer to receive the parsed number as a string. The output string 619 * will be nul-terminated if there is sufficient space. 620 * @param outBufLength The size of the output buffer. May be zero, in which case 621 * the outBuf pointer may be NULL, and the function will return the 622 * size of the output string. 623 * @param status A pointer to an UErrorCode to receive any errors 624 * @return the length of the output string, not including any terminating nul. 625 * @see unum_parse 626 * @see unum_parseInt64 627 * @see unum_format 628 * @see unum_formatInt64 629 * @see unum_formatDouble 630 * @stable ICU 4.4 631 */ 632 U_STABLE int32_t U_EXPORT2 633 unum_parseDecimal(const UNumberFormat* fmt, 634 const UChar* text, 635 int32_t textLength, 636 int32_t *parsePos /* 0 = start */, 637 char *outBuf, 638 int32_t outBufLength, 639 UErrorCode *status); 640 641 /** 642 * Parse a string into a double and a currency using a UNumberFormat. 643 * The string will be parsed according to the UNumberFormat's locale. 644 * @param fmt the formatter to use 645 * @param text the text to parse 646 * @param textLength the length of text, or -1 if null-terminated 647 * @param parsePos a pointer to an offset index into text at which to 648 * begin parsing. On output, *parsePos will point after the last 649 * parsed character. This parameter may be 0, in which case parsing 650 * begins at offset 0. 651 * @param currency a pointer to the buffer to receive the parsed null- 652 * terminated currency. This buffer must have a capacity of at least 653 * 4 UChars. 654 * @param status a pointer to an input-output UErrorCode 655 * @return the parsed double 656 * @see unum_parseDouble 657 * @see unum_formatDoubleCurrency 658 * @stable ICU 3.0 659 */ 660 U_STABLE double U_EXPORT2 661 unum_parseDoubleCurrency(const UNumberFormat* fmt, 662 const UChar* text, 663 int32_t textLength, 664 int32_t* parsePos, /* 0 = start */ 665 UChar* currency, 666 UErrorCode* status); 667 668 /** 669 * Set the pattern used by a UNumberFormat. This can only be used 670 * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR 671 * in the status. 672 * @param format The formatter to set. 673 * @param localized TRUE if the pattern is localized, FALSE otherwise. 674 * @param pattern The new pattern 675 * @param patternLength The length of pattern, or -1 if null-terminated. 676 * @param parseError A pointer to UParseError to recieve information 677 * about errors occurred during parsing, or NULL if no parse error 678 * information is desired. 679 * @param status A pointer to an input-output UErrorCode. 680 * @see unum_toPattern 681 * @see DecimalFormat 682 * @stable ICU 2.0 683 */ 684 U_STABLE void U_EXPORT2 685 unum_applyPattern( UNumberFormat *format, 686 UBool localized, 687 const UChar *pattern, 688 int32_t patternLength, 689 UParseError *parseError, 690 UErrorCode *status 691 ); 692 693 /** 694 * Get a locale for which decimal formatting patterns are available. 695 * A UNumberFormat in a locale returned by this function will perform the correct 696 * formatting and parsing for the locale. The results of this call are not 697 * valid for rule-based number formats. 698 * @param localeIndex The index of the desired locale. 699 * @return A locale for which number formatting patterns are available, or 0 if none. 700 * @see unum_countAvailable 701 * @stable ICU 2.0 702 */ 703 U_STABLE const char* U_EXPORT2 704 unum_getAvailable(int32_t localeIndex); 705 706 /** 707 * Determine how many locales have decimal formatting patterns available. The 708 * results of this call are not valid for rule-based number formats. 709 * This function is useful for determining the loop ending condition for 710 * calls to {@link #unum_getAvailable }. 711 * @return The number of locales for which decimal formatting patterns are available. 712 * @see unum_getAvailable 713 * @stable ICU 2.0 714 */ 715 U_STABLE int32_t U_EXPORT2 716 unum_countAvailable(void); 717 718 #if UCONFIG_HAVE_PARSEALLINPUT 719 /** 720 * @internal 721 */ 722 typedef enum UNumberFormatAttributeValue { 723 /** @internal */ 724 UNUM_NO = 0, 725 /** @internal */ 726 UNUM_YES = 1, 727 /** @internal */ 728 UNUM_MAYBE = 2 729 } UNumberFormatAttributeValue; 730 #endif 731 732 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */ 733 typedef enum UNumberFormatAttribute { 734 /** Parse integers only */ 735 UNUM_PARSE_INT_ONLY, 736 /** Use grouping separator */ 737 UNUM_GROUPING_USED, 738 /** Always show decimal point */ 739 UNUM_DECIMAL_ALWAYS_SHOWN, 740 /** Maximum integer digits */ 741 UNUM_MAX_INTEGER_DIGITS, 742 /** Minimum integer digits */ 743 UNUM_MIN_INTEGER_DIGITS, 744 /** Integer digits */ 745 UNUM_INTEGER_DIGITS, 746 /** Maximum fraction digits */ 747 UNUM_MAX_FRACTION_DIGITS, 748 /** Minimum fraction digits */ 749 UNUM_MIN_FRACTION_DIGITS, 750 /** Fraction digits */ 751 UNUM_FRACTION_DIGITS, 752 /** Multiplier */ 753 UNUM_MULTIPLIER, 754 /** Grouping size */ 755 UNUM_GROUPING_SIZE, 756 /** Rounding Mode */ 757 UNUM_ROUNDING_MODE, 758 /** Rounding increment */ 759 UNUM_ROUNDING_INCREMENT, 760 /** The width to which the output of <code>format()</code> is padded. */ 761 UNUM_FORMAT_WIDTH, 762 /** The position at which padding will take place. */ 763 UNUM_PADDING_POSITION, 764 /** Secondary grouping size */ 765 UNUM_SECONDARY_GROUPING_SIZE, 766 /** Use significant digits 767 * @stable ICU 3.0 */ 768 UNUM_SIGNIFICANT_DIGITS_USED, 769 /** Minimum significant digits 770 * @stable ICU 3.0 */ 771 UNUM_MIN_SIGNIFICANT_DIGITS, 772 /** Maximum significant digits 773 * @stable ICU 3.0 */ 774 UNUM_MAX_SIGNIFICANT_DIGITS, 775 /** Lenient parse mode used by rule-based formats. 776 * @stable ICU 3.0 777 */ 778 UNUM_LENIENT_PARSE, 779 #if UCONFIG_HAVE_PARSEALLINPUT 780 /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic). 781 * This is an internal ICU API. Do not use. 782 * @internal 783 */ 784 UNUM_PARSE_ALL_INPUT, 785 #endif 786 787 /** Count of "regular" numeric attributes. 788 * @internal */ 789 UNUM_NUMERIC_ATTRIBUTE_COUNT, 790 791 /** One below the first bitfield-boolean item. 792 * All items after this one are stored in boolean form. 793 * @internal */ 794 UNUM_MAX_NONBOOLEAN_ATTRIBUTE = 0x0FFF, 795 796 /** If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating. 797 * For example, formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing. 798 * Default: 0 (not set) 799 * @draft ICU 50 800 */ 801 UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS, 802 /** 803 * 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. 804 * Has no effect on formatting. 805 * Default: 0 (unset) 806 * @draft ICU 50 807 */ 808 UNUM_PARSE_NO_EXPONENT, 809 810 /** Limit of boolean attributes. 811 * @internal */ 812 UNUM_LIMIT_BOOLEAN_ATTRIBUTE 813 } UNumberFormatAttribute; 814 815 /** 816 * Get a numeric attribute associated with a UNumberFormat. 817 * An example of a numeric attribute is the number of integer digits a formatter will produce. 818 * @param fmt The formatter to query. 819 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 820 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 821 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 822 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE. 823 * @return The value of attr. 824 * @see unum_setAttribute 825 * @see unum_getDoubleAttribute 826 * @see unum_setDoubleAttribute 827 * @see unum_getTextAttribute 828 * @see unum_setTextAttribute 829 * @stable ICU 2.0 830 */ 831 U_STABLE int32_t U_EXPORT2 832 unum_getAttribute(const UNumberFormat* fmt, 833 UNumberFormatAttribute attr); 834 835 /** 836 * Set a numeric attribute associated with a UNumberFormat. 837 * An example of a numeric attribute is the number of integer digits a formatter will produce. If the 838 * formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand 839 * the lenient-parse attribute. 840 * @param fmt The formatter to set. 841 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 842 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 843 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 844 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE, 845 * or UNUM_LENIENT_PARSE. 846 * @param newValue The new value of attr. 847 * @see unum_getAttribute 848 * @see unum_getDoubleAttribute 849 * @see unum_setDoubleAttribute 850 * @see unum_getTextAttribute 851 * @see unum_setTextAttribute 852 * @stable ICU 2.0 853 */ 854 U_STABLE void U_EXPORT2 855 unum_setAttribute( UNumberFormat* fmt, 856 UNumberFormatAttribute attr, 857 int32_t newValue); 858 859 860 /** 861 * Get a numeric attribute associated with a UNumberFormat. 862 * An example of a numeric attribute is the number of integer digits a formatter will produce. 863 * If the formatter does not understand the attribute, -1 is returned. 864 * @param fmt The formatter to query. 865 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT. 866 * @return The value of attr. 867 * @see unum_getAttribute 868 * @see unum_setAttribute 869 * @see unum_setDoubleAttribute 870 * @see unum_getTextAttribute 871 * @see unum_setTextAttribute 872 * @stable ICU 2.0 873 */ 874 U_STABLE double U_EXPORT2 875 unum_getDoubleAttribute(const UNumberFormat* fmt, 876 UNumberFormatAttribute attr); 877 878 /** 879 * Set a numeric attribute associated with a UNumberFormat. 880 * An example of a numeric attribute is the number of integer digits a formatter will produce. 881 * If the formatter does not understand the attribute, this call is ignored. 882 * @param fmt The formatter to set. 883 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT. 884 * @param newValue The new value of attr. 885 * @see unum_getAttribute 886 * @see unum_setAttribute 887 * @see unum_getDoubleAttribute 888 * @see unum_getTextAttribute 889 * @see unum_setTextAttribute 890 * @stable ICU 2.0 891 */ 892 U_STABLE void U_EXPORT2 893 unum_setDoubleAttribute( UNumberFormat* fmt, 894 UNumberFormatAttribute attr, 895 double newValue); 896 897 /** The possible UNumberFormat text attributes @stable ICU 2.0*/ 898 typedef enum UNumberFormatTextAttribute { 899 /** Positive prefix */ 900 UNUM_POSITIVE_PREFIX, 901 /** Positive suffix */ 902 UNUM_POSITIVE_SUFFIX, 903 /** Negative prefix */ 904 UNUM_NEGATIVE_PREFIX, 905 /** Negative suffix */ 906 UNUM_NEGATIVE_SUFFIX, 907 /** The character used to pad to the format width. */ 908 UNUM_PADDING_CHARACTER, 909 /** The ISO currency code */ 910 UNUM_CURRENCY_CODE, 911 /** 912 * The default rule set. This is only available with rule-based formatters. 913 * @stable ICU 3.0 914 */ 915 UNUM_DEFAULT_RULESET, 916 /** 917 * The public rule sets. This is only available with rule-based formatters. 918 * This is a read-only attribute. The public rulesets are returned as a 919 * single string, with each ruleset name delimited by ';' (semicolon). 920 * @stable ICU 3.0 921 */ 922 UNUM_PUBLIC_RULESETS 923 } UNumberFormatTextAttribute; 924 925 /** 926 * Get a text attribute associated with a UNumberFormat. 927 * An example of a text attribute is the suffix for positive numbers. If the formatter 928 * does not understand the attribute, U_UNSUPPORTED_ERROR is returned as the status. 929 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS. 930 * @param fmt The formatter to query. 931 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 932 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 933 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS. 934 * @param result A pointer to a buffer to receive the attribute. 935 * @param resultLength The maximum size of result. 936 * @param status A pointer to an UErrorCode to receive any errors 937 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 938 * @see unum_setTextAttribute 939 * @see unum_getAttribute 940 * @see unum_setAttribute 941 * @stable ICU 2.0 942 */ 943 U_STABLE int32_t U_EXPORT2 944 unum_getTextAttribute( const UNumberFormat* fmt, 945 UNumberFormatTextAttribute tag, 946 UChar* result, 947 int32_t resultLength, 948 UErrorCode* status); 949 950 /** 951 * Set a text attribute associated with a UNumberFormat. 952 * An example of a text attribute is the suffix for positive numbers. Rule-based formatters 953 * only understand UNUM_DEFAULT_RULESET. 954 * @param fmt The formatter to set. 955 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 956 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 957 * or UNUM_DEFAULT_RULESET. 958 * @param newValue The new value of attr. 959 * @param newValueLength The length of newValue, or -1 if null-terminated. 960 * @param status A pointer to an UErrorCode to receive any errors 961 * @see unum_getTextAttribute 962 * @see unum_getAttribute 963 * @see unum_setAttribute 964 * @stable ICU 2.0 965 */ 966 U_STABLE void U_EXPORT2 967 unum_setTextAttribute( UNumberFormat* fmt, 968 UNumberFormatTextAttribute tag, 969 const UChar* newValue, 970 int32_t newValueLength, 971 UErrorCode *status); 972 973 /** 974 * Extract the pattern from a UNumberFormat. The pattern will follow 975 * the DecimalFormat pattern syntax. 976 * @param fmt The formatter to query. 977 * @param isPatternLocalized TRUE if the pattern should be localized, 978 * FALSE otherwise. This is ignored if the formatter is a rule-based 979 * formatter. 980 * @param result A pointer to a buffer to receive the pattern. 981 * @param resultLength The maximum size of result. 982 * @param status A pointer to an input-output UErrorCode. 983 * @return The total buffer size needed; if greater than resultLength, 984 * the output was truncated. 985 * @see unum_applyPattern 986 * @see DecimalFormat 987 * @stable ICU 2.0 988 */ 989 U_STABLE int32_t U_EXPORT2 990 unum_toPattern( const UNumberFormat* fmt, 991 UBool isPatternLocalized, 992 UChar* result, 993 int32_t resultLength, 994 UErrorCode* status); 995 996 997 /** 998 * Constants for specifying a number format symbol. 999 * @stable ICU 2.0 1000 */ 1001 typedef enum UNumberFormatSymbol { 1002 /** The decimal separator */ 1003 UNUM_DECIMAL_SEPARATOR_SYMBOL = 0, 1004 /** The grouping separator */ 1005 UNUM_GROUPING_SEPARATOR_SYMBOL = 1, 1006 /** The pattern separator */ 1007 UNUM_PATTERN_SEPARATOR_SYMBOL = 2, 1008 /** The percent sign */ 1009 UNUM_PERCENT_SYMBOL = 3, 1010 /** Zero*/ 1011 UNUM_ZERO_DIGIT_SYMBOL = 4, 1012 /** Character representing a digit in the pattern */ 1013 UNUM_DIGIT_SYMBOL = 5, 1014 /** The minus sign */ 1015 UNUM_MINUS_SIGN_SYMBOL = 6, 1016 /** The plus sign */ 1017 UNUM_PLUS_SIGN_SYMBOL = 7, 1018 /** The currency symbol */ 1019 UNUM_CURRENCY_SYMBOL = 8, 1020 /** The international currency symbol */ 1021 UNUM_INTL_CURRENCY_SYMBOL = 9, 1022 /** The monetary separator */ 1023 UNUM_MONETARY_SEPARATOR_SYMBOL = 10, 1024 /** The exponential symbol */ 1025 UNUM_EXPONENTIAL_SYMBOL = 11, 1026 /** Per mill symbol */ 1027 UNUM_PERMILL_SYMBOL = 12, 1028 /** Escape padding character */ 1029 UNUM_PAD_ESCAPE_SYMBOL = 13, 1030 /** Infinity symbol */ 1031 UNUM_INFINITY_SYMBOL = 14, 1032 /** Nan symbol */ 1033 UNUM_NAN_SYMBOL = 15, 1034 /** Significant digit symbol 1035 * @stable ICU 3.0 */ 1036 UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16, 1037 /** The monetary grouping separator 1038 * @stable ICU 3.6 1039 */ 1040 UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17, 1041 /** One 1042 * @stable ICU 4.6 1043 */ 1044 UNUM_ONE_DIGIT_SYMBOL = 18, 1045 /** Two 1046 * @stable ICU 4.6 1047 */ 1048 UNUM_TWO_DIGIT_SYMBOL = 19, 1049 /** Three 1050 * @stable ICU 4.6 1051 */ 1052 UNUM_THREE_DIGIT_SYMBOL = 20, 1053 /** Four 1054 * @stable ICU 4.6 1055 */ 1056 UNUM_FOUR_DIGIT_SYMBOL = 21, 1057 /** Five 1058 * @stable ICU 4.6 1059 */ 1060 UNUM_FIVE_DIGIT_SYMBOL = 22, 1061 /** Six 1062 * @stable ICU 4.6 1063 */ 1064 UNUM_SIX_DIGIT_SYMBOL = 23, 1065 /** Seven 1066 * @stable ICU 4.6 1067 */ 1068 UNUM_SEVEN_DIGIT_SYMBOL = 24, 1069 /** Eight 1070 * @stable ICU 4.6 1071 */ 1072 UNUM_EIGHT_DIGIT_SYMBOL = 25, 1073 /** Nine 1074 * @stable ICU 4.6 1075 */ 1076 UNUM_NINE_DIGIT_SYMBOL = 26, 1077 /** count symbol constants */ 1078 UNUM_FORMAT_SYMBOL_COUNT = 27 1079 } UNumberFormatSymbol; 1080 1081 /** 1082 * Get a symbol associated with a UNumberFormat. 1083 * A UNumberFormat uses symbols to represent the special locale-dependent 1084 * characters in a number, for example the percent sign. This API is not 1085 * supported for rule-based formatters. 1086 * @param fmt The formatter to query. 1087 * @param symbol The UNumberFormatSymbol constant for the symbol to get 1088 * @param buffer The string buffer that will receive the symbol string; 1089 * if it is NULL, then only the length of the symbol is returned 1090 * @param size The size of the string buffer 1091 * @param status A pointer to an UErrorCode to receive any errors 1092 * @return The length of the symbol; the buffer is not modified if 1093 * <code>length>=size</code> 1094 * @see unum_setSymbol 1095 * @stable ICU 2.0 1096 */ 1097 U_STABLE int32_t U_EXPORT2 1098 unum_getSymbol(const UNumberFormat *fmt, 1099 UNumberFormatSymbol symbol, 1100 UChar *buffer, 1101 int32_t size, 1102 UErrorCode *status); 1103 1104 /** 1105 * Set a symbol associated with a UNumberFormat. 1106 * A UNumberFormat uses symbols to represent the special locale-dependent 1107 * characters in a number, for example the percent sign. This API is not 1108 * supported for rule-based formatters. 1109 * @param fmt The formatter to set. 1110 * @param symbol The UNumberFormatSymbol constant for the symbol to set 1111 * @param value The string to set the symbol to 1112 * @param length The length of the string, or -1 for a zero-terminated string 1113 * @param status A pointer to an UErrorCode to receive any errors. 1114 * @see unum_getSymbol 1115 * @stable ICU 2.0 1116 */ 1117 U_STABLE void U_EXPORT2 1118 unum_setSymbol(UNumberFormat *fmt, 1119 UNumberFormatSymbol symbol, 1120 const UChar *value, 1121 int32_t length, 1122 UErrorCode *status); 1123 1124 1125 /** 1126 * Get the locale for this number format object. 1127 * You can choose between valid and actual locale. 1128 * @param fmt The formatter to get the locale from 1129 * @param type type of the locale we're looking for (valid or actual) 1130 * @param status error code for the operation 1131 * @return the locale name 1132 * @stable ICU 2.8 1133 */ 1134 U_STABLE const char* U_EXPORT2 1135 unum_getLocaleByType(const UNumberFormat *fmt, 1136 ULocDataLocaleType type, 1137 UErrorCode* status); 1138 1139 #endif /* #if !UCONFIG_NO_FORMATTING */ 1140 1141 #endif 1142