ICU-64260.0.1.tar.gz

[apple/icu.git] / icuSources / i18n / unicode / upluralrules.h

diff --git a/icuSources/i18n/unicode/upluralrules.h b/icuSources/i18n/unicode/upluralrules.h
index 4d75344425fcbe9e1e033490395a66164f45841e..2554ae0ea0a395c4d0934f13b3829c304b907bf0 100644 (file)
--- a/icuSources/i18n/unicode/upluralrules.h
+++ b/icuSources/i18n/unicode/upluralrules.h
@@ -20,6 +20,9 @@
 #include "unicode/unum.h"
 #endif  /* U_HIDE_INTERNAL_API */
 
+// Forward-declaration
+struct UFormattedNumber;
+
 /**
  * \file
  * \brief C API: Plural rules, select plural keywords for numeric values.
@@ -132,14 +135,15 @@ U_NAMESPACE_END
 
 
 /**
- * Given a number, returns the keyword of the first rule that
+ * Given a floating-point number, returns the keyword of the first rule that
  * applies to the number, according to the supplied UPluralRules object.
  * @param uplrules The UPluralRules object specifying the rules.
  * @param number The number for which the rule has to be determined.
- * @param keyword The keyword of the rule that applies to number.
- * @param capacity The capacity of keyword.
+ * @param keyword An output buffer to write the keyword of the rule that
+ *         applies to number.
+ * @param capacity The capacity of the keyword buffer.
  * @param status A pointer to a UErrorCode to receive any errors.
- * @return The length of keyword.
+ * @return The length of the keyword.
  * @stable ICU 4.8
  */
 U_CAPI int32_t U_EXPORT2
@@ -148,6 +152,31 @@ uplrules_select(const UPluralRules *uplrules,
                UChar *keyword, int32_t capacity,
                UErrorCode *status);
 
+#ifndef U_HIDE_DRAFT_API
+/**
+ * Given a formatted number, returns the keyword of the first rule
+ * that applies to the number, according to the supplied UPluralRules object.
+ *
+ * A UFormattedNumber allows you to specify an exponent or trailing zeros,
+ * which can affect the plural category. To get a UFormattedNumber, see
+ * {@link UNumberFormatter}.
+ *
+ * @param uplrules The UPluralRules object specifying the rules.
+ * @param number The formatted number for which the rule has to be determined.
+ * @param keyword The destination buffer for the keyword of the rule that
+ *         applies to number.
+ * @param capacity The capacity of the keyword buffer.
+ * @param status A pointer to a UErrorCode to receive any errors.
+ * @return The length of the keyword.
+ * @draft ICU 64
+ */
+U_CAPI int32_t U_EXPORT2
+uplrules_selectFormatted(const UPluralRules *uplrules,
+               const struct UFormattedNumber* number,
+               UChar *keyword, int32_t capacity,
+               UErrorCode *status);
+#endif  /* U_HIDE_DRAFT_API */
+
 #ifndef U_HIDE_INTERNAL_API
 /**
  * Given a number, returns the keyword of the first rule that applies to the
@@ -160,7 +189,8 @@ uplrules_select(const UPluralRules *uplrules,
  * @param fmt The UNumberFormat specifying how the number will be formatted
  *        (this can affect the plural form, e.g. "1 dollar" vs "1.0 dollars").
  *        If this is NULL, the function behaves like uplrules_select.
- * @param keyword The keyword of the rule that applies to number.
+ * @param keyword An output buffer to write the keyword of the rule that
+ *         applies to number.
  * @param capacity The capacity of the keyword buffer.
  * @param status A pointer to a UErrorCode to receive any errors.
  * @return The length of keyword.
@@ -175,7 +205,6 @@ uplrules_selectWithFormat(const UPluralRules *uplrules,
 
 #endif  /* U_HIDE_INTERNAL_API */
 
-#ifndef U_HIDE_DRAFT_API
 /**
  * Creates a string enumeration of all plural rule keywords used in this
  * UPluralRules object. The rule "other" is always present by default.
@@ -184,12 +213,11 @@ uplrules_selectWithFormat(const UPluralRules *uplrules,
  * @param status A pointer to a UErrorCode to receive any errors.
  * @return a string enumeration over plural rule keywords, or NULL
  * upon error. The caller is responsible for closing the result.
- * @draft ICU 59
+ * @stable ICU 59
  */
-U_DRAFT UEnumeration* U_EXPORT2
+U_STABLE UEnumeration* U_EXPORT2
 uplrules_getKeywords(const UPluralRules *uplrules,
                      UErrorCode *status);
-#endif  /* U_HIDE_DRAFT_API */
 
 #endif /* #if !UCONFIG_NO_FORMATTING */