* "one: n is 1; few: n in 2..4"* This defines two rules, for 'one' and 'few'. The condition for @@ -74,24 +97,89 @@ class RuleParser; * and_condition = relation ('and' relation)* * relation = is_relation | in_relation | within_relation | 'n'
- * The difference between 'in' and 'within' is that 'in' only includes - * integers in the specified range, while 'within' includes all values.
- *- * Keywords - * could be defined by users or from ICU locale data. There are 6 - * predefined values in ICU - 'zero', 'one', 'two', 'few', 'many' and - * 'other'. Callers need to check the value of keyword returned by - * {@link #select} method. - *
+ *+ * The i, f, and v values are defined as follows: + *
+ *+ * Examples are in the following table: + *
+ *| n | + *i | + *f | + *v | + *
|---|---|---|---|
| 1.0 | + *1 | + *0 | + *1 | + *
| 1.00 | + *1 | + *0 | + *2 | + *
| 1.3 | + *1 | + *3 | + *1 | + *
| 1.03 | + *1 | + *3 | + *2 | + *
| 1.23 | + *1 | + *23 | + *2 | + *
+ * The difference between 'in' and 'within' is that 'in' only includes integers in the specified range, while 'within' + * includes all values. Using 'within' with a range_list consisting entirely of values is the same as using 'in' (it's + * not an error). + *
+ + * An "identifier" is a sequence of characters that do not have the + * Unicode Pattern_Syntax or Pattern_White_Space properties. + *+ * The difference between 'in' and 'within' is that 'in' only includes + * integers in the specified range, while 'within' includes all values. + * Using 'within' with a range_list consisting entirely of values is the + * same as using 'in' (it's not an error). + *
+ *+ * Keywords + * could be defined by users or from ICU locale data. There are 6 + * predefined values in ICU - 'zero', 'one', 'two', 'few', 'many' and + * 'other'. Callers need to check the value of keyword returned by + * {@link #select} method. + *
* * Examples:* UnicodeString keyword = pl->select(number); @@ -103,7 +191,7 @@ class RuleParser; * Note:
** ICU defines plural rules for many locales based on CLDR Language Plural Rules. - * For these predefined rules, see CLDR page at + * For these predefined rules, see CLDR page at * http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html *
*/ @@ -145,7 +233,7 @@ public: /** * Creates a PluralRules from a description if it is parsable, otherwise - * returns null. + * returns NULL. * * @param description rule description * @param status Output param set to success/failure code on exit, which @@ -167,8 +255,9 @@ public: static PluralRules* U_EXPORT2 createDefaultRules(UErrorCode& status); /** - * Provides access to the predefinedPluralRulesfor a given + * Provides access to the predefined cardinal-numberPluralRulesfor a given * locale. + * Same as forLocale(locale, UPLURAL_TYPE_CARDINAL, status). * * @param locale The locale for which aPluralRulesobject is * returned. @@ -182,7 +271,61 @@ public: * @stable ICU 4.0 */ static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UErrorCode& status); - + + /** + * Provides access to the predefinedPluralRulesfor a given + * locale and the plural type. + * + * @param locale The locale for which aPluralRulesobject is + * returned. + * @param type The plural type (e.g., cardinal or ordinal). + * @param status Output param set to success/failure code on exit, which + * must not indicate a failure before the function call. + * @return The predefinedPluralRulesobject pointer for + * this locale. If there's no predefined rules for this locale, + * the rules for the closest parent in the locale hierarchy + * that has one will be returned. The final fallback always + * returns the default 'other' rules. + * @stable ICU 50 + */ + static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UPluralType type, UErrorCode& status); + +#ifndef U_HIDE_INTERNAL_API + /** + * Return a StringEnumeration over the locales for which there is plurals data. + * @return a StringEnumeration over the locales available. + * @internal + */ + static StringEnumeration* U_EXPORT2 getAvailableLocales(UErrorCode &status); + + /** + * Returns whether or not there are overrides. + * @param locale the locale to check. + * @return + * @internal + */ + static UBool hasOverride(const Locale &locale); + + /** + * For ICU use only. + * creates a SharedPluralRules object + * @internal + */ + static PluralRules* U_EXPORT2 internalForLocale(const Locale& locale, UPluralType type, UErrorCode& status); + + /** + * For ICU use only. + * Returns handle to the shared, cached PluralRules instance. + * Caller must call removeRef() on returned value once it is done with + * the shared instance. + * @internal + */ + static const SharedPluralRules* U_EXPORT2 createSharedInstance( + const Locale& locale, UPluralType type, UErrorCode& status); + + +#endif /* U_HIDE_INTERNAL_API */ + /** * Given a number, returns the keyword of the first rule that applies to * the number. This function can be used with isKeyword* functions to @@ -193,7 +336,7 @@ public: * @stable ICU 4.0 */ UnicodeString select(int32_t number) const; - + /** * Given a number, returns the keyword of the first rule that applies to * the number. This function can be used with isKeyword* functions to @@ -205,6 +348,33 @@ public: */ UnicodeString select(double number) const; +#ifndef U_HIDE_INTERNAL_API + /** + * Given a number and a format, returns the keyword of the first applicable + * rule for this PluralRules object. + * Note: This internal preview interface may be removed in the future if + * an architecturally cleaner solution reaches stable status. + * @param obj The numeric object for which the rule should be determined. + * @param fmt The NumberFormat specifying how the number will be formatted + * (this can affect the plural form, e.g. "1 dollar" vs "1.0 dollars"). + * @param status Input/output parameter. If at entry this indicates a + * failure status, the method returns immediately; otherwise + * this is set to indicate the outcome of the call. + * @return The keyword of the selected rule. Undefined in the case of an error. + * @internal ICU 59 technology preview, may be removed in the future + */ + UnicodeString select(const Formattable& obj, const NumberFormat& fmt, UErrorCode& status) const; + + /** + * @internal + */ + UnicodeString select(const IFixedDecimal &number) const; + /** + * @internal + */ + UnicodeString select(const VisibleDigitsWithExponent &number) const; +#endif /* U_HIDE_INTERNAL_API */ + /** * Returns a list of all rule keywords used in thisPluralRules* object. The rule 'other' is always present by default. @@ -217,6 +387,66 @@ public: */ StringEnumeration* getKeywords(UErrorCode& status) const; +#ifndef U_HIDE_DEPRECATED_API + /** + * Deprecated Function, does not return useful results. + * + * Originally intended to return a unique value for this keyword if it exists, + * else the constant UPLRULES_NO_UNIQUE_VALUE. + * + * @param keyword The keyword. + * @return Stub deprecated function returns UPLRULES_NO_UNIQUE_VALUE always. + * @deprecated ICU 55 + */ + double getUniqueKeywordValue(const UnicodeString& keyword); + + /** + * Deprecated Function, does not produce useful results. + * + * Originally intended to return all the values for which select() would return the keyword. + * If the keyword is unknown, returns no values, but this is not an error. If + * the number of values is unlimited, returns no values and -1 as the + * count. + * + * The number of returned values is typically small. + * + * @param keyword The keyword. + * @param dest Array into which to put the returned values. May + * be NULL if destCapacity is 0. + * @param destCapacity The capacity of the array, must be at least 0. + * @param status The error code. Deprecated function, always sets U_UNSUPPORTED_ERROR. + * @return The count of values available, or -1. This count + * can be larger than destCapacity, but no more than + * destCapacity values will be written. + * @deprecated ICU 55 + */ + int32_t getAllKeywordValues(const UnicodeString &keyword, + double *dest, int32_t destCapacity, + UErrorCode& status); +#endif /* U_HIDE_DEPRECATED_API */ + + /** + * Returns sample values for which select() would return the keyword. If + * the keyword is unknown, returns no values, but this is not an error. + * + * The number of returned values is typically small. + * + * @param keyword The keyword. + * @param dest Array into which to put the returned values. May + * be NULL if destCapacity is 0. + * @param destCapacity The capacity of the array, must be at least 0. + * @param status The error code. + * @return The count of values written. + * If more than destCapacity samples are available, then + * only destCapacity are written, and destCapacity is returned as the count, + * rather than setting a U_BUFFER_OVERFLOW_ERROR. + * (The actual number of keyword values could be unlimited.) + * @stable ICU 4.8 + */ + int32_t getSamples(const UnicodeString &keyword, + double *dest, int32_t destCapacity, + UErrorCode& status); + /** * Returns TRUE if the given keyword is defined in this *PluralRulesobject. @@ -233,11 +463,18 @@ public: * Returns keyword for default plural form. * * @return keyword for default plural form. - * @internal 4.0 * @stable ICU 4.0 */ UnicodeString getKeywordOther() const; +#ifndef U_HIDE_INTERNAL_API + /** + * + * @internal + */ + UnicodeString getRules() const; +#endif /* U_HIDE_INTERNAL_API */ + /** * Compares the equality of two PluralRules objects. * @@ -276,22 +513,19 @@ public: private: - Hashtable *fLocaleStringsHash; - UnicodeString mLocaleName; - RuleChain *mRules; - RuleParser *mParser; + RuleChain *mRules; PluralRules(); // default constructor not implemented - int32_t getRepeatLimit() const; - void parseDescription(UnicodeString& ruleData, RuleChain& rules, UErrorCode &status); - void getNextLocale(const UnicodeString& localeData, int32_t* curIndex, UnicodeString& localeName); - void addRules(RuleChain& rules); - int32_t getNumberValue(const UnicodeString& token) const; - UnicodeString getRuleFromResource(const Locale& locale, UErrorCode& status); + void parseDescription(const UnicodeString& ruleData, UErrorCode &status); + int32_t getNumberValue(const UnicodeString& token) const; + UnicodeString getRuleFromResource(const Locale& locale, UPluralType type, UErrorCode& status); + RuleChain *rulesForKeyword(const UnicodeString &keyword) const; + friend class PluralRuleParser; }; U_NAMESPACE_END +#endif // U_SHOW_CPLUSPLUS_API #endif /* #if !UCONFIG_NO_FORMATTING */