icuSources/i18n/unicode/unum.h

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