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