Package com.ibm.icu.text

Class PluralRules

  • All Implemented Interfaces:
    Serializable
    public class PluralRules
extends Object
implements Serializable

    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 select(double) method examines each condition in order and returns the keyword for the first condition that matches the number. If none match, KEYWORD_OTHER is returned.

    A PluralRules object is immutable. It contains caches for sample values, but those are synchronized.

    PluralRules is Serializable so that it can be used in formatters, which are serializable.

    For more information, details, and tips for writing rules, see the LDML spec, C.11 Language Plural Rules

    Examples: 

     "one: n is 1; few: n in 2..4"

    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 - and be an integer - for this condition to pass. All other numbers are assigned the keyword "other" by the default rule. 

     "zero: n is 0; one: n is 1; zero: n mod 100 in 1..19"

    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... 

     "one: n is 1; few: n mod 10 in 2..4 and n mod 100 not in 12..14"

    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...

    Syntax: 

     rules         = rule (';' rule)*
 rule          = keyword ':' condition
 keyword       = <identifier>
 condition     = and_condition ('or' and_condition)*
 and_condition = relation ('and' relation)*
 relation      = not? expr not? rel not? range_list
 expr          = ('n' | 'i' | 'f' | 'v' | 't') (mod value)?
 not           = 'not' | '!'
 rel           = 'in' | 'is' | '=' | '≠' | 'within'
 mod           = 'mod' | '%'
 range_list    = (range | value) (',' range_list)*
 value         = digit+
 digit         = 0|1|2|3|4|5|6|7|8|9
 range         = value'..'value

    Each not term inverts the meaning; however, there should not be more than one of them.

    The i, f, t, and v values are defined as follows:

    • i to be the integer digits.
    • f to be the visible decimal digits, as an integer.
    • t to be the visible decimal digits—without trailing zeros—as an integer.
    • v to be the number of visible fraction digits.
    • j is defined to only match integers. That is j is 3 fails if v != 0 (eg for 3.1 or 3.0).

    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

    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).

    See Also:
    Serialized Form

    • Method Detail

      • parseDescription

        public static PluralRules parseDescription​(String description)
                                    throws ParseException
        Parses a plural rules description and returns a PluralRules.
        Parameters:
        description - the rule description.
        Throws:
        ParseException - if the description cannot be parsed. The exception index is typically not set, it will be -1.

      • createRules

        public static PluralRules createRules​(String description)
        Creates a PluralRules from a description if it is parsable, otherwise returns null.
        Parameters:
        description - the rule description.
        Returns:
        the PluralRules

      • forLocale

        public static PluralRules forLocale​(ULocale locale)
        Provides access to the predefined cardinal-number PluralRules for a given locale. Same as forLocale(locale, PluralType.CARDINAL).

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

        Parameters:
        locale - The locale for which a PluralRules object is returned.
        Returns:
        The predefined PluralRules object 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 rules.

      • forLocale

        public static PluralRules forLocale​(Locale locale)
        Provides access to the predefined cardinal-number PluralRules for a given JDK locale. Same as forLocale(locale, PluralType.CARDINAL).

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

        Parameters:
        locale - The JDK locale for which a PluralRules object is returned.
        Returns:
        The predefined PluralRules object 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 rules.

      • forLocale

        public static PluralRules forLocale​(ULocale locale,
                                    PluralRules.PluralType type)
        Provides access to the predefined PluralRules for a given locale and the plural type.

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

        Parameters:
        locale - The locale for which a PluralRules object is returned.
        type - The plural type (e.g., cardinal or ordinal).
        Returns:
        The predefined PluralRules object 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 rules.

      • forLocale

        public static PluralRules forLocale​(Locale locale,
                                    PluralRules.PluralType type)
        Provides access to the predefined PluralRules for a given JDK locale and the plural type.

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

        Parameters:
        locale - The JDK locale for which a PluralRules object is returned.
        type - The plural type (e.g., cardinal or ordinal).
        Returns:
        The predefined PluralRules object 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 rules.

      • hashCode

        @Deprecated
public int hashCode()
        Deprecated.
        This API is ICU internal only.
        Description copied from class: Object
        Returns an integer hash code for this object. By contract, any two objects for which Object.equals(java.lang.Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

        Note that hash values must not change over time unless information used in equals comparisons also changes.

        See Writing a correct hashCode method if you intend implementing your own hashCode method.

        Overrides:
        hashCode in class Object
        Returns:
        this object's hash code.
        See Also:
        Object.equals(java.lang.Object)

      • select

        public String select​(double number)
        Given a number, returns the keyword of the first rule that applies to the number.
        Parameters:
        number - The number for which the rule has to be determined.
        Returns:
        The keyword of the selected rule.

      • select

        @Deprecated
public String select​(double number,
                     int countVisibleFractionDigits,
                     long fractionaldigits)
        Deprecated.
        This API is ICU internal only.
        Given a number, returns the keyword of the first rule that applies to the number.
        Parameters:
        number - The number for which the rule has to be determined.
        Returns:
        The keyword of the selected rule.

      • select

        @Deprecated
public String select​(PluralRules.FixedDecimal sample)
        Deprecated.
        This API is ICU internal only.
        Given a number information, returns the keyword of the first rule that applies to the number.
        Parameters:
        sample - The number information for which the rule has to be determined.
        Returns:
        The keyword of the selected rule.

      • matches

        @Deprecated
public boolean matches​(PluralRules.FixedDecimal sample,
                       String keyword)
        Deprecated.
        This API is ICU internal only.
        Given a number information, and keyword, return whether the keyword would match the number.
        Parameters:
        sample - The number information for which the rule has to be determined.
        keyword - The keyword to filter on

      • getKeywords

        public Set<String> getKeywords()
        Returns a set of all rule keywords used in this PluralRules object. The rule "other" is always present by default.
        Returns:
        The set of keywords.

      • getUniqueKeywordValue

        public double getUniqueKeywordValue​(String keyword)
        Returns the unique value that this keyword matches, or NO_UNIQUE_VALUE if the keyword matches multiple values or is not defined for this PluralRules.
        Parameters:
        keyword - the keyword to check for a unique value
        Returns:
        The unique value for the keyword, or NO_UNIQUE_VALUE.

      • getAllKeywordValues

        public Collection<Double> getAllKeywordValues​(String keyword)
        Returns all the values that trigger this keyword, or null if the number of such values is unlimited.
        Parameters:
        keyword - the keyword
        Returns:
        the values that trigger this keyword, or null. The returned collection is immutable. It will be empty if the keyword is not defined.

      • getAllKeywordValues

        @Deprecated
public Collection<Double> getAllKeywordValues​(String keyword,
                                              PluralRules.SampleType type)
        Deprecated.
        This API is ICU internal only.
        Returns all the values that trigger this keyword, or null if the number of such values is unlimited.
        Parameters:
        keyword - the keyword
        type - the type of samples requested, INTEGER or DECIMAL
        Returns:
        the values that trigger this keyword, or null. The returned collection is immutable. It will be empty if the keyword is not defined.

      • getSamples

        public Collection<Double> getSamples​(String keyword)
        Returns a list of integer values for which select() would return that keyword, or null if the keyword is not defined. The returned collection is unmodifiable. The returned list is not complete, and there might be additional values that would return the keyword.
        Parameters:
        keyword - the keyword to test
        Returns:
        a list of values matching the keyword.

      • getSamples

        @Deprecated
public Collection<Double> getSamples​(String keyword,
                                     PluralRules.SampleType sampleType)
        Deprecated.
        ICU internal only
        Returns a list of values for which select() would return that keyword, or null if the keyword is not defined. The returned collection is unmodifiable. The returned list is not complete, and there might be additional values that would return the keyword. The keyword might be defined, and yet have an empty set of samples, IF there are samples for the other sampleType.
        Parameters:
        keyword - the keyword to test
        sampleType - the type of samples requested, INTEGER or DECIMAL
        Returns:
        a list of values matching the keyword.

      • addSample

        @Deprecated
public boolean addSample​(String keyword,
                         Number sample,
                         int maxCount,
                         Set<Double> result)
        Deprecated.
        This API is ICU internal only.

      • getDecimalSamples

        @Deprecated
public PluralRules.FixedDecimalSamples getDecimalSamples​(String keyword,
                                                         PluralRules.SampleType sampleType)
        Deprecated.
        This API is ICU internal only.
        Returns a list of values for which select() would return that keyword, or null if the keyword is not defined or no samples are available. The returned collection is unmodifiable. The returned list is not complete, and there might be additional values that would return the keyword.
        Parameters:
        keyword - the keyword to test
        sampleType - the type of samples requested, INTEGER or DECIMAL
        Returns:
        a list of values matching the keyword.

      • getAvailableULocales

        public static ULocale[] getAvailableULocales()
        Returns the set of locales for which PluralRules are known.
        Returns:
        the set of locales for which PluralRules are known, as a list

      • getFunctionalEquivalent

        public static ULocale getFunctionalEquivalent​(ULocale locale,
                                              boolean[] isAvailable)
        Returns the 'functionally equivalent' locale with respect to plural rules. Calling PluralRules.forLocale with the functionally equivalent locale, and with the provided locale, returns rules that behave the same.
        All locales with the same functionally equivalent locale have plural rules that behave the same. This is not exaustive; there may be other locales whose plural rules behave the same that do not have the same equivalent locale.
        Parameters:
        locale - the locale to check
        isAvailable - if not null and of length > 0, this will hold 'true' at index 0 if locale is directly defined (without fallback) as having plural rules
        Returns:
        the functionally-equivalent locale

      • toString

        public String toString()
        Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression: 
           getClass().getName() + '@' + Integer.toHexString(hashCode())

        See Writing a useful toString method if you intend implementing your own toString method.

        Overrides:
        toString in class Object
        Returns:
        a printable representation of this object.

      • equals

        public boolean equals​(Object rhs)
        Compares this instance with the specified object and indicates if they are equal. In order to be equal, o must represent the same object as this instance using a class-specific comparison. The general contract is that this comparison should be reflexive, symmetric, and transitive. Also, no object reference other than null is equal to null.

        The default implementation returns true only if this == o. See Writing a correct equals method if you intend implementing your own equals method.

        The general contract for the equals and Object.hashCode() methods is that if equals returns true for any two objects, then hashCode() must return the same value for these objects. This means that subclasses of Object usually override either both methods or neither of them.

        Overrides:
        equals in class Object
        Parameters:
        rhs - the object to compare this instance with.
        Returns:
        true if the specified object is equal to this Object; false otherwise.
        See Also:
        Object.hashCode()

      • equals

        public boolean equals​(PluralRules rhs)
        Returns true if rhs is equal to this.
        Parameters:
        rhs - the PluralRules to compare to.
        Returns:
        true if this and rhs are equal.

      • getKeywordStatus

        public PluralRules.KeywordStatus getKeywordStatus​(String keyword,
                                                  int offset,
                                                  Set<Double> explicits,
                                                  Output<Double> uniqueValue)
        Find the status for the keyword, given a certain set of explicit values.
        Parameters:
        keyword - the particular keyword (call rules.getKeywords() to get the valid ones)
        offset - the offset used, or 0.0d if not. Internally, the offset is subtracted from each explicit value before checking against the keyword values.
        explicits - a set of Doubles that are used explicitly (eg [=0], "[=1]"). May be empty or null.
        uniqueValue - If non null, set to the unique value.
        Returns:
        the KeywordStatus

      • getKeywordStatus

        @Deprecated
public PluralRules.KeywordStatus getKeywordStatus​(String keyword,
                                                  int offset,
                                                  Set<Double> explicits,
                                                  Output<Double> uniqueValue,
                                                  PluralRules.SampleType sampleType)
        Deprecated.
        This API is ICU internal only.
        Find the status for the keyword, given a certain set of explicit values.
        Parameters:
        keyword - the particular keyword (call rules.getKeywords() to get the valid ones)
        offset - the offset used, or 0.0d if not. Internally, the offset is subtracted from each explicit value before checking against the keyword values.
        explicits - a set of Doubles that are used explicitly (eg [=0], "[=1]"). May be empty or null.
        sampleType - request KeywordStatus relative to INTEGER or DECIMAL values
        uniqueValue - If non null, set to the unique value.
        Returns:
        the KeywordStatus