From: Shane Carr Date: Wed, 27 Sep 2017 09:03:19 +0000 (+0000) Subject: ICU-13177 Adding more documentation. X-Git-Tag: release-60-rc~98^2~6 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=b40a5ff9ebe3281b734d44f90887ee77abc7a124;p=icu ICU-13177 Adding more documentation. X-SVN-Rev: 40476 --- diff --git a/icu4c/source/common/unicode/docmain.h b/icu4c/source/common/unicode/docmain.h index 698e2ae596c..636931cf258 100644 --- a/icu4c/source/common/unicode/docmain.h +++ b/icu4c/source/common/unicode/docmain.h @@ -140,7 +140,7 @@ * * Number Formatting * unum.h - * icu::NumberFormat + * icu::number::NumberFormatter (ICU 60+) or icu::NumberFormat (older versions) * * * Number Spellout
(Rule Based Number Formatting) diff --git a/icu4c/source/i18n/unicode/numberformatter.h b/icu4c/source/i18n/unicode/numberformatter.h index c8414363d93..097d47423cd 100644 --- a/icu4c/source/i18n/unicode/numberformatter.h +++ b/icu4c/source/i18n/unicode/numberformatter.h @@ -18,6 +18,62 @@ #include "unicode/ucurr.h" #include "unicode/unum.h" +#ifndef U_HIDE_DRAFT_API + +/** + * \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: + * + * 
+ * // Most basic usage:
+ * NumberFormatter::withLocale(...).format(123).toString();  // 1,234 in en-US
+ *
+ * // Custom notation, unit, and rounding strategy:
+ * NumberFormatter::with()
+ *     .notation(Notation::compactShort())
+ *     .unit(CurrencyUnit("EUR", status))
+ *     .rounding(Rounder::maxDigits(2))
+ *     .locale(...)
+ *     .format(1234)
+ *     .toString();  // €1.2K in en-US
+ *
+ * // Create a formatter in a singleton for use later:
+ * static const LocalizedNumberFormatter formatter = NumberFormatter::withLocale(...)
+ *     .unit(NoUnit::percent())
+ *     .rounding(Rounder::fixedFraction(3));
+ * formatter.format(5.9831).toString();  // 5.983% in en-US
+ *
+ * // Create a "template" in a singleton but without setting a locale until the call site:
+ * static const UnlocalizedNumberFormatter template = NumberFormatter::with()
+ *     .sign(UNumberSignDisplay::UNUM_SIGN_ALWAYS)
+ *     .adoptUnit(MeasureUnit::createMeter(status))
+ *     .unitWidth(UNumberUnitWidth::UNUM_UNIT_WIDTH_FULL_NAME);
+ * template.locale(...).format(1234).toString();  // +1,234 meters in en-US
+ *
+ * + *

+ * This API offers more features than DecimalFormat and is geared toward new users of ICU. + * + *

+ * NumberFormatter instances are immutable and thread safe. This means that invoking a configuration method has no + * effect on the receiving instance; you must store and use the new number formatter instance it returns instead. + * + * 

+ * UnlocalizedNumberFormatter formatter = UnlocalizedNumberFormatter::with().notation(Notation::scientific());
+ * formatter.rounding(Rounder.maxFraction(2)); // does nothing!
+ * formatter.locale(Locale.getEnglish()).format(9.8765).toString(); // prints "9.8765E0", not "9.88E0"
+ *
+ * + *

+ * This API is based on the fluent design pattern popularized by libraries such as Google's Guava. For + * extensive details on the design of this API, read the design doc. + * + * @author Shane Carr + */ + /** * An enum declaring how to render units, including currencies. Example outputs when formatting 123 USD and 123 * meters in en-CA: @@ -953,12 +1009,24 @@ class IncrementRounder : public Rounder { friend class Rounder; }; +/** + * @internal This API is a technical preview. It is likely to change in an upcoming release. + */ class Grouper : public UMemory { public: + /** + * @internal This API is a technical preview. It is likely to change in an upcoming release. + */ static Grouper defaults(); + /** + * @internal This API is a technical preview. It is likely to change in an upcoming release. + */ static Grouper minTwoDigits(); + /** + * @internal This API is a technical preview. It is likely to change in an upcoming release. + */ static Grouper none(); private: @@ -1381,7 +1449,12 @@ class NumberFormatterSettings { * NumberFormatter::with().rounding(Rounder::fixedFraction(2)) * * - * The default is to not perform rounding. + *

+ * In most cases, the default rounding strategy is to round to 6 fraction places; i.e., + * Rounder.maxFraction(6). The exceptions are if compact notation is being used, then the compact + * notation rounding strategy is used (see {@link Notation#compactShort} for details), or if the unit is a currency, + * then standard currency rounding is used, which varies from currency to currency (see {@link Rounder#currency} for + * details). * * @param rounder * The rounding strategy to use. @@ -1687,6 +1760,12 @@ class UnlocalizedNumberFormatter friend class NumberFormatter; }; +/** + * A NumberFormatter that has a locale associated with it; this means .format() methods are available. + * + * @see NumberFormatter + * @draft ICU 60 + */ class LocalizedNumberFormatter : public NumberFormatterSettings, public UMemory { public: @@ -1769,14 +1848,68 @@ class LocalizedNumberFormatter friend class UnlocalizedNumberFormatter; }; +/** + * The result of a number formatting operation. This class allows the result to be exported in several data types, + * including a UnicodeString and a FieldPositionIterator. + * + * @draft ICU 60 + */ class FormattedNumber : public UMemory { public: + /** + * Returns a UnicodeString representation of the the formatted number. + * + * @return a UnicodeString containing the localized number. + * @draft ICU 60 + */ UnicodeString toString() const; + /** + * Appends the formatted number to an Appendable. + * + * @param appendable + * The Appendable to which to append the formatted number string. + * @return The same Appendable, for chaining. + * @draft ICU 60 + * @see Appendable + */ Appendable &appendTo(Appendable &appendable); + /** + * Determine the start and end indices of the first occurrence of the given field in the output string. + * This allows you to determine the locations of the integer part, fraction part, and sign. + * + *

+ * If multiple different field attributes are needed, this method can be called repeatedly, or if all field + * attributes are needed, consider using populateFieldPositionIterator(). + * + *

+ * If a field occurs multiple times in an output string, such as a grouping separator, this method will only ever + * return the first occurrence. Use populateFieldPositionIterator() to access all occurrences of an attribute. + * + * @param fieldPosition + * The FieldPosition to populate with the start and end indices of the desired field. + * @param status + * Set if an error occurs while populating the FieldPosition. + * @draft ICU 60 + * @see UNumberFormatFields + */ void populateFieldPosition(FieldPosition &fieldPosition, UErrorCode &status); + /** + * Export the formatted number to a FieldPositionIterator. This allows you to determine which characters in + * the output string correspond to which fields, such as the integer part, fraction part, and sign. + * + *

+ * If information on only one field is needed, consider using populateFieldPosition() instead. + * + * @param iterator + * The FieldPositionIterator to populate with all of the fields present in the formatted number. + * @param status + * Set if an error occurs while populating the FieldPositionIterator. + * @draft ICU 60 + * @see UNumberFormatFields + */ void populateFieldPositionIterator(FieldPositionIterator &iterator, UErrorCode &status); ~FormattedNumber(); @@ -1795,7 +1928,7 @@ class FormattedNumber : public UMemory { }; /** - * The NumberFormatter class cannot be constructed directly; use one of the factory methods. + * See the main description in numberformatter.h for documentation and examples. * * @draft ICU 60 */ @@ -1828,6 +1961,8 @@ class NumberFormatter final { } // namespace number U_NAMESPACE_END +#endif // U_HIDE_DRAFT_API + #endif // __NUMBERFORMATTER_H__ #endif /* #if !UCONFIG_NO_FORMATTING */ diff --git a/icu4c/source/i18n/unicode/numfmt.h b/icu4c/source/i18n/unicode/numfmt.h index 24ae1b91759..62666820f37 100644 --- a/icu4c/source/i18n/unicode/numfmt.h +++ b/icu4c/source/i18n/unicode/numfmt.h @@ -58,6 +58,11 @@ class StringEnumeration; * formatting and parsing a number. Also provides methods for * determining which locales have number formats, and what their names * are. + * + *

NOTE: Starting in ICU 60, there is a new set of APIs for localized number + * formatting that are designed to be an improvement over DecimalFormat. New users are discouraged + * from using DecimalFormat. For more information, see numberformatter.h. + * * \headerfile unicode/numfmt.h "unicode/numfmt.h" *

* NumberFormat helps you to format and parse numbers for any locale.