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