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 #ifndef U_FORCE_HIDE_DEPRECATED_API
 342     /**
 343      * One more than the highest normal UCurrencySpacing value.
 344      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
 345      */
 346     UNUM_CURRENCY_SPACING_COUNT
 347 #endif  // U_FORCE_HIDE_DEPRECATED_API
 348 };
 349 typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */
 350
 351
 352 /**
 353  * FieldPosition and UFieldPosition selectors for format fields
 354  * defined by NumberFormat and UNumberFormat.
 355  * @stable ICU 49
 356  */
 357 typedef enum UNumberFormatFields {
 358     /** @stable ICU 49 */
 359     UNUM_INTEGER_FIELD,
 360     /** @stable ICU 49 */
 361     UNUM_FRACTION_FIELD,
 362     /** @stable ICU 49 */
 363     UNUM_DECIMAL_SEPARATOR_FIELD,
 364     /** @stable ICU 49 */
 365     UNUM_EXPONENT_SYMBOL_FIELD,
 366     /** @stable ICU 49 */
 367     UNUM_EXPONENT_SIGN_FIELD,
 368     /** @stable ICU 49 */
 369     UNUM_EXPONENT_FIELD,
 370     /** @stable ICU 49 */
 371     UNUM_GROUPING_SEPARATOR_FIELD,
 372     /** @stable ICU 49 */
 373     UNUM_CURRENCY_FIELD,
 374     /** @stable ICU 49 */
 375     UNUM_PERCENT_FIELD,
 376     /** @stable ICU 49 */
 377     UNUM_PERMILL_FIELD,
 378     /** @stable ICU 49 */
 379     UNUM_SIGN_FIELD,
 380 #ifndef U_HIDE_DRAFT_API
 381     /** @draft ICU 64 */
 382     UNUM_MEASURE_UNIT_FIELD,
 383     /** @draft ICU 64 */
 384     UNUM_COMPACT_FIELD,
 385 #endif  /* U_HIDE_DRAFT_API */
 386
 387 #ifndef U_HIDE_DEPRECATED_API
 388     /**
 389      * One more than the highest normal UNumberFormatFields value.
 390      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
 391      */
 392     UNUM_FIELD_COUNT = UNUM_SIGN_FIELD + 3
 393 #endif  /* U_HIDE_DEPRECATED_API */
 394 } UNumberFormatFields;
 395
 396
 397 /**
 398  * Create and return a new UNumberFormat for formatting and parsing
 399  * numbers.  A UNumberFormat may be used to format numbers by calling
 400  * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }.
 401  * The caller must call {@link #unum_close } when done to release resources
 402  * used by this object.
 403  * @param style The type of number format to open: one of
 404  * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC,
 405  * UNUM_CURRENCY_ISO, UNUM_CURRENCY_PLURAL, UNUM_SPELLOUT,
 406  * UNUM_ORDINAL, UNUM_DURATION, UNUM_NUMBERING_SYSTEM,
 407  * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT.
 408  * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the
 409  * number format is opened using the given pattern, which must conform
 410  * to the syntax described in DecimalFormat or RuleBasedNumberFormat,
 411  * respectively.
 412  *
 413  * <p><strong>NOTE::</strong> New users with are strongly encouraged to
 414  * use unumf_openForSkeletonAndLocale instead of unum_open.
 415  *
 416  * @param pattern A pattern specifying the format to use.
 417  * This parameter is ignored unless the style is
 418  * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
 419  * @param patternLength The number of characters in the pattern, or -1
 420  * if null-terminated. This parameter is ignored unless the style is
 421  * UNUM_PATTERN.
 422  * @param locale A locale identifier to use to determine formatting
 423  * and parsing conventions, or NULL to use the default locale.
 424  * @param parseErr A pointer to a UParseError struct to receive the
 425  * details of any parsing errors, or NULL if no parsing error details
 426  * are desired.
 427  * @param status A pointer to an input-output UErrorCode.
 428  * @return A pointer to a newly created UNumberFormat, or NULL if an
 429  * error occurred.
 430  * @see unum_close
 431  * @see DecimalFormat
 432  * @stable ICU 2.0
 433  */
 434 U_STABLE UNumberFormat* U_EXPORT2
 435 unum_open(  UNumberFormatStyle    style,
 436             const    UChar*    pattern,
 437             int32_t            patternLength,
 438             const    char*     locale,
 439             UParseError*       parseErr,
 440             UErrorCode*        status);
 441
 442
 443 /**
 444 * Close a UNumberFormat.
 445 * Once closed, a UNumberFormat may no longer be used.
 446 * @param fmt The formatter to close.
 447 * @stable ICU 2.0
 448 */
 449 U_STABLE void U_EXPORT2
 450 unum_close(UNumberFormat* fmt);
 451
 452 #if U_SHOW_CPLUSPLUS_API
 453
 454 U_NAMESPACE_BEGIN
 455
 456 /**
 457  * \class LocalUNumberFormatPointer
 458  * "Smart pointer" class, closes a UNumberFormat via unum_close().
 459  * For most methods see the LocalPointerBase base class.
 460  *
 461  * @see LocalPointerBase
 462  * @see LocalPointer
 463  * @stable ICU 4.4
 464  */
 465 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close);
 466
 467 U_NAMESPACE_END
 468
 469 #endif
 470
 471 /**
 472  * Open a copy of a UNumberFormat.
 473  * This function performs a deep copy.
 474  * @param fmt The format to copy
 475  * @param status A pointer to an UErrorCode to receive any errors.
 476  * @return A pointer to a UNumberFormat identical to fmt.
 477  * @stable ICU 2.0
 478  */
 479 U_STABLE UNumberFormat* U_EXPORT2
 480 unum_clone(const UNumberFormat *fmt,
 481        UErrorCode *status);
 482
 483 /**
 484 * Format an integer using a UNumberFormat.
 485 * The integer will be formatted according to the UNumberFormat's locale.
 486 * @param fmt The formatter to use.
 487 * @param number The number to format.
 488 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
 489 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
 490 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
 491 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
 492 * @param resultLength The maximum size of result.
 493 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 494 * is read.  On output, position->beginIndex and position->endIndex indicate
 495 * the beginning and ending indices of field number position->field, if such
 496 * a field exists.  This parameter may be NULL, in which case no field
 497 * @param status A pointer to an UErrorCode to receive any errors
 498 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 499 * @see unum_formatInt64
 500 * @see unum_formatDouble
 501 * @see unum_parse
 502 * @see unum_parseInt64
 503 * @see unum_parseDouble
 504 * @see UFieldPosition
 505 * @stable ICU 2.0
 506 */
 507 U_STABLE int32_t U_EXPORT2
 508 unum_format(    const    UNumberFormat*    fmt,
 509         int32_t            number,
 510         UChar*            result,
 511         int32_t            resultLength,
 512         UFieldPosition    *pos,
 513         UErrorCode*        status);
 514
 515 /**
 516 * Format an int64 using a UNumberFormat.
 517 * The int64 will be formatted according to the UNumberFormat's locale.
 518 * @param fmt The formatter to use.
 519 * @param number The number to format.
 520 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
 521 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
 522 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
 523 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
 524 * @param resultLength The maximum size of result.
 525 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 526 * is read.  On output, position->beginIndex and position->endIndex indicate
 527 * the beginning and ending indices of field number position->field, if such
 528 * a field exists.  This parameter may be NULL, in which case no field
 529 * @param status A pointer to an UErrorCode to receive any errors
 530 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 531 * @see unum_format
 532 * @see unum_formatDouble
 533 * @see unum_parse
 534 * @see unum_parseInt64
 535 * @see unum_parseDouble
 536 * @see UFieldPosition
 537 * @stable ICU 2.0
 538 */
 539 U_STABLE int32_t U_EXPORT2
 540 unum_formatInt64(const UNumberFormat *fmt,
 541         int64_t         number,
 542         UChar*          result,
 543         int32_t         resultLength,
 544         UFieldPosition *pos,
 545         UErrorCode*     status);
 546
 547 /**
 548 * Format a double using a UNumberFormat.
 549 * The double will be formatted according to the UNumberFormat's locale.
 550 * @param fmt The formatter to use.
 551 * @param number The number to format.
 552 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
 553 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
 554 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
 555 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
 556 * @param resultLength The maximum size of result.
 557 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 558 * is read.  On output, position->beginIndex and position->endIndex indicate
 559 * the beginning and ending indices of field number position->field, if such
 560 * a field exists.  This parameter may be NULL, in which case no field
 561 * @param status A pointer to an UErrorCode to receive any errors
 562 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 563 * @see unum_format
 564 * @see unum_formatInt64
 565 * @see unum_parse
 566 * @see unum_parseInt64
 567 * @see unum_parseDouble
 568 * @see UFieldPosition
 569 * @stable ICU 2.0
 570 */
 571 U_STABLE int32_t U_EXPORT2
 572 unum_formatDouble(    const    UNumberFormat*  fmt,
 573             double          number,
 574             UChar*          result,
 575             int32_t         resultLength,
 576             UFieldPosition  *pos, /* 0 if ignore */
 577             UErrorCode*     status);
 578
 579 /**
 580 * Format a double using a UNumberFormat according to the UNumberFormat's locale,
 581 * and initialize a UFieldPositionIterator that enumerates the subcomponents of
 582 * the resulting string.
 583 *
 584 * @param format
 585 *          The formatter to use.
 586 * @param number
 587 *          The number to format.
 588 * @param result
 589 *          A pointer to a buffer to receive the NULL-terminated formatted
 590 *          number. If the formatted number fits into dest but cannot be
 591 *          NULL-terminated (length == resultLength) then the error code is set
 592 *          to U_STRING_NOT_TERMINATED_WARNING. If the formatted number doesn't
 593 *          fit into result then the error code is set to
 594 *          U_BUFFER_OVERFLOW_ERROR.
 595 * @param resultLength
 596 *          The maximum size of result.
 597 * @param fpositer
 598 *          A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}
 599 *          (may be NULL if field position information is not needed, but in this
 600 *          case it's preferable to use {@link #unum_formatDouble}). Iteration
 601 *          information already present in the UFieldPositionIterator is deleted,
 602 *          and the iterator is reset to apply to the fields in the formatted
 603 *          string created by this function call. The field values and indexes
 604 *          returned by {@link #ufieldpositer_next} represent fields denoted by
 605 *          the UNumberFormatFields enum. Fields are not returned in a guaranteed
 606 *          order. Fields cannot overlap, but they may nest. For example, 1234
 607 *          could format as "1,234" which might consist of a grouping separator
 608 *          field for ',' and an integer field encompassing the entire string.
 609 * @param status
 610 *          A pointer to an UErrorCode to receive any errors
 611 * @return
 612 *          The total buffer size needed; if greater than resultLength, the
 613 *          output was truncated.
 614 * @see unum_formatDouble
 615 * @see unum_parse
 616 * @see unum_parseDouble
 617 * @see UFieldPositionIterator
 618 * @see UNumberFormatFields
 619 * @stable ICU 59
 620 */
 621 U_STABLE int32_t U_EXPORT2
 622 unum_formatDoubleForFields(const UNumberFormat* format,
 623                            double number,
 624                            UChar* result,
 625                            int32_t resultLength,
 626                            UFieldPositionIterator* fpositer,
 627                            UErrorCode* status);
 628
 629
 630 /**
 631 * Format a decimal number using a UNumberFormat.
 632 * The number will be formatted according to the UNumberFormat's locale.
 633 * The syntax of the input number is a "numeric string"
 634 * as defined in the Decimal Arithmetic Specification, available at
 635 * http://speleotrove.com/decimal
 636 * @param fmt The formatter to use.
 637 * @param number The number to format.
 638 * @param length The length of the input number, or -1 if the input is nul-terminated.
 639 * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
 640 * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
 641 * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
 642 * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
 643 * @param resultLength The maximum size of result.
 644 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 645 *               is read.  On output, position->beginIndex and position->endIndex indicate
 646 *               the beginning and ending indices of field number position->field, if such
 647 *               a field exists.  This parameter may be NULL, in which case it is ignored.
 648 * @param status A pointer to an UErrorCode to receive any errors
 649 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 650 * @see unum_format
 651 * @see unum_formatInt64
 652 * @see unum_parse
 653 * @see unum_parseInt64
 654 * @see unum_parseDouble
 655 * @see UFieldPosition
 656 * @stable ICU 4.4
 657 */
 658 U_STABLE int32_t U_EXPORT2
 659 unum_formatDecimal(    const    UNumberFormat*  fmt,
 660             const char *    number,
 661             int32_t         length,
 662             UChar*          result,
 663             int32_t         resultLength,
 664             UFieldPosition  *pos, /* 0 if ignore */
 665             UErrorCode*     status);
 666
 667 /**
 668  * Format a double currency amount using a UNumberFormat.
 669  * The double will be formatted according to the UNumberFormat's locale.
 670  * @param fmt the formatter to use
 671  * @param number the number to format
 672  * @param currency the 3-letter null-terminated ISO 4217 currency code
 673  * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
 674  * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
 675  * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
 676  * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
 677  * @param resultLength the maximum number of UChars to write to result
 678  * @param pos a pointer to a UFieldPosition.  On input,
 679  * position->field is read.  On output, position->beginIndex and
 680  * position->endIndex indicate the beginning and ending indices of
 681  * field number position->field, if such a field exists.  This
 682  * parameter may be NULL, in which case it is ignored.
 683  * @param status a pointer to an input-output UErrorCode
 684  * @return the total buffer size needed; if greater than resultLength,
 685  * the output was truncated.
 686  * @see unum_formatDouble
 687  * @see unum_parseDoubleCurrency
 688  * @see UFieldPosition
 689  * @stable ICU 3.0
 690  */
 691 U_STABLE int32_t U_EXPORT2
 692 unum_formatDoubleCurrency(const UNumberFormat* fmt,
 693                           double number,
 694                           UChar* currency,
 695                           UChar* result,
 696                           int32_t resultLength,
 697                           UFieldPosition* pos,
 698                           UErrorCode* status);
 699
 700 /**
 701  * Format a UFormattable into a string.
 702  * @param fmt the formatter to use
 703  * @param number the number to format, as a UFormattable
 704  * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
 705  * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
 706  * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
 707  * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
 708  * @param resultLength the maximum number of UChars to write to result
 709  * @param pos a pointer to a UFieldPosition.  On input,
 710  * position->field is read.  On output, position->beginIndex and
 711  * position->endIndex indicate the beginning and ending indices of
 712  * field number position->field, if such a field exists.  This
 713  * parameter may be NULL, in which case it is ignored.
 714  * @param status a pointer to an input-output UErrorCode
 715  * @return the total buffer size needed; if greater than resultLength,
 716  * the output was truncated. Will return 0 on error.
 717  * @see unum_parseToUFormattable
 718  * @stable ICU 52
 719  */
 720 U_STABLE int32_t U_EXPORT2
 721 unum_formatUFormattable(const UNumberFormat* fmt,
 722                         const UFormattable *number,
 723                         UChar *result,
 724                         int32_t resultLength,
 725                         UFieldPosition *pos,
 726                         UErrorCode *status);
 727
 728 /**
 729 * Parse a string into an integer using a UNumberFormat.
 730 * The string will be parsed according to the UNumberFormat's locale.
 731 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
 732 * and UNUM_DECIMAL_COMPACT_LONG.
 733 * @param fmt The formatter to use.
 734 * @param text The text to parse.
 735 * @param textLength The length of text, or -1 if null-terminated.
 736 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
 737 * to begin parsing.  If not NULL, on output the offset at which parsing ended.
 738 * @param status A pointer to an UErrorCode to receive any errors
 739 * @return The value of the parsed integer
 740 * @see unum_parseInt64
 741 * @see unum_parseDouble
 742 * @see unum_format
 743 * @see unum_formatInt64
 744 * @see unum_formatDouble
 745 * @stable ICU 2.0
 746 */
 747 U_STABLE int32_t U_EXPORT2
 748 unum_parse(    const   UNumberFormat*  fmt,
 749         const   UChar*          text,
 750         int32_t         textLength,
 751         int32_t         *parsePos /* 0 = start */,
 752         UErrorCode      *status);
 753
 754 /**
 755 * Parse a string into an int64 using a UNumberFormat.
 756 * The string will be parsed according to the UNumberFormat's locale.
 757 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
 758 * and UNUM_DECIMAL_COMPACT_LONG.
 759 * @param fmt The formatter to use.
 760 * @param text The text to parse.
 761 * @param textLength The length of text, or -1 if null-terminated.
 762 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
 763 * to begin parsing.  If not NULL, on output the offset at which parsing ended.
 764 * @param status A pointer to an UErrorCode to receive any errors
 765 * @return The value of the parsed integer
 766 * @see unum_parse
 767 * @see unum_parseDouble
 768 * @see unum_format
 769 * @see unum_formatInt64
 770 * @see unum_formatDouble
 771 * @stable ICU 2.8
 772 */
 773 U_STABLE int64_t U_EXPORT2
 774 unum_parseInt64(const UNumberFormat*  fmt,
 775         const UChar*  text,
 776         int32_t       textLength,
 777         int32_t       *parsePos /* 0 = start */,
 778         UErrorCode    *status);
 779
 780 /**
 781 * Parse a string into a double using a UNumberFormat.
 782 * The string will be parsed according to the UNumberFormat's locale.
 783 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
 784 * and UNUM_DECIMAL_COMPACT_LONG.
 785 * @param fmt The formatter to use.
 786 * @param text The text to parse.
 787 * @param textLength The length of text, or -1 if null-terminated.
 788 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
 789 * to begin parsing.  If not NULL, on output the offset at which parsing ended.
 790 * @param status A pointer to an UErrorCode to receive any errors
 791 * @return The value of the parsed double
 792 * @see unum_parse
 793 * @see unum_parseInt64
 794 * @see unum_format
 795 * @see unum_formatInt64
 796 * @see unum_formatDouble
 797 * @stable ICU 2.0
 798 */
 799 U_STABLE double U_EXPORT2
 800 unum_parseDouble(    const   UNumberFormat*  fmt,
 801             const   UChar*          text,
 802             int32_t         textLength,
 803             int32_t         *parsePos /* 0 = start */,
 804             UErrorCode      *status);
 805
 806
 807 /**
 808 * Parse a number from a string into an unformatted numeric string using a UNumberFormat.
 809 * The input string will be parsed according to the UNumberFormat's locale.
 810 * The syntax of the output is a "numeric string"
 811 * as defined in the Decimal Arithmetic Specification, available at
 812 * http://speleotrove.com/decimal
 813 * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
 814 * and UNUM_DECIMAL_COMPACT_LONG.
 815 * @param fmt The formatter to use.
 816 * @param text The text to parse.
 817 * @param textLength The length of text, or -1 if null-terminated.
 818 * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
 819 *                 to begin parsing.  If not NULL, on output the offset at which parsing ended.
 820 * @param outBuf A (char *) buffer to receive the parsed number as a string.  The output string
 821 *               will be nul-terminated if there is sufficient space.
 822 * @param outBufLength The size of the output buffer.  May be zero, in which case
 823 *               the outBuf pointer may be NULL, and the function will return the
 824 *               size of the output string.
 825 * @param status A pointer to an UErrorCode to receive any errors
 826 * @return the length of the output string, not including any terminating nul.
 827 * @see unum_parse
 828 * @see unum_parseInt64
 829 * @see unum_format
 830 * @see unum_formatInt64
 831 * @see unum_formatDouble
 832 * @stable ICU 4.4
 833 */
 834 U_STABLE int32_t U_EXPORT2
 835 unum_parseDecimal(const   UNumberFormat*  fmt,
 836                  const   UChar*          text,
 837                          int32_t         textLength,
 838                          int32_t         *parsePos /* 0 = start */,
 839                          char            *outBuf,
 840                          int32_t         outBufLength,
 841                          UErrorCode      *status);
 842
 843 /**
 844  * Parse a string into a double and a currency using a UNumberFormat.
 845  * The string will be parsed according to the UNumberFormat's locale.
 846  * @param fmt the formatter to use
 847  * @param text the text to parse
 848  * @param textLength the length of text, or -1 if null-terminated
 849  * @param parsePos a pointer to an offset index into text at which to
 850  * begin parsing. On output, *parsePos will point after the last
 851  * parsed character.  This parameter may be NULL, in which case parsing
 852  * begins at offset 0.
 853  * @param currency a pointer to the buffer to receive the parsed null-
 854  * terminated currency.  This buffer must have a capacity of at least
 855  * 4 UChars.
 856  * @param status a pointer to an input-output UErrorCode
 857  * @return the parsed double
 858  * @see unum_parseDouble
 859  * @see unum_formatDoubleCurrency
 860  * @stable ICU 3.0
 861  */
 862 U_STABLE double U_EXPORT2
 863 unum_parseDoubleCurrency(const UNumberFormat* fmt,
 864                          const UChar* text,
 865                          int32_t textLength,
 866                          int32_t* parsePos, /* 0 = start */
 867                          UChar* currency,
 868                          UErrorCode* status);
 869
 870 /**
 871  * Parse a UChar string into a UFormattable.
 872  * Example code:
 873  * \snippet test/cintltst/cnumtst.c unum_parseToUFormattable
 874  * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT
 875  * and UNUM_DECIMAL_COMPACT_LONG.
 876  * @param fmt the formatter to use
 877  * @param result the UFormattable to hold the result. If NULL, a new UFormattable will be allocated (which the caller must close with ufmt_close).
 878  * @param text the text to parse
 879  * @param textLength the length of text, or -1 if null-terminated
 880  * @param parsePos a pointer to an offset index into text at which to
 881  * begin parsing. On output, *parsePos will point after the last
 882  * parsed character.  This parameter may be NULL in which case parsing
 883  * begins at offset 0.
 884  * @param status a pointer to an input-output UErrorCode
 885  * @return the UFormattable.  Will be ==result unless NULL was passed in for result, in which case it will be the newly opened UFormattable.
 886  * @see ufmt_getType
 887  * @see ufmt_close
 888  * @stable ICU 52
 889  */
 890 U_STABLE UFormattable* U_EXPORT2
 891 unum_parseToUFormattable(const UNumberFormat* fmt,
 892                          UFormattable *result,
 893                          const UChar* text,
 894                          int32_t textLength,
 895                          int32_t* parsePos, /* 0 = start */
 896                          UErrorCode* status);
 897
 898 /**
 899  * Set the pattern used by a UNumberFormat.  This can only be used
 900  * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR
 901  * in the status.
 902  * @param format The formatter to set.
 903  * @param localized TRUE if the pattern is localized, FALSE otherwise.
 904  * @param pattern The new pattern
 905  * @param patternLength The length of pattern, or -1 if null-terminated.
 906  * @param parseError A pointer to UParseError to receive information
 907  * about errors occurred during parsing, or NULL if no parse error
 908  * information is desired.
 909  * @param status A pointer to an input-output UErrorCode.
 910  * @see unum_toPattern
 911  * @see DecimalFormat
 912  * @stable ICU 2.0
 913  */
 914 U_STABLE void U_EXPORT2
 915 unum_applyPattern(          UNumberFormat  *format,
 916                             UBool          localized,
 917                     const   UChar          *pattern,
 918                             int32_t         patternLength,
 919                             UParseError    *parseError,
 920                             UErrorCode     *status
 921                                     );
 922
 923 /**
 924 * Get a locale for which decimal formatting patterns are available.
 925 * A UNumberFormat in a locale returned by this function will perform the correct
 926 * formatting and parsing for the locale.  The results of this call are not
 927 * valid for rule-based number formats.
 928 * @param localeIndex The index of the desired locale.
 929 * @return A locale for which number formatting patterns are available, or 0 if none.
 930 * @see unum_countAvailable
 931 * @stable ICU 2.0
 932 */
 933 U_STABLE const char* U_EXPORT2
 934 unum_getAvailable(int32_t localeIndex);
 935
 936 /**
 937 * Determine how many locales have decimal formatting patterns available.  The
 938 * results of this call are not valid for rule-based number formats.
 939 * This function is useful for determining the loop ending condition for
 940 * calls to {@link #unum_getAvailable }.
 941 * @return The number of locales for which decimal formatting patterns are available.
 942 * @see unum_getAvailable
 943 * @stable ICU 2.0
 944 */
 945 U_STABLE int32_t U_EXPORT2
 946 unum_countAvailable(void);
 947
 948 #if UCONFIG_HAVE_PARSEALLINPUT
 949 /* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */
 950 /**
 951  * @internal
 952  */
 953 typedef enum UNumberFormatAttributeValue {
 954 #ifndef U_HIDE_INTERNAL_API
 955   /** @internal */
 956   UNUM_NO = 0,
 957   /** @internal */
 958   UNUM_YES = 1,
 959   /** @internal */
 960   UNUM_MAYBE = 2
 961 #else
 962   /** @internal */
 963   UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN
 964 #endif /* U_HIDE_INTERNAL_API */
 965 } UNumberFormatAttributeValue;
 966 #endif
 967
 968 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */
 969 typedef enum UNumberFormatAttribute {
 970   /** Parse integers only */
 971   UNUM_PARSE_INT_ONLY,
 972   /** Use grouping separator */
 973   UNUM_GROUPING_USED,
 974   /** Always show decimal point */
 975   UNUM_DECIMAL_ALWAYS_SHOWN,
 976   /** Maximum integer digits */
 977   UNUM_MAX_INTEGER_DIGITS,
 978   /** Minimum integer digits */
 979   UNUM_MIN_INTEGER_DIGITS,
 980   /** Integer digits */
 981   UNUM_INTEGER_DIGITS,
 982   /** Maximum fraction digits */
 983   UNUM_MAX_FRACTION_DIGITS,
 984   /** Minimum fraction digits */
 985   UNUM_MIN_FRACTION_DIGITS,
 986   /** Fraction digits */
 987   UNUM_FRACTION_DIGITS,
 988   /** Multiplier */
 989   UNUM_MULTIPLIER,
 990   /** Grouping size */
 991   UNUM_GROUPING_SIZE,
 992   /** Rounding Mode */
 993   UNUM_ROUNDING_MODE,
 994   /** Rounding increment */
 995   UNUM_ROUNDING_INCREMENT,
 996   /** The width to which the output of <code>format()</code> is padded. */
 997   UNUM_FORMAT_WIDTH,
 998   /** The position at which padding will take place. */
 999   UNUM_PADDING_POSITION,
1000   /** Secondary grouping size */
1001   UNUM_SECONDARY_GROUPING_SIZE,
1002   /** Use significant digits
1003    * @stable ICU 3.0 */
1004   UNUM_SIGNIFICANT_DIGITS_USED,
1005   /** Minimum significant digits
1006    * @stable ICU 3.0 */
1007   UNUM_MIN_SIGNIFICANT_DIGITS,
1008   /** Maximum significant digits
1009    * @stable ICU 3.0 */
1010   UNUM_MAX_SIGNIFICANT_DIGITS,
1011   /** Lenient parse mode used by rule-based formats.
1012    * @stable ICU 3.0
1013    */
1014   UNUM_LENIENT_PARSE,
1015 #if UCONFIG_HAVE_PARSEALLINPUT
1016   /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic).
1017    * This is an internal ICU API. Do not use.
1018    * @internal
1019    */
1020   UNUM_PARSE_ALL_INPUT = 20,
1021 #endif
1022   /**
1023     * Scale, which adjusts the position of the
1024     * decimal point when formatting.  Amounts will be multiplied by 10 ^ (scale)
1025     * before they are formatted.  The default value for the scale is 0 ( no adjustment ).
1026     *
1027     * <p>Example: setting the scale to 3, 123 formats as "123,000"
1028     * <p>Example: setting the scale to -4, 123 formats as "0.0123"
1029     *
1030     * This setting is analogous to getMultiplierScale() and setMultiplierScale() in decimfmt.h.
1031     *
1032    * @stable ICU 51 */
1033   UNUM_SCALE = 21,
1034
1035 #ifndef U_HIDE_DRAFT_API
1036   /**
1037    * Minimum grouping digits; most commonly set to 2 to print "1000" instead of "1,000".
1038    * See DecimalFormat::getMinimumGroupingDigits().
1039    *
1040    * For better control over grouping strategies, use UNumberFormatter.
1041    *
1042    * @draft ICU 64
1043    */
1044   UNUM_MINIMUM_GROUPING_DIGITS = 22,
1045 #endif /* U_HIDE_DRAFT_API */
1046 #ifndef U_HIDE_INTERNAL_API
1047   /** Apple addition for <rdar://problem/39240173>.
1048    * In open-source ICU 60 and earlier, unum_formatDouble pinned
1049    * double to string conversion at DBL_DIG=15 (from <float.h>)
1050    * significant digits; beginning in ICU 61, several extra digit
1051    * digits could be produced. However, by default Apple ICU
1052    * still pins to 15 digits if UNUM_SIGNIFICANT_DIGITS_USED is
1053    * false and UNUM_MAX_FRACTION_DIGITS > 15; this is to improve
1054    * compatibility with Numbers. This default can be overriden
1055    * by setting UNUM_FORMAT_WITH_FULL_PRECISION to true.
1056    * @internal */
1057   UNUM_FORMAT_WITH_FULL_PRECISION = 48,
1058 #endif  /* U_HIDE_INTERNAL_API */
1059
1060   /**
1061    * if this attribute is set to 0, it is set to UNUM_CURRENCY_STANDARD purpose,
1062    * otherwise it is UNUM_CURRENCY_CASH purpose
1063    * Default: 0 (UNUM_CURRENCY_STANDARD purpose)
1064    * @stable ICU 54
1065    */
1066   UNUM_CURRENCY_USAGE = 23,
1067
1068 #ifndef U_HIDE_INTERNAL_API
1069   /** One below the first bitfield-boolean item.
1070    * All items after this one are stored in boolean form.
1071    * @internal */
1072   UNUM_MAX_NONBOOLEAN_ATTRIBUTE = 0x0FFF,
1073 #endif /* U_HIDE_INTERNAL_API */
1074
1075   /** If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating.
1076    * For example,  formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing.
1077    * Default: 0 (not set)
1078    * @stable ICU 50
1079    */
1080   UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS = 0x1000,
1081   /**
1082    * 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.
1083    * Has no effect on formatting.
1084    * Default: 0 (unset)
1085    * @stable ICU 50
1086    */
1087   UNUM_PARSE_NO_EXPONENT = 0x1001,
1088
1089   /**
1090    * if this attribute is set to 1, specifies that, if the pattern contains a
1091    * decimal mark the input is required to have one. If this attribute is set to 0,
1092    * specifies that input does not have to contain a decimal mark.
1093    * Has no effect on formatting.
1094    * Default: 0 (unset)
1095    * @stable ICU 54
1096    */
1097   UNUM_PARSE_DECIMAL_MARK_REQUIRED = 0x1002,
1098
1099 #ifndef U_HIDE_DRAFT_API
1100
1101   /**
1102    * Parsing: if set to 1, parsing is sensitive to case (lowercase/uppercase).
1103    *
1104    * @draft ICU 64
1105    */
1106   UNUM_PARSE_CASE_SENSITIVE = 0x1003,
1107
1108   /**
1109    * Formatting: if set to 1, whether to show the plus sign on non-negative numbers.
1110    *
1111    * For better control over sign display, use UNumberFormatter.
1112    *
1113    * @draft ICU 64
1114    */
1115   UNUM_SIGN_ALWAYS_SHOWN = 0x1004,
1116
1117 #endif /* U_HIDE_DRAFT_API */
1118
1119 #ifndef U_HIDE_INTERNAL_API
1120   /** Limit of boolean attributes. (value should
1121    * not depend on U_HIDE conditionals)
1122    * @internal */
1123   UNUM_LIMIT_BOOLEAN_ATTRIBUTE = 0x1005,
1124 #endif /* U_HIDE_INTERNAL_API */
1125
1126 } UNumberFormatAttribute;
1127
1128 /**
1129 * Get a numeric attribute associated with a UNumberFormat.
1130 * An example of a numeric attribute is the number of integer digits a formatter will produce.
1131 * @param fmt The formatter to query.
1132 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
1133 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
1134 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
1135 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
1136 * UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS.
1137 * @return The value of attr.
1138 * @see unum_setAttribute
1139 * @see unum_getDoubleAttribute
1140 * @see unum_setDoubleAttribute
1141 * @see unum_getTextAttribute
1142 * @see unum_setTextAttribute
1143 * @stable ICU 2.0
1144 */
1145 U_STABLE int32_t U_EXPORT2
1146 unum_getAttribute(const UNumberFormat*          fmt,
1147           UNumberFormatAttribute  attr);
1148
1149 /**
1150 * Set a numeric attribute associated with a UNumberFormat.
1151 * An example of a numeric attribute is the number of integer digits a formatter will produce.  If the
1152 * formatter does not understand the attribute, the call is ignored.  Rule-based formatters only understand
1153 * the lenient-parse attribute.
1154 * @param fmt The formatter to set.
1155 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
1156 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
1157 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
1158 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
1159 * UNUM_LENIENT_PARSE, UNUM_SCALE, UNUM_MINIMUM_GROUPING_DIGITS.
1160 * @param newValue The new value of attr.
1161 * @see unum_getAttribute
1162 * @see unum_getDoubleAttribute
1163 * @see unum_setDoubleAttribute
1164 * @see unum_getTextAttribute
1165 * @see unum_setTextAttribute
1166 * @stable ICU 2.0
1167 */
1168 U_STABLE void U_EXPORT2
1169 unum_setAttribute(    UNumberFormat*          fmt,
1170             UNumberFormatAttribute  attr,
1171             int32_t                 newValue);
1172
1173
1174 /**
1175 * Get a numeric attribute associated with a UNumberFormat.
1176 * An example of a numeric attribute is the number of integer digits a formatter will produce.
1177 * If the formatter does not understand the attribute, -1 is returned.
1178 * @param fmt The formatter to query.
1179 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT.
1180 * @return The value of attr.
1181 * @see unum_getAttribute
1182 * @see unum_setAttribute
1183 * @see unum_setDoubleAttribute
1184 * @see unum_getTextAttribute
1185 * @see unum_setTextAttribute
1186 * @stable ICU 2.0
1187 */
1188 U_STABLE double U_EXPORT2
1189 unum_getDoubleAttribute(const UNumberFormat*          fmt,
1190           UNumberFormatAttribute  attr);
1191
1192 /**
1193 * Set a numeric attribute associated with a UNumberFormat.
1194 * An example of a numeric attribute is the number of integer digits a formatter will produce.
1195 * If the formatter does not understand the attribute, this call is ignored.
1196 * @param fmt The formatter to set.
1197 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT.
1198 * @param newValue The new value of attr.
1199 * @see unum_getAttribute
1200 * @see unum_setAttribute
1201 * @see unum_getDoubleAttribute
1202 * @see unum_getTextAttribute
1203 * @see unum_setTextAttribute
1204 * @stable ICU 2.0
1205 */
1206 U_STABLE void U_EXPORT2
1207 unum_setDoubleAttribute(    UNumberFormat*          fmt,
1208             UNumberFormatAttribute  attr,
1209             double                 newValue);
1210
1211 /** The possible UNumberFormat text attributes @stable ICU 2.0*/
1212 typedef enum UNumberFormatTextAttribute {
1213   /** Positive prefix */
1214   UNUM_POSITIVE_PREFIX,
1215   /** Positive suffix */
1216   UNUM_POSITIVE_SUFFIX,
1217   /** Negative prefix */
1218   UNUM_NEGATIVE_PREFIX,
1219   /** Negative suffix */
1220   UNUM_NEGATIVE_SUFFIX,
1221   /** The character used to pad to the format width. */
1222   UNUM_PADDING_CHARACTER,
1223   /** The ISO currency code */
1224   UNUM_CURRENCY_CODE,
1225   /**
1226    * The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:",
1227    * "%spellout-ordinal-masculine-plural:", "%spellout-ordinal-feminine:", or
1228    * "%spellout-ordinal-neuter:". The available public rulesets can be listed using
1229    * unum_getTextAttribute with UNUM_PUBLIC_RULESETS. This is only available with
1230    * rule-based formatters.
1231    * @stable ICU 3.0
1232    */
1233   UNUM_DEFAULT_RULESET,
1234   /**
1235    * The public rule sets.  This is only available with rule-based formatters.
1236    * This is a read-only attribute.  The public rulesets are returned as a
1237    * single string, with each ruleset name delimited by ';' (semicolon). See the
1238    * CLDR LDML spec for more information about RBNF rulesets:
1239    * http://www.unicode.org/reports/tr35/tr35-numbers.html#Rule-Based_Number_Formatting
1240    * @stable ICU 3.0
1241    */
1242   UNUM_PUBLIC_RULESETS
1243 } UNumberFormatTextAttribute;
1244
1245 /**
1246 * Get a text attribute associated with a UNumberFormat.
1247 * An example of a text attribute is the suffix for positive numbers.  If the formatter
1248 * does not understand the attribute, U_UNSUPPORTED_ERROR is returned as the status.
1249 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS.
1250 * @param fmt The formatter to query.
1251 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
1252 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
1253 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS.
1254 * @param result A pointer to a buffer to receive the attribute.
1255 * @param resultLength The maximum size of result.
1256 * @param status A pointer to an UErrorCode to receive any errors
1257 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
1258 * @see unum_setTextAttribute
1259 * @see unum_getAttribute
1260 * @see unum_setAttribute
1261 * @stable ICU 2.0
1262 */
1263 U_STABLE int32_t U_EXPORT2
1264 unum_getTextAttribute(    const    UNumberFormat*                    fmt,
1265             UNumberFormatTextAttribute      tag,
1266             UChar*                            result,
1267             int32_t                            resultLength,
1268             UErrorCode*                        status);
1269
1270 /**
1271 * Set a text attribute associated with a UNumberFormat.
1272 * An example of a text attribute is the suffix for positive numbers.  Rule-based formatters
1273 * only understand UNUM_DEFAULT_RULESET.
1274 * @param fmt The formatter to set.
1275 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
1276 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
1277 * or UNUM_DEFAULT_RULESET.
1278 * @param newValue The new value of attr.
1279 * @param newValueLength The length of newValue, or -1 if null-terminated.
1280 * @param status A pointer to an UErrorCode to receive any errors
1281 * @see unum_getTextAttribute
1282 * @see unum_getAttribute
1283 * @see unum_setAttribute
1284 * @stable ICU 2.0
1285 */
1286 U_STABLE void U_EXPORT2
1287 unum_setTextAttribute(    UNumberFormat*                    fmt,
1288             UNumberFormatTextAttribute      tag,
1289             const    UChar*                            newValue,
1290             int32_t                            newValueLength,
1291             UErrorCode                        *status);
1292
1293 /**
1294  * Extract the pattern from a UNumberFormat.  The pattern will follow
1295  * the DecimalFormat pattern syntax.
1296  * @param fmt The formatter to query.
1297  * @param isPatternLocalized TRUE if the pattern should be localized,
1298  * FALSE otherwise.  This is ignored if the formatter is a rule-based
1299  * formatter.
1300  * @param result A pointer to a buffer to receive the pattern.
1301  * @param resultLength The maximum size of result.
1302  * @param status A pointer to an input-output UErrorCode.
1303  * @return The total buffer size needed; if greater than resultLength,
1304  * the output was truncated.
1305  * @see unum_applyPattern
1306  * @see DecimalFormat
1307  * @stable ICU 2.0
1308  */
1309 U_STABLE int32_t U_EXPORT2
1310 unum_toPattern(    const    UNumberFormat*          fmt,
1311         UBool                  isPatternLocalized,
1312         UChar*                  result,
1313         int32_t                 resultLength,
1314         UErrorCode*             status);
1315
1316
1317 /**
1318  * Constants for specifying a number format symbol.
1319  * @stable ICU 2.0
1320  */
1321 typedef enum UNumberFormatSymbol {
1322   /** The decimal separator */
1323   UNUM_DECIMAL_SEPARATOR_SYMBOL = 0,
1324   /** The grouping separator */
1325   UNUM_GROUPING_SEPARATOR_SYMBOL = 1,
1326   /** The pattern separator */
1327   UNUM_PATTERN_SEPARATOR_SYMBOL = 2,
1328   /** The percent sign */
1329   UNUM_PERCENT_SYMBOL = 3,
1330   /** Zero*/
1331   UNUM_ZERO_DIGIT_SYMBOL = 4,
1332   /** Character representing a digit in the pattern */
1333   UNUM_DIGIT_SYMBOL = 5,
1334   /** The minus sign */
1335   UNUM_MINUS_SIGN_SYMBOL = 6,
1336   /** The plus sign */
1337   UNUM_PLUS_SIGN_SYMBOL = 7,
1338   /** The currency symbol */
1339   UNUM_CURRENCY_SYMBOL = 8,
1340   /** The international currency symbol */
1341   UNUM_INTL_CURRENCY_SYMBOL = 9,
1342   /** The monetary separator */
1343   UNUM_MONETARY_SEPARATOR_SYMBOL = 10,
1344   /** The exponential symbol */
1345   UNUM_EXPONENTIAL_SYMBOL = 11,
1346   /** Per mill symbol */
1347   UNUM_PERMILL_SYMBOL = 12,
1348   /** Escape padding character */
1349   UNUM_PAD_ESCAPE_SYMBOL = 13,
1350   /** Infinity symbol */
1351   UNUM_INFINITY_SYMBOL = 14,
1352   /** Nan symbol */
1353   UNUM_NAN_SYMBOL = 15,
1354   /** Significant digit symbol
1355    * @stable ICU 3.0 */
1356   UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16,
1357   /** The monetary grouping separator
1358    * @stable ICU 3.6
1359    */
1360   UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17,
1361   /** One
1362    * @stable ICU 4.6
1363    */
1364   UNUM_ONE_DIGIT_SYMBOL = 18,
1365   /** Two
1366    * @stable ICU 4.6
1367    */
1368   UNUM_TWO_DIGIT_SYMBOL = 19,
1369   /** Three
1370    * @stable ICU 4.6
1371    */
1372   UNUM_THREE_DIGIT_SYMBOL = 20,
1373   /** Four
1374    * @stable ICU 4.6
1375    */
1376   UNUM_FOUR_DIGIT_SYMBOL = 21,
1377   /** Five
1378    * @stable ICU 4.6
1379    */
1380   UNUM_FIVE_DIGIT_SYMBOL = 22,
1381   /** Six
1382    * @stable ICU 4.6
1383    */
1384   UNUM_SIX_DIGIT_SYMBOL = 23,
1385   /** Seven
1386     * @stable ICU 4.6
1387    */
1388   UNUM_SEVEN_DIGIT_SYMBOL = 24,
1389   /** Eight
1390    * @stable ICU 4.6
1391    */
1392   UNUM_EIGHT_DIGIT_SYMBOL = 25,
1393   /** Nine
1394    * @stable ICU 4.6
1395    */
1396   UNUM_NINE_DIGIT_SYMBOL = 26,
1397
1398   /** Multiplication sign
1399    * @stable ICU 54
1400    */
1401   UNUM_EXPONENT_MULTIPLICATION_SYMBOL = 27,
1402
1403 #ifndef U_HIDE_DEPRECATED_API
1404     /**
1405      * One more than the highest normal UNumberFormatSymbol value.
1406      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
1407      */
1408   UNUM_FORMAT_SYMBOL_COUNT = 28
1409 #endif  /* U_HIDE_DEPRECATED_API */
1410 } UNumberFormatSymbol;
1411
1412 /**
1413 * Get a symbol associated with a UNumberFormat.
1414 * A UNumberFormat uses symbols to represent the special locale-dependent
1415 * characters in a number, for example the percent sign. This API is not
1416 * supported for rule-based formatters.
1417 * @param fmt The formatter to query.
1418 * @param symbol The UNumberFormatSymbol constant for the symbol to get
1419 * @param buffer The string buffer that will receive the symbol string;
1420 *               if it is NULL, then only the length of the symbol is returned
1421 * @param size The size of the string buffer
1422 * @param status A pointer to an UErrorCode to receive any errors
1423 * @return The length of the symbol; the buffer is not modified if
1424 *         <code>length&gt;=size</code>
1425 * @see unum_setSymbol
1426 * @stable ICU 2.0
1427 */
1428 U_STABLE int32_t U_EXPORT2
1429 unum_getSymbol(const UNumberFormat *fmt,
1430                UNumberFormatSymbol symbol,
1431                UChar *buffer,
1432                int32_t size,
1433                UErrorCode *status);
1434
1435 /**
1436 * Set a symbol associated with a UNumberFormat.
1437 * A UNumberFormat uses symbols to represent the special locale-dependent
1438 * characters in a number, for example the percent sign.  This API is not
1439 * supported for rule-based formatters.
1440 * @param fmt The formatter to set.
1441 * @param symbol The UNumberFormatSymbol constant for the symbol to set
1442 * @param value The string to set the symbol to
1443 * @param length The length of the string, or -1 for a zero-terminated string
1444 * @param status A pointer to an UErrorCode to receive any errors.
1445 * @see unum_getSymbol
1446 * @stable ICU 2.0
1447 */
1448 U_STABLE void U_EXPORT2
1449 unum_setSymbol(UNumberFormat *fmt,
1450                UNumberFormatSymbol symbol,
1451                const UChar *value,
1452                int32_t length,
1453                UErrorCode *status);
1454
1455
1456 /**
1457  * Get the locale for this number format object.
1458  * You can choose between valid and actual locale.
1459  * @param fmt The formatter to get the locale from
1460  * @param type type of the locale we're looking for (valid or actual)
1461  * @param status error code for the operation
1462  * @return the locale name
1463  * @stable ICU 2.8
1464  */
1465 U_STABLE const char* U_EXPORT2
1466 unum_getLocaleByType(const UNumberFormat *fmt,
1467                      ULocDataLocaleType type,
1468                      UErrorCode* status);
1469
1470 /**
1471  * Set a particular UDisplayContext value in the formatter, such as
1472  * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
1473  * @param fmt The formatter for which to set a UDisplayContext value.
1474  * @param value The UDisplayContext value to set.
1475  * @param status A pointer to an UErrorCode to receive any errors
1476  * @stable ICU 53
1477  */
1478 U_STABLE void U_EXPORT2
1479 unum_setContext(UNumberFormat* fmt, UDisplayContext value, UErrorCode* status);
1480
1481 /**
1482  * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
1483  * such as UDISPCTX_TYPE_CAPITALIZATION.
1484  * @param fmt The formatter to query.
1485  * @param type The UDisplayContextType whose value to return
1486  * @param status A pointer to an UErrorCode to receive any errors
1487  * @return The UDisplayContextValue for the specified type.
1488  * @stable ICU 53
1489  */
1490 U_STABLE UDisplayContext U_EXPORT2
1491 unum_getContext(const UNumberFormat *fmt, UDisplayContextType type, UErrorCode* status);
1492
1493 #endif /* #if !UCONFIG_NO_FORMATTING */
1494
1495 #endif