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