PluralRules Class Reference

Defines rules for mapping positive long values onto a small set of keywords. More...

#include <plurrule.h>

Inheritance diagram for PluralRules:
UObject UMemory

Public Member Functions

 PluralRules (UErrorCode &status)
 Constructor.
 PluralRules (const PluralRules &other)
 Copy constructor.
virtual ~PluralRules ()
 Destructor.
PluralRulesclone () const
 Clone.
PluralRulesoperator= (const PluralRules &)
 Assignment operator.
UnicodeString select (int32_t number) const
 Given a number, returns the keyword of the first rule that applies to the number.
UnicodeString select (double number) const
 Given a number, returns the keyword of the first rule that applies to the number.
StringEnumerationgetKeywords (UErrorCode &status) const
 Returns a list of all rule keywords used in this PluralRules object.
UBool isKeyword (const UnicodeString &keyword) const
 Returns TRUE if the given keyword is defined in this PluralRules object.
UnicodeString getKeywordOther () const
 Returns keyword for default plural form.
virtual UBool operator== (const PluralRules &other) const
 Compares the equality of two PluralRules objects.
UBool operator!= (const PluralRules &other) const
 Compares the inequality of two PluralRules objects.
virtual UClassID getDynamicClassID () const
 ICU "poor man's RTTI", returns a UClassID for the actual class.

Static Public Member Functions

static PluralRulescreateRules (const UnicodeString &description, UErrorCode &status)
 Creates a PluralRules from a description if it is parsable, otherwise returns null.
static PluralRulescreateDefaultRules (UErrorCode &status)
 The default rules that accept any number.
static PluralRulesforLocale (const Locale &locale, UErrorCode &status)
 Provides access to the predefined PluralRules for a given locale.
static UClassID getStaticClassID (void)
 ICU "poor man's RTTI", returns a UClassID for this class.

Detailed Description

Defines rules for mapping positive long values onto a small set of keywords.

Rules are constructed from a text description, consisting of a series of keywords and conditions. The 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.

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 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      = is_relation | in_relation | within_relation | 'n' <EOL>
 is_relation   = expr 'is' ('not')? value
 in_relation   = expr ('not')? 'in' range
 within_relation = expr ('not')? 'within' range
 expr          = 'n' ('mod' value)?
 value         = digit+
 digit         = 0|1|2|3|4|5|6|7|8|9
 range         = value'..'value

The difference between 'in' and 'within' is that 'in' only includes integers in the specified range, while 'within' includes all values.

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

Examples:

 UnicodeString keyword = pl->select(number);
 if (keyword== UnicodeString("one") {
     ...
 }
 else if ( ... )
 

Definition at line 104 of file plurrule.h.


Constructor & Destructor Documentation

PluralRules::PluralRules ( UErrorCode status  ) 

Constructor.

Parameters:
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::PluralRules ( const PluralRules other  ) 

Copy constructor.

Stable:
ICU 4.0
virtual PluralRules::~PluralRules (  )  [virtual]

Destructor.

Stable:
ICU 4.0

Member Function Documentation

PluralRules* PluralRules::clone (  )  const

Clone.

Stable:
ICU 4.0
static PluralRules* PluralRules::createDefaultRules ( UErrorCode status  )  [static]

The default rules that accept any number.

Parameters:
status Output param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns:
new PluralRules pointer. NULL if there is an error.
Stable:
ICU 4.0
static PluralRules* PluralRules::createRules ( const UnicodeString description,
UErrorCode status 
) [static]

Creates a PluralRules from a description if it is parsable, otherwise returns null.

Parameters:
description rule description
status Output param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns:
new PluralRules pointer. NULL if there is an error.
Stable:
ICU 4.0
static PluralRules* PluralRules::forLocale ( const Locale locale,
UErrorCode status 
) [static]

Provides access to the predefined PluralRules for a given locale.

Parameters:
locale The locale for which a PluralRules object is returned.
status Output param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns:
The predefined PluralRules 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
virtual UClassID PluralRules::getDynamicClassID (  )  const [virtual]

ICU "poor man's RTTI", returns a UClassID for the actual class.

Stable:
ICU 4.0

Implements UObject.

UnicodeString PluralRules::getKeywordOther (  )  const

Returns keyword for default plural form.

Returns:
keyword for default plural form.
Internal:
Do not use. This API is for internal use only. 4.0
Stable:
ICU 4.0
StringEnumeration* PluralRules::getKeywords ( UErrorCode status  )  const

Returns a list of all rule keywords used in this PluralRules object.

The rule 'other' is always present by default.

Parameters:
status Output param set to success/failure code on exit, which must not indicate a failure before the function call.
Returns:
StringEnumeration with the keywords. The caller must delete the object.
Stable:
ICU 4.0
static UClassID PluralRules::getStaticClassID ( void   )  [static]

ICU "poor man's RTTI", returns a UClassID for this class.

Stable:
ICU 4.0
UBool PluralRules::isKeyword ( const UnicodeString keyword  )  const

Returns TRUE if the given keyword is defined in this PluralRules object.

Parameters:
keyword the input keyword.
Returns:
TRUE if the input keyword is defined. Otherwise, return FALSE.
Stable:
ICU 4.0
UBool PluralRules::operator!= ( const PluralRules other  )  const [inline]

Compares the inequality of two PluralRules objects.

Parameters:
other The PluralRules object to be compared with.
Returns:
True if the given PluralRules is not the same as this PluralRules; false otherwise.
Stable:
ICU 4.0

Definition at line 253 of file plurrule.h.

PluralRules& PluralRules::operator= ( const PluralRules  ) 

Assignment operator.

Stable:
ICU 4.0
virtual UBool PluralRules::operator== ( const PluralRules other  )  const [virtual]

Compares the equality of two PluralRules objects.

Parameters:
other The other PluralRules object to be compared with.
Returns:
True if the given PluralRules is the same as this PluralRules; false otherwise.
Stable:
ICU 4.0
UnicodeString PluralRules::select ( double  number  )  const

Given a number, returns the keyword of the first rule that applies to the number.

This function can be used with isKeyword* functions to determine the keyword for default plural rules.

Parameters:
number The number for which the rule has to be determined.
Returns:
The keyword of the selected rule.
Stable:
ICU 4.0
UnicodeString PluralRules::select ( int32_t  number  )  const

Given a number, returns the keyword of the first rule that applies to the number.

This function can be used with isKeyword* functions to determine the keyword for default plural rules.

Parameters:
number The number for which the rule has to be determined.
Returns:
The keyword of the selected rule.
Stable:
ICU 4.0

The documentation for this class was generated from the following file:
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on Sat Jan 23 15:17:43 2010 for ICU 4.3.4 by  doxygen 1.6.1