From e85938bd2c759a478c8ab3de18e4a14fa7ec872e Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Thu, 18 Feb 2021 05:57:00 +0000 Subject: [PATCH] ICU-21203 ICU-21198 ICU-21479 Improve docs discoverability for NumberFormatter See #1559 --- docs/userguide/format_parse/numbers/index.md | 2 +- icu4c/source/i18n/unicode/numberformatter.h | 16 ++++++++++---- icu4c/source/i18n/unicode/unum.h | 6 ++++++ icu4c/source/i18n/unicode/unumberformatter.h | 6 ++++++ icu4c/source/test/cintltst/cnumtst.c | 21 +++++++++++++++++++ .../com/ibm/icu/number/NumberFormatter.java | 8 +++++-- .../icu/number/NumberFormatterSettings.java | 3 +++ 7 files changed, 55 insertions(+), 7 deletions(-) diff --git a/docs/userguide/format_parse/numbers/index.md b/docs/userguide/format_parse/numbers/index.md index 85766131099..1f04ca71353 100644 --- a/docs/userguide/format_parse/numbers/index.md +++ b/docs/userguide/format_parse/numbers/index.md @@ -13,7 +13,7 @@ License & terms of use: http://www.unicode.org/copyright.html # 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 5bbb837d5f9..25239c303df 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. * * 
  * // Most basic usage:
@@ -2247,6 +2246,9 @@ class U_I18N_API NumberFormatterSettings {
      * 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 @@ class U_I18N_API NumberFormatter final {
      * 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 @@ class U_I18N_API NumberFormatter final {
      * 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 68207a9bec1..705e6fee2a2 100644
--- a/icu4c/source/i18n/unicode/unum.h
+++ b/icu4c/source/i18n/unicode/unum.h
@@ -692,6 +692,12 @@ unum_formatDecimal(    const    UNumberFormat*  fmt,
 /**
  * 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 bd1164d6a8a..71bbc587db5 100644
--- a/icu4c/source/i18n/unicode/unumberformatter.h
+++ b/icu4c/source/i18n/unicode/unumberformatter.h
@@ -468,6 +468,9 @@ typedef struct UFormattedNumber UFormattedNumber;
  * 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 @@ unumf_openForSkeletonAndLocale(const UChar* skeleton, int32_t skeletonLen, const
  * 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 daeff15b20a..357aca56079 100644
--- a/icu4c/source/test/cintltst/cnumtst.c
+++ b/icu4c/source/test/cintltst/cnumtst.c
@@ -75,6 +75,7 @@ static void TestSetMaxFracAndRoundIncr(void);
 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 @@ void addNumForTest(TestNode** root)
     TESTCASE(TestIgnorePadding);
     TESTCASE(TestSciNotationMaxFracCap);
     TESTCASE(TestMinIntMinFracZero);
+    TESTCASE(Test21479_ExactCurrency);
 }
 
 /* test Parse int 64 */
@@ -3576,4 +3578,23 @@ static void TestMinIntMinFracZero(void) {
     }
 }
 
+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 d347af81afb..e5e1e4dbe6c 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.text.DecimalFormatSymbols;
 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}.
  *
  * 
  * // Most basic usage:
@@ -477,6 +478,9 @@ public final class NumberFormatter {
      * 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 fed476b2a26..05392b00c99 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 @@ public abstract class NumberFormatterSettings
      * 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.
      * @throws UnsupportedOperationException