1/* 2******************************************************************************* 3* Copyright (C) 1997-2010, International Business Machines Corporation and others. 4* All Rights Reserved. 5* Modification History: 6* 7* Date Name Description 8* 06/24/99 helena Integrated Alan's NF enhancements and Java2 bug fixes 9******************************************************************************* 10*/ 11 12#ifndef _UNUM 13#define _UNUM 14 15#include "unicode/utypes.h" 16 17#if !UCONFIG_NO_FORMATTING 18 19#include "unicode/localpointer.h" 20#include "unicode/uloc.h" 21#include "unicode/umisc.h" 22#include "unicode/parseerr.h" 23/** 24 * \file 25 * \brief C API: NumberFormat 26 * 27 * <h2> Number Format C API </h2> 28 * 29 * Number Format C API Provides functions for 30 * formatting and parsing a number. Also provides methods for 31 * determining which locales have number formats, and what their names 32 * are. 33 * <P> 34 * UNumberFormat helps you to format and parse numbers for any locale. 35 * Your code can be completely independent of the locale conventions 36 * for decimal points, thousands-separators, or even the particular 37 * decimal digits used, or whether the number format is even decimal. 38 * There are different number format styles like decimal, currency, 39 * percent and spellout. 40 * <P> 41 * To format a number for the current Locale, use one of the static 42 * factory methods: 43 * <pre> 44 * \code 45 * UChar myString[20]; 46 * double myNumber = 7.0; 47 * UErrorCode status = U_ZERO_ERROR; 48 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status); 49 * unum_formatDouble(nf, myNumber, myString, 20, NULL, &status); 50 * printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*) 51 * \endcode 52 * </pre> 53 * If you are formatting multiple numbers, it is more efficient to get 54 * the format and use it multiple times so that the system doesn't 55 * have to fetch the information about the local language and country 56 * conventions multiple times. 57 * <pre> 58 * \code 59 * uint32_t i, resultlength, reslenneeded; 60 * UErrorCode status = U_ZERO_ERROR; 61 * UFieldPosition pos; 62 * uint32_t a[] = { 123, 3333, -1234567 }; 63 * const uint32_t a_len = sizeof(a) / sizeof(a[0]); 64 * UNumberFormat* nf; 65 * UChar* result = NULL; 66 * 67 * nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status); 68 * for (i = 0; i < a_len; i++) { 69 * resultlength=0; 70 * reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status); 71 * result = NULL; 72 * if(status==U_BUFFER_OVERFLOW_ERROR){ 73 * status=U_ZERO_ERROR; 74 * resultlength=reslenneeded+1; 75 * result=(UChar*)malloc(sizeof(UChar) * resultlength); 76 * unum_format(nf, a[i], result, resultlength, &pos, &status); 77 * } 78 * printf( " Example 2: %s\n", austrdup(result)); 79 * free(result); 80 * } 81 * \endcode 82 * </pre> 83 * To format a number for a different Locale, specify it in the 84 * call to unum_open(). 85 * <pre> 86 * \code 87 * UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, "fr_FR", NULL, &success) 88 * \endcode 89 * </pre> 90 * You can use a NumberFormat API unum_parse() to parse. 91 * <pre> 92 * \code 93 * UErrorCode status = U_ZERO_ERROR; 94 * int32_t pos=0; 95 * int32_t num; 96 * num = unum_parse(nf, str, u_strlen(str), &pos, &status); 97 * \endcode 98 * </pre> 99 * Use UNUM_DECIMAL to get the normal number format for that country. 100 * There are other static options available. Use UNUM_CURRENCY 101 * to get the currency number format for that country. Use UNUM_PERCENT 102 * to get a format for displaying percentages. With this format, a 103 * fraction from 0.53 is displayed as 53%. 104 * <P> 105 * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat 106 * formatter. The pattern must conform to the syntax defined for those 107 * formatters. 108 * <P> 109 * You can also control the display of numbers with such function as 110 * unum_getAttribues() and unum_setAtributes(), which let you set the 111 * miminum fraction digits, grouping, etc. 112 * @see UNumberFormatAttributes for more details 113 * <P> 114 * You can also use forms of the parse and format methods with 115 * ParsePosition and UFieldPosition to allow you to: 116 * <ul type=round> 117 * <li>(a) progressively parse through pieces of a string. 118 * <li>(b) align the decimal point and other areas. 119 * </ul> 120 * <p> 121 * It is also possible to change or set the symbols used for a particular 122 * locale like the currency symbol, the grouping seperator , monetary seperator 123 * etc by making use of functions unum_setSymbols() and unum_getSymbols(). 124 */ 125 126/** A number formatter. 127 * For usage in C programs. 128 * @stable ICU 2.0 129 */ 130typedef void* UNumberFormat; 131 132/** The possible number format styles. 133 * @stable ICU 2.0 134 */ 135typedef enum UNumberFormatStyle { 136 /** 137 * Decimal format defined by pattern 138 * @stable ICU 3.0 139 */ 140 UNUM_PATTERN_DECIMAL=0, 141 /** Decimal format */ 142 UNUM_DECIMAL=1, 143 /** Currency format */ 144 UNUM_CURRENCY, 145 /** Percent format */ 146 UNUM_PERCENT, 147 /** Scientific format */ 148 UNUM_SCIENTIFIC, 149 /** Spellout rule-based format */ 150 UNUM_SPELLOUT, 151 /** 152 * Ordinal rule-based format 153 * @stable ICU 3.0 154 */ 155 UNUM_ORDINAL, 156 /** 157 * Duration rule-based format 158 * @stable ICU 3.0 159 */ 160 UNUM_DURATION, 161 /** 162 * Numbering system rule-based format 163 * @stable ICU 4.2 164 */ 165 UNUM_NUMBERING_SYSTEM, 166 /** 167 * Rule-based format defined by pattern 168 * @stable ICU 3.0 169 */ 170 UNUM_PATTERN_RULEBASED, 171 /** Default format */ 172 UNUM_DEFAULT = UNUM_DECIMAL, 173 /** (Alias for UNUM_PATTERN_DECIMAL) */ 174 UNUM_IGNORE = UNUM_PATTERN_DECIMAL 175} UNumberFormatStyle; 176 177/** The possible number format rounding modes. 178 * @stable ICU 2.0 179 */ 180typedef enum UNumberFormatRoundingMode { 181 UNUM_ROUND_CEILING, 182 UNUM_ROUND_FLOOR, 183 UNUM_ROUND_DOWN, 184 UNUM_ROUND_UP, 185 /** 186 * Half-even rounding, misspelled name 187 * @deprecated, ICU 3.8 188 */ 189 UNUM_FOUND_HALFEVEN, 190 UNUM_ROUND_HALFDOWN, 191 UNUM_ROUND_HALFUP, 192 /** 193 * Half-even rounding 194 * @stable, ICU 3.8 195 */ 196 UNUM_ROUND_HALFEVEN = UNUM_FOUND_HALFEVEN 197} UNumberFormatRoundingMode; 198 199/** The possible number format pad positions. 200 * @stable ICU 2.0 201 */ 202typedef enum UNumberFormatPadPosition { 203 UNUM_PAD_BEFORE_PREFIX, 204 UNUM_PAD_AFTER_PREFIX, 205 UNUM_PAD_BEFORE_SUFFIX, 206 UNUM_PAD_AFTER_SUFFIX 207} UNumberFormatPadPosition; 208 209/** 210 * Create and return a new UNumberFormat for formatting and parsing 211 * numbers. A UNumberFormat may be used to format numbers by calling 212 * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }. 213 * The caller must call {@link #unum_close } when done to release resources 214 * used by this object. 215 * @param style The type of number format to open: one of 216 * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT, 217 * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT. 218 * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the 219 * number format is opened using the given pattern, which must conform 220 * to the syntax described in DecimalFormat or RuleBasedNumberFormat, 221 * respectively. 222 * @param pattern A pattern specifying the format to use. 223 * This parameter is ignored unless the style is 224 * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED. 225 * @param patternLength The number of characters in the pattern, or -1 226 * if null-terminated. This parameter is ignored unless the style is 227 * UNUM_PATTERN. 228 * @param locale A locale identifier to use to determine formatting 229 * and parsing conventions, or NULL to use the default locale. 230 * @param parseErr A pointer to a UParseError struct to receive the 231 * details of any parsing errors, or NULL if no parsing error details 232 * are desired. 233 * @param status A pointer to an input-output UErrorCode. 234 * @return A pointer to a newly created UNumberFormat, or NULL if an 235 * error occurred. 236 * @see unum_close 237 * @see DecimalFormat 238 * @stable ICU 2.0 239 */ 240U_STABLE UNumberFormat* U_EXPORT2 241unum_open( UNumberFormatStyle style, 242 const UChar* pattern, 243 int32_t patternLength, 244 const char* locale, 245 UParseError* parseErr, 246 UErrorCode* status); 247 248 249/** 250* Close a UNumberFormat. 251* Once closed, a UNumberFormat may no longer be used. 252* @param fmt The formatter to close. 253* @stable ICU 2.0 254*/ 255U_STABLE void U_EXPORT2 256unum_close(UNumberFormat* fmt); 257 258#if U_SHOW_CPLUSPLUS_API 259 260U_NAMESPACE_BEGIN 261 262/** 263 * \class LocalUNumberFormatPointer 264 * "Smart pointer" class, closes a UNumberFormat via unum_close(). 265 * For most methods see the LocalPointerBase base class. 266 * 267 * @see LocalPointerBase 268 * @see LocalPointer 269 * @stable ICU 4.4 270 */ 271U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close); 272 273U_NAMESPACE_END 274 275#endif 276 277/** 278 * Open a copy of a UNumberFormat. 279 * This function performs a deep copy. 280 * @param fmt The format to copy 281 * @param status A pointer to an UErrorCode to receive any errors. 282 * @return A pointer to a UNumberFormat identical to fmt. 283 * @stable ICU 2.0 284 */ 285U_STABLE UNumberFormat* U_EXPORT2 286unum_clone(const UNumberFormat *fmt, 287 UErrorCode *status); 288 289/** 290* Format an integer using a UNumberFormat. 291* The integer will be formatted according to the UNumberFormat's locale. 292* @param fmt The formatter to use. 293* @param number The number to format. 294* @param result A pointer to a buffer to receive the formatted number. 295* @param resultLength The maximum size of result. 296* @param pos A pointer to a UFieldPosition. On input, position->field 297* is read. On output, position->beginIndex and position->endIndex indicate 298* the beginning and ending indices of field number position->field, if such 299* a field exists. This parameter may be NULL, in which case no field 300* @param status A pointer to an UErrorCode to receive any errors 301* @return The total buffer size needed; if greater than resultLength, the output was truncated. 302* @see unum_formatInt64 303* @see unum_formatDouble 304* @see unum_parse 305* @see unum_parseInt64 306* @see unum_parseDouble 307* @see UFieldPosition 308* @stable ICU 2.0 309*/ 310U_STABLE int32_t U_EXPORT2 311unum_format( const UNumberFormat* fmt, 312 int32_t number, 313 UChar* result, 314 int32_t resultLength, 315 UFieldPosition *pos, 316 UErrorCode* status); 317 318/** 319* Format an int64 using a UNumberFormat. 320* The int64 will be formatted according to the UNumberFormat's locale. 321* @param fmt The formatter to use. 322* @param number The number to format. 323* @param result A pointer to a buffer to receive the formatted number. 324* @param resultLength The maximum size of result. 325* @param pos A pointer to a UFieldPosition. On input, position->field 326* is read. On output, position->beginIndex and position->endIndex indicate 327* the beginning and ending indices of field number position->field, if such 328* a field exists. This parameter may be NULL, in which case no field 329* @param status A pointer to an UErrorCode to receive any errors 330* @return The total buffer size needed; if greater than resultLength, the output was truncated. 331* @see unum_format 332* @see unum_formatDouble 333* @see unum_parse 334* @see unum_parseInt64 335* @see unum_parseDouble 336* @see UFieldPosition 337* @stable ICU 2.0 338*/ 339U_STABLE int32_t U_EXPORT2 340unum_formatInt64(const UNumberFormat *fmt, 341 int64_t number, 342 UChar* result, 343 int32_t resultLength, 344 UFieldPosition *pos, 345 UErrorCode* status); 346 347/** 348* Format a double using a UNumberFormat. 349* The double will be formatted according to the UNumberFormat's locale. 350* @param fmt The formatter to use. 351* @param number The number to format. 352* @param result A pointer to a buffer to receive the formatted number. 353* @param resultLength The maximum size of result. 354* @param pos A pointer to a UFieldPosition. On input, position->field 355* is read. On output, position->beginIndex and position->endIndex indicate 356* the beginning and ending indices of field number position->field, if such 357* a field exists. This parameter may be NULL, in which case no field 358* @param status A pointer to an UErrorCode to receive any errors 359* @return The total buffer size needed; if greater than resultLength, the output was truncated. 360* @see unum_format 361* @see unum_formatInt64 362* @see unum_parse 363* @see unum_parseInt64 364* @see unum_parseDouble 365* @see UFieldPosition 366* @stable ICU 2.0 367*/ 368U_STABLE int32_t U_EXPORT2 369unum_formatDouble( const UNumberFormat* fmt, 370 double number, 371 UChar* result, 372 int32_t resultLength, 373 UFieldPosition *pos, /* 0 if ignore */ 374 UErrorCode* status); 375 376/** 377* Format a decimal number using a UNumberFormat. 378* The number will be formatted according to the UNumberFormat's locale. 379* The syntax of the input number is a "numeric string" 380* as defined in the Decimal Arithmetic Specification, available at 381* http://speleotrove.com/decimal 382* @param fmt The formatter to use. 383* @param number The number to format. 384* @param length The length of the input number, or -1 if the input is nul-terminated. 385* @param result A pointer to a buffer to receive the formatted number. 386* @param resultLength The maximum size of result. 387* @param pos A pointer to a UFieldPosition. On input, position->field 388* is read. On output, position->beginIndex and position->endIndex indicate 389* the beginning and ending indices of field number position->field, if such 390* a field exists. This parameter may be NULL, in which case it is ignored. 391* @param status A pointer to an UErrorCode to receive any errors 392* @return The total buffer size needed; if greater than resultLength, the output was truncated. 393* @see unum_format 394* @see unum_formatInt64 395* @see unum_parse 396* @see unum_parseInt64 397* @see unum_parseDouble 398* @see UFieldPosition 399* @stable ICU 4.4 400*/ 401U_STABLE int32_t U_EXPORT2 402unum_formatDecimal( const UNumberFormat* fmt, 403 const char * number, 404 int32_t length, 405 UChar* result, 406 int32_t resultLength, 407 UFieldPosition *pos, /* 0 if ignore */ 408 UErrorCode* status); 409 410/** 411 * Format a double currency amount using a UNumberFormat. 412 * The double will be formatted according to the UNumberFormat's locale. 413 * @param fmt the formatter to use 414 * @param number the number to format 415 * @param currency the 3-letter null-terminated ISO 4217 currency code 416 * @param result a pointer to the buffer to receive the formatted number 417 * @param resultLength the maximum number of UChars to write to result 418 * @param pos a pointer to a UFieldPosition. On input, 419 * position->field is read. On output, position->beginIndex and 420 * position->endIndex indicate the beginning and ending indices of 421 * field number position->field, if such a field exists. This 422 * parameter may be NULL, in which case it is ignored. 423 * @param status a pointer to an input-output UErrorCode 424 * @return the total buffer size needed; if greater than resultLength, 425 * the output was truncated. 426 * @see unum_formatDouble 427 * @see unum_parseDoubleCurrency 428 * @see UFieldPosition 429 * @stable ICU 3.0 430 */ 431U_STABLE int32_t U_EXPORT2 432unum_formatDoubleCurrency(const UNumberFormat* fmt, 433 double number, 434 UChar* currency, 435 UChar* result, 436 int32_t resultLength, 437 UFieldPosition* pos, /* ignored if 0 */ 438 UErrorCode* status); 439 440/** 441* Parse a string into an integer using a UNumberFormat. 442* The string will be parsed according to the UNumberFormat's locale. 443* @param fmt The formatter to use. 444* @param text The text to parse. 445* @param textLength The length of text, or -1 if null-terminated. 446* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 447* to begin parsing. If not 0, on output the offset at which parsing ended. 448* @param status A pointer to an UErrorCode to receive any errors 449* @return The value of the parsed integer 450* @see unum_parseInt64 451* @see unum_parseDouble 452* @see unum_format 453* @see unum_formatInt64 454* @see unum_formatDouble 455* @stable ICU 2.0 456*/ 457U_STABLE int32_t U_EXPORT2 458unum_parse( const UNumberFormat* fmt, 459 const UChar* text, 460 int32_t textLength, 461 int32_t *parsePos /* 0 = start */, 462 UErrorCode *status); 463 464/** 465* Parse a string into an int64 using a UNumberFormat. 466* The string will be parsed according to the UNumberFormat's locale. 467* @param fmt The formatter to use. 468* @param text The text to parse. 469* @param textLength The length of text, or -1 if null-terminated. 470* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 471* to begin parsing. If not 0, on output the offset at which parsing ended. 472* @param status A pointer to an UErrorCode to receive any errors 473* @return The value of the parsed integer 474* @see unum_parse 475* @see unum_parseDouble 476* @see unum_format 477* @see unum_formatInt64 478* @see unum_formatDouble 479* @stable ICU 2.8 480*/ 481U_STABLE int64_t U_EXPORT2 482unum_parseInt64(const UNumberFormat* fmt, 483 const UChar* text, 484 int32_t textLength, 485 int32_t *parsePos /* 0 = start */, 486 UErrorCode *status); 487 488/** 489* Parse a string into a double using a UNumberFormat. 490* The string will be parsed according to the UNumberFormat's locale. 491* @param fmt The formatter to use. 492* @param text The text to parse. 493* @param textLength The length of text, or -1 if null-terminated. 494* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 495* to begin parsing. If not 0, on output the offset at which parsing ended. 496* @param status A pointer to an UErrorCode to receive any errors 497* @return The value of the parsed double 498* @see unum_parse 499* @see unum_parseInt64 500* @see unum_format 501* @see unum_formatInt64 502* @see unum_formatDouble 503* @stable ICU 2.0 504*/ 505U_STABLE double U_EXPORT2 506unum_parseDouble( const UNumberFormat* fmt, 507 const UChar* text, 508 int32_t textLength, 509 int32_t *parsePos /* 0 = start */, 510 UErrorCode *status); 511 512 513/** 514* Parse a number from a string into an unformatted numeric string using a UNumberFormat. 515* The input string will be parsed according to the UNumberFormat's locale. 516* The syntax of the output is a "numeric string" 517* as defined in the Decimal Arithmetic Specification, available at 518* http://speleotrove.com/decimal 519* @param fmt The formatter to use. 520* @param text The text to parse. 521* @param textLength The length of text, or -1 if null-terminated. 522* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 523* to begin parsing. If not 0, on output the offset at which parsing ended. 524* @param outBuf A (char *) buffer to receive the parsed number as a string. The output string 525* will be nul-terminated if there is sufficient space. 526* @param outBufLength The size of the output buffer. May be zero, in which case 527* the outBuf pointer may be NULL, and the function will return the 528* size of the output string. 529* @param status A pointer to an UErrorCode to receive any errors 530* @return the length of the output string, not including any terminating nul. 531* @see unum_parse 532* @see unum_parseInt64 533* @see unum_format 534* @see unum_formatInt64 535* @see unum_formatDouble 536* @stable ICU 4.4 537*/ 538U_STABLE int32_t U_EXPORT2 539unum_parseDecimal(const UNumberFormat* fmt, 540 const UChar* text, 541 int32_t textLength, 542 int32_t *parsePos /* 0 = start */, 543 char *outBuf, 544 int32_t outBufLength, 545 UErrorCode *status); 546 547/** 548 * Parse a string into a double and a currency using a UNumberFormat. 549 * The string will be parsed according to the UNumberFormat's locale. 550 * @param fmt the formatter to use 551 * @param text the text to parse 552 * @param textLength the length of text, or -1 if null-terminated 553 * @param parsePos a pointer to an offset index into text at which to 554 * begin parsing. On output, *parsePos will point after the last 555 * parsed character. This parameter may be 0, in which case parsing 556 * begins at offset 0. 557 * @param currency a pointer to the buffer to receive the parsed null- 558 * terminated currency. This buffer must have a capacity of at least 559 * 4 UChars. 560 * @param status a pointer to an input-output UErrorCode 561 * @return the parsed double 562 * @see unum_parseDouble 563 * @see unum_formatDoubleCurrency 564 * @stable ICU 3.0 565 */ 566U_STABLE double U_EXPORT2 567unum_parseDoubleCurrency(const UNumberFormat* fmt, 568 const UChar* text, 569 int32_t textLength, 570 int32_t* parsePos, /* 0 = start */ 571 UChar* currency, 572 UErrorCode* status); 573 574/** 575 * Set the pattern used by a UNumberFormat. This can only be used 576 * on a DecimalFormat, other formats return U_ILLEGAL_ARGUMENT_ERROR 577 * in the status. 578 * @param format The formatter to set. 579 * @param localized TRUE if the pattern is localized, FALSE otherwise. 580 * @param pattern The new pattern 581 * @param patternLength The length of pattern, or -1 if null-terminated. 582 * @param parseError A pointer to UParseError to recieve information 583 * about errors occurred during parsing, or NULL if no parse error 584 * information is desired. 585 * @param status A pointer to an input-output UErrorCode. 586 * @see unum_toPattern 587 * @see DecimalFormat 588 * @stable ICU 2.0 589 */ 590U_STABLE void U_EXPORT2 591unum_applyPattern( UNumberFormat *format, 592 UBool localized, 593 const UChar *pattern, 594 int32_t patternLength, 595 UParseError *parseError, 596 UErrorCode *status 597 ); 598 599/** 600* Get a locale for which decimal formatting patterns are available. 601* A UNumberFormat in a locale returned by this function will perform the correct 602* formatting and parsing for the locale. The results of this call are not 603* valid for rule-based number formats. 604* @param localeIndex The index of the desired locale. 605* @return A locale for which number formatting patterns are available, or 0 if none. 606* @see unum_countAvailable 607* @stable ICU 2.0 608*/ 609U_STABLE const char* U_EXPORT2 610unum_getAvailable(int32_t localeIndex); 611 612/** 613* Determine how many locales have decimal formatting patterns available. The 614* results of this call are not valid for rule-based number formats. 615* This function is useful for determining the loop ending condition for 616* calls to {@link #unum_getAvailable }. 617* @return The number of locales for which decimal formatting patterns are available. 618* @see unum_getAvailable 619* @stable ICU 2.0 620*/ 621U_STABLE int32_t U_EXPORT2 622unum_countAvailable(void); 623 624/** The possible UNumberFormat numeric attributes @stable ICU 2.0 */ 625typedef enum UNumberFormatAttribute { 626 /** Parse integers only */ 627 UNUM_PARSE_INT_ONLY, 628 /** Use grouping separator */ 629 UNUM_GROUPING_USED, 630 /** Always show decimal point */ 631 UNUM_DECIMAL_ALWAYS_SHOWN, 632 /** Maximum integer digits */ 633 UNUM_MAX_INTEGER_DIGITS, 634 /** Minimum integer digits */ 635 UNUM_MIN_INTEGER_DIGITS, 636 /** Integer digits */ 637 UNUM_INTEGER_DIGITS, 638 /** Maximum fraction digits */ 639 UNUM_MAX_FRACTION_DIGITS, 640 /** Minimum fraction digits */ 641 UNUM_MIN_FRACTION_DIGITS, 642 /** Fraction digits */ 643 UNUM_FRACTION_DIGITS, 644 /** Multiplier */ 645 UNUM_MULTIPLIER, 646 /** Grouping size */ 647 UNUM_GROUPING_SIZE, 648 /** Rounding Mode */ 649 UNUM_ROUNDING_MODE, 650 /** Rounding increment */ 651 UNUM_ROUNDING_INCREMENT, 652 /** The width to which the output of <code>format()</code> is padded. */ 653 UNUM_FORMAT_WIDTH, 654 /** The position at which padding will take place. */ 655 UNUM_PADDING_POSITION, 656 /** Secondary grouping size */ 657 UNUM_SECONDARY_GROUPING_SIZE, 658 /** Use significant digits 659 * @stable ICU 3.0 */ 660 UNUM_SIGNIFICANT_DIGITS_USED, 661 /** Minimum significant digits 662 * @stable ICU 3.0 */ 663 UNUM_MIN_SIGNIFICANT_DIGITS, 664 /** Maximum significant digits 665 * @stable ICU 3.0 */ 666 UNUM_MAX_SIGNIFICANT_DIGITS, 667 /** Lenient parse mode used by rule-based formats. 668 * @stable ICU 3.0 669 */ 670 UNUM_LENIENT_PARSE 671} UNumberFormatAttribute; 672 673/** 674* Get a numeric attribute associated with a UNumberFormat. 675* An example of a numeric attribute is the number of integer digits a formatter will produce. 676* @param fmt The formatter to query. 677* @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 678* UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 679* UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 680* UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE. 681* @return The value of attr. 682* @see unum_setAttribute 683* @see unum_getDoubleAttribute 684* @see unum_setDoubleAttribute 685* @see unum_getTextAttribute 686* @see unum_setTextAttribute 687* @stable ICU 2.0 688*/ 689U_STABLE int32_t U_EXPORT2 690unum_getAttribute(const UNumberFormat* fmt, 691 UNumberFormatAttribute attr); 692 693/** 694* Set a numeric attribute associated with a UNumberFormat. 695* An example of a numeric attribute is the number of integer digits a formatter will produce. If the 696* formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand 697* the lenient-parse attribute. 698* @param fmt The formatter to set. 699* @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, 700* UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, 701* UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, 702* UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE, 703* or UNUM_LENIENT_PARSE. 704* @param newValue The new value of attr. 705* @see unum_getAttribute 706* @see unum_getDoubleAttribute 707* @see unum_setDoubleAttribute 708* @see unum_getTextAttribute 709* @see unum_setTextAttribute 710* @stable ICU 2.0 711*/ 712U_STABLE void U_EXPORT2 713unum_setAttribute( UNumberFormat* fmt, 714 UNumberFormatAttribute attr, 715 int32_t newValue); 716 717 718/** 719* Get a numeric attribute associated with a UNumberFormat. 720* An example of a numeric attribute is the number of integer digits a formatter will produce. 721* If the formatter does not understand the attribute, -1 is returned. 722* @param fmt The formatter to query. 723* @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT. 724* @return The value of attr. 725* @see unum_getAttribute 726* @see unum_setAttribute 727* @see unum_setDoubleAttribute 728* @see unum_getTextAttribute 729* @see unum_setTextAttribute 730* @stable ICU 2.0 731*/ 732U_STABLE double U_EXPORT2 733unum_getDoubleAttribute(const UNumberFormat* fmt, 734 UNumberFormatAttribute attr); 735 736/** 737* Set a numeric attribute associated with a UNumberFormat. 738* An example of a numeric attribute is the number of integer digits a formatter will produce. 739* If the formatter does not understand the attribute, this call is ignored. 740* @param fmt The formatter to set. 741* @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT. 742* @param newValue The new value of attr. 743* @see unum_getAttribute 744* @see unum_setAttribute 745* @see unum_getDoubleAttribute 746* @see unum_getTextAttribute 747* @see unum_setTextAttribute 748* @stable ICU 2.0 749*/ 750U_STABLE void U_EXPORT2 751unum_setDoubleAttribute( UNumberFormat* fmt, 752 UNumberFormatAttribute attr, 753 double newValue); 754 755/** The possible UNumberFormat text attributes @stable ICU 2.0*/ 756typedef enum UNumberFormatTextAttribute { 757 /** Positive prefix */ 758 UNUM_POSITIVE_PREFIX, 759 /** Positive suffix */ 760 UNUM_POSITIVE_SUFFIX, 761 /** Negative prefix */ 762 UNUM_NEGATIVE_PREFIX, 763 /** Negative suffix */ 764 UNUM_NEGATIVE_SUFFIX, 765 /** The character used to pad to the format width. */ 766 UNUM_PADDING_CHARACTER, 767 /** The ISO currency code */ 768 UNUM_CURRENCY_CODE, 769 /** 770 * The default rule set. This is only available with rule-based formatters. 771 * @stable ICU 3.0 772 */ 773 UNUM_DEFAULT_RULESET, 774 /** 775 * The public rule sets. This is only available with rule-based formatters. 776 * This is a read-only attribute. The public rulesets are returned as a 777 * single string, with each ruleset name delimited by ';' (semicolon). 778 * @stable ICU 3.0 779 */ 780 UNUM_PUBLIC_RULESETS 781} UNumberFormatTextAttribute; 782 783/** 784* Get a text attribute associated with a UNumberFormat. 785* An example of a text attribute is the suffix for positive numbers. If the formatter 786* does not understand the attributre, U_UNSUPPORTED_ERROR is returned as the status. 787* Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS. 788* @param fmt The formatter to query. 789* @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 790* UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 791* UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS. 792* @param result A pointer to a buffer to receive the attribute. 793* @param resultLength The maximum size of result. 794* @param status A pointer to an UErrorCode to receive any errors 795* @return The total buffer size needed; if greater than resultLength, the output was truncated. 796* @see unum_setTextAttribute 797* @see unum_getAttribute 798* @see unum_setAttribute 799* @stable ICU 2.0 800*/ 801U_STABLE int32_t U_EXPORT2 802unum_getTextAttribute( const UNumberFormat* fmt, 803 UNumberFormatTextAttribute tag, 804 UChar* result, 805 int32_t resultLength, 806 UErrorCode* status); 807 808/** 809* Set a text attribute associated with a UNumberFormat. 810* An example of a text attribute is the suffix for positive numbers. Rule-based formatters 811* only understand UNUM_DEFAULT_RULESET. 812* @param fmt The formatter to set. 813* @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, 814* UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE, 815* or UNUM_DEFAULT_RULESET. 816* @param newValue The new value of attr. 817* @param newValueLength The length of newValue, or -1 if null-terminated. 818* @param status A pointer to an UErrorCode to receive any errors 819* @see unum_getTextAttribute 820* @see unum_getAttribute 821* @see unum_setAttribute 822* @stable ICU 2.0 823*/ 824U_STABLE void U_EXPORT2 825unum_setTextAttribute( UNumberFormat* fmt, 826 UNumberFormatTextAttribute tag, 827 const UChar* newValue, 828 int32_t newValueLength, 829 UErrorCode *status); 830 831/** 832 * Extract the pattern from a UNumberFormat. The pattern will follow 833 * the DecimalFormat pattern syntax. 834 * @param fmt The formatter to query. 835 * @param isPatternLocalized TRUE if the pattern should be localized, 836 * FALSE otherwise. This is ignored if the formatter is a rule-based 837 * formatter. 838 * @param result A pointer to a buffer to receive the pattern. 839 * @param resultLength The maximum size of result. 840 * @param status A pointer to an input-output UErrorCode. 841 * @return The total buffer size needed; if greater than resultLength, 842 * the output was truncated. 843 * @see unum_applyPattern 844 * @see DecimalFormat 845 * @stable ICU 2.0 846 */ 847U_STABLE int32_t U_EXPORT2 848unum_toPattern( const UNumberFormat* fmt, 849 UBool isPatternLocalized, 850 UChar* result, 851 int32_t resultLength, 852 UErrorCode* status); 853 854 855/** 856 * Constants for specifying a number format symbol. 857 * @stable ICU 2.0 858 */ 859typedef enum UNumberFormatSymbol { 860 /** The decimal separator */ 861 UNUM_DECIMAL_SEPARATOR_SYMBOL = 0, 862 /** The grouping separator */ 863 UNUM_GROUPING_SEPARATOR_SYMBOL = 1, 864 /** The pattern separator */ 865 UNUM_PATTERN_SEPARATOR_SYMBOL = 2, 866 /** The percent sign */ 867 UNUM_PERCENT_SYMBOL = 3, 868 /** Zero*/ 869 UNUM_ZERO_DIGIT_SYMBOL = 4, 870 /** Character representing a digit in the pattern */ 871 UNUM_DIGIT_SYMBOL = 5, 872 /** The minus sign */ 873 UNUM_MINUS_SIGN_SYMBOL = 6, 874 /** The plus sign */ 875 UNUM_PLUS_SIGN_SYMBOL = 7, 876 /** The currency symbol */ 877 UNUM_CURRENCY_SYMBOL = 8, 878 /** The international currency symbol */ 879 UNUM_INTL_CURRENCY_SYMBOL = 9, 880 /** The monetary separator */ 881 UNUM_MONETARY_SEPARATOR_SYMBOL = 10, 882 /** The exponential symbol */ 883 UNUM_EXPONENTIAL_SYMBOL = 11, 884 /** Per mill symbol */ 885 UNUM_PERMILL_SYMBOL = 12, 886 /** Escape padding character */ 887 UNUM_PAD_ESCAPE_SYMBOL = 13, 888 /** Infinity symbol */ 889 UNUM_INFINITY_SYMBOL = 14, 890 /** Nan symbol */ 891 UNUM_NAN_SYMBOL = 15, 892 /** Significant digit symbol 893 * @stable ICU 3.0 */ 894 UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16, 895 /** The monetary grouping separator 896 * @stable ICU 3.6 897 */ 898 UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17, 899 /** One 900 * @draft ICU 4.6 901 */ 902 UNUM_ONE_DIGIT_SYMBOL = 18, 903 /** Two 904 * @draft ICU 4.6 905 */ 906 UNUM_TWO_DIGIT_SYMBOL = 19, 907 /** Three 908 * @draft ICU 4.6 909 */ 910 UNUM_THREE_DIGIT_SYMBOL = 20, 911 /** Four 912 * @draft ICU 4.6 913 */ 914 UNUM_FOUR_DIGIT_SYMBOL = 21, 915 /** Five 916 * @draft ICU 4.6 917 */ 918 UNUM_FIVE_DIGIT_SYMBOL = 22, 919 /** Six 920 * @draft ICU 4.6 921 */ 922 UNUM_SIX_DIGIT_SYMBOL = 23, 923 /** Seven 924 * @draft ICU 4.6 925 */ 926 UNUM_SEVEN_DIGIT_SYMBOL = 24, 927 /** Eight 928 * @draft ICU 4.6 929 */ 930 UNUM_EIGHT_DIGIT_SYMBOL = 25, 931 /** Nine 932 * @draft ICU 4.6 933 */ 934 UNUM_NINE_DIGIT_SYMBOL = 26, 935 /** count symbol constants */ 936 UNUM_FORMAT_SYMBOL_COUNT = 27 937} UNumberFormatSymbol; 938 939/** 940* Get a symbol associated with a UNumberFormat. 941* A UNumberFormat uses symbols to represent the special locale-dependent 942* characters in a number, for example the percent sign. This API is not 943* supported for rule-based formatters. 944* @param fmt The formatter to query. 945* @param symbol The UNumberFormatSymbol constant for the symbol to get 946* @param buffer The string buffer that will receive the symbol string; 947* if it is NULL, then only the length of the symbol is returned 948* @param size The size of the string buffer 949* @param status A pointer to an UErrorCode to receive any errors 950* @return The length of the symbol; the buffer is not modified if 951* <code>length>=size</code> 952* @see unum_setSymbol 953* @stable ICU 2.0 954*/ 955U_STABLE int32_t U_EXPORT2 956unum_getSymbol(const UNumberFormat *fmt, 957 UNumberFormatSymbol symbol, 958 UChar *buffer, 959 int32_t size, 960 UErrorCode *status); 961 962/** 963* Set a symbol associated with a UNumberFormat. 964* A UNumberFormat uses symbols to represent the special locale-dependent 965* characters in a number, for example the percent sign. This API is not 966* supported for rule-based formatters. 967* @param fmt The formatter to set. 968* @param symbol The UNumberFormatSymbol constant for the symbol to set 969* @param value The string to set the symbol to 970* @param length The length of the string, or -1 for a zero-terminated string 971* @param status A pointer to an UErrorCode to receive any errors. 972* @see unum_getSymbol 973* @stable ICU 2.0 974*/ 975U_STABLE void U_EXPORT2 976unum_setSymbol(UNumberFormat *fmt, 977 UNumberFormatSymbol symbol, 978 const UChar *value, 979 int32_t length, 980 UErrorCode *status); 981 982 983/** 984 * Get the locale for this number format object. 985 * You can choose between valid and actual locale. 986 * @param fmt The formatter to get the locale from 987 * @param type type of the locale we're looking for (valid or actual) 988 * @param status error code for the operation 989 * @return the locale name 990 * @stable ICU 2.8 991 */ 992U_STABLE const char* U_EXPORT2 993unum_getLocaleByType(const UNumberFormat *fmt, 994 ULocDataLocaleType type, 995 UErrorCode* status); 996 997#endif /* #if !UCONFIG_NO_FORMATTING */ 998 999#endif 1000