icuSources/i18n/unicode/unum.h

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