michael@0: /* michael@0: ******************************************************************************* michael@0: * Copyright (C) 2008-2013, International Business Machines Corporation and michael@0: * others. All Rights Reserved. michael@0: ******************************************************************************* michael@0: * michael@0: * michael@0: * File PLURRULE.H michael@0: * michael@0: * Modification History:* michael@0: * Date Name Description michael@0: * michael@0: ******************************************************************************** michael@0: */ michael@0: michael@0: #ifndef PLURRULE michael@0: #define PLURRULE michael@0: michael@0: #include "unicode/utypes.h" michael@0: michael@0: /** michael@0: * \file michael@0: * \brief C++ API: PluralRules object michael@0: */ michael@0: michael@0: #if !UCONFIG_NO_FORMATTING michael@0: michael@0: #include "unicode/format.h" michael@0: #include "unicode/upluralrules.h" michael@0: michael@0: /** michael@0: * Value returned by PluralRules::getUniqueKeywordValue() when there is no michael@0: * unique value to return. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: #define UPLRULES_NO_UNIQUE_VALUE ((double)-0.00123456777) michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: class Hashtable; michael@0: class FixedDecimal; michael@0: class RuleChain; michael@0: class PluralRuleParser; michael@0: class PluralKeywordEnumeration; michael@0: class AndConstraint; michael@0: michael@0: /** michael@0: * Defines rules for mapping non-negative numeric values onto a small set of michael@0: * keywords. Rules are constructed from a text description, consisting michael@0: * of a series of keywords and conditions. The {@link #select} method michael@0: * examines each condition in order and returns the keyword for the michael@0: * first condition that matches the number. If none match, michael@0: * default rule(other) is returned. michael@0: * michael@0: * For more information, details, and tips for writing rules, see the michael@0: * LDML spec, C.11 Language Plural Rules: michael@0: * http://www.unicode.org/draft/reports/tr35/tr35.html#Language_Plural_Rules michael@0: * michael@0: * Examples:
michael@0:  *   "one: n is 1; few: n in 2..4"
michael@0: * This defines two rules, for 'one' and 'few'. The condition for michael@0: * 'one' is "n is 1" which means that the number must be equal to michael@0: * 1 for this condition to pass. The condition for 'few' is michael@0: * "n in 2..4" which means that the number must be between 2 and michael@0: * 4 inclusive for this condition to pass. All other numbers michael@0: * are assigned the keyword "other" by the default rule. michael@0: * 

michael@0:  *    "zero: n is 0; one: n is 1; zero: n mod 100 in 1..19"
michael@0: * This illustrates that the same keyword can be defined multiple times. michael@0: * Each rule is examined in order, and the first keyword whose condition michael@0: * passes is the one returned. Also notes that a modulus is applied michael@0: * to n in the last rule. Thus its condition holds for 119, 219, 319... michael@0: * 

michael@0:  *    "one: n is 1; few: n mod 10 in 2..4 and n mod 100 not in 12..14"
michael@0: * This illustrates conjunction and negation. The condition for 'few' michael@0: * has two parts, both of which must be met: "n mod 10 in 2..4" and michael@0: * "n mod 100 not in 12..14". The first part applies a modulus to n michael@0: * before the test as in the previous example. The second part applies michael@0: * a different modulus and also uses negation, thus it matches all michael@0: * numbers _not_ in 12, 13, 14, 112, 113, 114, 212, 213, 214... michael@0: *

michael@0: *

michael@0: * Syntax:

michael@0:  * \code
michael@0:  * rules         = rule (';' rule)*
michael@0:  * rule          = keyword ':' condition
michael@0:  * keyword       = 
michael@0:  * condition     = and_condition ('or' and_condition)*
michael@0:  * and_condition = relation ('and' relation)*
michael@0:  * relation      = is_relation | in_relation | within_relation | 'n' 
michael@0:  * is_relation   = expr 'is' ('not')? value
michael@0:  * in_relation   = expr ('not')? 'in' range_list
michael@0:  * within_relation = expr ('not')? 'within' range
michael@0:  * expr          = ('n' | 'i' | 'f' | 'v' | 'j') ('mod' value)?
michael@0:  * range_list    = (range | value) (',' range_list)*
michael@0:  * value         = digit+  ('.' digit+)?
michael@0:  * digit         = 0|1|2|3|4|5|6|7|8|9
michael@0:  * range         = value'..'value
michael@0:  * \endcode
michael@0:  *

michael@0: *

michael@0: *

michael@0: * The i, f, and v values are defined as follows: michael@0: *

michael@0: * michael@0: *

michael@0: * Examples are in the following table: michael@0: *

michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: * michael@0: *
nifv
1.0101
1.00102
1.3131
1.03132
1.231232
michael@0: *

michael@0: * The difference between 'in' and 'within' is that 'in' only includes integers in the specified range, while 'within' michael@0: * includes all values. Using 'within' with a range_list consisting entirely of values is the same as using 'in' (it's michael@0: * not an error). michael@0: *

michael@0: michael@0: * An "identifier" is a sequence of characters that do not have the michael@0: * Unicode Pattern_Syntax or Pattern_White_Space properties. michael@0: *

michael@0: * The difference between 'in' and 'within' is that 'in' only includes michael@0: * integers in the specified range, while 'within' includes all values. michael@0: * Using 'within' with a range_list consisting entirely of values is the michael@0: * same as using 'in' (it's not an error). michael@0: *

michael@0: *

michael@0: * Keywords michael@0: * could be defined by users or from ICU locale data. There are 6 michael@0: * predefined values in ICU - 'zero', 'one', 'two', 'few', 'many' and michael@0: * 'other'. Callers need to check the value of keyword returned by michael@0: * {@link #select} method. michael@0: *

michael@0: * michael@0: * Examples:
michael@0:  * UnicodeString keyword = pl->select(number);
michael@0:  * if (keyword== UnicodeString("one") {
michael@0:  *     ...
michael@0:  * }
michael@0:  * else if ( ... )
michael@0:  *
michael@0: * Note:
michael@0: *

michael@0: * ICU defines plural rules for many locales based on CLDR Language Plural Rules. michael@0: * For these predefined rules, see CLDR page at michael@0: * http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html michael@0: *

michael@0: */ michael@0: class U_I18N_API PluralRules : public UObject { michael@0: public: michael@0: michael@0: /** michael@0: * Constructor. michael@0: * @param status Output param set to success/failure code on exit, which michael@0: * must not indicate a failure before the function call. michael@0: * michael@0: * @stable ICU 4.0 michael@0: */ michael@0: PluralRules(UErrorCode& status); michael@0: michael@0: /** michael@0: * Copy constructor. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: PluralRules(const PluralRules& other); michael@0: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: virtual ~PluralRules(); michael@0: michael@0: /** michael@0: * Clone michael@0: * @stable ICU 4.0 michael@0: */ michael@0: PluralRules* clone() const; michael@0: michael@0: /** michael@0: * Assignment operator. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: PluralRules& operator=(const PluralRules&); michael@0: michael@0: /** michael@0: * Creates a PluralRules from a description if it is parsable, otherwise michael@0: * returns NULL. michael@0: * michael@0: * @param description rule description michael@0: * @param status Output param set to success/failure code on exit, which michael@0: * must not indicate a failure before the function call. michael@0: * @return new PluralRules pointer. NULL if there is an error. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: static PluralRules* U_EXPORT2 createRules(const UnicodeString& description, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * The default rules that accept any number. michael@0: * michael@0: * @param status Output param set to success/failure code on exit, which michael@0: * must not indicate a failure before the function call. michael@0: * @return new PluralRules pointer. NULL if there is an error. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: static PluralRules* U_EXPORT2 createDefaultRules(UErrorCode& status); michael@0: michael@0: /** michael@0: * Provides access to the predefined cardinal-number PluralRules for a given michael@0: * locale. michael@0: * Same as forLocale(locale, UPLURAL_TYPE_CARDINAL, status). michael@0: * michael@0: * @param locale The locale for which a PluralRules object is michael@0: * returned. michael@0: * @param status Output param set to success/failure code on exit, which michael@0: * must not indicate a failure before the function call. michael@0: * @return The predefined PluralRules object pointer for michael@0: * this locale. If there's no predefined rules for this locale, michael@0: * the rules for the closest parent in the locale hierarchy michael@0: * that has one will be returned. The final fallback always michael@0: * returns the default 'other' rules. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UErrorCode& status); michael@0: michael@0: /** michael@0: * Provides access to the predefined PluralRules for a given michael@0: * locale and the plural type. michael@0: * michael@0: * @param locale The locale for which a PluralRules object is michael@0: * returned. michael@0: * @param type The plural type (e.g., cardinal or ordinal). michael@0: * @param status Output param set to success/failure code on exit, which michael@0: * must not indicate a failure before the function call. michael@0: * @return The predefined PluralRules object pointer for michael@0: * this locale. If there's no predefined rules for this locale, michael@0: * the rules for the closest parent in the locale hierarchy michael@0: * that has one will be returned. The final fallback always michael@0: * returns the default 'other' rules. michael@0: * @stable ICU 50 michael@0: */ michael@0: static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UPluralType type, UErrorCode& status); michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Return a StringEnumeration over the locales for which there is plurals data. michael@0: * @return a StringEnumeration over the locales available. michael@0: * @internal michael@0: */ michael@0: static StringEnumeration* U_EXPORT2 getAvailableLocales(UErrorCode &status); michael@0: michael@0: /** michael@0: * Returns whether or not there are overrides. michael@0: * @param locale the locale to check. michael@0: * @return michael@0: * @internal michael@0: */ michael@0: static UBool hasOverride(const Locale &locale); michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * Given a number, returns the keyword of the first rule that applies to michael@0: * the number. This function can be used with isKeyword* functions to michael@0: * determine the keyword for default plural rules. michael@0: * michael@0: * @param number The number for which the rule has to be determined. michael@0: * @return The keyword of the selected rule. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: UnicodeString select(int32_t number) const; michael@0: michael@0: /** michael@0: * Given a number, returns the keyword of the first rule that applies to michael@0: * the number. This function can be used with isKeyword* functions to michael@0: * determine the keyword for default plural rules. michael@0: * michael@0: * @param number The number for which the rule has to be determined. michael@0: * @return The keyword of the selected rule. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: UnicodeString select(double number) const; michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * @internal michael@0: */ michael@0: UnicodeString select(const FixedDecimal &number) const; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * Returns a list of all rule keywords used in this PluralRules michael@0: * object. The rule 'other' is always present by default. michael@0: * michael@0: * @param status Output param set to success/failure code on exit, which michael@0: * must not indicate a failure before the function call. michael@0: * @return StringEnumeration with the keywords. michael@0: * The caller must delete the object. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: StringEnumeration* getKeywords(UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Returns a unique value for this keyword if it exists, else the constant michael@0: * UPLRULES_NO_UNIQUE_VALUE. michael@0: * michael@0: * @param keyword The keyword. michael@0: * @return The unique value that generates the keyword, or michael@0: * UPLRULES_NO_UNIQUE_VALUE if the keyword is undefined or there is no michael@0: * unique value that generates this keyword. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: double getUniqueKeywordValue(const UnicodeString& keyword); michael@0: michael@0: /** michael@0: * Returns all the values for which select() would return the keyword. If michael@0: * the keyword is unknown, returns no values, but this is not an error. If michael@0: * the number of values is unlimited, returns no values and -1 as the michael@0: * count. michael@0: * michael@0: * The number of returned values is typically small. michael@0: * michael@0: * @param keyword The keyword. michael@0: * @param dest Array into which to put the returned values. May michael@0: * be NULL if destCapacity is 0. michael@0: * @param destCapacity The capacity of the array, must be at least 0. michael@0: * @param status The error code. michael@0: * @return The count of values available, or -1. This count michael@0: * can be larger than destCapacity, but no more than michael@0: * destCapacity values will be written. michael@0: * @stable ICU 4.8 michael@0: */ michael@0: int32_t getAllKeywordValues(const UnicodeString &keyword, michael@0: double *dest, int32_t destCapacity, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns sample values for which select() would return the keyword. If michael@0: * the keyword is unknown, returns no values, but this is not an error. michael@0: * michael@0: * The number of returned values is typically small. michael@0: * michael@0: * @param keyword The keyword. michael@0: * @param dest Array into which to put the returned values. May michael@0: * be NULL if destCapacity is 0. michael@0: * @param destCapacity The capacity of the array, must be at least 0. michael@0: * @param status The error code. michael@0: * @return The count of values written. michael@0: * If more than destCapacity samples are available, then michael@0: * only destCapacity are written, and destCapacity is returned as the count, michael@0: * rather than setting a U_BUFFER_OVERFLOW_ERROR. michael@0: * (The actual number of keyword values could be unlimited.) michael@0: * @stable ICU 4.8 michael@0: */ michael@0: int32_t getSamples(const UnicodeString &keyword, michael@0: double *dest, int32_t destCapacity, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Returns TRUE if the given keyword is defined in this michael@0: * PluralRules object. michael@0: * michael@0: * @param keyword the input keyword. michael@0: * @return TRUE if the input keyword is defined. michael@0: * Otherwise, return FALSE. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: UBool isKeyword(const UnicodeString& keyword) const; michael@0: michael@0: michael@0: /** michael@0: * Returns keyword for default plural form. michael@0: * michael@0: * @return keyword for default plural form. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: UnicodeString getKeywordOther() const; michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * michael@0: * @internal michael@0: */ michael@0: UnicodeString getRules() const; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * Compares the equality of two PluralRules objects. michael@0: * michael@0: * @param other The other PluralRules object to be compared with. michael@0: * @return True if the given PluralRules is the same as this michael@0: * PluralRules; false otherwise. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: virtual UBool operator==(const PluralRules& other) const; michael@0: michael@0: /** michael@0: * Compares the inequality of two PluralRules objects. michael@0: * michael@0: * @param other The PluralRules object to be compared with. michael@0: * @return True if the given PluralRules is not the same as this michael@0: * PluralRules; false otherwise. michael@0: * @stable ICU 4.0 michael@0: */ michael@0: UBool operator!=(const PluralRules& other) const {return !operator==(other);} michael@0: michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for this class. michael@0: * michael@0: * @stable ICU 4.0 michael@0: * michael@0: */ michael@0: static UClassID U_EXPORT2 getStaticClassID(void); michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for the actual class. michael@0: * michael@0: * @stable ICU 4.0 michael@0: */ michael@0: virtual UClassID getDynamicClassID() const; michael@0: michael@0: michael@0: private: michael@0: RuleChain *mRules; michael@0: michael@0: PluralRules(); // default constructor not implemented michael@0: void parseDescription(const UnicodeString& ruleData, UErrorCode &status); michael@0: int32_t getNumberValue(const UnicodeString& token) const; michael@0: UnicodeString getRuleFromResource(const Locale& locale, UPluralType type, UErrorCode& status); michael@0: RuleChain *rulesForKeyword(const UnicodeString &keyword) const; michael@0: michael@0: friend class PluralRuleParser; michael@0: }; michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif /* #if !UCONFIG_NO_FORMATTING */ michael@0: michael@0: #endif // _PLURRULE michael@0: //eof