# Formatting Numbers
Since ICU 60, the recommended mechanism for formatting numbers is
-[`NumberFormatter`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/numberformatter_8h.html)
+[`NumberFormatter`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/numberformatter_8h.html#details)
([Java](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/number/NumberFormatter.html)). `NumberFormatter` supports the formatting of:
- Decimal Formatting
/**
* \file
- * \brief C++ API: Library for localized number formatting introduced in ICU 60.
- *
- * This library was introduced in ICU 60 to simplify the process of formatting localized number strings.
- * Basic usage examples:
+ * \brief C++ API: All-in-one formatter for localized numbers, currencies, and units.
+ *
+ * For a full list of options, see icu::number::NumberFormatterSettings.
*
* <pre>
* // Most basic usage:
* The returned skeleton is in normalized form, such that two number formatters with equivalent
* behavior should produce the same skeleton.
*
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
* @return A number skeleton string with behavior corresponding to this number formatter.
* @stable ICU 62
*/
* It is possible for an error to occur while parsing. See the overload of this method if you are
* interested in the location of a possible parse error.
*
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
* @param skeleton
* The skeleton string off of which to base this NumberFormatter.
* @param status
* If an error occurs while parsing the skeleton string, the offset into the skeleton string at
* which the error occurred will be saved into the UParseError, if provided.
*
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
* @param skeleton
* The skeleton string off of which to base this NumberFormatter.
* @param perror
/**
* Format a double currency amount using a UNumberFormat.
* The double will be formatted according to the UNumberFormat's locale.
+ *
+ * To format an exact decimal value with a currency, use
+ * `unum_setTextAttribute(UNUM_CURRENCY_CODE, ...)` followed by unum_formatDecimal.
+ * Your UNumberFormat must be created with the UNUM_CURRENCY style. Alternatively,
+ * consider using unumf_openForSkeletonAndLocale.
+ *
* @param fmt the formatter to use
* @param number the number to format
* @param currency the 3-letter null-terminated ISO 4217 currency code
* For more details on skeleton strings, see the documentation in numberformatter.h. For more details on
* the usage of this API, see the documentation at the top of unumberformatter.h.
*
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
* NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
*
* @param skeleton The skeleton string, like u"percent precision-integer"
* Like unumf_openForSkeletonAndLocale, but accepts a UParseError, which will be populated with the
* location of a skeleton syntax error if such a syntax error exists.
*
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
* @param skeleton The skeleton string, like u"percent precision-integer"
* @param skeletonLen The number of UChars in the skeleton string, or -1 if it is NUL-terminated.
* @param locale The NUL-terminated locale ID.
static void TestIgnorePadding(void);
static void TestSciNotationMaxFracCap(void);
static void TestMinIntMinFracZero(void);
+static void Test21479_ExactCurrency(void);
#define TESTCASE(x) addTest(root, &x, "tsformat/cnumtst/" #x)
TESTCASE(TestIgnorePadding);
TESTCASE(TestSciNotationMaxFracCap);
TESTCASE(TestMinIntMinFracZero);
+ TESTCASE(Test21479_ExactCurrency);
}
/* test Parse int 64 */
}
}
+static void Test21479_ExactCurrency(void) {
+ UErrorCode status = U_ZERO_ERROR;
+ UNumberFormat* nf = unum_open(UNUM_CURRENCY, NULL, 0, "en_US", NULL, &status);
+ if ( U_FAILURE(status) ) {
+ log_data_err("unum_open UNUM_CURRENCY for en_US fails with %s\n", u_errorName(status));
+ goto cleanup;
+ }
+ unum_setTextAttribute(nf, UNUM_CURRENCY_CODE, u"EUR", -1, &status);
+ UChar result[40];
+ unum_formatDecimal(nf, "987654321000000000000001", -1, result, 40, NULL, &status);
+ if (!assertSuccess("Formatting currency decimal", &status)) {
+ goto cleanup;
+ }
+ assertUEquals("", u"€987,654,321,000,000,000,000,001.00", result);
+
+ cleanup:
+ unum_close(nf);
+}
+
#endif /* #if !UCONFIG_NO_FORMATTING */
import com.ibm.icu.util.ULocale;
/**
- * The main entrypoint to the localized number formatting library introduced in ICU 60. Basic usage
- * examples:
+ * All-in-one formatter for localized numbers, currencies, and units.
+ *
+ * For a full list of options, see {@link NumberFormatterSettings}.
*
* <pre>
* // Most basic usage:
* Call this method at the beginning of a NumberFormatter fluent chain to create an instance based
* on a given number skeleton string.
*
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
+ *
* @param skeleton
* The skeleton string off of which to base this NumberFormatter.
* @return An {@link UnlocalizedNumberFormatter}, to be used for chaining.
* <p>
* The returned skeleton is in normalized form, such that two number formatters with equivalent
* behavior should produce the same skeleton.
+ * <p>
+ * For more information on number skeleton strings, see:
+ * https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html
*
* @return A number skeleton string with behavior corresponding to this number formatter.
* @throws UnsupportedOperationException
projects / icu / commitdiff