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