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