diff --git a/icu4c/source/i18n/unicode/numberformatter.h b/icu4c/source/i18n/unicode/numberformatter.h index 615cf49f7b7..ec97bcc7f98 100644 --- a/icu4c/source/i18n/unicode/numberformatter.h +++ b/icu4c/source/i18n/unicode/numberformatter.h @@ -1507,10 +1507,15 @@ class U_I18N_API NumberFormatterSettings { * All units will be properly localized with locale data, and all units are compatible with notation styles, * rounding precisions, and other number formatter settings. * + * \note If the usage() is set, the output unit **will be changed** to + * produce localised units, according to usage, locale and unit. See + * FormattedNumber::getOutputUnit(). + * * Pass this method any instance of {@link MeasureUnit}. For units of measure: * *
      * NumberFormatter::with().unit(MeasureUnit::getMeter())
+     * NumberFormatter::with().unit(MeasureUnit::forIdentifier("foot-per-second", status))
      * 
* * Currency: @@ -2038,6 +2043,54 @@ class U_I18N_API NumberFormatterSettings { */ Derived scale(const Scale &scale) &&; +#ifndef U_HIDE_DRAFT_API + /** + * Specifies the usage for which numbers will be formatted ("person", + * "road", "person", etc.) + * + * When a `usage` is specified, the output unit will change depending on the + * `Locale` and the unit quantity. For example, formatting length + * measurements specified in meters: + * + * `NumberFormatter::with().usage("person").unit(MeasureUnit::getMeter()).locale("en-US")` + * * When formatting 0.25, the output will be "10 inches". + * * When formatting 1.50, the output will be "4 feet and 11 inches". + * + * The input unit specified via unit() determines the type of measurement + * being formatted (e.g. "length" when the unit is "foot"). The usage + * requested will be looked for only within this category of measurement + * units. + * + * The output unit can be found via FormattedNumber::getOutputUnit(). + * + * If the usage has multiple parts (e.g. "land-agriculture-grain") and does + * not match a known usage preference, the last part will be dropped + * repeatedly until a match is found (e.g. trying "land-agriculture", then + * "land"). If a match is still not found, usage will fall back to + * "default". + * + * Setting usage to an empty string clears the usage (disables usage-based + * localized formatting). + * + * @param usage A `usage` parameter from the units resource. See the + * unitPreferenceData in *source/data/misc/units.txt*, generated from + * `unitPreferenceData` in [CLDR's + * supplemental/units.xml](https://github.com/unicode-org/cldr/blob/master/common/supplemental/units.xml). + * @return The fluent chain. + * @draft ICU 68 + */ + Derived usage(StringPiece usage) const &; + + /** + * Overload of usage() for use on an rvalue reference. + * + * @param usage The unit `usage`. + * @return The fluent chain. + * @draft ICU 68 + */ + Derived usage(StringPiece usage) &&; +#endif // U_HIDE_DRAFT_API + #ifndef U_HIDE_INTERNAL_API /** @@ -2508,6 +2561,21 @@ class U_I18N_API FormattedNumber : public UMemory, public FormattedValue { inline StringClass toDecimalNumber(UErrorCode& status) const; #endif // U_HIDE_DRAFT_API +#ifndef U_HIDE_DRAFT_API + /** + * Gets the resolved output unit. + * + * The output unit is dependent upon the localized preferences for the usage + * specified via NumberFormatterSettings::usage(), and may be a unit with + * UMEASURE_UNIT_MIXED unit complexity (MeasureUnit::getComplexity()), such + * as "foot+inch" or "hour+minute+second". + * + * @return `MeasureUnit`. + * @draft ICU 68 + */ + MeasureUnit getOutputUnit(UErrorCode& status) const; +#endif // U_HIDE_DRAFT_API + #ifndef U_HIDE_INTERNAL_API /**