icuSources/i18n/unicode/unum.h

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