icuSources/i18n/unicode/unum.h

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