michael@0: /*
michael@0: *******************************************************************************
michael@0: * Copyright (C) 1997-2013, International Business Machines Corporation and others.
michael@0: * All Rights Reserved.
michael@0: * Modification History:
michael@0: *
michael@0: *   Date        Name        Description
michael@0: *   06/24/99    helena      Integrated Alan's NF enhancements and Java2 bug fixes
michael@0: *******************************************************************************
michael@0: */
michael@0: 
michael@0: #ifndef _UNUM
michael@0: #define _UNUM
michael@0: 
michael@0: #include "unicode/utypes.h"
michael@0: 
michael@0: #if !UCONFIG_NO_FORMATTING
michael@0: 
michael@0: #include "unicode/localpointer.h"
michael@0: #include "unicode/uloc.h"
michael@0: #include "unicode/umisc.h"
michael@0: #include "unicode/parseerr.h"
michael@0: #include "unicode/uformattable.h"
michael@0: 
michael@0: /**
michael@0:  * \file
michael@0:  * \brief C API: NumberFormat
michael@0:  *
michael@0:  * <h2> Number Format C API </h2>
michael@0:  *
michael@0:  * Number Format C API  Provides functions for
michael@0:  * formatting and parsing a number.  Also provides methods for
michael@0:  * determining which locales have number formats, and what their names
michael@0:  * are.
michael@0:  * <P>
michael@0:  * UNumberFormat helps you to format and parse numbers for any locale.
michael@0:  * Your code can be completely independent of the locale conventions
michael@0:  * for decimal points, thousands-separators, or even the particular
michael@0:  * decimal digits used, or whether the number format is even decimal.
michael@0:  * There are different number format styles like decimal, currency,
michael@0:  * percent and spellout.
michael@0:  * <P>
michael@0:  * To format a number for the current Locale, use one of the static
michael@0:  * factory methods:
michael@0:  * <pre>
michael@0:  * \code
michael@0:  *    UChar myString[20];
michael@0:  *    double myNumber = 7.0;
michael@0:  *    UErrorCode status = U_ZERO_ERROR;
michael@0:  *    UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
michael@0:  *    unum_formatDouble(nf, myNumber, myString, 20, NULL, &status);
michael@0:  *    printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*)
michael@0:  * \endcode
michael@0:  * </pre>
michael@0:  * If you are formatting multiple numbers, it is more efficient to get
michael@0:  * the format and use it multiple times so that the system doesn't
michael@0:  * have to fetch the information about the local language and country
michael@0:  * conventions multiple times.
michael@0:  * <pre>
michael@0:  * \code
michael@0:  * uint32_t i, resultlength, reslenneeded;
michael@0:  * UErrorCode status = U_ZERO_ERROR;
michael@0:  * UFieldPosition pos;
michael@0:  * uint32_t a[] = { 123, 3333, -1234567 };
michael@0:  * const uint32_t a_len = sizeof(a) / sizeof(a[0]);
michael@0:  * UNumberFormat* nf;
michael@0:  * UChar* result = NULL;
michael@0:  *
michael@0:  * nf = unum_open(UNUM_DEFAULT, NULL, -1, NULL, NULL, &status);
michael@0:  * for (i = 0; i < a_len; i++) {
michael@0:  *    resultlength=0;
michael@0:  *    reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status);
michael@0:  *    result = NULL;
michael@0:  *    if(status==U_BUFFER_OVERFLOW_ERROR){
michael@0:  *       status=U_ZERO_ERROR;
michael@0:  *       resultlength=reslenneeded+1;
michael@0:  *       result=(UChar*)malloc(sizeof(UChar) * resultlength);
michael@0:  *       unum_format(nf, a[i], result, resultlength, &pos, &status);
michael@0:  *    }
michael@0:  *    printf( " Example 2: %s\n", austrdup(result));
michael@0:  *    free(result);
michael@0:  * }
michael@0:  * \endcode
michael@0:  * </pre>
michael@0:  * To format a number for a different Locale, specify it in the
michael@0:  * call to unum_open().
michael@0:  * <pre>
michael@0:  * \code
michael@0:  *     UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, -1, "fr_FR", NULL, &success)
michael@0:  * \endcode
michael@0:  * </pre>
michael@0:  * You can use a NumberFormat API unum_parse() to parse.
michael@0:  * <pre>
michael@0:  * \code
michael@0:  *    UErrorCode status = U_ZERO_ERROR;
michael@0:  *    int32_t pos=0;
michael@0:  *    int32_t num;
michael@0:  *    num = unum_parse(nf, str, u_strlen(str), &pos, &status);
michael@0:  * \endcode
michael@0:  * </pre>
michael@0:  * Use UNUM_DECIMAL to get the normal number format for that country.
michael@0:  * There are other static options available.  Use UNUM_CURRENCY
michael@0:  * to get the currency number format for that country.  Use UNUM_PERCENT
michael@0:  * to get a format for displaying percentages. With this format, a
michael@0:  * fraction from 0.53 is displayed as 53%.
michael@0:  * <P>
michael@0:  * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat
michael@0:  * formatter.  The pattern must conform to the syntax defined for those
michael@0:  * formatters.
michael@0:  * <P>
michael@0:  * You can also control the display of numbers with such function as
michael@0:  * unum_getAttributes() and unum_setAttributes(), which let you set the
michael@0:  * miminum fraction digits, grouping, etc.
michael@0:  * @see UNumberFormatAttributes for more details
michael@0:  * <P>
michael@0:  * You can also use forms of the parse and format methods with
michael@0:  * ParsePosition and UFieldPosition to allow you to:
michael@0:  * <ul type=round>
michael@0:  *   <li>(a) progressively parse through pieces of a string.
michael@0:  *   <li>(b) align the decimal point and other areas.
michael@0:  * </ul>
michael@0:  * <p>
michael@0:  * It is also possible to change or set the symbols used for a particular
michael@0:  * locale like the currency symbol, the grouping seperator , monetary seperator
michael@0:  * etc by making use of functions unum_setSymbols() and unum_getSymbols().
michael@0:  */
michael@0: 
michael@0: /** A number formatter.
michael@0:  *  For usage in C programs.
michael@0:  *  @stable ICU 2.0
michael@0:  */
michael@0: typedef void* UNumberFormat;
michael@0: 
michael@0: /** The possible number format styles. 
michael@0:  *  @stable ICU 2.0
michael@0:  */
michael@0: typedef enum UNumberFormatStyle {
michael@0:     /**
michael@0:      * Decimal format defined by a pattern string.
michael@0:      * @stable ICU 3.0
michael@0:      */
michael@0:     UNUM_PATTERN_DECIMAL=0,
michael@0:     /**
michael@0:      * Decimal format ("normal" style).
michael@0:      * @stable ICU 2.0
michael@0:      */
michael@0:     UNUM_DECIMAL=1,
michael@0:     /**
michael@0:      * Currency format with a currency symbol, e.g., "$1.00".
michael@0:      * @stable ICU 2.0
michael@0:      */
michael@0:     UNUM_CURRENCY,
michael@0:     /**
michael@0:      * Percent format
michael@0:      * @stable ICU 2.0
michael@0:      */
michael@0:     UNUM_PERCENT,
michael@0:     /**
michael@0:      * Scientific format
michael@0:      * @stable ICU 2.1
michael@0:      */
michael@0:     UNUM_SCIENTIFIC,
michael@0:     /**
michael@0:      * Spellout rule-based format
michael@0:      * @stable ICU 2.0
michael@0:      */
michael@0:     UNUM_SPELLOUT,
michael@0:     /** 
michael@0:      * Ordinal rule-based format 
michael@0:      * @stable ICU 3.0
michael@0:      */
michael@0:     UNUM_ORDINAL,
michael@0:     /** 
michael@0:      * Duration rule-based format 
michael@0:      * @stable ICU 3.0
michael@0:      */
michael@0:     UNUM_DURATION,
michael@0:     /** 
michael@0:      * Numbering system rule-based format
michael@0:      * @stable ICU 4.2
michael@0:      */
michael@0:     UNUM_NUMBERING_SYSTEM,
michael@0:     /** 
michael@0:      * Rule-based format defined by a pattern string.
michael@0:      * @stable ICU 3.0
michael@0:      */
michael@0:     UNUM_PATTERN_RULEBASED,
michael@0:     /**
michael@0:      * Currency format with an ISO currency code, e.g., "USD1.00".
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UNUM_CURRENCY_ISO,
michael@0:     /**
michael@0:      * Currency format with a pluralized currency name,
michael@0:      * e.g., "1.00 US dollar" and "3.00 US dollars".
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UNUM_CURRENCY_PLURAL,
michael@0:     /**
michael@0:      * One more than the highest number format style constant.
michael@0:      * @stable ICU 4.8
michael@0:      */
michael@0:     UNUM_FORMAT_STYLE_COUNT,
michael@0:     /**
michael@0:      * Default format
michael@0:      * @stable ICU 2.0
michael@0:      */
michael@0:     UNUM_DEFAULT = UNUM_DECIMAL,
michael@0:     /**
michael@0:      * Alias for UNUM_PATTERN_DECIMAL
michael@0:      * @stable ICU 3.0
michael@0:      */
michael@0:     UNUM_IGNORE = UNUM_PATTERN_DECIMAL
michael@0: } UNumberFormatStyle;
michael@0: 
michael@0: /** The possible number format rounding modes. 
michael@0:  *  @stable ICU 2.0
michael@0:  */
michael@0: typedef enum UNumberFormatRoundingMode {
michael@0:     UNUM_ROUND_CEILING,
michael@0:     UNUM_ROUND_FLOOR,
michael@0:     UNUM_ROUND_DOWN,
michael@0:     UNUM_ROUND_UP,
michael@0:     /**
michael@0:      * Half-even rounding
michael@0:      * @stable, ICU 3.8
michael@0:      */
michael@0:     UNUM_ROUND_HALFEVEN,
michael@0: #ifndef U_HIDE_DEPRECATED_API
michael@0:     /**
michael@0:      * Half-even rounding, misspelled name
michael@0:      * @deprecated, ICU 3.8
michael@0:      */
michael@0:     UNUM_FOUND_HALFEVEN = UNUM_ROUND_HALFEVEN,
michael@0: #endif  /* U_HIDE_DEPRECATED_API */
michael@0:     UNUM_ROUND_HALFDOWN = UNUM_ROUND_HALFEVEN + 1,
michael@0:     UNUM_ROUND_HALFUP,
michael@0:     /** 
michael@0:       * ROUND_UNNECESSARY reports an error if formatted result is not exact.
michael@0:       * @stable ICU 4.8
michael@0:       */
michael@0:     UNUM_ROUND_UNNECESSARY
michael@0: } UNumberFormatRoundingMode;
michael@0: 
michael@0: /** The possible number format pad positions. 
michael@0:  *  @stable ICU 2.0
michael@0:  */
michael@0: typedef enum UNumberFormatPadPosition {
michael@0:     UNUM_PAD_BEFORE_PREFIX,
michael@0:     UNUM_PAD_AFTER_PREFIX,
michael@0:     UNUM_PAD_BEFORE_SUFFIX,
michael@0:     UNUM_PAD_AFTER_SUFFIX
michael@0: } UNumberFormatPadPosition;
michael@0: 
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0: /**
michael@0:  * Constants for specifying short or long format.
michael@0:  * @draft ICU 51
michael@0:  */
michael@0: typedef enum UNumberCompactStyle {
michael@0:   /** @draft ICU 51 */
michael@0:   UNUM_SHORT,
michael@0:   /** @draft ICU 51 */
michael@0:   UNUM_LONG
michael@0:   /** @draft ICU 51 */
michael@0: } UNumberCompactStyle;
michael@0: #endif /* U_HIDE_DRAFT_API */
michael@0: 
michael@0: /**
michael@0:  * Constants for specifying currency spacing
michael@0:  * @stable ICU 4.8
michael@0:  */
michael@0: enum UCurrencySpacing {
michael@0:     /** @stable ICU 4.8 */
michael@0:     UNUM_CURRENCY_MATCH,
michael@0:     /** @stable ICU 4.8 */
michael@0:     UNUM_CURRENCY_SURROUNDING_MATCH,
michael@0:     /** @stable ICU 4.8 */
michael@0:     UNUM_CURRENCY_INSERT,
michael@0:     /** @stable ICU 4.8 */
michael@0:     UNUM_CURRENCY_SPACING_COUNT
michael@0: };
michael@0: typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * FieldPosition and UFieldPosition selectors for format fields
michael@0:  * defined by NumberFormat and UNumberFormat.
michael@0:  * @stable ICU 49
michael@0:  */
michael@0: typedef enum UNumberFormatFields {
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_INTEGER_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_FRACTION_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_DECIMAL_SEPARATOR_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_EXPONENT_SYMBOL_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_EXPONENT_SIGN_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_EXPONENT_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_GROUPING_SEPARATOR_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_CURRENCY_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_PERCENT_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_PERMILL_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_SIGN_FIELD,
michael@0:     /** @stable ICU 49 */
michael@0:     UNUM_FIELD_COUNT
michael@0: } UNumberFormatFields;
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Create and return a new UNumberFormat for formatting and parsing
michael@0:  * numbers.  A UNumberFormat may be used to format numbers by calling
michael@0:  * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }.
michael@0:  * The caller must call {@link #unum_close } when done to release resources
michael@0:  * used by this object.
michael@0:  * @param style The type of number format to open: one of
michael@0:  * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, UNUM_SPELLOUT,
michael@0:  * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT.
michael@0:  * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the
michael@0:  * number format is opened using the given pattern, which must conform
michael@0:  * to the syntax described in DecimalFormat or RuleBasedNumberFormat,
michael@0:  * respectively.
michael@0:  * @param pattern A pattern specifying the format to use. 
michael@0:  * This parameter is ignored unless the style is
michael@0:  * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED.
michael@0:  * @param patternLength The number of characters in the pattern, or -1
michael@0:  * if null-terminated. This parameter is ignored unless the style is
michael@0:  * UNUM_PATTERN.
michael@0:  * @param locale A locale identifier to use to determine formatting
michael@0:  * and parsing conventions, or NULL to use the default locale.
michael@0:  * @param parseErr A pointer to a UParseError struct to receive the
michael@0:  * details of any parsing errors, or NULL if no parsing error details
michael@0:  * are desired.
michael@0:  * @param status A pointer to an input-output UErrorCode.
michael@0:  * @return A pointer to a newly created UNumberFormat, or NULL if an
michael@0:  * error occurred.
michael@0:  * @see unum_close
michael@0:  * @see DecimalFormat
michael@0:  * @stable ICU 2.0
michael@0:  */
michael@0: U_STABLE UNumberFormat* U_EXPORT2 
michael@0: unum_open(  UNumberFormatStyle    style,
michael@0:             const    UChar*    pattern,
michael@0:             int32_t            patternLength,
michael@0:             const    char*     locale,
michael@0:             UParseError*       parseErr,
michael@0:             UErrorCode*        status);
michael@0: 
michael@0: 
michael@0: /**
michael@0: * Close a UNumberFormat.
michael@0: * Once closed, a UNumberFormat may no longer be used.
michael@0: * @param fmt The formatter to close.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2 
michael@0: unum_close(UNumberFormat* fmt);
michael@0: 
michael@0: #if U_SHOW_CPLUSPLUS_API
michael@0: 
michael@0: U_NAMESPACE_BEGIN
michael@0: 
michael@0: /**
michael@0:  * \class LocalUNumberFormatPointer
michael@0:  * "Smart pointer" class, closes a UNumberFormat via unum_close().
michael@0:  * For most methods see the LocalPointerBase base class.
michael@0:  *
michael@0:  * @see LocalPointerBase
michael@0:  * @see LocalPointer
michael@0:  * @stable ICU 4.4
michael@0:  */
michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close);
michael@0: 
michael@0: U_NAMESPACE_END
michael@0: 
michael@0: #endif
michael@0: 
michael@0: /**
michael@0:  * Open a copy of a UNumberFormat.
michael@0:  * This function performs a deep copy.
michael@0:  * @param fmt The format to copy
michael@0:  * @param status A pointer to an UErrorCode to receive any errors.
michael@0:  * @return A pointer to a UNumberFormat identical to fmt.
michael@0:  * @stable ICU 2.0
michael@0:  */
michael@0: U_STABLE UNumberFormat* U_EXPORT2 
michael@0: unum_clone(const UNumberFormat *fmt,
michael@0:        UErrorCode *status);
michael@0: 
michael@0: /**
michael@0: * Format an integer using a UNumberFormat.
michael@0: * The integer will be formatted according to the UNumberFormat's locale.
michael@0: * @param fmt The formatter to use.
michael@0: * @param number The number to format.
michael@0: * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
michael@0: * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
michael@0: * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
michael@0: * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param pos    A pointer to a UFieldPosition.  On input, position->field
michael@0: * is read.  On output, position->beginIndex and position->endIndex indicate
michael@0: * the beginning and ending indices of field number position->field, if such
michael@0: * a field exists.  This parameter may be NULL, in which case no field
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The total buffer size needed; if greater than resultLength, the output was truncated.
michael@0: * @see unum_formatInt64
michael@0: * @see unum_formatDouble
michael@0: * @see unum_parse
michael@0: * @see unum_parseInt64
michael@0: * @see unum_parseDouble
michael@0: * @see UFieldPosition
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_format(    const    UNumberFormat*    fmt,
michael@0:         int32_t            number,
michael@0:         UChar*            result,
michael@0:         int32_t            resultLength,
michael@0:         UFieldPosition    *pos,
michael@0:         UErrorCode*        status);
michael@0: 
michael@0: /**
michael@0: * Format an int64 using a UNumberFormat.
michael@0: * The int64 will be formatted according to the UNumberFormat's locale.
michael@0: * @param fmt The formatter to use.
michael@0: * @param number The number to format.
michael@0: * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
michael@0: * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
michael@0: * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
michael@0: * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param pos    A pointer to a UFieldPosition.  On input, position->field
michael@0: * is read.  On output, position->beginIndex and position->endIndex indicate
michael@0: * the beginning and ending indices of field number position->field, if such
michael@0: * a field exists.  This parameter may be NULL, in which case no field
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The total buffer size needed; if greater than resultLength, the output was truncated.
michael@0: * @see unum_format
michael@0: * @see unum_formatDouble
michael@0: * @see unum_parse
michael@0: * @see unum_parseInt64
michael@0: * @see unum_parseDouble
michael@0: * @see UFieldPosition
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_formatInt64(const UNumberFormat *fmt,
michael@0:         int64_t         number,
michael@0:         UChar*          result,
michael@0:         int32_t         resultLength,
michael@0:         UFieldPosition *pos,
michael@0:         UErrorCode*     status);
michael@0: 
michael@0: /**
michael@0: * Format a double using a UNumberFormat.
michael@0: * The double will be formatted according to the UNumberFormat's locale.
michael@0: * @param fmt The formatter to use.
michael@0: * @param number The number to format.
michael@0: * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
michael@0: * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
michael@0: * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
michael@0: * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param pos    A pointer to a UFieldPosition.  On input, position->field
michael@0: * is read.  On output, position->beginIndex and position->endIndex indicate
michael@0: * the beginning and ending indices of field number position->field, if such
michael@0: * a field exists.  This parameter may be NULL, in which case no field
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The total buffer size needed; if greater than resultLength, the output was truncated.
michael@0: * @see unum_format
michael@0: * @see unum_formatInt64
michael@0: * @see unum_parse
michael@0: * @see unum_parseInt64
michael@0: * @see unum_parseDouble
michael@0: * @see UFieldPosition
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_formatDouble(    const    UNumberFormat*  fmt,
michael@0:             double          number,
michael@0:             UChar*          result,
michael@0:             int32_t         resultLength,
michael@0:             UFieldPosition  *pos, /* 0 if ignore */
michael@0:             UErrorCode*     status);
michael@0: 
michael@0: /**
michael@0: * Format a decimal number using a UNumberFormat.
michael@0: * The number will be formatted according to the UNumberFormat's locale.
michael@0: * The syntax of the input number is a "numeric string"
michael@0: * as defined in the Decimal Arithmetic Specification, available at
michael@0: * http://speleotrove.com/decimal
michael@0: * @param fmt The formatter to use.
michael@0: * @param number The number to format.
michael@0: * @param length The length of the input number, or -1 if the input is nul-terminated.
michael@0: * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
michael@0: * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
michael@0: * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
michael@0: * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param pos    A pointer to a UFieldPosition.  On input, position->field
michael@0: *               is read.  On output, position->beginIndex and position->endIndex indicate
michael@0: *               the beginning and ending indices of field number position->field, if such
michael@0: *               a field exists.  This parameter may be NULL, in which case it is ignored.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The total buffer size needed; if greater than resultLength, the output was truncated.
michael@0: * @see unum_format
michael@0: * @see unum_formatInt64
michael@0: * @see unum_parse
michael@0: * @see unum_parseInt64
michael@0: * @see unum_parseDouble
michael@0: * @see UFieldPosition
michael@0: * @stable ICU 4.4 
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_formatDecimal(    const    UNumberFormat*  fmt,
michael@0:             const char *    number,
michael@0:             int32_t         length,
michael@0:             UChar*          result,
michael@0:             int32_t         resultLength,
michael@0:             UFieldPosition  *pos, /* 0 if ignore */
michael@0:             UErrorCode*     status);
michael@0: 
michael@0: /**
michael@0:  * Format a double currency amount using a UNumberFormat.
michael@0:  * The double will be formatted according to the UNumberFormat's locale.
michael@0:  * @param fmt the formatter to use
michael@0:  * @param number the number to format
michael@0:  * @param currency the 3-letter null-terminated ISO 4217 currency code
michael@0:  * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
michael@0:  * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
michael@0:  * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
michael@0:  * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
michael@0:  * @param resultLength the maximum number of UChars to write to result
michael@0:  * @param pos a pointer to a UFieldPosition.  On input,
michael@0:  * position->field is read.  On output, position->beginIndex and
michael@0:  * position->endIndex indicate the beginning and ending indices of
michael@0:  * field number position->field, if such a field exists.  This
michael@0:  * parameter may be NULL, in which case it is ignored.
michael@0:  * @param status a pointer to an input-output UErrorCode
michael@0:  * @return the total buffer size needed; if greater than resultLength,
michael@0:  * the output was truncated.
michael@0:  * @see unum_formatDouble
michael@0:  * @see unum_parseDoubleCurrency
michael@0:  * @see UFieldPosition
michael@0:  * @stable ICU 3.0
michael@0:  */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: unum_formatDoubleCurrency(const UNumberFormat* fmt,
michael@0:                           double number,
michael@0:                           UChar* currency,
michael@0:                           UChar* result,
michael@0:                           int32_t resultLength,
michael@0:                           UFieldPosition* pos,
michael@0:                           UErrorCode* status);
michael@0: 
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0: /**
michael@0:  * Format a UFormattable into a string.
michael@0:  * @param fmt the formatter to use
michael@0:  * @param number the number to format, as a UFormattable
michael@0:  * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If
michael@0:  * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength)
michael@0:  * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number
michael@0:  * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR.
michael@0:  * @param resultLength the maximum number of UChars to write to result
michael@0:  * @param pos a pointer to a UFieldPosition.  On input,
michael@0:  * position->field is read.  On output, position->beginIndex and
michael@0:  * position->endIndex indicate the beginning and ending indices of
michael@0:  * field number position->field, if such a field exists.  This
michael@0:  * parameter may be NULL, in which case it is ignored.
michael@0:  * @param status a pointer to an input-output UErrorCode
michael@0:  * @return the total buffer size needed; if greater than resultLength,
michael@0:  * the output was truncated. Will return 0 on error.
michael@0:  * @see unum_parseToUFormattable
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT int32_t U_EXPORT2
michael@0: unum_formatUFormattable(const UNumberFormat* fmt,
michael@0:                         const UFormattable *number,
michael@0:                         UChar *result,
michael@0:                         int32_t resultLength,
michael@0:                         UFieldPosition *pos,
michael@0:                         UErrorCode *status);
michael@0: #endif  /* U_HIDE_DRAFT_API */
michael@0: 
michael@0: /**
michael@0: * Parse a string into an integer using a UNumberFormat.
michael@0: * The string will be parsed according to the UNumberFormat's locale.
michael@0: * @param fmt The formatter to use.
michael@0: * @param text The text to parse.
michael@0: * @param textLength The length of text, or -1 if null-terminated.
michael@0: * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
michael@0: * to begin parsing.  If not NULL, on output the offset at which parsing ended.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The value of the parsed integer
michael@0: * @see unum_parseInt64
michael@0: * @see unum_parseDouble
michael@0: * @see unum_format
michael@0: * @see unum_formatInt64
michael@0: * @see unum_formatDouble
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_parse(    const   UNumberFormat*  fmt,
michael@0:         const   UChar*          text,
michael@0:         int32_t         textLength,
michael@0:         int32_t         *parsePos /* 0 = start */,
michael@0:         UErrorCode      *status);
michael@0: 
michael@0: /**
michael@0: * Parse a string into an int64 using a UNumberFormat.
michael@0: * The string will be parsed according to the UNumberFormat's locale.
michael@0: * @param fmt The formatter to use.
michael@0: * @param text The text to parse.
michael@0: * @param textLength The length of text, or -1 if null-terminated.
michael@0: * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
michael@0: * to begin parsing.  If not NULL, on output the offset at which parsing ended.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The value of the parsed integer
michael@0: * @see unum_parse
michael@0: * @see unum_parseDouble
michael@0: * @see unum_format
michael@0: * @see unum_formatInt64
michael@0: * @see unum_formatDouble
michael@0: * @stable ICU 2.8
michael@0: */
michael@0: U_STABLE int64_t U_EXPORT2 
michael@0: unum_parseInt64(const UNumberFormat*  fmt,
michael@0:         const UChar*  text,
michael@0:         int32_t       textLength,
michael@0:         int32_t       *parsePos /* 0 = start */,
michael@0:         UErrorCode    *status);
michael@0: 
michael@0: /**
michael@0: * Parse a string into a double using a UNumberFormat.
michael@0: * The string will be parsed according to the UNumberFormat's locale.
michael@0: * @param fmt The formatter to use.
michael@0: * @param text The text to parse.
michael@0: * @param textLength The length of text, or -1 if null-terminated.
michael@0: * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
michael@0: * to begin parsing.  If not NULL, on output the offset at which parsing ended.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The value of the parsed double
michael@0: * @see unum_parse
michael@0: * @see unum_parseInt64
michael@0: * @see unum_format
michael@0: * @see unum_formatInt64
michael@0: * @see unum_formatDouble
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE double U_EXPORT2 
michael@0: unum_parseDouble(    const   UNumberFormat*  fmt,
michael@0:             const   UChar*          text,
michael@0:             int32_t         textLength,
michael@0:             int32_t         *parsePos /* 0 = start */,
michael@0:             UErrorCode      *status);
michael@0: 
michael@0: 
michael@0: /**
michael@0: * Parse a number from a string into an unformatted numeric string using a UNumberFormat.
michael@0: * The input string will be parsed according to the UNumberFormat's locale.
michael@0: * The syntax of the output is a "numeric string"
michael@0: * as defined in the Decimal Arithmetic Specification, available at
michael@0: * http://speleotrove.com/decimal
michael@0: * @param fmt The formatter to use.
michael@0: * @param text The text to parse.
michael@0: * @param textLength The length of text, or -1 if null-terminated.
michael@0: * @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which
michael@0: *                 to begin parsing.  If not NULL, on output the offset at which parsing ended.
michael@0: * @param outBuf A (char *) buffer to receive the parsed number as a string.  The output string
michael@0: *               will be nul-terminated if there is sufficient space.
michael@0: * @param outBufLength The size of the output buffer.  May be zero, in which case
michael@0: *               the outBuf pointer may be NULL, and the function will return the
michael@0: *               size of the output string.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return the length of the output string, not including any terminating nul.
michael@0: * @see unum_parse
michael@0: * @see unum_parseInt64
michael@0: * @see unum_format
michael@0: * @see unum_formatInt64
michael@0: * @see unum_formatDouble
michael@0: * @stable ICU 4.4
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_parseDecimal(const   UNumberFormat*  fmt,
michael@0:                  const   UChar*          text,
michael@0:                          int32_t         textLength,
michael@0:                          int32_t         *parsePos /* 0 = start */,
michael@0:                          char            *outBuf,
michael@0:                          int32_t         outBufLength,
michael@0:                          UErrorCode      *status);
michael@0: 
michael@0: /**
michael@0:  * Parse a string into a double and a currency using a UNumberFormat.
michael@0:  * The string will be parsed according to the UNumberFormat's locale.
michael@0:  * @param fmt the formatter to use
michael@0:  * @param text the text to parse
michael@0:  * @param textLength the length of text, or -1 if null-terminated
michael@0:  * @param parsePos a pointer to an offset index into text at which to
michael@0:  * begin parsing. On output, *parsePos will point after the last
michael@0:  * parsed character.  This parameter may be NULL, in which case parsing
michael@0:  * begins at offset 0.
michael@0:  * @param currency a pointer to the buffer to receive the parsed null-
michael@0:  * terminated currency.  This buffer must have a capacity of at least
michael@0:  * 4 UChars.
michael@0:  * @param status a pointer to an input-output UErrorCode
michael@0:  * @return the parsed double
michael@0:  * @see unum_parseDouble
michael@0:  * @see unum_formatDoubleCurrency
michael@0:  * @stable ICU 3.0
michael@0:  */
michael@0: U_STABLE double U_EXPORT2
michael@0: unum_parseDoubleCurrency(const UNumberFormat* fmt,
michael@0:                          const UChar* text,
michael@0:                          int32_t textLength,
michael@0:                          int32_t* parsePos, /* 0 = start */
michael@0:                          UChar* currency,
michael@0:                          UErrorCode* status);
michael@0: 
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0: /**
michael@0:  * Parse a UChar string into a UFormattable.
michael@0:  * Example code:
michael@0:  * \snippet test/cintltst/cnumtst.c unum_parseToUFormattable
michael@0:  * @param fmt the formatter to use
michael@0:  * @param result the UFormattable to hold the result. If NULL, a new UFormattable will be allocated (which the caller must close with ufmt_close).
michael@0:  * @param text the text to parse
michael@0:  * @param textLength the length of text, or -1 if null-terminated
michael@0:  * @param parsePos a pointer to an offset index into text at which to
michael@0:  * begin parsing. On output, *parsePos will point after the last
michael@0:  * parsed character.  This parameter may be NULL in which case parsing
michael@0:  * begins at offset 0.
michael@0:  * @param status a pointer to an input-output UErrorCode
michael@0:  * @return the UFormattable.  Will be ==result unless NULL was passed in for result, in which case it will be the newly opened UFormattable.
michael@0:  * @see ufmt_getType
michael@0:  * @see ufmt_close
michael@0:  * @draft ICU 52
michael@0:  */
michael@0: U_DRAFT UFormattable* U_EXPORT2
michael@0: unum_parseToUFormattable(const UNumberFormat* fmt,
michael@0:                          UFormattable *result,
michael@0:                          const UChar* text,
michael@0:                          int32_t textLength,
michael@0:                          int32_t* parsePos, /* 0 = start */
michael@0:                          UErrorCode* status);
michael@0: #endif  /* U_HIDE_DRAFT_API */
michael@0: 
michael@0: /**
michael@0:  * Set the pattern used by a UNumberFormat.  This can only be used
michael@0:  * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR
michael@0:  * in the status.
michael@0:  * @param format The formatter to set.
michael@0:  * @param localized TRUE if the pattern is localized, FALSE otherwise.
michael@0:  * @param pattern The new pattern
michael@0:  * @param patternLength The length of pattern, or -1 if null-terminated.
michael@0:  * @param parseError A pointer to UParseError to recieve information
michael@0:  * about errors occurred during parsing, or NULL if no parse error
michael@0:  * information is desired.
michael@0:  * @param status A pointer to an input-output UErrorCode.
michael@0:  * @see unum_toPattern
michael@0:  * @see DecimalFormat
michael@0:  * @stable ICU 2.0
michael@0:  */
michael@0: U_STABLE void U_EXPORT2 
michael@0: unum_applyPattern(          UNumberFormat  *format,
michael@0:                             UBool          localized,
michael@0:                     const   UChar          *pattern,
michael@0:                             int32_t         patternLength,
michael@0:                             UParseError    *parseError,
michael@0:                             UErrorCode     *status
michael@0:                                     );
michael@0: 
michael@0: /**
michael@0: * Get a locale for which decimal formatting patterns are available.
michael@0: * A UNumberFormat in a locale returned by this function will perform the correct
michael@0: * formatting and parsing for the locale.  The results of this call are not
michael@0: * valid for rule-based number formats.
michael@0: * @param localeIndex The index of the desired locale.
michael@0: * @return A locale for which number formatting patterns are available, or 0 if none.
michael@0: * @see unum_countAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE const char* U_EXPORT2 
michael@0: unum_getAvailable(int32_t localeIndex);
michael@0: 
michael@0: /**
michael@0: * Determine how many locales have decimal formatting patterns available.  The
michael@0: * results of this call are not valid for rule-based number formats.
michael@0: * This function is useful for determining the loop ending condition for
michael@0: * calls to {@link #unum_getAvailable }.
michael@0: * @return The number of locales for which decimal formatting patterns are available.
michael@0: * @see unum_getAvailable
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_countAvailable(void);
michael@0: 
michael@0: #if UCONFIG_HAVE_PARSEALLINPUT
michael@0: /**
michael@0:  * @internal
michael@0:  */
michael@0: typedef enum UNumberFormatAttributeValue {
michael@0:   /** @internal */
michael@0:   UNUM_NO = 0,
michael@0:   /** @internal */
michael@0:   UNUM_YES = 1,
michael@0:   /** @internal */
michael@0:   UNUM_MAYBE = 2
michael@0: } UNumberFormatAttributeValue;
michael@0: #endif
michael@0: 
michael@0: /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */
michael@0: typedef enum UNumberFormatAttribute {
michael@0:   /** Parse integers only */
michael@0:   UNUM_PARSE_INT_ONLY,
michael@0:   /** Use grouping separator */
michael@0:   UNUM_GROUPING_USED,
michael@0:   /** Always show decimal point */
michael@0:   UNUM_DECIMAL_ALWAYS_SHOWN,
michael@0:   /** Maximum integer digits */
michael@0:   UNUM_MAX_INTEGER_DIGITS,
michael@0:   /** Minimum integer digits */
michael@0:   UNUM_MIN_INTEGER_DIGITS,
michael@0:   /** Integer digits */
michael@0:   UNUM_INTEGER_DIGITS,
michael@0:   /** Maximum fraction digits */
michael@0:   UNUM_MAX_FRACTION_DIGITS,
michael@0:   /** Minimum fraction digits */
michael@0:   UNUM_MIN_FRACTION_DIGITS,
michael@0:   /** Fraction digits */
michael@0:   UNUM_FRACTION_DIGITS,
michael@0:   /** Multiplier */
michael@0:   UNUM_MULTIPLIER,
michael@0:   /** Grouping size */
michael@0:   UNUM_GROUPING_SIZE,
michael@0:   /** Rounding Mode */
michael@0:   UNUM_ROUNDING_MODE,
michael@0:   /** Rounding increment */
michael@0:   UNUM_ROUNDING_INCREMENT,
michael@0:   /** The width to which the output of <code>format()</code> is padded. */
michael@0:   UNUM_FORMAT_WIDTH,
michael@0:   /** The position at which padding will take place. */
michael@0:   UNUM_PADDING_POSITION,
michael@0:   /** Secondary grouping size */
michael@0:   UNUM_SECONDARY_GROUPING_SIZE,
michael@0:   /** Use significant digits
michael@0:    * @stable ICU 3.0 */
michael@0:   UNUM_SIGNIFICANT_DIGITS_USED,
michael@0:   /** Minimum significant digits
michael@0:    * @stable ICU 3.0 */
michael@0:   UNUM_MIN_SIGNIFICANT_DIGITS,
michael@0:   /** Maximum significant digits
michael@0:    * @stable ICU 3.0 */
michael@0:   UNUM_MAX_SIGNIFICANT_DIGITS,
michael@0:   /** Lenient parse mode used by rule-based formats.
michael@0:    * @stable ICU 3.0
michael@0:    */
michael@0:   UNUM_LENIENT_PARSE,
michael@0: #if UCONFIG_HAVE_PARSEALLINPUT
michael@0:   /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic).
michael@0:    * This is an internal ICU API. Do not use.
michael@0:    * @internal
michael@0:    */
michael@0:   UNUM_PARSE_ALL_INPUT = UNUM_LENIENT_PARSE + 1,
michael@0: #endif
michael@0: #ifndef U_HIDE_DRAFT_API
michael@0:   /** 
michael@0:     * Scale, which adjusts the position of the
michael@0:     * decimal point when formatting.  Amounts will be multiplied by 10 ^ (scale)
michael@0:     * before they are formatted.  The default value for the scale is 0 ( no adjustment ).
michael@0:     *
michael@0:     * <p>Example: setting the scale to 3, 123 formats as "123,000"
michael@0:     * <p>Example: setting the scale to -4, 123 formats as "0.0123"
michael@0:     *
michael@0:    * @draft ICU 51 */
michael@0:   UNUM_SCALE = UNUM_LENIENT_PARSE + 2,
michael@0: #endif /* U_HIDE_DRAFT_API */
michael@0: 
michael@0: #ifndef U_HIDE_INTERNAL_API
michael@0:   /** Count of "regular" numeric attributes.
michael@0:    * @internal */
michael@0:   UNUM_NUMERIC_ATTRIBUTE_COUNT = UNUM_LENIENT_PARSE + 3,
michael@0: 
michael@0:   /** One below the first bitfield-boolean item.
michael@0:    * All items after this one are stored in boolean form.
michael@0:    * @internal */
michael@0:   UNUM_MAX_NONBOOLEAN_ATTRIBUTE = 0x0FFF,
michael@0: #endif  /* U_HIDE_INTERNAL_API */
michael@0: 
michael@0:   /** If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating.
michael@0:    * For example,  formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing.
michael@0:    * Default: 0 (not set)
michael@0:    * @stable ICU 50
michael@0:    */
michael@0:   UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS = 0x1000,
michael@0:   /** 
michael@0:    * if this attribute is set to 1, specifies that, if the pattern doesn't contain an exponent, the exponent will not be parsed. If the pattern does contain an exponent, this attribute has no effect.
michael@0:    * Has no effect on formatting.
michael@0:    * Default: 0 (unset)
michael@0:    * @stable ICU 50
michael@0:    */
michael@0:   UNUM_PARSE_NO_EXPONENT,
michael@0: 
michael@0: #ifndef U_HIDE_INTERNAL_API
michael@0:   /** Limit of boolean attributes.
michael@0:    * @internal */
michael@0:   UNUM_LIMIT_BOOLEAN_ATTRIBUTE
michael@0: #endif  /* U_HIDE_INTERNAL_API */
michael@0: } UNumberFormatAttribute;
michael@0: 
michael@0: /**
michael@0: * Get a numeric attribute associated with a UNumberFormat.
michael@0: * An example of a numeric attribute is the number of integer digits a formatter will produce.
michael@0: * @param fmt The formatter to query.
michael@0: * @param attr The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
michael@0: * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
michael@0: * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
michael@0: * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
michael@0: * UNUM_SCALE.
michael@0: * @return The value of attr.
michael@0: * @see unum_setAttribute
michael@0: * @see unum_getDoubleAttribute
michael@0: * @see unum_setDoubleAttribute
michael@0: * @see unum_getTextAttribute
michael@0: * @see unum_setTextAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_getAttribute(const UNumberFormat*          fmt,
michael@0:           UNumberFormatAttribute  attr);
michael@0: 
michael@0: /**
michael@0: * Set a numeric attribute associated with a UNumberFormat.
michael@0: * An example of a numeric attribute is the number of integer digits a formatter will produce.  If the
michael@0: * formatter does not understand the attribute, the call is ignored.  Rule-based formatters only understand
michael@0: * the lenient-parse attribute.
michael@0: * @param fmt The formatter to set.
michael@0: * @param attr The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED,
michael@0: * UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS,
michael@0: * UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER,
michael@0: * UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION, UNUM_SECONDARY_GROUPING_SIZE,
michael@0: * UNUM_LENIENT_PARSE, or UNUM_SCALE.
michael@0: * @param newValue The new value of attr.
michael@0: * @see unum_getAttribute
michael@0: * @see unum_getDoubleAttribute
michael@0: * @see unum_setDoubleAttribute
michael@0: * @see unum_getTextAttribute
michael@0: * @see unum_setTextAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2 
michael@0: unum_setAttribute(    UNumberFormat*          fmt,
michael@0:             UNumberFormatAttribute  attr,
michael@0:             int32_t                 newValue);
michael@0: 
michael@0: 
michael@0: /**
michael@0: * Get a numeric attribute associated with a UNumberFormat.
michael@0: * An example of a numeric attribute is the number of integer digits a formatter will produce.
michael@0: * If the formatter does not understand the attribute, -1 is returned.
michael@0: * @param fmt The formatter to query.
michael@0: * @param attr The attribute to query; e.g. UNUM_ROUNDING_INCREMENT.
michael@0: * @return The value of attr.
michael@0: * @see unum_getAttribute
michael@0: * @see unum_setAttribute
michael@0: * @see unum_setDoubleAttribute
michael@0: * @see unum_getTextAttribute
michael@0: * @see unum_setTextAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE double U_EXPORT2 
michael@0: unum_getDoubleAttribute(const UNumberFormat*          fmt,
michael@0:           UNumberFormatAttribute  attr);
michael@0: 
michael@0: /**
michael@0: * Set a numeric attribute associated with a UNumberFormat.
michael@0: * An example of a numeric attribute is the number of integer digits a formatter will produce.
michael@0: * If the formatter does not understand the attribute, this call is ignored.
michael@0: * @param fmt The formatter to set.
michael@0: * @param attr The attribute to set; e.g. UNUM_ROUNDING_INCREMENT.
michael@0: * @param newValue The new value of attr.
michael@0: * @see unum_getAttribute
michael@0: * @see unum_setAttribute
michael@0: * @see unum_getDoubleAttribute
michael@0: * @see unum_getTextAttribute
michael@0: * @see unum_setTextAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2 
michael@0: unum_setDoubleAttribute(    UNumberFormat*          fmt,
michael@0:             UNumberFormatAttribute  attr,
michael@0:             double                 newValue);
michael@0: 
michael@0: /** The possible UNumberFormat text attributes @stable ICU 2.0*/
michael@0: typedef enum UNumberFormatTextAttribute {
michael@0:   /** Positive prefix */
michael@0:   UNUM_POSITIVE_PREFIX,
michael@0:   /** Positive suffix */
michael@0:   UNUM_POSITIVE_SUFFIX,
michael@0:   /** Negative prefix */
michael@0:   UNUM_NEGATIVE_PREFIX,
michael@0:   /** Negative suffix */
michael@0:   UNUM_NEGATIVE_SUFFIX,
michael@0:   /** The character used to pad to the format width. */
michael@0:   UNUM_PADDING_CHARACTER,
michael@0:   /** The ISO currency code */
michael@0:   UNUM_CURRENCY_CODE,
michael@0:   /**
michael@0:    * The default rule set.  This is only available with rule-based formatters.
michael@0:    * @stable ICU 3.0
michael@0:    */
michael@0:   UNUM_DEFAULT_RULESET,
michael@0:   /**
michael@0:    * The public rule sets.  This is only available with rule-based formatters.
michael@0:    * This is a read-only attribute.  The public rulesets are returned as a
michael@0:    * single string, with each ruleset name delimited by ';' (semicolon).
michael@0:    * @stable ICU 3.0
michael@0:    */
michael@0:   UNUM_PUBLIC_RULESETS
michael@0: } UNumberFormatTextAttribute;
michael@0: 
michael@0: /**
michael@0: * Get a text attribute associated with a UNumberFormat.
michael@0: * An example of a text attribute is the suffix for positive numbers.  If the formatter
michael@0: * does not understand the attribute, U_UNSUPPORTED_ERROR is returned as the status.
michael@0: * Rule-based formatters only understand UNUM_DEFAULT_RULESET and UNUM_PUBLIC_RULESETS.
michael@0: * @param fmt The formatter to query.
michael@0: * @param tag The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
michael@0: * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
michael@0: * UNUM_DEFAULT_RULESET, or UNUM_PUBLIC_RULESETS.
michael@0: * @param result A pointer to a buffer to receive the attribute.
michael@0: * @param resultLength The maximum size of result.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The total buffer size needed; if greater than resultLength, the output was truncated.
michael@0: * @see unum_setTextAttribute
michael@0: * @see unum_getAttribute
michael@0: * @see unum_setAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_getTextAttribute(    const    UNumberFormat*                    fmt,
michael@0:             UNumberFormatTextAttribute      tag,
michael@0:             UChar*                            result,
michael@0:             int32_t                            resultLength,
michael@0:             UErrorCode*                        status);
michael@0: 
michael@0: /**
michael@0: * Set a text attribute associated with a UNumberFormat.
michael@0: * An example of a text attribute is the suffix for positive numbers.  Rule-based formatters
michael@0: * only understand UNUM_DEFAULT_RULESET.
michael@0: * @param fmt The formatter to set.
michael@0: * @param tag The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX,
michael@0: * UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX, UNUM_PADDING_CHARACTER, UNUM_CURRENCY_CODE,
michael@0: * or UNUM_DEFAULT_RULESET.
michael@0: * @param newValue The new value of attr.
michael@0: * @param newValueLength The length of newValue, or -1 if null-terminated.
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @see unum_getTextAttribute
michael@0: * @see unum_getAttribute
michael@0: * @see unum_setAttribute
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2 
michael@0: unum_setTextAttribute(    UNumberFormat*                    fmt,
michael@0:             UNumberFormatTextAttribute      tag,
michael@0:             const    UChar*                            newValue,
michael@0:             int32_t                            newValueLength,
michael@0:             UErrorCode                        *status);
michael@0: 
michael@0: /**
michael@0:  * Extract the pattern from a UNumberFormat.  The pattern will follow
michael@0:  * the DecimalFormat pattern syntax.
michael@0:  * @param fmt The formatter to query.
michael@0:  * @param isPatternLocalized TRUE if the pattern should be localized,
michael@0:  * FALSE otherwise.  This is ignored if the formatter is a rule-based
michael@0:  * formatter.
michael@0:  * @param result A pointer to a buffer to receive the pattern.
michael@0:  * @param resultLength The maximum size of result.
michael@0:  * @param status A pointer to an input-output UErrorCode.
michael@0:  * @return The total buffer size needed; if greater than resultLength,
michael@0:  * the output was truncated.
michael@0:  * @see unum_applyPattern
michael@0:  * @see DecimalFormat
michael@0:  * @stable ICU 2.0
michael@0:  */
michael@0: U_STABLE int32_t U_EXPORT2 
michael@0: unum_toPattern(    const    UNumberFormat*          fmt,
michael@0:         UBool                  isPatternLocalized,
michael@0:         UChar*                  result,
michael@0:         int32_t                 resultLength,
michael@0:         UErrorCode*             status);
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Constants for specifying a number format symbol.
michael@0:  * @stable ICU 2.0
michael@0:  */
michael@0: typedef enum UNumberFormatSymbol {
michael@0:   /** The decimal separator */
michael@0:   UNUM_DECIMAL_SEPARATOR_SYMBOL = 0,
michael@0:   /** The grouping separator */
michael@0:   UNUM_GROUPING_SEPARATOR_SYMBOL = 1,
michael@0:   /** The pattern separator */
michael@0:   UNUM_PATTERN_SEPARATOR_SYMBOL = 2,
michael@0:   /** The percent sign */
michael@0:   UNUM_PERCENT_SYMBOL = 3,
michael@0:   /** Zero*/
michael@0:   UNUM_ZERO_DIGIT_SYMBOL = 4,
michael@0:   /** Character representing a digit in the pattern */
michael@0:   UNUM_DIGIT_SYMBOL = 5,
michael@0:   /** The minus sign */
michael@0:   UNUM_MINUS_SIGN_SYMBOL = 6,
michael@0:   /** The plus sign */
michael@0:   UNUM_PLUS_SIGN_SYMBOL = 7,
michael@0:   /** The currency symbol */
michael@0:   UNUM_CURRENCY_SYMBOL = 8,
michael@0:   /** The international currency symbol */
michael@0:   UNUM_INTL_CURRENCY_SYMBOL = 9,
michael@0:   /** The monetary separator */
michael@0:   UNUM_MONETARY_SEPARATOR_SYMBOL = 10,
michael@0:   /** The exponential symbol */
michael@0:   UNUM_EXPONENTIAL_SYMBOL = 11,
michael@0:   /** Per mill symbol */
michael@0:   UNUM_PERMILL_SYMBOL = 12,
michael@0:   /** Escape padding character */
michael@0:   UNUM_PAD_ESCAPE_SYMBOL = 13,
michael@0:   /** Infinity symbol */
michael@0:   UNUM_INFINITY_SYMBOL = 14,
michael@0:   /** Nan symbol */
michael@0:   UNUM_NAN_SYMBOL = 15,
michael@0:   /** Significant digit symbol
michael@0:    * @stable ICU 3.0 */
michael@0:   UNUM_SIGNIFICANT_DIGIT_SYMBOL = 16,
michael@0:   /** The monetary grouping separator 
michael@0:    * @stable ICU 3.6
michael@0:    */
michael@0:   UNUM_MONETARY_GROUPING_SEPARATOR_SYMBOL = 17,
michael@0:   /** One
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_ONE_DIGIT_SYMBOL = 18,
michael@0:   /** Two
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_TWO_DIGIT_SYMBOL = 19,
michael@0:   /** Three
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_THREE_DIGIT_SYMBOL = 20,
michael@0:   /** Four
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_FOUR_DIGIT_SYMBOL = 21,
michael@0:   /** Five
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_FIVE_DIGIT_SYMBOL = 22,
michael@0:   /** Six
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_SIX_DIGIT_SYMBOL = 23,
michael@0:   /** Seven
michael@0:     * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_SEVEN_DIGIT_SYMBOL = 24,
michael@0:   /** Eight
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_EIGHT_DIGIT_SYMBOL = 25,
michael@0:   /** Nine
michael@0:    * @stable ICU 4.6
michael@0:    */
michael@0:   UNUM_NINE_DIGIT_SYMBOL = 26,
michael@0:   /** count symbol constants */
michael@0:   UNUM_FORMAT_SYMBOL_COUNT = 27
michael@0: } UNumberFormatSymbol;
michael@0: 
michael@0: /**
michael@0: * Get a symbol associated with a UNumberFormat.
michael@0: * A UNumberFormat uses symbols to represent the special locale-dependent
michael@0: * characters in a number, for example the percent sign. This API is not
michael@0: * supported for rule-based formatters.
michael@0: * @param fmt The formatter to query.
michael@0: * @param symbol The UNumberFormatSymbol constant for the symbol to get
michael@0: * @param buffer The string buffer that will receive the symbol string;
michael@0: *               if it is NULL, then only the length of the symbol is returned
michael@0: * @param size The size of the string buffer
michael@0: * @param status A pointer to an UErrorCode to receive any errors
michael@0: * @return The length of the symbol; the buffer is not modified if
michael@0: *         <code>length&gt;=size</code>
michael@0: * @see unum_setSymbol
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE int32_t U_EXPORT2
michael@0: unum_getSymbol(const UNumberFormat *fmt,
michael@0:                UNumberFormatSymbol symbol,
michael@0:                UChar *buffer,
michael@0:                int32_t size,
michael@0:                UErrorCode *status);
michael@0: 
michael@0: /**
michael@0: * Set a symbol associated with a UNumberFormat.
michael@0: * A UNumberFormat uses symbols to represent the special locale-dependent
michael@0: * characters in a number, for example the percent sign.  This API is not
michael@0: * supported for rule-based formatters.
michael@0: * @param fmt The formatter to set.
michael@0: * @param symbol The UNumberFormatSymbol constant for the symbol to set
michael@0: * @param value The string to set the symbol to
michael@0: * @param length The length of the string, or -1 for a zero-terminated string
michael@0: * @param status A pointer to an UErrorCode to receive any errors.
michael@0: * @see unum_getSymbol
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: U_STABLE void U_EXPORT2
michael@0: unum_setSymbol(UNumberFormat *fmt,
michael@0:                UNumberFormatSymbol symbol,
michael@0:                const UChar *value,
michael@0:                int32_t length,
michael@0:                UErrorCode *status);
michael@0: 
michael@0: 
michael@0: /**
michael@0:  * Get the locale for this number format object.
michael@0:  * You can choose between valid and actual locale.
michael@0:  * @param fmt The formatter to get the locale from
michael@0:  * @param type type of the locale we're looking for (valid or actual) 
michael@0:  * @param status error code for the operation
michael@0:  * @return the locale name
michael@0:  * @stable ICU 2.8
michael@0:  */
michael@0: U_STABLE const char* U_EXPORT2
michael@0: unum_getLocaleByType(const UNumberFormat *fmt,
michael@0:                      ULocDataLocaleType type,
michael@0:                      UErrorCode* status); 
michael@0: 
michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */
michael@0: 
michael@0: #endif