icuSources/i18n/unicode/unum.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 1997-2010, 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_getAttribues() and unum_setAtributes(), 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 pattern
 138      * @stable ICU 3.0
 139      */
 140     UNUM_PATTERN_DECIMAL=0,
 141     /** Decimal format */
 142     UNUM_DECIMAL=1,
 143     /** Currency format */
 144     UNUM_CURRENCY,
 145     /** Percent format */
 146     UNUM_PERCENT,
 147     /** Scientific format */
 148     UNUM_SCIENTIFIC,
 149     /** Spellout rule-based format */
 150     UNUM_SPELLOUT,
 151     /**
 152      * Ordinal rule-based format
 153      * @stable ICU 3.0
 154      */
 155     UNUM_ORDINAL,
 156     /**
 157      * Duration rule-based format
 158      * @stable ICU 3.0
 159      */
 160     UNUM_DURATION,
 161     /**
 162      * Numbering system rule-based format
 163      * @stable ICU 4.2
 164      */
 165     UNUM_NUMBERING_SYSTEM,
 166     /**
 167      * Rule-based format defined by pattern
 168      * @stable ICU 3.0
 169      */
 170     UNUM_PATTERN_RULEBASED,
 171     /** Default format */
 172     UNUM_DEFAULT = UNUM_DECIMAL,
 173     /** (Alias for UNUM_PATTERN_DECIMAL) */
 174     UNUM_IGNORE = UNUM_PATTERN_DECIMAL
 175 } UNumberFormatStyle;
 176
 177 /** The possible number format rounding modes.
 178  *  @stable ICU 2.0
 179  */
 180 typedef enum UNumberFormatRoundingMode {
 181     UNUM_ROUND_CEILING,
 182     UNUM_ROUND_FLOOR,
 183     UNUM_ROUND_DOWN,
 184     UNUM_ROUND_UP,
 185     /**
 186      * Half-even rounding, misspelled name
 187      * @deprecated, ICU 3.8
 188      */
 189     UNUM_FOUND_HALFEVEN,
 190     UNUM_ROUND_HALFDOWN,
 191     UNUM_ROUND_HALFUP,
 192     /**
 193      * Half-even rounding
 194      * @stable, ICU 3.8
 195      */
 196     UNUM_ROUND_HALFEVEN = UNUM_FOUND_HALFEVEN
 197 } UNumberFormatRoundingMode;
 198
 199 /** The possible number format pad positions.
 200  *  @stable ICU 2.0
 201  */
 202 typedef enum UNumberFormatPadPosition {
 203     UNUM_PAD_BEFORE_PREFIX,
 204     UNUM_PAD_AFTER_PREFIX,
 205     UNUM_PAD_BEFORE_SUFFIX,
 206     UNUM_PAD_AFTER_SUFFIX
 207 } UNumberFormatPadPosition;
 208
 209 /**
 210  * Create and return a new UNumberFormat for formatting and parsing
 211  * numbers.  A UNumberFormat may be used to format numbers by calling
 212  * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }.
 213  * The caller must call {@link #unum_close } when done to release resources
 214  * used by this object.
 215  * @param style The type of number format to open: one of
 216  * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT,
 217  * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT.
 218  * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the
 219  * number format is opened using the given pattern, which must conform
 220  * to the syntax described in DecimalFormat or RuleBasedNumberFormat,
 221  * respectively.
 222  * @param pattern A pattern specifying the format to use.
 223  * This parameter is ignored unless the style is
 224  * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
 225  * @param patternLength The number of characters in the pattern, or -1
 226  * if null-terminated. This parameter is ignored unless the style is
 227  * UNUM_PATTERN.
 228  * @param locale A locale identifier to use to determine formatting
 229  * and parsing conventions, or NULL to use the default locale.
 230  * @param parseErr A pointer to a UParseError struct to receive the
 231  * details of any parsing errors, or NULL if no parsing error details
 232  * are desired.
 233  * @param status A pointer to an input-output UErrorCode.
 234  * @return A pointer to a newly created UNumberFormat, or NULL if an
 235  * error occurred.
 236  * @see unum_close
 237  * @see DecimalFormat
 238  * @stable ICU 2.0
 239  */
 240 U_STABLE UNumberFormat* U_EXPORT2
 241 unum_open(  UNumberFormatStyle    style,
 242             const    UChar*    pattern,
 243             int32_t            patternLength,
 244             const    char*     locale,
 245             UParseError*       parseErr,
 246             UErrorCode*        status);
 247
 248
 249 /**
 250 * Close a UNumberFormat.
 251 * Once closed, a UNumberFormat may no longer be used.
 252 * @param fmt The formatter to close.
 253 * @stable ICU 2.0
 254 */
 255 U_STABLE void U_EXPORT2
 256 unum_close(UNumberFormat* fmt);
 257
 258 #if U_SHOW_CPLUSPLUS_API
 259
 260 U_NAMESPACE_BEGIN
 261
 262 /**
 263  * \class LocalUNumberFormatPointer
 264  * "Smart pointer" class, closes a UNumberFormat via unum_close().
 265  * For most methods see the LocalPointerBase base class.
 266  *
 267  * @see LocalPointerBase
 268  * @see LocalPointer
 269  * @stable ICU 4.4
 270  */
 271 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close);
 272
 273 U_NAMESPACE_END
 274
 275 #endif
 276
 277 /**
 278  * Open a copy of a UNumberFormat.
 279  * This function performs a deep copy.
 280  * @param fmt The format to copy
 281  * @param status A pointer to an UErrorCode to receive any errors.
 282  * @return A pointer to a UNumberFormat identical to fmt.
 283  * @stable ICU 2.0
 284  */
 285 U_STABLE UNumberFormat* U_EXPORT2
 286 unum_clone(const UNumberFormat *fmt,
 287        UErrorCode *status);
 288
 289 /**
 290 * Format an integer using a UNumberFormat.
 291 * The integer will be formatted according to the UNumberFormat's locale.
 292 * @param fmt The formatter to use.
 293 * @param number The number to format.
 294 * @param result A pointer to a buffer to receive the formatted number.
 295 * @param resultLength The maximum size of result.
 296 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 297 * is read.  On output, position->beginIndex and position->endIndex indicate
 298 * the beginning and ending indices of field number position->field, if such
 299 * a field exists.  This parameter may be NULL, in which case no field
 300 * @param status A pointer to an UErrorCode to receive any errors
 301 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 302 * @see unum_formatInt64
 303 * @see unum_formatDouble
 304 * @see unum_parse
 305 * @see unum_parseInt64
 306 * @see unum_parseDouble
 307 * @see UFieldPosition
 308 * @stable ICU 2.0
 309 */
 310 U_STABLE int32_t U_EXPORT2
 311 unum_format(    const    UNumberFormat*    fmt,
 312         int32_t            number,
 313         UChar*            result,
 314         int32_t            resultLength,
 315         UFieldPosition    *pos,
 316         UErrorCode*        status);
 317
 318 /**
 319 * Format an int64 using a UNumberFormat.
 320 * The int64 will be formatted according to the UNumberFormat's locale.
 321 * @param fmt The formatter to use.
 322 * @param number The number to format.
 323 * @param result A pointer to a buffer to receive the formatted number.
 324 * @param resultLength The maximum size of result.
 325 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 326 * is read.  On output, position->beginIndex and position->endIndex indicate
 327 * the beginning and ending indices of field number position->field, if such
 328 * a field exists.  This parameter may be NULL, in which case no field
 329 * @param status A pointer to an UErrorCode to receive any errors
 330 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 331 * @see unum_format
 332 * @see unum_formatDouble
 333 * @see unum_parse
 334 * @see unum_parseInt64
 335 * @see unum_parseDouble
 336 * @see UFieldPosition
 337 * @stable ICU 2.0
 338 */
 339 U_STABLE int32_t U_EXPORT2
 340 unum_formatInt64(const UNumberFormat *fmt,
 341         int64_t         number,
 342         UChar*          result,
 343         int32_t         resultLength,
 344         UFieldPosition *pos,
 345         UErrorCode*     status);
 346
 347 /**
 348 * Format a double using a UNumberFormat.
 349 * The double will be formatted according to the UNumberFormat's locale.
 350 * @param fmt The formatter to use.
 351 * @param number The number to format.
 352 * @param result A pointer to a buffer to receive the formatted number.
 353 * @param resultLength The maximum size of result.
 354 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 355 * is read.  On output, position->beginIndex and position->endIndex indicate
 356 * the beginning and ending indices of field number position->field, if such
 357 * a field exists.  This parameter may be NULL, in which case no field
 358 * @param status A pointer to an UErrorCode to receive any errors
 359 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 360 * @see unum_format
 361 * @see unum_formatInt64
 362 * @see unum_parse
 363 * @see unum_parseInt64
 364 * @see unum_parseDouble
 365 * @see UFieldPosition
 366 * @stable ICU 2.0
 367 */
 368 U_STABLE int32_t U_EXPORT2
 369 unum_formatDouble(    const    UNumberFormat*  fmt,
 370             double          number,
 371             UChar*          result,
 372             int32_t         resultLength,
 373             UFieldPosition  *pos, /* 0 if ignore */
 374             UErrorCode*     status);
 375
 376 /**
 377 * Format a decimal number using a UNumberFormat.
 378 * The number will be formatted according to the UNumberFormat's locale.
 379 * The syntax of the input number is a "numeric string"
 380 * as defined in the Decimal Arithmetic Specification, available at
 381 * http://speleotrove.com/decimal
 382 * @param fmt The formatter to use.
 383 * @param number The number to format.
 384 * @param length The length of the input number, or -1 if the input is nul-terminated.
 385 * @param result A pointer to a buffer to receive the formatted number.
 386 * @param resultLength The maximum size of result.
 387 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 388 *               is read.  On output, position->beginIndex and position->endIndex indicate
 389 *               the beginning and ending indices of field number position->field, if such
 390 *               a field exists.  This parameter may be NULL, in which case it is ignored.
 391 * @param status A pointer to an UErrorCode to receive any errors
 392 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 393 * @see unum_format
 394 * @see unum_formatInt64
 395 * @see unum_parse
 396 * @see unum_parseInt64
 397 * @see unum_parseDouble
 398 * @see UFieldPosition
 399 * @stable ICU 4.4
 400 */
 401 U_STABLE int32_t U_EXPORT2
 402 unum_formatDecimal(    const    UNumberFormat*  fmt,
 403             const char *    number,
 404             int32_t         length,
 405             UChar*          result,
 406             int32_t         resultLength,
 407             UFieldPosition  *pos, /* 0 if ignore */
 408             UErrorCode*     status);
 409
 410 /**
 411  * Format a double currency amount using a UNumberFormat.
 412  * The double will be formatted according to the UNumberFormat's locale.
 413  * @param fmt the formatter to use
 414  * @param number the number to format
 415  * @param currency the 3-letter null-terminated ISO 4217 currency code
 416  * @param result a pointer to the buffer to receive the formatted number
 417  * @param resultLength the maximum number of UChars to write to result
 418  * @param pos a pointer to a UFieldPosition.  On input,
 419  * position->field is read.  On output, position->beginIndex and
 420  * position->endIndex indicate the beginning and ending indices of
 421  * field number position->field, if such a field exists.  This
 422  * parameter may be NULL, in which case it is ignored.
 423  * @param status a pointer to an input-output UErrorCode
 424  * @return the total buffer size needed; if greater than resultLength,
 425  * the output was truncated.
 426  * @see unum_formatDouble
 427  * @see unum_parseDoubleCurrency
 428  * @see UFieldPosition
 429  * @stable ICU 3.0
 430  */
 431 U_STABLE int32_t U_EXPORT2
 432 unum_formatDoubleCurrency(const UNumberFormat* fmt,
 433                           double number,
 434                           UChar* currency,
 435                           UChar* result,
 436                           int32_t resultLength,
 437                           UFieldPosition* pos, /* ignored if 0 */
 438                           UErrorCode* status);
 439
 440 /**
 441 * Parse a string into an integer using a UNumberFormat.
 442 * The string will be parsed according to the UNumberFormat's locale.
 443 * @param fmt The formatter to use.
 444 * @param text The text to parse.
 445 * @param textLength The length of text, or -1 if null-terminated.
 446 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
 447 * to begin parsing.  If not 0, on output the offset at which parsing ended.
 448 * @param status A pointer to an UErrorCode to receive any errors
 449 * @return The value of the parsed integer
 450 * @see unum_parseInt64
 451 * @see unum_parseDouble
 452 * @see unum_format
 453 * @see unum_formatInt64
 454 * @see unum_formatDouble
 455 * @stable ICU 2.0
 456 */
 457 U_STABLE int32_t U_EXPORT2
 458 unum_parse(    const   UNumberFormat*  fmt,
 459         const   UChar*          text,
 460         int32_t         textLength,
 461         int32_t         *parsePos /* 0 = start */,
 462         UErrorCode      *status);
 463
 464 /**
 465 * Parse a string into an int64 using a UNumberFormat.
 466 * The string will be parsed according to the UNumberFormat's locale.
 467 * @param fmt The formatter to use.
 468 * @param text The text to parse.
 469 * @param textLength The length of text, or -1 if null-terminated.
 470 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
 471 * to begin parsing.  If not 0, on output the offset at which parsing ended.
 472 * @param status A pointer to an UErrorCode to receive any errors
 473 * @return The value of the parsed integer
 474 * @see unum_parse
 475 * @see unum_parseDouble
 476 * @see unum_format
 477 * @see unum_formatInt64
 478 * @see unum_formatDouble
 479 * @stable ICU 2.8
 480 */
 481 U_STABLE int64_t U_EXPORT2
 482 unum_parseInt64(const UNumberFormat*  fmt,
 483         const UChar*  text,
 484         int32_t       textLength,
 485         int32_t       *parsePos /* 0 = start */,
 486         UErrorCode    *status);
 487
 488 /**
 489 * Parse a string into a double using a UNumberFormat.
 490 * The string will be parsed according to the UNumberFormat's locale.
 491 * @param fmt The formatter to use.
 492 * @param text The text to parse.
 493 * @param textLength The length of text, or -1 if null-terminated.
 494 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
 495 * to begin parsing.  If not 0, on output the offset at which parsing ended.
 496 * @param status A pointer to an UErrorCode to receive any errors
 497 * @return The value of the parsed double
 498 * @see unum_parse
 499 * @see unum_parseInt64
 500 * @see unum_format
 501 * @see unum_formatInt64
 502 * @see unum_formatDouble
 503 * @stable ICU 2.0
 504 */
 505 U_STABLE double U_EXPORT2
 506 unum_parseDouble(    const   UNumberFormat*  fmt,
 507             const   UChar*          text,
 508             int32_t         textLength,
 509             int32_t         *parsePos /* 0 = start */,
 510             UErrorCode      *status);
 511
 512
 513 /**
 514 * Parse a number from a string into an unformatted numeric string using a UNumberFormat.
 515 * The input string will be parsed according to the UNumberFormat's locale.
 516 * The syntax of the output is a "numeric string"
 517 * as defined in the Decimal Arithmetic Specification, available at
 518 * http://speleotrove.com/decimal
 519 * @param fmt The formatter to use.
 520 * @param text The text to parse.
 521 * @param textLength The length of text, or -1 if null-terminated.
 522 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
 523 *                 to begin parsing.  If not 0, on output the offset at which parsing ended.
 524 * @param outBuf A (char *) buffer to receive the parsed number as a string.  The output string
 525 *               will be nul-terminated if there is sufficient space.
 526 * @param outBufLength The size of the output buffer.  May be zero, in which case
 527 *               the outBuf pointer may be NULL, and the function will return the
 528 *               size of the output string.
 529 * @param status A pointer to an UErrorCode to receive any errors
 530 * @return the length of the output string, not including any terminating nul.
 531 * @see unum_parse
 532 * @see unum_parseInt64
 533 * @see unum_format
 534 * @see unum_formatInt64
 535 * @see unum_formatDouble
 536 * @stable ICU 4.4
 537 */
 538 U_STABLE int32_t U_EXPORT2
 539 unum_parseDecimal(const   UNumberFormat*  fmt,
 540                  const   UChar*          text,
 541                          int32_t         textLength,
 542                          int32_t         *parsePos /* 0 = start */,
 543                          char            *outBuf,
 544                          int32_t         outBufLength,
 545                          UErrorCode      *status);
 546
 547 /**
 548  * Parse a string into a double and a currency using a UNumberFormat.
 549  * The string will be parsed according to the UNumberFormat's locale.
 550  * @param fmt the formatter to use
 551  * @param text the text to parse
 552  * @param textLength the length of text, or -1 if null-terminated
 553  * @param parsePos a pointer to an offset index into text at which to
 554  * begin parsing. On output, *parsePos will point after the last
 555  * parsed character.  This parameter may be 0, in which case parsing
 556  * begins at offset 0.
 557  * @param currency a pointer to the buffer to receive the parsed null-
 558  * terminated currency.  This buffer must have a capacity of at least
 559  * 4 UChars.
 560  * @param status a pointer to an input-output UErrorCode
 561  * @return the parsed double
 562  * @see unum_parseDouble
 563  * @see unum_formatDoubleCurrency
 564  * @stable ICU 3.0
 565  */
 566 U_STABLE double U_EXPORT2
 567 unum_parseDoubleCurrency(const UNumberFormat* fmt,
 568                          const UChar* text,
 569                          int32_t textLength,
 570                          int32_t* parsePos, /* 0 = start */
 571                          UChar* currency,
 572                          UErrorCode* status);
 573
 574 /**
 575  * Set the pattern used by a UNumberFormat.  This can only be used
 576  * on a DecimalFormat, other formats return U_ILLEGAL_ARGUMENT_ERROR
 577  * in the status.
 578  * @param format The formatter to set.
 579  * @param localized TRUE if the pattern is localized, FALSE otherwise.
 580  * @param pattern The new pattern
 581  * @param patternLength The length of pattern, or -1 if null-terminated.
 582  * @param parseError A pointer to UParseError to recieve information
 583  * about errors occurred during parsing, or NULL if no parse error
 584  * information is desired.
 585  * @param status A pointer to an input-output UErrorCode.
 586  * @see unum_toPattern
 587  * @see DecimalFormat
 588  * @stable ICU 2.0
 589  */
 590 U_STABLE void U_EXPORT2
 591 unum_applyPattern(          UNumberFormat  *format,
 592                             UBool          localized,
 593                     const   UChar          *pattern,
 594                             int32_t         patternLength,
 595                             UParseError    *parseError,
 596                             UErrorCode     *status
 597                                     );
 598
 599 /**
 600 * Get a locale for which decimal formatting patterns are available.
 601 * A UNumberFormat in a locale returned by this function will perform the correct
 602 * formatting and parsing for the locale.  The results of this call are not
 603 * valid for rule-based number formats.
 604 * @param localeIndex The index of the desired locale.
 605 * @return A locale for which number formatting patterns are available, or 0 if none.
 606 * @see unum_countAvailable
 607 * @stable ICU 2.0
 608 */
 609 U_STABLE const char* U_EXPORT2
 610 unum_getAvailable(int32_t localeIndex);
 611
 612 /**
 613 * Determine how many locales have decimal formatting patterns available.  The
 614 * results of this call are not valid for rule-based number formats.
 615 * This function is useful for determining the loop ending condition for
 616 * calls to {@link #unum_getAvailable }.
 617 * @return The number of locales for which decimal formatting patterns are available.
 618 * @see unum_getAvailable
 619 * @stable ICU 2.0
 620 */
 621 U_STABLE int32_t U_EXPORT2
 622 unum_countAvailable(void);
 623
 624 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */
 625 typedef enum UNumberFormatAttribute {
 626   /** Parse integers only */
 627   UNUM_PARSE_INT_ONLY,
 628   /** Use grouping separator */
 629   UNUM_GROUPING_USED,
 630   /** Always show decimal point */
 631   UNUM_DECIMAL_ALWAYS_SHOWN,
 632   /** Maximum integer digits */
 633   UNUM_MAX_INTEGER_DIGITS,
 634   /** Minimum integer digits */
 635   UNUM_MIN_INTEGER_DIGITS,
 636   /** Integer digits */
 637   UNUM_INTEGER_DIGITS,
 638   /** Maximum fraction digits */
 639   UNUM_MAX_FRACTION_DIGITS,
 640   /** Minimum fraction digits */
 641   UNUM_MIN_FRACTION_DIGITS,
 642   /** Fraction digits */
 643   UNUM_FRACTION_DIGITS,
 644   /** Multiplier */
 645   UNUM_MULTIPLIER,
 646   /** Grouping size */
 647   UNUM_GROUPING_SIZE,
 648   /** Rounding Mode */
 649   UNUM_ROUNDING_MODE,
 650   /** Rounding increment */
 651   UNUM_ROUNDING_INCREMENT,
 652   /** The width to which the output of <code>format()</code> is padded. */
 653   UNUM_FORMAT_WIDTH,
 654   /** The position at which padding will take place. */
 655   UNUM_PADDING_POSITION,
 656   /** Secondary grouping size */
 657   UNUM_SECONDARY_GROUPING_SIZE,
 658   /** Use significant digits
 659    * @stable ICU 3.0 */
 660   UNUM_SIGNIFICANT_DIGITS_USED,
 661   /** Minimum significant digits
 662    * @stable ICU 3.0 */
 663   UNUM_MIN_SIGNIFICANT_DIGITS,
 664   /** Maximum significant digits
 665    * @stable ICU 3.0 */
 666   UNUM_MAX_SIGNIFICANT_DIGITS,
 667   /** Lenient parse mode used by rule-based formats.
 668    * @stable ICU 3.0
 669    */
 670   UNUM_LENIENT_PARSE
 671 } UNumberFormatAttribute;
 672
 673 /**
 674 * Get a numeric attribute associated with a UNumberFormat.
 675 * An example of a numeric attribute is the number of integer digits a formatter will produce.
 676 * @param fmt The formatter to query.
 677 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
 678 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
 679 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
 680 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE.
 681 * @return The value of attr.
 682 * @see unum_setAttribute
 683 * @see unum_getDoubleAttribute
 684 * @see unum_setDoubleAttribute
 685 * @see unum_getTextAttribute
 686 * @see unum_setTextAttribute
 687 * @stable ICU 2.0
 688 */
 689 U_STABLE int32_t U_EXPORT2
 690 unum_getAttribute(const UNumberFormat*          fmt,
 691           UNumberFormatAttribute  attr);
 692
 693 /**
 694 * Set a numeric attribute associated with a UNumberFormat.
 695 * An example of a numeric attribute is the number of integer digits a formatter will produce.  If the
 696 * formatter does not understand the attribute, the call is ignored.  Rule-based formatters only understand
 697 * the lenient-parse attribute.
 698 * @param fmt The formatter to set.
 699 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
 700 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
 701 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
 702 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
 703 * or UNUM_LENIENT_PARSE.
 704 * @param newValue The new value of attr.
 705 * @see unum_getAttribute
 706 * @see unum_getDoubleAttribute
 707 * @see unum_setDoubleAttribute
 708 * @see unum_getTextAttribute
 709 * @see unum_setTextAttribute
 710 * @stable ICU 2.0
 711 */
 712 U_STABLE void U_EXPORT2
 713 unum_setAttribute(    UNumberFormat*          fmt,
 714             UNumberFormatAttribute  attr,
 715             int32_t                 newValue);
 716
 717
 718 /**
 719 * Get a numeric attribute associated with a UNumberFormat.
 720 * An example of a numeric attribute is the number of integer digits a formatter will produce.
 721 * If the formatter does not understand the attribute, -1 is returned.
 722 * @param fmt The formatter to query.
 723 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT.
 724 * @return The value of attr.
 725 * @see unum_getAttribute
 726 * @see unum_setAttribute
 727 * @see unum_setDoubleAttribute
 728 * @see unum_getTextAttribute
 729 * @see unum_setTextAttribute
 730 * @stable ICU 2.0
 731 */
 732 U_STABLE double U_EXPORT2
 733 unum_getDoubleAttribute(const UNumberFormat*          fmt,
 734           UNumberFormatAttribute  attr);
 735
 736 /**
 737 * Set a numeric attribute associated with a UNumberFormat.
 738 * An example of a numeric attribute is the number of integer digits a formatter will produce.
 739 * If the formatter does not understand the attribute, this call is ignored.
 740 * @param fmt The formatter to set.
 741 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT.
 742 * @param newValue The new value of attr.
 743 * @see unum_getAttribute
 744 * @see unum_setAttribute
 745 * @see unum_getDoubleAttribute
 746 * @see unum_getTextAttribute
 747 * @see unum_setTextAttribute
 748 * @stable ICU 2.0
 749 */
 750 U_STABLE void U_EXPORT2
 751 unum_setDoubleAttribute(    UNumberFormat*          fmt,
 752             UNumberFormatAttribute  attr,
 753             double                 newValue);
 754
 755 /** The possible UNumberFormat text attributes @stable ICU 2.0*/
 756 typedef enum UNumberFormatTextAttribute {
 757   /** Positive prefix */
 758   UNUM_POSITIVE_PREFIX,
 759   /** Positive suffix */
 760   UNUM_POSITIVE_SUFFIX,
 761   /** Negative prefix */
 762   UNUM_NEGATIVE_PREFIX,
 763   /** Negative suffix */
 764   UNUM_NEGATIVE_SUFFIX,
 765   /** The character used to pad to the format width. */
 766   UNUM_PADDING_CHARACTER,
 767   /** The ISO currency code */
 768   UNUM_CURRENCY_CODE,
 769   /**
 770    * The default rule set.  This is only available with rule-based formatters.
 771    * @stable ICU 3.0
 772    */
 773   UNUM_DEFAULT_RULESET,
 774   /**
 775    * The public rule sets.  This is only available with rule-based formatters.
 776    * This is a read-only attribute.  The public rulesets are returned as a
 777    * single string, with each ruleset name delimited by ';' (semicolon).
 778    * @stable ICU 3.0
 779    */
 780   UNUM_PUBLIC_RULESETS
 781 } UNumberFormatTextAttribute;
 782
 783 /**
 784 * Get a text attribute associated with a UNumberFormat.
 785 * An example of a text attribute is the suffix for positive numbers.  If the formatter
 786 * does not understand the attributre, U_UNSUPPORTED_ERROR is returned as the status.
 787 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS.
 788 * @param fmt The formatter to query.
 789 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
 790 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
 791 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS.
 792 * @param result A pointer to a buffer to receive the attribute.
 793 * @param resultLength The maximum size of result.
 794 * @param status A pointer to an UErrorCode to receive any errors
 795 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 796 * @see unum_setTextAttribute
 797 * @see unum_getAttribute
 798 * @see unum_setAttribute
 799 * @stable ICU 2.0
 800 */
 801 U_STABLE int32_t U_EXPORT2
 802 unum_getTextAttribute(    const    UNumberFormat*                    fmt,
 803             UNumberFormatTextAttribute      tag,
 804             UChar*                            result,
 805             int32_t                            resultLength,
 806             UErrorCode*                        status);
 807
 808 /**
 809 * Set a text attribute associated with a UNumberFormat.
 810 * An example of a text attribute is the suffix for positive numbers.  Rule-based formatters
 811 * only understand UNUM_DEFAULT_RULESET.
 812 * @param fmt The formatter to set.
 813 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
 814 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
 815 * or UNUM_DEFAULT_RULESET.
 816 * @param newValue The new value of attr.
 817 * @param newValueLength The length of newValue, or -1 if null-terminated.
 818 * @param status A pointer to an UErrorCode to receive any errors
 819 * @see unum_getTextAttribute
 820 * @see unum_getAttribute
 821 * @see unum_setAttribute
 822 * @stable ICU 2.0
 823 */
 824 U_STABLE void U_EXPORT2
 825 unum_setTextAttribute(    UNumberFormat*                    fmt,
 826             UNumberFormatTextAttribute      tag,
 827             const    UChar*                            newValue,
 828             int32_t                            newValueLength,
 829             UErrorCode                        *status);
 830
 831 /**
 832  * Extract the pattern from a UNumberFormat.  The pattern will follow
 833  * the DecimalFormat pattern syntax.
 834  * @param fmt The formatter to query.
 835  * @param isPatternLocalized TRUE if the pattern should be localized,
 836  * FALSE otherwise.  This is ignored if the formatter is a rule-based
 837  * formatter.
 838  * @param result A pointer to a buffer to receive the pattern.
 839  * @param resultLength The maximum size of result.
 840  * @param status A pointer to an input-output UErrorCode.
 841  * @return The total buffer size needed; if greater than resultLength,
 842  * the output was truncated.
 843  * @see unum_applyPattern
 844  * @see DecimalFormat
 845  * @stable ICU 2.0
 846  */
 847 U_STABLE int32_t U_EXPORT2
 848 unum_toPattern(    const    UNumberFormat*          fmt,
 849         UBool                  isPatternLocalized,
 850         UChar*                  result,
 851         int32_t                 resultLength,
 852         UErrorCode*             status);
 853
 854
 855 /**
 856  * Constants for specifying a number format symbol.
 857  * @stable ICU 2.0
 858  */
 859 typedef enum UNumberFormatSymbol {
 860   /** The decimal separator */
 861   UNUM_DECIMAL_SEPARATOR_SYMBOL = 0,
 862   /** The grouping separator */
 863   UNUM_GROUPING_SEPARATOR_SYMBOL = 1,
 864   /** The pattern separator */
 865   UNUM_PATTERN_SEPARATOR_SYMBOL = 2,
 866   /** The percent sign */
 867   UNUM_PERCENT_SYMBOL = 3,
 868   /** Zero*/
 869   UNUM_ZERO_DIGIT_SYMBOL = 4,
 870   /** Character representing a digit in the pattern */
 871   UNUM_DIGIT_SYMBOL = 5,
 872   /** The minus sign */
 873   UNUM_MINUS_SIGN_SYMBOL = 6,
 874   /** The plus sign */
 875   UNUM_PLUS_SIGN_SYMBOL = 7,
 876   /** The currency symbol */
 877   UNUM_CURRENCY_SYMBOL = 8,
 878   /** The international currency symbol */
 879   UNUM_INTL_CURRENCY_SYMBOL = 9,
 880   /** The monetary separator */
 881   UNUM_MONETARY_SEPARATOR_SYMBOL = 10,
 882   /** The exponential symbol */
 883   UNUM_EXPONENTIAL_SYMBOL = 11,
 884   /** Per mill symbol */
 885   UNUM_PERMILL_SYMBOL = 12,
 886   /** Escape padding character */
 887   UNUM_PAD_ESCAPE_SYMBOL = 13,
 888   /** Infinity symbol */
 889   UNUM_INFINITY_SYMBOL = 14,
 890   /** Nan symbol */
 891   UNUM_NAN_SYMBOL = 15,
 892   /** Significant digit symbol
 893    * @stable ICU 3.0 */
 894   UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16,
 895   /** The monetary grouping separator
 896    * @stable ICU 3.6
 897    */
 898   UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17,
 899   /** One
 900    * @draft ICU 4.6
 901    */
 902   UNUM_ONE_DIGIT_SYMBOL = 18,
 903   /** Two
 904    * @draft ICU 4.6
 905    */
 906   UNUM_TWO_DIGIT_SYMBOL = 19,
 907   /** Three
 908    * @draft ICU 4.6
 909    */
 910   UNUM_THREE_DIGIT_SYMBOL = 20,
 911   /** Four
 912    * @draft ICU 4.6
 913    */
 914   UNUM_FOUR_DIGIT_SYMBOL = 21,
 915   /** Five
 916    * @draft ICU 4.6
 917    */
 918   UNUM_FIVE_DIGIT_SYMBOL = 22,
 919   /** Six
 920    * @draft ICU 4.6
 921    */
 922   UNUM_SIX_DIGIT_SYMBOL = 23,
 923   /** Seven
 924     * @draft ICU 4.6
 925    */
 926   UNUM_SEVEN_DIGIT_SYMBOL = 24,
 927   /** Eight
 928    * @draft ICU 4.6
 929    */
 930   UNUM_EIGHT_DIGIT_SYMBOL = 25,
 931   /** Nine
 932    * @draft ICU 4.6
 933    */
 934   UNUM_NINE_DIGIT_SYMBOL = 26,
 935   /** count symbol constants */
 936   UNUM_FORMAT_SYMBOL_COUNT = 27
 937 } UNumberFormatSymbol;
 938
 939 /**
 940 * Get a symbol associated with a UNumberFormat.
 941 * A UNumberFormat uses symbols to represent the special locale-dependent
 942 * characters in a number, for example the percent sign. This API is not
 943 * supported for rule-based formatters.
 944 * @param fmt The formatter to query.
 945 * @param symbol The UNumberFormatSymbol constant for the symbol to get
 946 * @param buffer The string buffer that will receive the symbol string;
 947 *               if it is NULL, then only the length of the symbol is returned
 948 * @param size The size of the string buffer
 949 * @param status A pointer to an UErrorCode to receive any errors
 950 * @return The length of the symbol; the buffer is not modified if
 951 *         <code>length&gt;=size</code>
 952 * @see unum_setSymbol
 953 * @stable ICU 2.0
 954 */
 955 U_STABLE int32_t U_EXPORT2
 956 unum_getSymbol(const UNumberFormat *fmt,
 957                UNumberFormatSymbol symbol,
 958                UChar *buffer,
 959                int32_t size,
 960                UErrorCode *status);
 961
 962 /**
 963 * Set a symbol associated with a UNumberFormat.
 964 * A UNumberFormat uses symbols to represent the special locale-dependent
 965 * characters in a number, for example the percent sign.  This API is not
 966 * supported for rule-based formatters.
 967 * @param fmt The formatter to set.
 968 * @param symbol The UNumberFormatSymbol constant for the symbol to set
 969 * @param value The string to set the symbol to
 970 * @param length The length of the string, or -1 for a zero-terminated string
 971 * @param status A pointer to an UErrorCode to receive any errors.
 972 * @see unum_getSymbol
 973 * @stable ICU 2.0
 974 */
 975 U_STABLE void U_EXPORT2
 976 unum_setSymbol(UNumberFormat *fmt,
 977                UNumberFormatSymbol symbol,
 978                const UChar *value,
 979                int32_t length,
 980                UErrorCode *status);
 981
 982
 983 /**
 984  * Get the locale for this number format object.
 985  * You can choose between valid and actual locale.
 986  * @param fmt The formatter to get the locale from
 987  * @param type type of the locale we're looking for (valid or actual)
 988  * @param status error code for the operation
 989  * @return the locale name
 990  * @stable ICU 2.8
 991  */
 992 U_STABLE const char* U_EXPORT2
 993 unum_getLocaleByType(const UNumberFormat *fmt,
 994                      ULocDataLocaleType type,
 995                      UErrorCode* status);
 996
 997 #endif /* #if !UCONFIG_NO_FORMATTING */
 998
 999 #endif