1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 *******************************************************************************
5 * Copyright (C) 2008-2015, International Business Machines Corporation and
6 * others. All Rights Reserved.
7 *******************************************************************************
12 * Modification History:*
13 * Date Name Description
15 ********************************************************************************
21 #include "unicode/utypes.h"
25 * \brief C++ API: PluralRules object
28 #if !UCONFIG_NO_FORMATTING
30 #include "unicode/format.h"
31 #include "unicode/upluralrules.h"
34 * Value returned by PluralRules::getUniqueKeywordValue() when there is no
35 * unique value to return.
38 #define UPLRULES_NO_UNIQUE_VALUE ((double)-0.00123456777)
44 class VisibleDigitsWithExponent;
46 class PluralRuleParser;
47 class PluralKeywordEnumeration;
49 class SharedPluralRules;
52 * Defines rules for mapping non-negative numeric values onto a small set of
53 * keywords. Rules are constructed from a text description, consisting
54 * of a series of keywords and conditions. The {@link #select} method
55 * examines each condition in order and returns the keyword for the
56 * first condition that matches the number. If none match,
57 * default rule(other) is returned.
59 * For more information, details, and tips for writing rules, see the
60 * LDML spec, C.11 Language Plural Rules:
61 * http://www.unicode.org/draft/reports/tr35/tr35.html#Language_Plural_Rules
64 * "one: n is 1; few: n in 2..4"</pre>
65 * This defines two rules, for 'one' and 'few'. The condition for
66 * 'one' is "n is 1" which means that the number must be equal to
67 * 1 for this condition to pass. The condition for 'few' is
68 * "n in 2..4" which means that the number must be between 2 and
69 * 4 inclusive for this condition to pass. All other numbers
70 * are assigned the keyword "other" by the default rule.
72 * "zero: n is 0; one: n is 1; zero: n mod 100 in 1..19"</pre>
73 * This illustrates that the same keyword can be defined multiple times.
74 * Each rule is examined in order, and the first keyword whose condition
75 * passes is the one returned. Also notes that a modulus is applied
76 * to n in the last rule. Thus its condition holds for 119, 219, 319...
78 * "one: n is 1; few: n mod 10 in 2..4 and n mod 100 not in 12..14"</pre>
79 * This illustrates conjunction and negation. The condition for 'few'
80 * has two parts, both of which must be met: "n mod 10 in 2..4" and
81 * "n mod 100 not in 12..14". The first part applies a modulus to n
82 * before the test as in the previous example. The second part applies
83 * a different modulus and also uses negation, thus it matches all
84 * numbers _not_ in 12, 13, 14, 112, 113, 114, 212, 213, 214...
89 * rules = rule (';' rule)*
90 * rule = keyword ':' condition
91 * keyword = <identifier>
92 * condition = and_condition ('or' and_condition)*
93 * and_condition = relation ('and' relation)*
94 * relation = is_relation | in_relation | within_relation | 'n' <EOL>
95 * is_relation = expr 'is' ('not')? value
96 * in_relation = expr ('not')? 'in' range_list
97 * within_relation = expr ('not')? 'within' range
98 * expr = ('n' | 'i' | 'f' | 'v' | 'j') ('mod' value)?
99 * range_list = (range | value) (',' range_list)*
100 * value = digit+ ('.' digit+)?
101 * digit = 0|1|2|3|4|5|6|7|8|9
102 * range = value'..'value
107 * The i, f, and v values are defined as follows:
110 * <li>i to be the integer digits.</li>
111 * <li>f to be the visible fractional digits, as an integer.</li>
112 * <li>v to be the number of visible fraction digits.</li>
113 * <li>j is defined to only match integers. That is j is 3 fails if v != 0 (eg for 3.1 or 3.0).</li>
116 * Examples are in the following table:
118 * <table border='1' style="border-collapse:collapse">
129 * <td align="right">0</td>
135 * <td align="right">0</td>
141 * <td align="right">3</td>
147 * <td align="right">3</td>
153 * <td align="right">23</td>
159 * The difference between 'in' and 'within' is that 'in' only includes integers in the specified range, while 'within'
160 * includes all values. Using 'within' with a range_list consisting entirely of values is the same as using 'in' (it's
164 * An "identifier" is a sequence of characters that do not have the
165 * Unicode Pattern_Syntax or Pattern_White_Space properties.
167 * The difference between 'in' and 'within' is that 'in' only includes
168 * integers in the specified range, while 'within' includes all values.
169 * Using 'within' with a range_list consisting entirely of values is the
170 * same as using 'in' (it's not an error).
174 * could be defined by users or from ICU locale data. There are 6
175 * predefined values in ICU - 'zero', 'one', 'two', 'few', 'many' and
176 * 'other'. Callers need to check the value of keyword returned by
177 * {@link #select} method.
181 * UnicodeString keyword = pl->select(number);
182 * if (keyword== UnicodeString("one") {
187 * <strong>Note:</strong><br>
189 * ICU defines plural rules for many locales based on CLDR <i>Language Plural Rules</i>.
190 * For these predefined rules, see CLDR page at
191 * http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html
194 class U_I18N_API PluralRules : public UObject {
199 * @param status Output param set to success/failure code on exit, which
200 * must not indicate a failure before the function call.
204 PluralRules(UErrorCode& status);
210 PluralRules(const PluralRules& other);
216 virtual ~PluralRules();
222 PluralRules* clone() const;
225 * Assignment operator.
228 PluralRules& operator=(const PluralRules&);
231 * Creates a PluralRules from a description if it is parsable, otherwise
234 * @param description rule description
235 * @param status Output param set to success/failure code on exit, which
236 * must not indicate a failure before the function call.
237 * @return new PluralRules pointer. NULL if there is an error.
240 static PluralRules* U_EXPORT2 createRules(const UnicodeString& description,
244 * The default rules that accept any number.
246 * @param status Output param set to success/failure code on exit, which
247 * must not indicate a failure before the function call.
248 * @return new PluralRules pointer. NULL if there is an error.
251 static PluralRules* U_EXPORT2 createDefaultRules(UErrorCode& status);
254 * Provides access to the predefined cardinal-number <code>PluralRules</code> for a given
256 * Same as forLocale(locale, UPLURAL_TYPE_CARDINAL, status).
258 * @param locale The locale for which a <code>PluralRules</code> object is
260 * @param status Output param set to success/failure code on exit, which
261 * must not indicate a failure before the function call.
262 * @return The predefined <code>PluralRules</code> object pointer for
263 * this locale. If there's no predefined rules for this locale,
264 * the rules for the closest parent in the locale hierarchy
265 * that has one will be returned. The final fallback always
266 * returns the default 'other' rules.
269 static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UErrorCode& status);
272 * Provides access to the predefined <code>PluralRules</code> for a given
273 * locale and the plural type.
275 * @param locale The locale for which a <code>PluralRules</code> object is
277 * @param type The plural type (e.g., cardinal or ordinal).
278 * @param status Output param set to success/failure code on exit, which
279 * must not indicate a failure before the function call.
280 * @return The predefined <code>PluralRules</code> object pointer for
281 * this locale. If there's no predefined rules for this locale,
282 * the rules for the closest parent in the locale hierarchy
283 * that has one will be returned. The final fallback always
284 * returns the default 'other' rules.
287 static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UPluralType type, UErrorCode& status);
289 #ifndef U_HIDE_INTERNAL_API
291 * Return a StringEnumeration over the locales for which there is plurals data.
292 * @return a StringEnumeration over the locales available.
295 static StringEnumeration* U_EXPORT2 getAvailableLocales(UErrorCode &status);
298 * Returns whether or not there are overrides.
299 * @param locale the locale to check.
303 static UBool hasOverride(const Locale &locale);
307 * creates a SharedPluralRules object
310 static PluralRules* U_EXPORT2 internalForLocale(const Locale& locale, UPluralType type, UErrorCode& status);
314 * Returns handle to the shared, cached PluralRules instance.
315 * Caller must call removeRef() on returned value once it is done with
316 * the shared instance.
319 static const SharedPluralRules* U_EXPORT2 createSharedInstance(
320 const Locale& locale, UPluralType type, UErrorCode& status);
323 #endif /* U_HIDE_INTERNAL_API */
326 * Given a number, returns the keyword of the first rule that applies to
327 * the number. This function can be used with isKeyword* functions to
328 * determine the keyword for default plural rules.
330 * @param number The number for which the rule has to be determined.
331 * @return The keyword of the selected rule.
334 UnicodeString select(int32_t number) const;
337 * Given a number, returns the keyword of the first rule that applies to
338 * the number. This function can be used with isKeyword* functions to
339 * determine the keyword for default plural rules.
341 * @param number The number for which the rule has to be determined.
342 * @return The keyword of the selected rule.
345 UnicodeString select(double number) const;
347 #ifndef U_HIDE_INTERNAL_API
351 UnicodeString select(const FixedDecimal &number) const;
355 UnicodeString select(const VisibleDigitsWithExponent &number) const;
356 #endif /* U_HIDE_INTERNAL_API */
359 * Returns a list of all rule keywords used in this <code>PluralRules</code>
360 * object. The rule 'other' is always present by default.
362 * @param status Output param set to success/failure code on exit, which
363 * must not indicate a failure before the function call.
364 * @return StringEnumeration with the keywords.
365 * The caller must delete the object.
368 StringEnumeration* getKeywords(UErrorCode& status) const;
370 #ifndef U_HIDE_DEPRECATED_API
372 * Deprecated Function, does not return useful results.
374 * Originally intended to return a unique value for this keyword if it exists,
375 * else the constant UPLRULES_NO_UNIQUE_VALUE.
377 * @param keyword The keyword.
378 * @return Stub deprecated function returns UPLRULES_NO_UNIQUE_VALUE always.
381 double getUniqueKeywordValue(const UnicodeString& keyword);
384 * Deprecated Function, does not produce useful results.
386 * Orginally intended to return all the values for which select() would return the keyword.
387 * If the keyword is unknown, returns no values, but this is not an error. If
388 * the number of values is unlimited, returns no values and -1 as the
391 * The number of returned values is typically small.
393 * @param keyword The keyword.
394 * @param dest Array into which to put the returned values. May
395 * be NULL if destCapacity is 0.
396 * @param destCapacity The capacity of the array, must be at least 0.
397 * @param status The error code. Deprecated function, always sets U_UNSUPPORTED_ERROR.
398 * @return The count of values available, or -1. This count
399 * can be larger than destCapacity, but no more than
400 * destCapacity values will be written.
403 int32_t getAllKeywordValues(const UnicodeString &keyword,
404 double *dest, int32_t destCapacity,
406 #endif /* U_HIDE_DEPRECATED_API */
409 * Returns sample values for which select() would return the keyword. If
410 * the keyword is unknown, returns no values, but this is not an error.
412 * The number of returned values is typically small.
414 * @param keyword The keyword.
415 * @param dest Array into which to put the returned values. May
416 * be NULL if destCapacity is 0.
417 * @param destCapacity The capacity of the array, must be at least 0.
418 * @param status The error code.
419 * @return The count of values written.
420 * If more than destCapacity samples are available, then
421 * only destCapacity are written, and destCapacity is returned as the count,
422 * rather than setting a U_BUFFER_OVERFLOW_ERROR.
423 * (The actual number of keyword values could be unlimited.)
426 int32_t getSamples(const UnicodeString &keyword,
427 double *dest, int32_t destCapacity,
431 * Returns TRUE if the given keyword is defined in this
432 * <code>PluralRules</code> object.
434 * @param keyword the input keyword.
435 * @return TRUE if the input keyword is defined.
436 * Otherwise, return FALSE.
439 UBool isKeyword(const UnicodeString& keyword) const;
443 * Returns keyword for default plural form.
445 * @return keyword for default plural form.
448 UnicodeString getKeywordOther() const;
450 #ifndef U_HIDE_INTERNAL_API
455 UnicodeString getRules() const;
456 #endif /* U_HIDE_INTERNAL_API */
459 * Compares the equality of two PluralRules objects.
461 * @param other The other PluralRules object to be compared with.
462 * @return True if the given PluralRules is the same as this
463 * PluralRules; false otherwise.
466 virtual UBool operator==(const PluralRules& other) const;
469 * Compares the inequality of two PluralRules objects.
471 * @param other The PluralRules object to be compared with.
472 * @return True if the given PluralRules is not the same as this
473 * PluralRules; false otherwise.
476 UBool operator!=(const PluralRules& other) const {return !operator==(other);}
480 * ICU "poor man's RTTI", returns a UClassID for this class.
485 static UClassID U_EXPORT2 getStaticClassID(void);
488 * ICU "poor man's RTTI", returns a UClassID for the actual class.
492 virtual UClassID getDynamicClassID() const;
498 PluralRules(); // default constructor not implemented
499 void parseDescription(const UnicodeString& ruleData, UErrorCode &status);
500 int32_t getNumberValue(const UnicodeString& token) const;
501 UnicodeString getRuleFromResource(const Locale& locale, UPluralType type, UErrorCode& status);
502 RuleChain *rulesForKeyword(const UnicodeString &keyword) const;
504 friend class PluralRuleParser;
509 #endif /* #if !UCONFIG_NO_FORMATTING */