icuSources/i18n/unicode/unum.h

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