icuSources/i18n/unicode/unum.h

   1 /*
   2 *******************************************************************************
   3 * Copyright (C) 1997-2008, 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/uloc.h"
  20 #include "unicode/umisc.h"
  21 #include "unicode/parseerr.h"
  22 /**
  23  * \file
  24  * \brief C API: NumberFormat
  25  *
  26  * <h2> Number Format C API </h2>
  27  *
  28  * Number Format C API  Provides functions for
  29  * formatting and parsing a number.  Also provides methods for
  30  * determining which locales have number formats, and what their names
  31  * are.
  32  * <P>
  33  * UNumberFormat helps you to format and parse numbers for any locale.
  34  * Your code can be completely independent of the locale conventions
  35  * for decimal points, thousands-separators, or even the particular
  36  * decimal digits used, or whether the number format is even decimal.
  37  * There are different number format styles like decimal, currency,
  38  * percent and spellout.
  39  * <P>
  40  * To format a number for the current Locale, use one of the static
  41  * factory methods:
  42  * <pre>
  43  * \code
  44  *    UChar myString[20];
  45  *    double myNumber = 7.0;
  46  *    UErrorCode status = U_ZERO_ERROR;
  47  *    UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
  48  *    unum_formatDouble(nf, myNumber, myString, 20, NULL, &status);
  49  *    printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*)
  50  * \endcode
  51  * </pre>
  52  * If you are formatting multiple numbers, it is more efficient to get
  53  * the format and use it multiple times so that the system doesn't
  54  * have to fetch the information about the local language and country
  55  * conventions multiple times.
  56  * <pre>
  57  * \code
  58  * uint32_t i, resultlength, reslenneeded;
  59  * UErrorCode status = U_ZERO_ERROR;
  60  * UFieldPosition pos;
  61  * uint32_t a[] = { 123, 3333, -1234567 };
  62  * const uint32_t a_len = sizeof(a) / sizeof(a[0]);
  63  * UNumberFormat* nf;
  64  * UChar* result = NULL;
  65  *
  66  * nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
  67  * for (i = 0; i < a_len; i++) {
  68  *    resultlength=0;
  69  *    reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status);
  70  *    result = NULL;
  71  *    if(status==U_BUFFER_OVERFLOW_ERROR){
  72  *       status=U_ZERO_ERROR;
  73  *       resultlength=reslenneeded+1;
  74  *       result=(UChar*)malloc(sizeof(UChar) * resultlength);
  75  *       unum_format(nf, a[i], result, resultlength, &pos, &status);
  76  *    }
  77  *    printf( " Example 2: %s\n", austrdup(result));
  78  *    free(result);
  79  * }
  80  * \endcode
  81  * </pre>
  82  * To format a number for a different Locale, specify it in the
  83  * call to unum_open().
  84  * <pre>
  85  * \code
  86  *     UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, "fr_FR", NULL, &success)
  87  * \endcode
  88  * </pre>
  89  * You can use a NumberFormat API unum_parse() to parse.
  90  * <pre>
  91  * \code
  92  *    UErrorCode status = U_ZERO_ERROR;
  93  *    int32_t pos=0;
  94  *    int32_t num;
  95  *    num = unum_parse(nf, str, u_strlen(str), &pos, &status);
  96  * \endcode
  97  * </pre>
  98  * Use UNUM_DECIMAL to get the normal number format for that country.
  99  * There are other static options available.  Use UNUM_CURRENCY
 100  * to get the currency number format for that country.  Use UNUM_PERCENT
 101  * to get a format for displaying percentages. With this format, a
 102  * fraction from 0.53 is displayed as 53%.
 103  * <P>
 104  * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat
 105  * formatter.  The pattern must conform to the syntax defined for those
 106  * formatters.
 107  * <P>
 108  * You can also control the display of numbers with such function as
 109  * unum_getAttribues() and unum_setAtributes(), which let you set the
 110  * miminum fraction digits, grouping, etc.
 111  * @see UNumberFormatAttributes for more details
 112  * <P>
 113  * You can also use forms of the parse and format methods with
 114  * ParsePosition and UFieldPosition to allow you to:
 115  * <ul type=round>
 116  *   <li>(a) progressively parse through pieces of a string.
 117  *   <li>(b) align the decimal point and other areas.
 118  * </ul>
 119  * <p>
 120  * It is also possible to change or set the symbols used for a particular
 121  * locale like the currency symbol, the grouping seperator , monetary seperator
 122  * etc by making use of functions unum_setSymbols() and unum_getSymbols().
 123  */
 124
 125 /** A number formatter.
 126  *  For usage in C programs.
 127  *  @stable ICU 2.0
 128  */
 129 typedef void* UNumberFormat;
 130
 131 /** The possible number format styles.
 132  *  @stable ICU 2.0
 133  */
 134 typedef enum UNumberFormatStyle {
 135     /**
 136      * Decimal format defined by pattern
 137      * @stable ICU 3.0
 138      */
 139     UNUM_PATTERN_DECIMAL=0,
 140     /** Decimal format */
 141     UNUM_DECIMAL=1,
 142     /** Currency format */
 143     UNUM_CURRENCY,
 144     /** Percent format */
 145     UNUM_PERCENT,
 146     /** Scientific format */
 147     UNUM_SCIENTIFIC,
 148     /** Spellout rule-based format */
 149     UNUM_SPELLOUT,
 150     /**
 151      * Ordinal rule-based format
 152      * @stable ICU 3.0
 153      */
 154     UNUM_ORDINAL,
 155     /**
 156      * Duration rule-based format
 157      * @stable ICU 3.0
 158      */
 159     UNUM_DURATION,
 160     /**
 161      * Rule-based format defined by pattern
 162      * @stable ICU 3.0
 163      */
 164     UNUM_PATTERN_RULEBASED,
 165     /** Default format */
 166     UNUM_DEFAULT = UNUM_DECIMAL,
 167     /** (Alias for UNUM_PATTERN_DECIMAL) */
 168     UNUM_IGNORE = UNUM_PATTERN_DECIMAL
 169 } UNumberFormatStyle;
 170
 171 /** The possible number format rounding modes.
 172  *  @stable ICU 2.0
 173  */
 174 typedef enum UNumberFormatRoundingMode {
 175     UNUM_ROUND_CEILING,
 176     UNUM_ROUND_FLOOR,
 177     UNUM_ROUND_DOWN,
 178     UNUM_ROUND_UP,
 179     /**
 180      * Half-even rounding, misspelled name
 181      * @deprecated, ICU 3.8
 182      */
 183     UNUM_FOUND_HALFEVEN,
 184     UNUM_ROUND_HALFDOWN,
 185     UNUM_ROUND_HALFUP,
 186     /**
 187      * Half-even rounding
 188      * @stable, ICU 3.8
 189      */
 190     UNUM_ROUND_HALFEVEN = UNUM_FOUND_HALFEVEN
 191 } UNumberFormatRoundingMode;
 192
 193 /** The possible number format pad positions.
 194  *  @stable ICU 2.0
 195  */
 196 typedef enum UNumberFormatPadPosition {
 197     UNUM_PAD_BEFORE_PREFIX,
 198     UNUM_PAD_AFTER_PREFIX,
 199     UNUM_PAD_BEFORE_SUFFIX,
 200     UNUM_PAD_AFTER_SUFFIX
 201 } UNumberFormatPadPosition;
 202
 203 /**
 204  * Create and return a new UNumberFormat for formatting and parsing
 205  * numbers.  A UNumberFormat may be used to format numbers by calling
 206  * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }.
 207  * The caller must call {@link #unum_close } when done to release resources
 208  * used by this object.
 209  * @param style The type of number format to open: one of
 210  * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT,
 211  * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT.
 212  * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the
 213  * number format is opened using the given pattern, which must conform
 214  * to the syntax described in DecimalFormat or RuleBasedNumberFormat,
 215  * respectively.
 216  * @param pattern A pattern specifying the format to use.
 217  * This parameter is ignored unless the style is
 218  * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
 219  * @param patternLength The number of characters in the pattern, or -1
 220  * if null-terminated. This parameter is ignored unless the style is
 221  * UNUM_PATTERN.
 222  * @param locale A locale identifier to use to determine formatting
 223  * and parsing conventions, or NULL to use the default locale.
 224  * @param parseErr A pointer to a UParseError struct to receive the
 225  * details of any parsing errors, or NULL if no parsing error details
 226  * are desired.
 227  * @param status A pointer to an input-output UErrorCode.
 228  * @return A pointer to a newly created UNumberFormat, or NULL if an
 229  * error occurred.
 230  * @see unum_close
 231  * @see DecimalFormat
 232  * @stable ICU 2.0
 233  */
 234 U_STABLE UNumberFormat* U_EXPORT2
 235 unum_open(  UNumberFormatStyle    style,
 236             const    UChar*    pattern,
 237             int32_t            patternLength,
 238             const    char*     locale,
 239             UParseError*       parseErr,
 240             UErrorCode*        status);
 241
 242
 243 /**
 244 * Close a UNumberFormat.
 245 * Once closed, a UNumberFormat may no longer be used.
 246 * @param fmt The formatter to close.
 247 * @stable ICU 2.0
 248 */
 249 U_STABLE void U_EXPORT2
 250 unum_close(UNumberFormat* fmt);
 251
 252 /**
 253  * Open a copy of a UNumberFormat.
 254  * This function performs a deep copy.
 255  * @param fmt The format to copy
 256  * @param status A pointer to an UErrorCode to receive any errors.
 257  * @return A pointer to a UNumberFormat identical to fmt.
 258  * @stable ICU 2.0
 259  */
 260 U_STABLE UNumberFormat* U_EXPORT2
 261 unum_clone(const UNumberFormat *fmt,
 262        UErrorCode *status);
 263
 264 /**
 265 * Format an integer using a UNumberFormat.
 266 * The integer will be formatted according to the UNumberFormat's locale.
 267 * @param fmt The formatter to use.
 268 * @param number The number to format.
 269 * @param result A pointer to a buffer to receive the formatted number.
 270 * @param resultLength The maximum size of result.
 271 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 272 * is read.  On output, position->beginIndex and position->endIndex indicate
 273 * the beginning and ending indices of field number position->field, if such
 274 * a field exists.  This parameter may be NULL, in which case no field
 275 * @param status A pointer to an UErrorCode to receive any errors
 276 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 277 * @see unum_formatInt64
 278 * @see unum_formatDouble
 279 * @see unum_parse
 280 * @see unum_parseInt64
 281 * @see unum_parseDouble
 282 * @see UFieldPosition
 283 * @stable ICU 2.0
 284 */
 285 U_STABLE int32_t U_EXPORT2
 286 unum_format(    const    UNumberFormat*    fmt,
 287         int32_t            number,
 288         UChar*            result,
 289         int32_t            resultLength,
 290         UFieldPosition    *pos,
 291         UErrorCode*        status);
 292
 293 /**
 294 * Format an int64 using a UNumberFormat.
 295 * The int64 will be formatted according to the UNumberFormat's locale.
 296 * @param fmt The formatter to use.
 297 * @param number The number to format.
 298 * @param result A pointer to a buffer to receive the formatted number.
 299 * @param resultLength The maximum size of result.
 300 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 301 * is read.  On output, position->beginIndex and position->endIndex indicate
 302 * the beginning and ending indices of field number position->field, if such
 303 * a field exists.  This parameter may be NULL, in which case no field
 304 * @param status A pointer to an UErrorCode to receive any errors
 305 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 306 * @see unum_format
 307 * @see unum_formatDouble
 308 * @see unum_parse
 309 * @see unum_parseInt64
 310 * @see unum_parseDouble
 311 * @see UFieldPosition
 312 * @stable ICU 2.0
 313 */
 314 U_STABLE int32_t U_EXPORT2
 315 unum_formatInt64(const UNumberFormat *fmt,
 316         int64_t         number,
 317         UChar*          result,
 318         int32_t         resultLength,
 319         UFieldPosition *pos,
 320         UErrorCode*     status);
 321
 322 /**
 323 * Format a double using a UNumberFormat.
 324 * The double will be formatted according to the UNumberFormat's locale.
 325 * @param fmt The formatter to use.
 326 * @param number The number to format.
 327 * @param result A pointer to a buffer to receive the formatted number.
 328 * @param resultLength The maximum size of result.
 329 * @param pos    A pointer to a UFieldPosition.  On input, position->field
 330 * is read.  On output, position->beginIndex and position->endIndex indicate
 331 * the beginning and ending indices of field number position->field, if such
 332 * a field exists.  This parameter may be NULL, in which case no field
 333 * @param status A pointer to an UErrorCode to receive any errors
 334 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 335 * @see unum_format
 336 * @see unum_formatInt64
 337 * @see unum_parse
 338 * @see unum_parseInt64
 339 * @see unum_parseDouble
 340 * @see UFieldPosition
 341 * @stable ICU 2.0
 342 */
 343 U_STABLE int32_t U_EXPORT2
 344 unum_formatDouble(    const    UNumberFormat*  fmt,
 345             double          number,
 346             UChar*          result,
 347             int32_t         resultLength,
 348             UFieldPosition  *pos, /* 0 if ignore */
 349             UErrorCode*     status);
 350
 351 /**
 352  * Format a double currency amount using a UNumberFormat.
 353  * The double will be formatted according to the UNumberFormat's locale.
 354  * @param fmt the formatter to use
 355  * @param number the number to format
 356  * @param currency the 3-letter null-terminated ISO 4217 currency code
 357  * @param result a pointer to the buffer to receive the formatted number
 358  * @param resultLength the maximum number of UChars to write to result
 359  * @param pos a pointer to a UFieldPosition.  On input,
 360  * position->field is read.  On output, position->beginIndex and
 361  * position->endIndex indicate the beginning and ending indices of
 362  * field number position->field, if such a field exists.  This
 363  * parameter may be NULL, in which case it is ignored.
 364  * @param status a pointer to an input-output UErrorCode
 365  * @return the total buffer size needed; if greater than resultLength,
 366  * the output was truncated.
 367  * @see unum_formatDouble
 368  * @see unum_parseDoubleCurrency
 369  * @see UFieldPosition
 370  * @stable ICU 3.0
 371  */
 372 U_STABLE int32_t U_EXPORT2
 373 unum_formatDoubleCurrency(const UNumberFormat* fmt,
 374                           double number,
 375                           UChar* currency,
 376                           UChar* result,
 377                           int32_t resultLength,
 378                           UFieldPosition* pos, /* ignored if 0 */
 379                           UErrorCode* status);
 380
 381 /**
 382 * Parse a string into an integer using a UNumberFormat.
 383 * The string will be parsed according to the UNumberFormat's locale.
 384 * @param fmt The formatter to use.
 385 * @param text The text to parse.
 386 * @param textLength The length of text, or -1 if null-terminated.
 387 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
 388 * to begin parsing.  If not 0, on output the offset at which parsing ended.
 389 * @param status A pointer to an UErrorCode to receive any errors
 390 * @return The value of the parsed integer
 391 * @see unum_parseInt64
 392 * @see unum_parseDouble
 393 * @see unum_format
 394 * @see unum_formatInt64
 395 * @see unum_formatDouble
 396 * @stable ICU 2.0
 397 */
 398 U_STABLE int32_t U_EXPORT2
 399 unum_parse(    const   UNumberFormat*  fmt,
 400         const   UChar*          text,
 401         int32_t         textLength,
 402         int32_t         *parsePos /* 0 = start */,
 403         UErrorCode      *status);
 404
 405 /**
 406 * Parse a string into an int64 using a UNumberFormat.
 407 * The string will be parsed according to the UNumberFormat's locale.
 408 * @param fmt The formatter to use.
 409 * @param text The text to parse.
 410 * @param textLength The length of text, or -1 if null-terminated.
 411 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
 412 * to begin parsing.  If not 0, on output the offset at which parsing ended.
 413 * @param status A pointer to an UErrorCode to receive any errors
 414 * @return The value of the parsed integer
 415 * @see unum_parse
 416 * @see unum_parseDouble
 417 * @see unum_format
 418 * @see unum_formatInt64
 419 * @see unum_formatDouble
 420 * @stable ICU 2.8
 421 */
 422 U_STABLE int64_t U_EXPORT2
 423 unum_parseInt64(const UNumberFormat*  fmt,
 424         const UChar*  text,
 425         int32_t       textLength,
 426         int32_t       *parsePos /* 0 = start */,
 427         UErrorCode    *status);
 428
 429 /**
 430 * Parse a string into a double using a UNumberFormat.
 431 * The string will be parsed according to the UNumberFormat's locale.
 432 * @param fmt The formatter to use.
 433 * @param text The text to parse.
 434 * @param textLength The length of text, or -1 if null-terminated.
 435 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
 436 * to begin parsing.  If not 0, on output the offset at which parsing ended.
 437 * @param status A pointer to an UErrorCode to receive any errors
 438 * @return The value of the parsed double
 439 * @see unum_parse
 440 * @see unum_parseInt64
 441 * @see unum_format
 442 * @see unum_formatInt64
 443 * @see unum_formatDouble
 444 * @stable ICU 2.0
 445 */
 446 U_STABLE double U_EXPORT2
 447 unum_parseDouble(    const   UNumberFormat*  fmt,
 448             const   UChar*          text,
 449             int32_t         textLength,
 450             int32_t         *parsePos /* 0 = start */,
 451             UErrorCode      *status);
 452
 453 /**
 454  * Parse a string into a double and a currency using a UNumberFormat.
 455  * The string will be parsed according to the UNumberFormat's locale.
 456  * @param fmt the formatter to use
 457  * @param text the text to parse
 458  * @param textLength the length of text, or -1 if null-terminated
 459  * @param parsePos a pointer to an offset index into text at which to
 460  * begin parsing. On output, *parsePos will point after the last
 461  * parsed character.  This parameter may be 0, in which case parsing
 462  * begins at offset 0.
 463  * @param currency a pointer to the buffer to receive the parsed null-
 464  * terminated currency.  This buffer must have a capacity of at least
 465  * 4 UChars.
 466  * @param status a pointer to an input-output UErrorCode
 467  * @return the parsed double
 468  * @see unum_parseDouble
 469  * @see unum_formatDoubleCurrency
 470  * @stable ICU 3.0
 471  */
 472 U_STABLE double U_EXPORT2
 473 unum_parseDoubleCurrency(const UNumberFormat* fmt,
 474                          const UChar* text,
 475                          int32_t textLength,
 476                          int32_t* parsePos, /* 0 = start */
 477                          UChar* currency,
 478                          UErrorCode* status);
 479
 480 /**
 481  * Set the pattern used by a UNumberFormat.  This can only be used
 482  * on a DecimalFormat, other formats return U_ILLEGAL_ARGUMENT_ERROR
 483  * in the status.
 484  * @param format The formatter to set.
 485  * @param localized TRUE if the pattern is localized, FALSE otherwise.
 486  * @param pattern The new pattern
 487  * @param patternLength The length of pattern, or -1 if null-terminated.
 488  * @param parseError A pointer to UParseError to recieve information
 489  * about errors occurred during parsing, or NULL if no parse error
 490  * information is desired.
 491  * @param status A pointer to an input-output UErrorCode.
 492  * @see unum_toPattern
 493  * @see DecimalFormat
 494  * @stable ICU 2.0
 495  */
 496 U_STABLE void U_EXPORT2
 497 unum_applyPattern(          UNumberFormat  *format,
 498                             UBool          localized,
 499                     const   UChar          *pattern,
 500                             int32_t         patternLength,
 501                             UParseError    *parseError,
 502                             UErrorCode     *status
 503                                     );
 504
 505 /**
 506 * Get a locale for which decimal formatting patterns are available.
 507 * A UNumberFormat in a locale returned by this function will perform the correct
 508 * formatting and parsing for the locale.  The results of this call are not
 509 * valid for rule-based number formats.
 510 * @param index The index of the desired locale.
 511 * @return A locale for which number formatting patterns are available, or 0 if none.
 512 * @see unum_countAvailable
 513 * @stable ICU 2.0
 514 */
 515 U_STABLE const char* U_EXPORT2
 516 unum_getAvailable(int32_t index);
 517
 518 /**
 519 * Determine how many locales have decimal formatting patterns available.  The
 520 * results of this call are not valid for rule-based number formats.
 521 * This function is useful for determining the loop ending condition for
 522 * calls to {@link #unum_getAvailable }.
 523 * @return The number of locales for which decimal formatting patterns are available.
 524 * @see unum_getAvailable
 525 * @stable ICU 2.0
 526 */
 527 U_STABLE int32_t U_EXPORT2
 528 unum_countAvailable(void);
 529
 530 /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */
 531 typedef enum UNumberFormatAttribute {
 532   /** Parse integers only */
 533   UNUM_PARSE_INT_ONLY,
 534   /** Use grouping separator */
 535   UNUM_GROUPING_USED,
 536   /** Always show decimal point */
 537   UNUM_DECIMAL_ALWAYS_SHOWN,
 538   /** Maximum integer digits */
 539   UNUM_MAX_INTEGER_DIGITS,
 540   /** Minimum integer digits */
 541   UNUM_MIN_INTEGER_DIGITS,
 542   /** Integer digits */
 543   UNUM_INTEGER_DIGITS,
 544   /** Maximum fraction digits */
 545   UNUM_MAX_FRACTION_DIGITS,
 546   /** Minimum fraction digits */
 547   UNUM_MIN_FRACTION_DIGITS,
 548   /** Fraction digits */
 549   UNUM_FRACTION_DIGITS,
 550   /** Multiplier */
 551   UNUM_MULTIPLIER,
 552   /** Grouping size */
 553   UNUM_GROUPING_SIZE,
 554   /** Rounding Mode */
 555   UNUM_ROUNDING_MODE,
 556   /** Rounding increment */
 557   UNUM_ROUNDING_INCREMENT,
 558   /** The width to which the output of <code>format()</code> is padded. */
 559   UNUM_FORMAT_WIDTH,
 560   /** The position at which padding will take place. */
 561   UNUM_PADDING_POSITION,
 562   /** Secondary grouping size */
 563   UNUM_SECONDARY_GROUPING_SIZE,
 564   /** Use significant digits
 565    * @stable ICU 3.0 */
 566   UNUM_SIGNIFICANT_DIGITS_USED,
 567   /** Minimum significant digits
 568    * @stable ICU 3.0 */
 569   UNUM_MIN_SIGNIFICANT_DIGITS,
 570   /** Maximum significant digits
 571    * @stable ICU 3.0 */
 572   UNUM_MAX_SIGNIFICANT_DIGITS,
 573   /** Lenient parse mode used by rule-based formats.
 574    * @stable ICU 3.0
 575    */
 576   UNUM_LENIENT_PARSE
 577 } UNumberFormatAttribute;
 578
 579 /**
 580 * Get a numeric attribute associated with a UNumberFormat.
 581 * An example of a numeric attribute is the number of integer digits a formatter will produce.
 582 * @param fmt The formatter to query.
 583 * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
 584 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
 585 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
 586 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE.
 587 * @return The value of attr.
 588 * @see unum_setAttribute
 589 * @see unum_getDoubleAttribute
 590 * @see unum_setDoubleAttribute
 591 * @see unum_getTextAttribute
 592 * @see unum_setTextAttribute
 593 * @stable ICU 2.0
 594 */
 595 U_STABLE int32_t U_EXPORT2
 596 unum_getAttribute(const UNumberFormat*          fmt,
 597           UNumberFormatAttribute  attr);
 598
 599 /**
 600 * Set a numeric attribute associated with a UNumberFormat.
 601 * An example of a numeric attribute is the number of integer digits a formatter will produce.  If the
 602 * formatter does not understand the attribute, the call is ignored.  Rule-based formatters only understand
 603 * the lenient-parse attribute.
 604 * @param fmt The formatter to set.
 605 * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
 606 * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
 607 * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
 608 * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
 609 * or UNUM_LENIENT_PARSE.
 610 * @param newValue The new value of attr.
 611 * @see unum_getAttribute
 612 * @see unum_getDoubleAttribute
 613 * @see unum_setDoubleAttribute
 614 * @see unum_getTextAttribute
 615 * @see unum_setTextAttribute
 616 * @stable ICU 2.0
 617 */
 618 U_STABLE void U_EXPORT2
 619 unum_setAttribute(    UNumberFormat*          fmt,
 620             UNumberFormatAttribute  attr,
 621             int32_t                 newValue);
 622
 623
 624 /**
 625 * Get a numeric attribute associated with a UNumberFormat.
 626 * An example of a numeric attribute is the number of integer digits a formatter will produce.
 627 * If the formatter does not understand the attribute, -1 is returned.
 628 * @param fmt The formatter to query.
 629 * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT.
 630 * @return The value of attr.
 631 * @see unum_getAttribute
 632 * @see unum_setAttribute
 633 * @see unum_setDoubleAttribute
 634 * @see unum_getTextAttribute
 635 * @see unum_setTextAttribute
 636 * @stable ICU 2.0
 637 */
 638 U_STABLE double U_EXPORT2
 639 unum_getDoubleAttribute(const UNumberFormat*          fmt,
 640           UNumberFormatAttribute  attr);
 641
 642 /**
 643 * Set a numeric attribute associated with a UNumberFormat.
 644 * An example of a numeric attribute is the number of integer digits a formatter will produce.
 645 * If the formatter does not understand the attribute, this call is ignored.
 646 * @param fmt The formatter to set.
 647 * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT.
 648 * @param newValue The new value of attr.
 649 * @see unum_getAttribute
 650 * @see unum_setAttribute
 651 * @see unum_getDoubleAttribute
 652 * @see unum_getTextAttribute
 653 * @see unum_setTextAttribute
 654 * @stable ICU 2.0
 655 */
 656 U_STABLE void U_EXPORT2
 657 unum_setDoubleAttribute(    UNumberFormat*          fmt,
 658             UNumberFormatAttribute  attr,
 659             double                 newValue);
 660
 661 /** The possible UNumberFormat text attributes @stable ICU 2.0*/
 662 typedef enum UNumberFormatTextAttribute {
 663   /** Positive prefix */
 664   UNUM_POSITIVE_PREFIX,
 665   /** Positive suffix */
 666   UNUM_POSITIVE_SUFFIX,
 667   /** Negative prefix */
 668   UNUM_NEGATIVE_PREFIX,
 669   /** Negative suffix */
 670   UNUM_NEGATIVE_SUFFIX,
 671   /** The character used to pad to the format width. */
 672   UNUM_PADDING_CHARACTER,
 673   /** The ISO currency code */
 674   UNUM_CURRENCY_CODE,
 675   /**
 676    * The default rule set.  This is only available with rule-based formatters.
 677    * @stable ICU 3.0
 678    */
 679   UNUM_DEFAULT_RULESET,
 680   /**
 681    * The public rule sets.  This is only available with rule-based formatters.
 682    * This is a read-only attribute.  The public rulesets are returned as a
 683    * single string, with each ruleset name delimited by ';' (semicolon).
 684    * @stable ICU 3.0
 685    */
 686   UNUM_PUBLIC_RULESETS
 687 } UNumberFormatTextAttribute;
 688
 689 /**
 690 * Get a text attribute associated with a UNumberFormat.
 691 * An example of a text attribute is the suffix for positive numbers.  If the formatter
 692 * does not understand the attributre, U_UNSUPPORTED_ERROR is returned as the status.
 693 * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS.
 694 * @param fmt The formatter to query.
 695 * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
 696 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
 697 * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS.
 698 * @param result A pointer to a buffer to receive the attribute.
 699 * @param resultLength The maximum size of result.
 700 * @param status A pointer to an UErrorCode to receive any errors
 701 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
 702 * @see unum_setTextAttribute
 703 * @see unum_getAttribute
 704 * @see unum_setAttribute
 705 * @stable ICU 2.0
 706 */
 707 U_STABLE int32_t U_EXPORT2
 708 unum_getTextAttribute(    const    UNumberFormat*                    fmt,
 709             UNumberFormatTextAttribute      tag,
 710             UChar*                            result,
 711             int32_t                            resultLength,
 712             UErrorCode*                        status);
 713
 714 /**
 715 * Set a text attribute associated with a UNumberFormat.
 716 * An example of a text attribute is the suffix for positive numbers.  Rule-based formatters
 717 * only understand UNUM_DEFAULT_RULESET.
 718 * @param fmt The formatter to set.
 719 * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
 720 * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
 721 * or UNUM_DEFAULT_RULESET.
 722 * @param newValue The new value of attr.
 723 * @param newValueLength The length of newValue, or -1 if null-terminated.
 724 * @param status A pointer to an UErrorCode to receive any errors
 725 * @see unum_getTextAttribute
 726 * @see unum_getAttribute
 727 * @see unum_setAttribute
 728 * @stable ICU 2.0
 729 */
 730 U_STABLE void U_EXPORT2
 731 unum_setTextAttribute(    UNumberFormat*                    fmt,
 732             UNumberFormatTextAttribute      tag,
 733             const    UChar*                            newValue,
 734             int32_t                            newValueLength,
 735             UErrorCode                        *status);
 736
 737 /**
 738  * Extract the pattern from a UNumberFormat.  The pattern will follow
 739  * the DecimalFormat pattern syntax.
 740  * @param fmt The formatter to query.
 741  * @param isPatternLocalized TRUE if the pattern should be localized,
 742  * FALSE otherwise.  This is ignored if the formatter is a rule-based
 743  * formatter.
 744  * @param result A pointer to a buffer to receive the pattern.
 745  * @param resultLength The maximum size of result.
 746  * @param status A pointer to an input-output UErrorCode.
 747  * @return The total buffer size needed; if greater than resultLength,
 748  * the output was truncated.
 749  * @see unum_applyPattern
 750  * @see DecimalFormat
 751  * @stable ICU 2.0
 752  */
 753 U_STABLE int32_t U_EXPORT2
 754 unum_toPattern(    const    UNumberFormat*          fmt,
 755         UBool                  isPatternLocalized,
 756         UChar*                  result,
 757         int32_t                 resultLength,
 758         UErrorCode*             status);
 759
 760
 761 /**
 762  * Constants for specifying a number format symbol.
 763  * @stable ICU 2.0
 764  */
 765 typedef enum UNumberFormatSymbol {
 766   /** The decimal separator */
 767   UNUM_DECIMAL_SEPARATOR_SYMBOL = 0,
 768   /** The grouping separator */
 769   UNUM_GROUPING_SEPARATOR_SYMBOL = 1,
 770   /** The pattern separator */
 771   UNUM_PATTERN_SEPARATOR_SYMBOL = 2,
 772   /** The percent sign */
 773   UNUM_PERCENT_SYMBOL = 3,
 774   /** Zero*/
 775   UNUM_ZERO_DIGIT_SYMBOL = 4,
 776   /** Character representing a digit in the pattern */
 777   UNUM_DIGIT_SYMBOL = 5,
 778   /** The minus sign */
 779   UNUM_MINUS_SIGN_SYMBOL = 6,
 780   /** The plus sign */
 781   UNUM_PLUS_SIGN_SYMBOL = 7,
 782   /** The currency symbol */
 783   UNUM_CURRENCY_SYMBOL = 8,
 784   /** The international currency symbol */
 785   UNUM_INTL_CURRENCY_SYMBOL = 9,
 786   /** The monetary separator */
 787   UNUM_MONETARY_SEPARATOR_SYMBOL = 10,
 788   /** The exponential symbol */
 789   UNUM_EXPONENTIAL_SYMBOL = 11,
 790   /** Per mill symbol */
 791   UNUM_PERMILL_SYMBOL = 12,
 792   /** Escape padding character */
 793   UNUM_PAD_ESCAPE_SYMBOL = 13,
 794   /** Infinity symbol */
 795   UNUM_INFINITY_SYMBOL = 14,
 796   /** Nan symbol */
 797   UNUM_NAN_SYMBOL = 15,
 798   /** Significant digit symbol
 799    * @stable ICU 3.0 */
 800   UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16,
 801   /** The monetary grouping separator
 802    * @stable ICU 3.6
 803    */
 804   UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17,
 805   /** count symbol constants */
 806   UNUM_FORMAT_SYMBOL_COUNT = 18
 807 } UNumberFormatSymbol;
 808
 809 /**
 810 * Get a symbol associated with a UNumberFormat.
 811 * A UNumberFormat uses symbols to represent the special locale-dependent
 812 * characters in a number, for example the percent sign. This API is not
 813 * supported for rule-based formatters.
 814 * @param fmt The formatter to query.
 815 * @param symbol The UNumberFormatSymbol constant for the symbol to get
 816 * @param buffer The string buffer that will receive the symbol string;
 817 *               if it is NULL, then only the length of the symbol is returned
 818 * @param size The size of the string buffer
 819 * @param status A pointer to an UErrorCode to receive any errors
 820 * @return The length of the symbol; the buffer is not modified if
 821 *         <code>length&gt;=size</code>
 822 * @see unum_setSymbol
 823 * @stable ICU 2.0
 824 */
 825 U_STABLE int32_t U_EXPORT2
 826 unum_getSymbol(const UNumberFormat *fmt,
 827                UNumberFormatSymbol symbol,
 828                UChar *buffer,
 829                int32_t size,
 830                UErrorCode *status);
 831
 832 /**
 833 * Set a symbol associated with a UNumberFormat.
 834 * A UNumberFormat uses symbols to represent the special locale-dependent
 835 * characters in a number, for example the percent sign.  This API is not
 836 * supported for rule-based formatters.
 837 * @param fmt The formatter to set.
 838 * @param symbol The UNumberFormatSymbol constant for the symbol to set
 839 * @param value The string to set the symbol to
 840 * @param length The length of the string, or -1 for a zero-terminated string
 841 * @param status A pointer to an UErrorCode to receive any errors.
 842 * @see unum_getSymbol
 843 * @stable ICU 2.0
 844 */
 845 U_STABLE void U_EXPORT2
 846 unum_setSymbol(UNumberFormat *fmt,
 847                UNumberFormatSymbol symbol,
 848                const UChar *value,
 849                int32_t length,
 850                UErrorCode *status);
 851
 852
 853 /**
 854  * Get the locale for this number format object.
 855  * You can choose between valid and actual locale.
 856  * @param fmt The formatter to get the locale from
 857  * @param type type of the locale we're looking for (valid or actual)
 858  * @param status error code for the operation
 859  * @return the locale name
 860  * @stable ICU 2.8
 861  */
 862 U_STABLE const char* U_EXPORT2
 863 unum_getLocaleByType(const UNumberFormat *fmt,
 864                      ULocDataLocaleType type,
 865                      UErrorCode* status);
 866
 867 #endif /* #if !UCONFIG_NO_FORMATTING */
 868
 869 #endif