icuSources/i18n/unicode/unum.h

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