/src/icu/source/i18n/unicode/plurrule.h

Source (jump to first uncovered line)
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
* Copyright (C) 2008-2015, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*
*
* File PLURRULE.H
*
* Modification History:*
*   Date        Name        Description
*
********************************************************************************
*/

#ifndef PLURRULE
#define PLURRULE

#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

/**
 * \file
 * \brief C++ API: PluralRules object
 */

#if !UCONFIG_NO_FORMATTING

#include "unicode/format.h"
#include "unicode/upluralrules.h"
#ifndef U_HIDE_INTERNAL_API
#include "unicode/numfmt.h"
#endif  /* U_HIDE_INTERNAL_API */

/**
 * Value returned by PluralRules::getUniqueKeywordValue() when there is no
 * unique value to return.
 * @stable ICU 4.8
 */
#define UPLRULES_NO_UNIQUE_VALUE ((double)-0.00123456777)

U_NAMESPACE_BEGIN

class Hashtable;
class IFixedDecimal;
class FixedDecimal;
class RuleChain;
class PluralRuleParser;
class PluralKeywordEnumeration;
class AndConstraint;
class SharedPluralRules;
class StandardPluralRanges;

namespace number {
class FormattedNumber;
class FormattedNumberRange;
namespace impl {
class UFormattedNumberRangeData;
}
}

/**
 * Defines rules for mapping non-negative numeric values onto a small set of
 * keywords. Rules are constructed from a text description, consisting
 * of a series of keywords and conditions.  The {@link #select} method
 * examines each condition in order and returns the keyword for the
 * first condition that matches the number.  If none match,
 * default rule(other) is returned.
 *
 * For more information, details, and tips for writing rules, see the
 * LDML spec, C.11 Language Plural Rules:
 * http://www.unicode.org/draft/reports/tr35/tr35.html#Language_Plural_Rules
 *
 * Examples:<pre>
 *   "one: n is 1; few: n in 2..4"</pre>
 *  This defines two rules, for 'one' and 'few'.  The condition for
 *  'one' is "n is 1" which means that the number must be equal to
 *  1 for this condition to pass.  The condition for 'few' is
 *  "n in 2..4" which means that the number must be between 2 and
 *  4 inclusive for this condition to pass.  All other numbers
 *  are assigned the keyword "other" by the default rule.
 *  </p><pre>
 *    "zero: n is 0; one: n is 1; zero: n mod 100 in 1..19"</pre>
 *  This illustrates that the same keyword can be defined multiple times.
 *  Each rule is examined in order, and the first keyword whose condition
 *  passes is the one returned.  Also notes that a modulus is applied
 *  to n in the last rule.  Thus its condition holds for 119, 219, 319...
 *  </p><pre>
 *    "one: n is 1; few: n mod 10 in 2..4 and n mod 100 not in 12..14"</pre>
 *  This illustrates conjunction and negation.  The condition for 'few'
 *  has two parts, both of which must be met: "n mod 10 in 2..4" and
 *  "n mod 100 not in 12..14".  The first part applies a modulus to n
 *  before the test as in the previous example.  The second part applies
 *  a different modulus and also uses negation, thus it matches all
 *  numbers _not_ in 12, 13, 14, 112, 113, 114, 212, 213, 214...
 *  </p>
 *  <p>
 * Syntax:<pre>
 * \code
 * rules         = rule (';' rule)*
 * rule          = keyword ':' condition
 * keyword       = <identifier>
 * condition     = and_condition ('or' and_condition)*
 * and_condition = relation ('and' relation)*
 * relation      = is_relation | in_relation | within_relation | 'n' <EOL>
 * is_relation   = expr 'is' ('not')? value
 * in_relation   = expr ('not')? 'in' range_list
 * within_relation = expr ('not')? 'within' range
 * expr          = ('n' | 'i' | 'f' | 'v' | 'j') ('mod' value)?
 * range_list    = (range | value) (',' range_list)*
 * value         = digit+  ('.' digit+)?
 * digit         = 0|1|2|3|4|5|6|7|8|9
 * range         = value'..'value
 * \endcode
 * </pre></p>
 * <p>
 * <p>
 * The i, f, and v values are defined as follows:
 * </p>
 * <ul>
 * <li>i to be the integer digits.</li>
 * <li>f to be the visible fractional digits, as an integer.</li>
 * <li>v to be the number of visible fraction digits.</li>
 * <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>
 * </ul>
 * <p>
 * Examples are in the following table:
 * </p>
 * <table border='1' style="border-collapse:collapse">
 * <tr>
 * <th>n</th>
 * <th>i</th>
 * <th>f</th>
 * <th>v</th>
 * </tr>
 * <tr>
 * <td>1.0</td>
 * <td>1</td>
 * <td align="right">0</td>
 * <td>1</td>
 * </tr>
 * <tr>
 * <td>1.00</td>
 * <td>1</td>
 * <td align="right">0</td>
 * <td>2</td>
 * </tr>
 * <tr>
 * <td>1.3</td>
 * <td>1</td>
 * <td align="right">3</td>
 * <td>1</td>
 * </tr>
 * <tr>
 * <td>1.03</td>
 * <td>1</td>
 * <td align="right">3</td>
 * <td>2</td>
 * </tr>
 * <tr>
 * <td>1.23</td>
 * <td>1</td>
 * <td align="right">23</td>
 * <td>2</td>
 * </tr>
 * </table>
 * <p>
 * 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).
 * </p>

 * An "identifier" is a sequence of characters that do not have the
 * Unicode Pattern_Syntax or Pattern_White_Space properties.
 * <p>
 * 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).
 *</p>
 * <p>
 * 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.
 * </p>
 *
 * Examples:<pre>
 * UnicodeString keyword = pl->select(number);
 * if (keyword== UnicodeString("one") {
 *     ...
 * }
 * else if ( ... )
 * </pre>
 * <strong>Note:</strong><br>
 *  <p>
 *   ICU defines plural rules for many locales based on CLDR <i>Language Plural Rules</i>.
 *   For these predefined rules, see CLDR page at
 *    http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html
 * </p>
 */
class U_I18N_API PluralRules : public UObject {
public:

    /**
     * Constructor.
     * @param status  Output param set to success/failure code on exit, which
     *                must not indicate a failure before the function call.
     *
     * @stable ICU 4.0
     */
    PluralRules(UErrorCode& status);

    /**
     * Copy constructor.
     * @stable ICU 4.0
     */
    PluralRules(const PluralRules& other);

    /**
     * Destructor.
     * @stable ICU 4.0
     */
    virtual ~PluralRules();

    /**
     * Clone
     * @stable ICU 4.0
     */
    PluralRules* clone() const;

    /**
      * Assignment operator.
      * @stable ICU 4.0
      */
    PluralRules& operator=(const PluralRules&);

    /**
     * Creates a PluralRules from a description if it is parsable, otherwise
     * returns NULL.
     *
     * @param description rule description
     * @param status      Output param set to success/failure code on exit, which
     *                    must not indicate a failure before the function call.
     * @return            new PluralRules pointer. NULL if there is an error.
     * @stable ICU 4.0
     */
    static PluralRules* U_EXPORT2 createRules(const UnicodeString& description,
                                              UErrorCode& status);

    /**
     * The default rules that accept any number.
     *
     * @param status  Output param set to success/failure code on exit, which
     *                must not indicate a failure before the function call.
     * @return        new PluralRules pointer. NULL if there is an error.
     * @stable ICU 4.0
     */
    static PluralRules* U_EXPORT2 createDefaultRules(UErrorCode& status);

    /**
     * Provides access to the predefined cardinal-number <code>PluralRules</code> for a given
     * locale.
     * Same as forLocale(locale, UPLURAL_TYPE_CARDINAL, status).
     *
     * @param locale  The locale for which a <code>PluralRules</code> object is
     *                returned.
     * @param status  Output param set to success/failure code on exit, which
     *                must not indicate a failure before the function call.
     * @return        The predefined <code>PluralRules</code> object 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 4.0
     */
    static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UErrorCode& status);

    /**
     * Provides access to the predefined <code>PluralRules</code> for a given
     * locale and the plural type.
     *
     * @param locale  The locale for which a <code>PluralRules</code> object 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 predefined <code>PluralRules</code> object 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 an integer, returns the keyword of the first rule
     * that applies to  the number.  This function can be used with
     * isKeyword* functions to determine the keyword for default plural rules.
     *
     * @param number  The number for which the rule has to be determined.
     * @return        The keyword of the selected rule.
     * @stable ICU 4.0
     */
    UnicodeString select(int32_t number) const;

    /**
     * Given a floating-point number, returns the keyword of the first rule
     * that applies to  the number.  This function can be used with
     * isKeyword* functions to determine the keyword for default plural rules.
     *
     * @param number  The number for which the rule has to be determined.
     * @return        The keyword of the selected rule.
     * @stable ICU 4.0
     */
    UnicodeString select(double number) const;

    /**
     * Given a formatted number, returns the keyword of the first rule
     * that applies to  the number.  This function can be used with
     * isKeyword* functions to determine the keyword for default plural rules.
     *
     * A FormattedNumber allows you to specify an exponent or trailing zeros,
     * which can affect the plural category. To get a FormattedNumber, see
     * NumberFormatter.
     *
     * @param number  The number for which the rule has to be determined.
     * @param status  Set if an error occurs while selecting plural keyword.
     *                This could happen if the FormattedNumber is invalid.
     * @return        The keyword of the selected rule.
     * @stable ICU 64
     */
    UnicodeString select(const number::FormattedNumber& number, UErrorCode& status) const;

    /**
     * Given a formatted number range, returns the overall plural form of the
     * range. For example, "3-5" returns "other" in English.
     *
     * To get a FormattedNumberRange, see NumberRangeFormatter.
     * 
     * This method only works if PluralRules was created with a locale. If it was created
     * from PluralRules::createRules(), this method sets status code U_UNSUPPORTED_ERROR.
     * 
     * @param range  The number range onto which the rules will be applied.
     * @param status Set if an error occurs while selecting plural keyword.
     *               This could happen if the FormattedNumberRange is invalid,
     *               or if plural ranges data is unavailable.
     * @return       The keyword of the selected rule.
     * @stable ICU 68
     */
    UnicodeString select(const number::FormattedNumberRange& range, UErrorCode& status) const;

#ifndef U_HIDE_INTERNAL_API
    /**
     * @internal
     */
    UnicodeString select(const IFixedDecimal &number) const;
    /**
     * @internal
     */
    UnicodeString select(const number::impl::UFormattedNumberRangeData* urange, UErrorCode& status) const;
#endif  /* U_HIDE_INTERNAL_API */

    /**
     * Returns a list of all rule keywords used in this <code>PluralRules</code>
     * object.  The rule 'other' is always present by default.
     *
     * @param status Output param set to success/failure code on exit, which
     *               must not indicate a failure before the function call.
     * @return       StringEnumeration with the keywords.
     *               The caller must delete the object.
     * @stable ICU 4.0
     */
    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);

#ifndef U_HIDE_INTERNAL_API
    /**
     * Internal-only function that returns FixedDecimals instead of doubles.
     *
     * 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.)
     * @internal
     */
    int32_t getSamples(const UnicodeString &keyword,
                       FixedDecimal *dest, int32_t destCapacity,
                       UErrorCode& status);
#endif  /* U_HIDE_INTERNAL_API */

    /**
     * Returns true if the given keyword is defined in this
     * <code>PluralRules</code> object.
     *
     * @param keyword  the input keyword.
     * @return         true if the input keyword is defined.
     *                 Otherwise, return false.
     * @stable ICU 4.0
     */
    UBool isKeyword(const UnicodeString& keyword) const;


    /**
     * Returns keyword for default plural form.
     *
     * @return         keyword for default plural form.
     * @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.
     *
     * @param other The other PluralRules object to be compared with.
     * @return      true if the given PluralRules is the same as this
     *              PluralRules; false otherwise.
     * @stable ICU 4.0
     */
    virtual bool operator==(const PluralRules& other) const;

    /**
     * Compares the inequality of two PluralRules objects.
     *
     * @param other The PluralRules object to be compared with.
     * @return      true if the given PluralRules is not the same as this
     *              PluralRules; false otherwise.
     * @stable ICU 4.0
     */
    bool operator!=(const PluralRules& other) const  {return !operator==(other);}


    /**
     * ICU "poor man's RTTI", returns a UClassID for this class.
     *
     * @stable ICU 4.0
     *
    */
    static UClassID U_EXPORT2 getStaticClassID(void);

    /**
     * ICU "poor man's RTTI", returns a UClassID for the actual class.
     *
     * @stable ICU 4.0
     */
    virtual UClassID getDynamicClassID() const;


private:
    RuleChain  *mRules;
    StandardPluralRanges *mStandardPluralRanges;

    PluralRules();   // default constructor not implemented
    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;
    PluralRules    *clone(UErrorCode& status) const;

    /**
    * An internal status variable used to indicate that the object is in an 'invalid' state.
    * Used by copy constructor, the assignment operator and the clone method.
    */
    UErrorCode mInternalStatus;

    friend class PluralRuleParser;
};

U_NAMESPACE_END

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif /* U_SHOW_CPLUSPLUS_API */

#endif // _PLURRULE
//eof

Coverage Report

Created: 2023-02-22 06:51

Line	Count	Source (jump to first uncovered line)
1		// © 2016 and later: Unicode, Inc. and others.
2		// License & terms of use: http://www.unicode.org/copyright.html
3		/*
4		*******************************************************************************
5		* Copyright (C) 2008-2015, International Business Machines Corporation and
6		* others. All Rights Reserved.
7		*******************************************************************************
8		*
9		*
10		* File PLURRULE.H
11		*
12		* Modification History:*
13		* Date Name Description
14		*
15		********************************************************************************
16		*/
17
18		#ifndef PLURRULE
19		#define PLURRULE
20
21		#include "unicode/utypes.h"
22
23		#if U_SHOW_CPLUSPLUS_API
24
25		/**
26		* \file
27		* \brief C++ API: PluralRules object
28		*/
29
30		#if !UCONFIG_NO_FORMATTING
31
32		#include "unicode/format.h"
33		#include "unicode/upluralrules.h"
34		#ifndef U_HIDE_INTERNAL_API
35		#include "unicode/numfmt.h"
36		#endif /* U_HIDE_INTERNAL_API */
37
38		/**
39		* Value returned by PluralRules::getUniqueKeywordValue() when there is no
40		* unique value to return.
41		* @stable ICU 4.8
42		*/
43	0	#define UPLRULES_NO_UNIQUE_VALUE ((double)-0.00123456777)
44
45		U_NAMESPACE_BEGIN
46
47		class Hashtable;
48		class IFixedDecimal;
49		class FixedDecimal;
50		class RuleChain;
51		class PluralRuleParser;
52		class PluralKeywordEnumeration;
53		class AndConstraint;
54		class SharedPluralRules;
55		class StandardPluralRanges;
56
57		namespace number {
58		class FormattedNumber;
59		class FormattedNumberRange;
60		namespace impl {
61		class UFormattedNumberRangeData;
62		}
63		}
64
65		/**
66		* Defines rules for mapping non-negative numeric values onto a small set of
67		* keywords. Rules are constructed from a text description, consisting
68		* of a series of keywords and conditions. The {@link #select} method
69		* examines each condition in order and returns the keyword for the
70		* first condition that matches the number. If none match,
71		* default rule(other) is returned.
72		*
73		* For more information, details, and tips for writing rules, see the
74		* LDML spec, C.11 Language Plural Rules:
75		* http://www.unicode.org/draft/reports/tr35/tr35.html#Language_Plural_Rules
76		*
77		* Examples:<pre>
78		* "one: n is 1; few: n in 2..4"</pre>
79		* This defines two rules, for 'one' and 'few'. The condition for
80		* 'one' is "n is 1" which means that the number must be equal to
81		* 1 for this condition to pass. The condition for 'few' is
82		* "n in 2..4" which means that the number must be between 2 and
83		* 4 inclusive for this condition to pass. All other numbers
84		* are assigned the keyword "other" by the default rule.
85		* </p><pre>
86		* "zero: n is 0; one: n is 1; zero: n mod 100 in 1..19"</pre>
87		* This illustrates that the same keyword can be defined multiple times.
88		* Each rule is examined in order, and the first keyword whose condition
89		* passes is the one returned. Also notes that a modulus is applied
90		* to n in the last rule. Thus its condition holds for 119, 219, 319...
91		* </p><pre>
92		* "one: n is 1; few: n mod 10 in 2..4 and n mod 100 not in 12..14"</pre>
93		* This illustrates conjunction and negation. The condition for 'few'
94		* has two parts, both of which must be met: "n mod 10 in 2..4" and
95		* "n mod 100 not in 12..14". The first part applies a modulus to n
96		* before the test as in the previous example. The second part applies
97		* a different modulus and also uses negation, thus it matches all
98		* numbers _not_ in 12, 13, 14, 112, 113, 114, 212, 213, 214...
99		* </p>
100		* <p>
101		* Syntax:<pre>
102		* \code
103		* rules = rule (';' rule)*
104		* rule = keyword ':' condition
105		* keyword = <identifier>
106		* condition = and_condition ('or' and_condition)*
107		* and_condition = relation ('and' relation)*
108		* relation = is_relation \| in_relation \| within_relation \| 'n' <EOL>
109		* is_relation = expr 'is' ('not')? value
110		* in_relation = expr ('not')? 'in' range_list
111		* within_relation = expr ('not')? 'within' range
112		* expr = ('n' \| 'i' \| 'f' \| 'v' \| 'j') ('mod' value)?
113		* range_list = (range \| value) (',' range_list)*
114		* value = digit+ ('.' digit+)?
115		* digit = 0\|1\|2\|3\|4\|5\|6\|7\|8\|9
116		* range = value'..'value
117		* \endcode
118		* </pre></p>
119		* <p>
120		* <p>
121		* The i, f, and v values are defined as follows:
122		* </p>
123		* <ul>
124		* <li>i to be the integer digits.</li>
125		* <li>f to be the visible fractional digits, as an integer.</li>
126		* <li>v to be the number of visible fraction digits.</li>
127		* <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>
128		* </ul>
129		* <p>
130		* Examples are in the following table:
131		* </p>
132		* <table border='1' style="border-collapse:collapse">
133		* <tr>
134		* <th>n</th>
135		* <th>i</th>
136		* <th>f</th>
137		* <th>v</th>
138		* </tr>
139		* <tr>
140		* <td>1.0</td>
141		* <td>1</td>
142		* <td align="right">0</td>
143		* <td>1</td>
144		* </tr>
145		* <tr>
146		* <td>1.00</td>
147		* <td>1</td>
148		* <td align="right">0</td>
149		* <td>2</td>
150		* </tr>
151		* <tr>
152		* <td>1.3</td>
153		* <td>1</td>
154		* <td align="right">3</td>
155		* <td>1</td>
156		* </tr>
157		* <tr>
158		* <td>1.03</td>
159		* <td>1</td>
160		* <td align="right">3</td>
161		* <td>2</td>
162		* </tr>
163		* <tr>
164		* <td>1.23</td>
165		* <td>1</td>
166		* <td align="right">23</td>
167		* <td>2</td>
168		* </tr>
169		* </table>
170		* <p>
171		* The difference between 'in' and 'within' is that 'in' only includes integers in the specified range, while 'within'
172		* includes all values. Using 'within' with a range_list consisting entirely of values is the same as using 'in' (it's
173		* not an error).
174		* </p>
175
176		* An "identifier" is a sequence of characters that do not have the
177		* Unicode Pattern_Syntax or Pattern_White_Space properties.
178		* <p>
179		* The difference between 'in' and 'within' is that 'in' only includes
180		* integers in the specified range, while 'within' includes all values.
181		* Using 'within' with a range_list consisting entirely of values is the
182		* same as using 'in' (it's not an error).
183		*</p>
184		* <p>
185		* Keywords
186		* could be defined by users or from ICU locale data. There are 6
187		* predefined values in ICU - 'zero', 'one', 'two', 'few', 'many' and
188		* 'other'. Callers need to check the value of keyword returned by
189		* {@link #select} method.
190		* </p>
191		*
192		* Examples:<pre>
193		* UnicodeString keyword = pl->select(number);
194		* if (keyword== UnicodeString("one") {
195		* ...
196		* }
197		* else if ( ... )
198		* </pre>
199		* <strong>Note:</strong><br>
200		* <p>
201		* ICU defines plural rules for many locales based on CLDR <i>Language Plural Rules</i>.
202		* For these predefined rules, see CLDR page at
203		* http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html
204		* </p>
205		*/
206		class U_I18N_API PluralRules : public UObject {
207		public:
208
209		/**
210		* Constructor.
211		* @param status Output param set to success/failure code on exit, which
212		* must not indicate a failure before the function call.
213		*
214		* @stable ICU 4.0
215		*/
216		PluralRules(UErrorCode& status);
217
218		/**
219		* Copy constructor.
220		* @stable ICU 4.0
221		*/
222		PluralRules(const PluralRules& other);
223
224		/**
225		* Destructor.
226		* @stable ICU 4.0
227		*/
228		virtual ~PluralRules();
229
230		/**
231		* Clone
232		* @stable ICU 4.0
233		*/
234		PluralRules* clone() const;
235
236		/**
237		* Assignment operator.
238		* @stable ICU 4.0
239		*/
240		PluralRules& operator=(const PluralRules&);
241
242		/**
243		* Creates a PluralRules from a description if it is parsable, otherwise
244		* returns NULL.
245		*
246		* @param description rule description
247		* @param status Output param set to success/failure code on exit, which
248		* must not indicate a failure before the function call.
249		* @return new PluralRules pointer. NULL if there is an error.
250		* @stable ICU 4.0
251		*/
252		static PluralRules* U_EXPORT2 createRules(const UnicodeString& description,
253		UErrorCode& status);
254
255		/**
256		* The default rules that accept any number.
257		*
258		* @param status Output param set to success/failure code on exit, which
259		* must not indicate a failure before the function call.
260		* @return new PluralRules pointer. NULL if there is an error.
261		* @stable ICU 4.0
262		*/
263		static PluralRules* U_EXPORT2 createDefaultRules(UErrorCode& status);
264
265		/**
266		* Provides access to the predefined cardinal-number <code>PluralRules</code> for a given
267		* locale.
268		* Same as forLocale(locale, UPLURAL_TYPE_CARDINAL, status).
269		*
270		* @param locale The locale for which a <code>PluralRules</code> object is
271		* returned.
272		* @param status Output param set to success/failure code on exit, which
273		* must not indicate a failure before the function call.
274		* @return The predefined <code>PluralRules</code> object pointer for
275		* this locale. If there's no predefined rules for this locale,
276		* the rules for the closest parent in the locale hierarchy
277		* that has one will be returned. The final fallback always
278		* returns the default 'other' rules.
279		* @stable ICU 4.0
280		*/
281		static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UErrorCode& status);
282
283		/**
284		* Provides access to the predefined <code>PluralRules</code> for a given
285		* locale and the plural type.
286		*
287		* @param locale The locale for which a <code>PluralRules</code> object is
288		* returned.
289		* @param type The plural type (e.g., cardinal or ordinal).
290		* @param status Output param set to success/failure code on exit, which
291		* must not indicate a failure before the function call.
292		* @return The predefined <code>PluralRules</code> object pointer for
293		* this locale. If there's no predefined rules for this locale,
294		* the rules for the closest parent in the locale hierarchy
295		* that has one will be returned. The final fallback always
296		* returns the default 'other' rules.
297		* @stable ICU 50
298		*/
299		static PluralRules* U_EXPORT2 forLocale(const Locale& locale, UPluralType type, UErrorCode& status);
300
301		#ifndef U_HIDE_INTERNAL_API
302		/**
303		* Return a StringEnumeration over the locales for which there is plurals data.
304		* @return a StringEnumeration over the locales available.
305		* @internal
306		*/
307		static StringEnumeration* U_EXPORT2 getAvailableLocales(UErrorCode &status);
308
309		/**
310		* Returns whether or not there are overrides.
311		* @param locale the locale to check.
312		* @return
313		* @internal
314		*/
315		static UBool hasOverride(const Locale &locale);
316
317		/**
318		* For ICU use only.
319		* creates a SharedPluralRules object
320		* @internal
321		*/
322		static PluralRules* U_EXPORT2 internalForLocale(const Locale& locale, UPluralType type, UErrorCode& status);
323
324		/**
325		* For ICU use only.
326		* Returns handle to the shared, cached PluralRules instance.
327		* Caller must call removeRef() on returned value once it is done with
328		* the shared instance.
329		* @internal
330		*/
331		static const SharedPluralRules* U_EXPORT2 createSharedInstance(
332		const Locale& locale, UPluralType type, UErrorCode& status);
333
334
335		#endif /* U_HIDE_INTERNAL_API */
336
337		/**
338		* Given an integer, returns the keyword of the first rule
339		* that applies to the number. This function can be used with
340		* isKeyword* functions to determine the keyword for default plural rules.
341		*
342		* @param number The number for which the rule has to be determined.
343		* @return The keyword of the selected rule.
344		* @stable ICU 4.0
345		*/
346		UnicodeString select(int32_t number) const;
347
348		/**
349		* Given a floating-point number, returns the keyword of the first rule
350		* that applies to the number. This function can be used with
351		* isKeyword* functions to determine the keyword for default plural rules.
352		*
353		* @param number The number for which the rule has to be determined.
354		* @return The keyword of the selected rule.
355		* @stable ICU 4.0
356		*/
357		UnicodeString select(double number) const;
358
359		/**
360		* Given a formatted number, returns the keyword of the first rule
361		* that applies to the number. This function can be used with
362		* isKeyword* functions to determine the keyword for default plural rules.
363		*
364		* A FormattedNumber allows you to specify an exponent or trailing zeros,
365		* which can affect the plural category. To get a FormattedNumber, see
366		* NumberFormatter.
367		*
368		* @param number The number for which the rule has to be determined.
369		* @param status Set if an error occurs while selecting plural keyword.
370		* This could happen if the FormattedNumber is invalid.
371		* @return The keyword of the selected rule.
372		* @stable ICU 64
373		*/
374		UnicodeString select(const number::FormattedNumber& number, UErrorCode& status) const;
375
376		/**
377		* Given a formatted number range, returns the overall plural form of the
378		* range. For example, "3-5" returns "other" in English.
379		*
380		* To get a FormattedNumberRange, see NumberRangeFormatter.
381		*
382		* This method only works if PluralRules was created with a locale. If it was created
383		* from PluralRules::createRules(), this method sets status code U_UNSUPPORTED_ERROR.
384		*
385		* @param range The number range onto which the rules will be applied.
386		* @param status Set if an error occurs while selecting plural keyword.
387		* This could happen if the FormattedNumberRange is invalid,
388		* or if plural ranges data is unavailable.
389		* @return The keyword of the selected rule.
390		* @stable ICU 68
391		*/
392		UnicodeString select(const number::FormattedNumberRange& range, UErrorCode& status) const;
393
394		#ifndef U_HIDE_INTERNAL_API
395		/**
396		* @internal
397		*/
398		UnicodeString select(const IFixedDecimal &number) const;
399		/**
400		* @internal
401		*/
402		UnicodeString select(const number::impl::UFormattedNumberRangeData* urange, UErrorCode& status) const;
403		#endif /* U_HIDE_INTERNAL_API */
404
405		/**
406		* Returns a list of all rule keywords used in this <code>PluralRules</code>
407		* object. The rule 'other' is always present by default.
408		*
409		* @param status Output param set to success/failure code on exit, which
410		* must not indicate a failure before the function call.
411		* @return StringEnumeration with the keywords.
412		* The caller must delete the object.
413		* @stable ICU 4.0
414		*/
415		StringEnumeration* getKeywords(UErrorCode& status) const;
416
417		#ifndef U_HIDE_DEPRECATED_API
418		/**
419		* Deprecated Function, does not return useful results.
420		*
421		* Originally intended to return a unique value for this keyword if it exists,
422		* else the constant UPLRULES_NO_UNIQUE_VALUE.
423		*
424		* @param keyword The keyword.
425		* @return Stub deprecated function returns UPLRULES_NO_UNIQUE_VALUE always.
426		* @deprecated ICU 55
427		*/
428		double getUniqueKeywordValue(const UnicodeString& keyword);
429
430		/**
431		* Deprecated Function, does not produce useful results.
432		*
433		* Originally intended to return all the values for which select() would return the keyword.
434		* If the keyword is unknown, returns no values, but this is not an error. If
435		* the number of values is unlimited, returns no values and -1 as the
436		* count.
437		*
438		* The number of returned values is typically small.
439		*
440		* @param keyword The keyword.
441		* @param dest Array into which to put the returned values. May
442		* be NULL if destCapacity is 0.
443		* @param destCapacity The capacity of the array, must be at least 0.
444		* @param status The error code. Deprecated function, always sets U_UNSUPPORTED_ERROR.
445		* @return The count of values available, or -1. This count
446		* can be larger than destCapacity, but no more than
447		* destCapacity values will be written.
448		* @deprecated ICU 55
449		*/
450		int32_t getAllKeywordValues(const UnicodeString &keyword,
451		double *dest, int32_t destCapacity,
452		UErrorCode& status);
453		#endif /* U_HIDE_DEPRECATED_API */
454
455		/**
456		* Returns sample values for which select() would return the keyword. If
457		* the keyword is unknown, returns no values, but this is not an error.
458		*
459		* The number of returned values is typically small.
460		*
461		* @param keyword The keyword.
462		* @param dest Array into which to put the returned values. May
463		* be NULL if destCapacity is 0.
464		* @param destCapacity The capacity of the array, must be at least 0.
465		* @param status The error code.
466		* @return The count of values written.
467		* If more than destCapacity samples are available, then
468		* only destCapacity are written, and destCapacity is returned as the count,
469		* rather than setting a U_BUFFER_OVERFLOW_ERROR.
470		* (The actual number of keyword values could be unlimited.)
471		* @stable ICU 4.8
472		*/
473		int32_t getSamples(const UnicodeString &keyword,
474		double *dest, int32_t destCapacity,
475		UErrorCode& status);
476
477		#ifndef U_HIDE_INTERNAL_API
478		/**
479		* Internal-only function that returns FixedDecimals instead of doubles.
480		*
481		* Returns sample values for which select() would return the keyword. If
482		* the keyword is unknown, returns no values, but this is not an error.
483		*
484		* The number of returned values is typically small.
485		*
486		* @param keyword The keyword.
487		* @param dest Array into which to put the returned values. May
488		* be NULL if destCapacity is 0.
489		* @param destCapacity The capacity of the array, must be at least 0.
490		* @param status The error code.
491		* @return The count of values written.
492		* If more than destCapacity samples are available, then
493		* only destCapacity are written, and destCapacity is returned as the count,
494		* rather than setting a U_BUFFER_OVERFLOW_ERROR.
495		* (The actual number of keyword values could be unlimited.)
496		* @internal
497		*/
498		int32_t getSamples(const UnicodeString &keyword,
499		FixedDecimal *dest, int32_t destCapacity,
500		UErrorCode& status);
501		#endif /* U_HIDE_INTERNAL_API */
502
503		/**
504		* Returns true if the given keyword is defined in this
505		* <code>PluralRules</code> object.
506		*
507		* @param keyword the input keyword.
508		* @return true if the input keyword is defined.
509		* Otherwise, return false.
510		* @stable ICU 4.0
511		*/
512		UBool isKeyword(const UnicodeString& keyword) const;
513
514
515		/**
516		* Returns keyword for default plural form.
517		*
518		* @return keyword for default plural form.
519		* @stable ICU 4.0
520		*/
521		UnicodeString getKeywordOther() const;
522
523		#ifndef U_HIDE_INTERNAL_API
524		/**
525		*
526		* @internal
527		*/
528		UnicodeString getRules() const;
529		#endif /* U_HIDE_INTERNAL_API */
530
531		/**
532		* Compares the equality of two PluralRules objects.
533		*
534		* @param other The other PluralRules object to be compared with.
535		* @return true if the given PluralRules is the same as this
536		* PluralRules; false otherwise.
537		* @stable ICU 4.0
538		*/
539		virtual bool operator==(const PluralRules& other) const;
540
541		/**
542		* Compares the inequality of two PluralRules objects.
543		*
544		* @param other The PluralRules object to be compared with.
545		* @return true if the given PluralRules is not the same as this
546		* PluralRules; false otherwise.
547		* @stable ICU 4.0
548		*/
549	0	bool operator!=(const PluralRules& other) const {return !operator==(other);}
550
551
552		/**
553		* ICU "poor man's RTTI", returns a UClassID for this class.
554		*
555		* @stable ICU 4.0
556		*
557		*/
558		static UClassID U_EXPORT2 getStaticClassID(void);
559
560		/**
561		* ICU "poor man's RTTI", returns a UClassID for the actual class.
562		*
563		* @stable ICU 4.0
564		*/
565		virtual UClassID getDynamicClassID() const;
566
567
568		private:
569		RuleChain *mRules;
570		StandardPluralRanges *mStandardPluralRanges;
571
572		PluralRules(); // default constructor not implemented
573		void parseDescription(const UnicodeString& ruleData, UErrorCode &status);
574		int32_t getNumberValue(const UnicodeString& token) const;
575		UnicodeString getRuleFromResource(const Locale& locale, UPluralType type, UErrorCode& status);
576		RuleChain *rulesForKeyword(const UnicodeString &keyword) const;
577		PluralRules *clone(UErrorCode& status) const;
578
579		/**
580		* An internal status variable used to indicate that the object is in an 'invalid' state.
581		* Used by copy constructor, the assignment operator and the clone method.
582		*/
583		UErrorCode mInternalStatus;
584
585		friend class PluralRuleParser;
586		};
587
588		U_NAMESPACE_END
589
590		#endif /* #if !UCONFIG_NO_FORMATTING */
591
592		#endif /* U_SHOW_CPLUSPLUS_API */
593
594		#endif // _PLURRULE
595		//eof