ICU-21203 ICU-21198 ICU-21479 Improve docs discoverability for NumberFormatter
See #1559
diff --git a/docs/userguide/format_parse/numbers/index.md b/docs/userguide/format_parse/numbers/index.md
index 8576613..1f04ca7 100644
--- a/docs/userguide/format_parse/numbers/index.md
+++ b/docs/userguide/format_parse/numbers/index.md
@@ -13,7 +13,7 @@
# 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
diff --git a/icu4c/source/i18n/unicode/numberformatter.h b/icu4c/source/i18n/unicode/numberformatter.h
index 5bbb837..25239c3 100644
--- a/icu4c/source/i18n/unicode/numberformatter.h
+++ b/icu4c/source/i18n/unicode/numberformatter.h
@@ -28,10 +28,9 @@
/**
* \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:
@@ -2247,6 +2246,9 @@
* 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
*/
@@ -2779,6 +2781,9 @@
* 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
@@ -2795,6 +2800,9 @@
* 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
diff --git a/icu4c/source/i18n/unicode/unum.h b/icu4c/source/i18n/unicode/unum.h
index 68207a9..705e6fe 100644
--- a/icu4c/source/i18n/unicode/unum.h
+++ b/icu4c/source/i18n/unicode/unum.h
@@ -692,6 +692,12 @@
/**
* 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
diff --git a/icu4c/source/i18n/unicode/unumberformatter.h b/icu4c/source/i18n/unicode/unumberformatter.h
index bd1164d..71bbc58 100644
--- a/icu4c/source/i18n/unicode/unumberformatter.h
+++ b/icu4c/source/i18n/unicode/unumberformatter.h
@@ -468,6 +468,9 @@
* 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"
@@ -485,6 +488,9 @@
* 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.
diff --git a/icu4c/source/test/cintltst/cnumtst.c b/icu4c/source/test/cintltst/cnumtst.c
index daeff15..357aca5 100644
--- a/icu4c/source/test/cintltst/cnumtst.c
+++ b/icu4c/source/test/cintltst/cnumtst.c
@@ -75,6 +75,7 @@
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)
@@ -116,6 +117,7 @@
TESTCASE(TestIgnorePadding);
TESTCASE(TestSciNotationMaxFracCap);
TESTCASE(TestMinIntMinFracZero);
+ TESTCASE(Test21479_ExactCurrency);
}
/* test Parse int 64 */
@@ -3576,4 +3578,23 @@
}
}
+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 */
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatter.java b/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatter.java
index d347af8..e5e1e4d 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatter.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatter.java
@@ -9,8 +9,9 @@
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:
@@ -477,6 +478,9 @@
* 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.
diff --git a/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatterSettings.java b/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatterSettings.java
index fed476b..05392b0 100644
--- a/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatterSettings.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/number/NumberFormatterSettings.java
@@ -605,6 +605,9 @@
* <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
