+ * Use a pattern to create either a DecimalFormat or a RuleBasedNumberFormat + * formatter. The pattern must conform to the syntax defined for those + * formatters. + *
* You can also control the display of numbers with such function as - * unum_getAttribues() and unum_setAtributes(). where in you can set the - * miminum fraction digits, grouping used etc. + * unum_getAttributes() and unum_setAttributes(), which let you set the + * miminum fraction digits, grouping, etc. * @see UNumberFormatAttributes for more details *
* You can also use forms of the parse and format methods with @@ -126,20 +140,128 @@ typedef void* UNumberFormat; * @stable ICU 2.0 */ typedef enum UNumberFormatStyle { - /** Ignore style specification and open the pattern */ - UNUM_IGNORE=0, - /** Decimal format */ + /** + * Decimal format defined by a pattern string. + * @stable ICU 3.0 + */ + UNUM_PATTERN_DECIMAL=0, + /** + * Decimal format ("normal" style). + * @stable ICU 2.0 + */ UNUM_DECIMAL=1, - /** Currency format */ - UNUM_CURRENCY, - /** Percent format */ - UNUM_PERCENT, - /** Scientific format */ - UNUM_SCIENTIFIC, - /** Spellout format */ - UNUM_SPELLOUT, - /** Default format */ - UNUM_DEFAULT = UNUM_DECIMAL + /** + * Currency format (generic). + * Defaults to UNUM_CURRENCY_STANDARD style + * (using currency symbol, e.g., "$1.00", with non-accounting + * style for negative values e.g. using minus sign). + * The specific style may be specified using the -cf- locale key. + * @stable ICU 2.0 + */ + UNUM_CURRENCY=2, + /** + * Percent format + * @stable ICU 2.0 + */ + UNUM_PERCENT=3, + /** + * Scientific format + * @stable ICU 2.1 + */ + UNUM_SCIENTIFIC=4, + /** + * Spellout rule-based format. The default ruleset can be specified/changed using + * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets + * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS. + * @stable ICU 2.0 + */ + UNUM_SPELLOUT=5, + /** + * Ordinal rule-based format . The default ruleset can be specified/changed using + * unum_setTextAttribute with UNUM_DEFAULT_RULESET; the available public rulesets + * can be listed using unum_getTextAttribute with UNUM_PUBLIC_RULESETS. + * @stable ICU 3.0 + */ + UNUM_ORDINAL=6, + /** + * Duration rule-based format + * @stable ICU 3.0 + */ + UNUM_DURATION=7, + /** + * Numbering system rule-based format + * @stable ICU 4.2 + */ + UNUM_NUMBERING_SYSTEM=8, + /** + * Rule-based format defined by a pattern string. + * @stable ICU 3.0 + */ + UNUM_PATTERN_RULEBASED=9, + /** + * Currency format with an ISO currency code, e.g., "USD1.00". + * @stable ICU 4.8 + */ + UNUM_CURRENCY_ISO=10, + /** + * Currency format with a pluralized currency name, + * e.g., "1.00 US dollar" and "3.00 US dollars". + * @stable ICU 4.8 + */ + UNUM_CURRENCY_PLURAL=11, + /** + * Currency format for accounting, e.g., "($3.00)" for + * negative currency amount instead of "-$3.00" ({@link #UNUM_CURRENCY}). + * Overrides any style specified using -cf- key in locale. + * @stable ICU 53 + */ + UNUM_CURRENCY_ACCOUNTING=12, + /** + * Currency format with a currency symbol given CASH usage, e.g., + * "NT$3" instead of "NT$3.23". + * @stable ICU 54 + */ + UNUM_CASH_CURRENCY=13, + /** + * Decimal format expressed using compact notation + * (short form, corresponds to UNumberCompactStyle=UNUM_SHORT) + * e.g. "23K", "45B" + * @stable ICU 56 + */ + UNUM_DECIMAL_COMPACT_SHORT=14, + /** + * Decimal format expressed using compact notation + * (long form, corresponds to UNumberCompactStyle=UNUM_LONG) + * e.g. "23 thousand", "45 billion" + * @stable ICU 56 + */ + UNUM_DECIMAL_COMPACT_LONG=15, + /** + * Currency format with a currency symbol, e.g., "$1.00", + * using non-accounting style for negative values (e.g. minus sign). + * Overrides any style specified using -cf- key in locale. + * @stable ICU 56 + */ + UNUM_CURRENCY_STANDARD=16, + +#ifndef U_HIDE_DEPRECATED_API + /** + * One more than the highest normal UNumberFormatStyle value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ + UNUM_FORMAT_STYLE_COUNT=17, +#endif /* U_HIDE_DEPRECATED_API */ + + /** + * Default format + * @stable ICU 2.0 + */ + UNUM_DEFAULT = UNUM_DECIMAL, + /** + * Alias for UNUM_PATTERN_DECIMAL + * @stable ICU 3.0 + */ + UNUM_IGNORE = UNUM_PATTERN_DECIMAL } UNumberFormatStyle; /** The possible number format rounding modes. @@ -150,9 +272,25 @@ typedef enum UNumberFormatRoundingMode { UNUM_ROUND_FLOOR, UNUM_ROUND_DOWN, UNUM_ROUND_UP, - UNUM_FOUND_HALFEVEN, - UNUM_ROUND_HALFDOWN, - UNUM_ROUND_HALFUP + /** + * Half-even rounding + * @stable, ICU 3.8 + */ + UNUM_ROUND_HALFEVEN, +#ifndef U_HIDE_DEPRECATED_API + /** + * Half-even rounding, misspelled name + * @deprecated, ICU 3.8 + */ + UNUM_FOUND_HALFEVEN = UNUM_ROUND_HALFEVEN, +#endif /* U_HIDE_DEPRECATED_API */ + UNUM_ROUND_HALFDOWN = UNUM_ROUND_HALFEVEN + 1, + UNUM_ROUND_HALFUP, + /** + * ROUND_UNNECESSARY reports an error if formatted result is not exact. + * @stable ICU 4.8 + */ + UNUM_ROUND_UNNECESSARY } UNumberFormatRoundingMode; /** The possible number format pad positions. @@ -166,25 +304,112 @@ typedef enum UNumberFormatPadPosition { } UNumberFormatPadPosition; /** -* Open a new UNumberFormat for formatting and parsing numbers. -* A UNumberFormat may be used to format numbers in calls to \Ref{unum_format}, -* and to parse numbers in calls to \Ref{unum_parse}. -* @param style The type of number format to open: one of UNUM_DECIMAL, UNUM_CURRENCY, -* UNUM_PERCENT, UNUM_SPELLOUT, UNUM_DEFAULT or UNUM_IGNORE. If UNUM_IGNORE is passed -* then the style specification is ignored and a number format is opened with the pattern. -* @param pattern A pattern specifying the format to use. -* @param patternLength The number of characters in the pattern, or -1 if null-terminated. -* @param locale The locale specifying the formatting conventions -* @param parseErr a pointer to a UParseError struct to receive the -* details of any parsing errors. This parameter may be NULL if no -* parsing error details are desired. -* @param status A pointer to an UErrorCode to receive any errors -* @return A pointer to a UNumberFormat to use for formatting numbers, or 0 if -* an error occurred. -* @see unum_open -* @stable ICU 2.0 -*/ -U_CAPI UNumberFormat* U_EXPORT2 + * Constants for specifying short or long format. + * @stable ICU 51 + */ +typedef enum UNumberCompactStyle { + /** @stable ICU 51 */ + UNUM_SHORT, + /** @stable ICU 51 */ + UNUM_LONG + /** @stable ICU 51 */ +} UNumberCompactStyle; + +/** + * Constants for specifying currency spacing + * @stable ICU 4.8 + */ +enum UCurrencySpacing { + /** @stable ICU 4.8 */ + UNUM_CURRENCY_MATCH, + /** @stable ICU 4.8 */ + UNUM_CURRENCY_SURROUNDING_MATCH, + /** @stable ICU 4.8 */ + UNUM_CURRENCY_INSERT, + + /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, + * it is needed for layout of DecimalFormatSymbols object. */ + /** + * One more than the highest normal UCurrencySpacing value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ + UNUM_CURRENCY_SPACING_COUNT +}; +typedef enum UCurrencySpacing UCurrencySpacing; /**< @stable ICU 4.8 */ + + +/** + * FieldPosition and UFieldPosition selectors for format fields + * defined by NumberFormat and UNumberFormat. + * @stable ICU 49 + */ +typedef enum UNumberFormatFields { + /** @stable ICU 49 */ + UNUM_INTEGER_FIELD, + /** @stable ICU 49 */ + UNUM_FRACTION_FIELD, + /** @stable ICU 49 */ + UNUM_DECIMAL_SEPARATOR_FIELD, + /** @stable ICU 49 */ + UNUM_EXPONENT_SYMBOL_FIELD, + /** @stable ICU 49 */ + UNUM_EXPONENT_SIGN_FIELD, + /** @stable ICU 49 */ + UNUM_EXPONENT_FIELD, + /** @stable ICU 49 */ + UNUM_GROUPING_SEPARATOR_FIELD, + /** @stable ICU 49 */ + UNUM_CURRENCY_FIELD, + /** @stable ICU 49 */ + UNUM_PERCENT_FIELD, + /** @stable ICU 49 */ + UNUM_PERMILL_FIELD, + /** @stable ICU 49 */ + UNUM_SIGN_FIELD, +#ifndef U_HIDE_DEPRECATED_API + /** + * One more than the highest normal UNumberFormatFields value. + * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. + */ + UNUM_FIELD_COUNT +#endif /* U_HIDE_DEPRECATED_API */ +} UNumberFormatFields; + + +/** + * Create and return a new UNumberFormat for formatting and parsing + * numbers. A UNumberFormat may be used to format numbers by calling + * {@link #unum_format }, and to parse numbers by calling {@link #unum_parse }. + * The caller must call {@link #unum_close } when done to release resources + * used by this object. + * @param style The type of number format to open: one of + * UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SCIENTIFIC, + * UNUM_CURRENCY_ISO, UNUM_CURRENCY_PLURAL, UNUM_SPELLOUT, + * UNUM_ORDINAL, UNUM_DURATION, UNUM_NUMBERING_SYSTEM, + * UNUM_PATTERN_DECIMAL, UNUM_PATTERN_RULEBASED, or UNUM_DEFAULT. + * If UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED is passed then the + * number format is opened using the given pattern, which must conform + * to the syntax described in DecimalFormat or RuleBasedNumberFormat, + * respectively. + * @param pattern A pattern specifying the format to use. + * This parameter is ignored unless the style is + * UNUM_PATTERN_DECIMAL or UNUM_PATTERN_RULEBASED. + * @param patternLength The number of characters in the pattern, or -1 + * if null-terminated. This parameter is ignored unless the style is + * UNUM_PATTERN. + * @param locale A locale identifier to use to determine formatting + * and parsing conventions, or NULL to use the default locale. + * @param parseErr A pointer to a UParseError struct to receive the + * details of any parsing errors, or NULL if no parsing error details + * are desired. + * @param status A pointer to an input-output UErrorCode. + * @return A pointer to a newly created UNumberFormat, or NULL if an + * error occurred. + * @see unum_close + * @see DecimalFormat + * @stable ICU 2.0 + */ +U_STABLE UNumberFormat* U_EXPORT2 unum_open( UNumberFormatStyle style, const UChar* pattern, int32_t patternLength, @@ -199,9 +424,28 @@ unum_open( UNumberFormatStyle style, * @param fmt The formatter to close. * @stable ICU 2.0 */ -U_CAPI void U_EXPORT2 +U_STABLE void U_EXPORT2 unum_close(UNumberFormat* fmt); +#if U_SHOW_CPLUSPLUS_API + +U_NAMESPACE_BEGIN + +/** + * \class LocalUNumberFormatPointer + * "Smart pointer" class, closes a UNumberFormat via unum_close(). + * For most methods see the LocalPointerBase base class. + * + * @see LocalPointerBase + * @see LocalPointer + * @stable ICU 4.4 + */ +U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatPointer, UNumberFormat, unum_close); + +U_NAMESPACE_END + +#endif // U_SHOW_CPLUSPLUS_API + /** * Open a copy of a UNumberFormat. * This function performs a deep copy. @@ -210,7 +454,7 @@ unum_close(UNumberFormat* fmt); * @return A pointer to a UNumberFormat identical to fmt. * @stable ICU 2.0 */ -U_CAPI UNumberFormat* U_EXPORT2 +U_STABLE UNumberFormat* U_EXPORT2 unum_clone(const UNumberFormat *fmt, UErrorCode *status); @@ -219,7 +463,10 @@ unum_clone(const UNumberFormat *fmt, * The integer will be formatted according to the UNumberFormat's locale. * @param fmt The formatter to use. * @param number The number to format. -* @param result A pointer to a buffer to receive the formatted number. +* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If +* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) +* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number +* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. * @param resultLength The maximum size of result. * @param pos A pointer to a UFieldPosition. On input, position->field * is read. On output, position->beginIndex and position->endIndex indicate @@ -227,13 +474,15 @@ unum_clone(const UNumberFormat *fmt, * a field exists. This parameter may be NULL, in which case no field * @param status A pointer to an UErrorCode to receive any errors * @return The total buffer size needed; if greater than resultLength, the output was truncated. +* @see unum_formatInt64 * @see unum_formatDouble * @see unum_parse +* @see unum_parseInt64 * @see unum_parseDouble * @see UFieldPosition * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 unum_format( const UNumberFormat* fmt, int32_t number, UChar* result, @@ -241,12 +490,47 @@ unum_format( const UNumberFormat* fmt, UFieldPosition *pos, UErrorCode* status); +/** +* Format an int64 using a UNumberFormat. +* The int64 will be formatted according to the UNumberFormat's locale. +* @param fmt The formatter to use. +* @param number The number to format. +* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If +* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) +* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number +* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. +* @param resultLength The maximum size of result. +* @param pos A pointer to a UFieldPosition. On input, position->field +* is read. On output, position->beginIndex and position->endIndex indicate +* the beginning and ending indices of field number position->field, if such +* a field exists. This parameter may be NULL, in which case no field +* @param status A pointer to an UErrorCode to receive any errors +* @return The total buffer size needed; if greater than resultLength, the output was truncated. +* @see unum_format +* @see unum_formatDouble +* @see unum_parse +* @see unum_parseInt64 +* @see unum_parseDouble +* @see UFieldPosition +* @stable ICU 2.0 +*/ +U_STABLE int32_t U_EXPORT2 +unum_formatInt64(const UNumberFormat *fmt, + int64_t number, + UChar* result, + int32_t resultLength, + UFieldPosition *pos, + UErrorCode* status); + /** * Format a double using a UNumberFormat. * The double will be formatted according to the UNumberFormat's locale. * @param fmt The formatter to use. * @param number The number to format. -* @param result A pointer to a buffer to receive the formatted number. +* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If +* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) +* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number +* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. * @param resultLength The maximum size of result. * @param pos A pointer to a UFieldPosition. On input, position->field * is read. On output, position->beginIndex and position->endIndex indicate @@ -255,12 +539,14 @@ unum_format( const UNumberFormat* fmt, * @param status A pointer to an UErrorCode to receive any errors * @return The total buffer size needed; if greater than resultLength, the output was truncated. * @see unum_format +* @see unum_formatInt64 * @see unum_parse +* @see unum_parseInt64 * @see unum_parseDouble * @see UFieldPosition * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 unum_formatDouble( const UNumberFormat* fmt, double number, UChar* result, @@ -268,64 +554,344 @@ unum_formatDouble( const UNumberFormat* fmt, UFieldPosition *pos, /* 0 if ignore */ UErrorCode* status); +#ifndef U_HIDE_DRAFT_API +/** +* Format a double using a UNumberFormat according to the UNumberFormat's locale, +* and initialize a UFieldPositionIterator that enumerates the subcomponents of +* the resulting string. +* +* @param format +* The formatter to use. +* @param number +* The number to format. +* @param result +* A pointer to a buffer to receive the NULL-terminated formatted +* number. If the formatted number fits into dest but cannot be +* NULL-terminated (length == resultLength) then the error code is set +* to U_STRING_NOT_TERMINATED_WARNING. If the formatted number doesn't +* fit into result then the error code is set to +* U_BUFFER_OVERFLOW_ERROR. +* @param resultLength +* The maximum size of result. +* @param fpositer +* A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open} +* (may be NULL if field position information is not needed, but in this +* case it's preferable to use {@link #unum_formatDouble}). Iteration +* information already present in the UFieldPositionIterator is deleted, +* and the iterator is reset to apply to the fields in the formatted +* string created by this function call. The field values and indexes +* returned by {@link #ufieldpositer_next} represent fields denoted by +* the UNumberFormatFields enum. Fields are not returned in a guaranteed +* order. Fields cannot overlap, but they may nest. For example, 1234 +* could format as "1,234" which might consist of a grouping separator +* field for ',' and an integer field encompassing the entire string. +* @param status +* A pointer to an UErrorCode to receive any errors +* @return +* The total buffer size needed; if greater than resultLength, the +* output was truncated. +* @see unum_formatDouble +* @see unum_parse +* @see unum_parseDouble +* @see UFieldPositionIterator +* @see UNumberFormatFields +* @draft ICU 59 +*/ +U_DRAFT int32_t U_EXPORT2 +unum_formatDoubleForFields(const UNumberFormat* format, + double number, + UChar* result, + int32_t resultLength, + UFieldPositionIterator* fpositer, + UErrorCode* status); + +#endif /* U_HIDE_DRAFT_API */ + +/** +* Format a decimal number using a UNumberFormat. +* The number will be formatted according to the UNumberFormat's locale. +* The syntax of the input number is a "numeric string" +* as defined in the Decimal Arithmetic Specification, available at +* http://speleotrove.com/decimal +* @param fmt The formatter to use. +* @param number The number to format. +* @param length The length of the input number, or -1 if the input is nul-terminated. +* @param result A pointer to a buffer to receive the NULL-terminated formatted number. If +* the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) +* then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number +* doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. +* @param resultLength The maximum size of result. +* @param pos A pointer to a UFieldPosition. On input, position->field +* is read. On output, position->beginIndex and position->endIndex indicate +* the beginning and ending indices of field number position->field, if such +* a field exists. This parameter may be NULL, in which case it is ignored. +* @param status A pointer to an UErrorCode to receive any errors +* @return The total buffer size needed; if greater than resultLength, the output was truncated. +* @see unum_format +* @see unum_formatInt64 +* @see unum_parse +* @see unum_parseInt64 +* @see unum_parseDouble +* @see UFieldPosition +* @stable ICU 4.4 +*/ +U_STABLE int32_t U_EXPORT2 +unum_formatDecimal( const UNumberFormat* fmt, + const char * number, + int32_t length, + UChar* result, + int32_t resultLength, + UFieldPosition *pos, /* 0 if ignore */ + UErrorCode* status); + +/** + * Format a double currency amount using a UNumberFormat. + * The double will be formatted according to the UNumberFormat's locale. + * @param fmt the formatter to use + * @param number the number to format + * @param currency the 3-letter null-terminated ISO 4217 currency code + * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If + * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) + * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number + * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. + * @param resultLength the maximum number of UChars to write to result + * @param pos a pointer to a UFieldPosition. On input, + * position->field is read. On output, position->beginIndex and + * position->endIndex indicate the beginning and ending indices of + * field number position->field, if such a field exists. This + * parameter may be NULL, in which case it is ignored. + * @param status a pointer to an input-output UErrorCode + * @return the total buffer size needed; if greater than resultLength, + * the output was truncated. + * @see unum_formatDouble + * @see unum_parseDoubleCurrency + * @see UFieldPosition + * @stable ICU 3.0 + */ +U_STABLE int32_t U_EXPORT2 +unum_formatDoubleCurrency(const UNumberFormat* fmt, + double number, + UChar* currency, + UChar* result, + int32_t resultLength, + UFieldPosition* pos, + UErrorCode* status); + +/** + * Format a UFormattable into a string. + * @param fmt the formatter to use + * @param number the number to format, as a UFormattable + * @param result A pointer to a buffer to receive the NULL-terminated formatted number. If + * the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) + * then the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the formatted number + * doesn't fit into result then the error code is set to U_BUFFER_OVERFLOW_ERROR. + * @param resultLength the maximum number of UChars to write to result + * @param pos a pointer to a UFieldPosition. On input, + * position->field is read. On output, position->beginIndex and + * position->endIndex indicate the beginning and ending indices of + * field number position->field, if such a field exists. This + * parameter may be NULL, in which case it is ignored. + * @param status a pointer to an input-output UErrorCode + * @return the total buffer size needed; if greater than resultLength, + * the output was truncated. Will return 0 on error. + * @see unum_parseToUFormattable + * @stable ICU 52 + */ +U_STABLE int32_t U_EXPORT2 +unum_formatUFormattable(const UNumberFormat* fmt, + const UFormattable *number, + UChar *result, + int32_t resultLength, + UFieldPosition *pos, + UErrorCode *status); + /** * Parse a string into an integer using a UNumberFormat. * The string will be parsed according to the UNumberFormat's locale. +* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT +* and UNUM_DECIMAL_COMPACT_LONG. * @param fmt The formatter to use. * @param text The text to parse. * @param textLength The length of text, or -1 if null-terminated. -* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which -* to begin parsing. If not 0, on output the offset at which parsing ended. +* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which +* to begin parsing. If not NULL, on output the offset at which parsing ended. * @param status A pointer to an UErrorCode to receive any errors * @return The value of the parsed integer +* @see unum_parseInt64 * @see unum_parseDouble * @see unum_format +* @see unum_formatInt64 * @see unum_formatDouble * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 unum_parse( const UNumberFormat* fmt, const UChar* text, int32_t textLength, int32_t *parsePos /* 0 = start */, UErrorCode *status); +/** +* Parse a string into an int64 using a UNumberFormat. +* The string will be parsed according to the UNumberFormat's locale. +* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT +* and UNUM_DECIMAL_COMPACT_LONG. +* @param fmt The formatter to use. +* @param text The text to parse. +* @param textLength The length of text, or -1 if null-terminated. +* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which +* to begin parsing. If not NULL, on output the offset at which parsing ended. +* @param status A pointer to an UErrorCode to receive any errors +* @return The value of the parsed integer +* @see unum_parse +* @see unum_parseDouble +* @see unum_format +* @see unum_formatInt64 +* @see unum_formatDouble +* @stable ICU 2.8 +*/ +U_STABLE int64_t U_EXPORT2 +unum_parseInt64(const UNumberFormat* fmt, + const UChar* text, + int32_t textLength, + int32_t *parsePos /* 0 = start */, + UErrorCode *status); + /** * Parse a string into a double using a UNumberFormat. * The string will be parsed according to the UNumberFormat's locale. +* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT +* and UNUM_DECIMAL_COMPACT_LONG. * @param fmt The formatter to use. * @param text The text to parse. * @param textLength The length of text, or -1 if null-terminated. -* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which -* to begin parsing. If not 0, on output the offset at which parsing ended. +* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which +* to begin parsing. If not NULL, on output the offset at which parsing ended. * @param status A pointer to an UErrorCode to receive any errors * @return The value of the parsed double * @see unum_parse +* @see unum_parseInt64 * @see unum_format +* @see unum_formatInt64 * @see unum_formatDouble * @stable ICU 2.0 */ -U_CAPI double U_EXPORT2 +U_STABLE double U_EXPORT2 unum_parseDouble( const UNumberFormat* fmt, const UChar* text, int32_t textLength, int32_t *parsePos /* 0 = start */, UErrorCode *status); + /** -* Set the pattern used by an UNumberFormat. -* The pattern should follow the pattern syntax rules. -* @param format The formatter to set. -* @param localized TRUE if the pattern is localized, FALSE otherwise. -* @param pattern The new pattern -* @param parseError A pointer to UParseError to recieve information about errors -* occurred during parsing. -* @param patternLength The length of pattern, or -1 if null-terminated. +* Parse a number from a string into an unformatted numeric string using a UNumberFormat. +* The input string will be parsed according to the UNumberFormat's locale. +* The syntax of the output is a "numeric string" +* as defined in the Decimal Arithmetic Specification, available at +* http://speleotrove.com/decimal +* Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT +* and UNUM_DECIMAL_COMPACT_LONG. +* @param fmt The formatter to use. +* @param text The text to parse. +* @param textLength The length of text, or -1 if null-terminated. +* @param parsePos If not NULL, on input a pointer to an integer specifying the offset at which +* to begin parsing. If not NULL, on output the offset at which parsing ended. +* @param outBuf A (char *) buffer to receive the parsed number as a string. The output string +* will be nul-terminated if there is sufficient space. +* @param outBufLength The size of the output buffer. May be zero, in which case +* the outBuf pointer may be NULL, and the function will return the +* size of the output string. * @param status A pointer to an UErrorCode to receive any errors -* @see unum_toPattern -* @stable ICU 2.0 +* @return the length of the output string, not including any terminating nul. +* @see unum_parse +* @see unum_parseInt64 +* @see unum_format +* @see unum_formatInt64 +* @see unum_formatDouble +* @stable ICU 4.4 */ -U_CAPI void U_EXPORT2 +U_STABLE int32_t U_EXPORT2 +unum_parseDecimal(const UNumberFormat* fmt, + const UChar* text, + int32_t textLength, + int32_t *parsePos /* 0 = start */, + char *outBuf, + int32_t outBufLength, + UErrorCode *status); + +/** + * Parse a string into a double and a currency using a UNumberFormat. + * The string will be parsed according to the UNumberFormat's locale. + * @param fmt the formatter to use + * @param text the text to parse + * @param textLength the length of text, or -1 if null-terminated + * @param parsePos a pointer to an offset index into text at which to + * begin parsing. On output, *parsePos will point after the last + * parsed character. This parameter may be NULL, in which case parsing + * begins at offset 0. + * @param currency a pointer to the buffer to receive the parsed null- + * terminated currency. This buffer must have a capacity of at least + * 4 UChars. + * @param status a pointer to an input-output UErrorCode + * @return the parsed double + * @see unum_parseDouble + * @see unum_formatDoubleCurrency + * @stable ICU 3.0 + */ +U_STABLE double U_EXPORT2 +unum_parseDoubleCurrency(const UNumberFormat* fmt, + const UChar* text, + int32_t textLength, + int32_t* parsePos, /* 0 = start */ + UChar* currency, + UErrorCode* status); + +/** + * Parse a UChar string into a UFormattable. + * Example code: + * \snippet test/cintltst/cnumtst.c unum_parseToUFormattable + * Note: parsing is not supported for styles UNUM_DECIMAL_COMPACT_SHORT + * and UNUM_DECIMAL_COMPACT_LONG. + * @param fmt the formatter to use + * @param result the UFormattable to hold the result. If NULL, a new UFormattable will be allocated (which the caller must close with ufmt_close). + * @param text the text to parse + * @param textLength the length of text, or -1 if null-terminated + * @param parsePos a pointer to an offset index into text at which to + * begin parsing. On output, *parsePos will point after the last + * parsed character. This parameter may be NULL in which case parsing + * begins at offset 0. + * @param status a pointer to an input-output UErrorCode + * @return the UFormattable. Will be ==result unless NULL was passed in for result, in which case it will be the newly opened UFormattable. + * @see ufmt_getType + * @see ufmt_close + * @stable ICU 52 + */ +U_STABLE UFormattable* U_EXPORT2 +unum_parseToUFormattable(const UNumberFormat* fmt, + UFormattable *result, + const UChar* text, + int32_t textLength, + int32_t* parsePos, /* 0 = start */ + UErrorCode* status); + +/** + * Set the pattern used by a UNumberFormat. This can only be used + * on a DecimalFormat, other formats return U_UNSUPPORTED_ERROR + * in the status. + * @param format The formatter to set. + * @param localized TRUE if the pattern is localized, FALSE otherwise. + * @param pattern The new pattern + * @param patternLength The length of pattern, or -1 if null-terminated. + * @param parseError A pointer to UParseError to recieve information + * about errors occurred during parsing, or NULL if no parse error + * information is desired. + * @param status A pointer to an input-output UErrorCode. + * @see unum_toPattern + * @see DecimalFormat + * @stable ICU 2.0 + */ +U_STABLE void U_EXPORT2 unum_applyPattern( UNumberFormat *format, UBool localized, const UChar *pattern, @@ -335,28 +901,50 @@ unum_applyPattern( UNumberFormat *format, ); /** -* Get a locale for which number formatting patterns are available. +* Get a locale for which decimal formatting patterns are available. * A UNumberFormat in a locale returned by this function will perform the correct -* formatting and parsing for the locale. -* @param index The index of the desired locale. +* formatting and parsing for the locale. The results of this call are not +* valid for rule-based number formats. +* @param localeIndex The index of the desired locale. * @return A locale for which number formatting patterns are available, or 0 if none. * @see unum_countAvailable * @stable ICU 2.0 */ -U_CAPI const char* U_EXPORT2 -unum_getAvailable(int32_t index); +U_STABLE const char* U_EXPORT2 +unum_getAvailable(int32_t localeIndex); /** -* Determine how many locales have number formatting patterns available. -* This function is most useful as determining the loop ending condition for -* calls to \Ref{unum_getAvailable}. -* @return The number of locales for which number formatting patterns are available. +* Determine how many locales have decimal formatting patterns available. The +* results of this call are not valid for rule-based number formats. +* This function is useful for determining the loop ending condition for +* calls to {@link #unum_getAvailable }. +* @return The number of locales for which decimal formatting patterns are available. * @see unum_getAvailable * @stable ICU 2.0 */ -U_CAPI int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 unum_countAvailable(void); +#if UCONFIG_HAVE_PARSEALLINPUT +/* The UNumberFormatAttributeValue type cannot be #ifndef U_HIDE_INTERNAL_API, needed for .h variable declaration */ +/** + * @internal + */ +typedef enum UNumberFormatAttributeValue { +#ifndef U_HIDE_INTERNAL_API + /** @internal */ + UNUM_NO = 0, + /** @internal */ + UNUM_YES = 1, + /** @internal */ + UNUM_MAYBE = 2 +#else + /** @internal */ + UNUM_FORMAT_ATTRIBUTE_VALUE_HIDDEN +#endif /* U_HIDE_INTERNAL_API */ +} UNumberFormatAttributeValue; +#endif + /** The possible UNumberFormat numeric attributes @stable ICU 2.0 */ typedef enum UNumberFormatAttribute { /** Parse integers only */ @@ -390,7 +978,98 @@ typedef enum UNumberFormatAttribute { /** The position at which padding will take place. */ UNUM_PADDING_POSITION, /** Secondary grouping size */ - UNUM_SECONDARY_GROUPING_SIZE + UNUM_SECONDARY_GROUPING_SIZE, + /** Use significant digits + * @stable ICU 3.0 */ + UNUM_SIGNIFICANT_DIGITS_USED, + /** Minimum significant digits + * @stable ICU 3.0 */ + UNUM_MIN_SIGNIFICANT_DIGITS, + /** Maximum significant digits + * @stable ICU 3.0 */ + UNUM_MAX_SIGNIFICANT_DIGITS, + /** Lenient parse mode used by rule-based formats. + * @stable ICU 3.0 + */ + UNUM_LENIENT_PARSE, +#if UCONFIG_HAVE_PARSEALLINPUT + /** Consume all input. (may use fastpath). Set to UNUM_YES (require fastpath), UNUM_NO (skip fastpath), or UNUM_MAYBE (heuristic). + * This is an internal ICU API. Do not use. + * @internal + */ + UNUM_PARSE_ALL_INPUT = 20, +#endif + /** + * Scale, which adjusts the position of the + * decimal point when formatting. Amounts will be multiplied by 10 ^ (scale) + * before they are formatted. The default value for the scale is 0 ( no adjustment ). + * + *
Example: setting the scale to 3, 123 formats as "123,000" + *
Example: setting the scale to -4, 123 formats as "0.0123"
+ *
+ * @stable ICU 51 */
+ UNUM_SCALE = 21,
+#ifndef U_HIDE_INTERNAL_API
+ /**
+ * Minimum grouping digits, technology preview.
+ * See DecimalFormat::getMinimumGroupingDigits().
+ *
+ * @internal technology preview
+ */
+ UNUM_MINIMUM_GROUPING_DIGITS = 22,
+ /* TODO: test C API when it becomes @draft */
+#endif /* U_HIDE_INTERNAL_API */
+#ifndef U_HIDE_INTERNAL_API
+ /** Count of "regular" numeric attributes.
+ * This internal value was unused by ICU and removed in ICU 56.
+ * Unfortunately CF references it (but does not use it) so it
+ * is being temporarily restored per