src/third_party/icu/source/i18n/unicode/unum.h

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