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