Tizen Native API  5.0
PluralRules

Defines rules for mapping non-negative numeric values onto a small set of keywords.

Required Header

#include <utils_i18n.h>

Overview

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. For more information, details, and tips for writing rules, see the LDML spec, C.11 Language Plural Rules: https://www.unicode.org/reports/tr35/tr35-53/tr35-numbers.html#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 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_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

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

  • i to be the integer digits.
  • f to be the visible fractional digits, 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       1.0     1.00    1.3     1.03    1.23

          i       1       1       1       1       1

          f       0       0       3       3       23

          v       1       2       2       2       2

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

Example:

          char keyword[BUFSIZE] = { 0 };
          int32_t number = 10
          int32_t output_length = -1;
          i18n_plural_rules_select_int32(plural_rules, number, BUFSIZE, keyword, &output_length);
          if (strncmp(keyword, "one", output_length) == 0) {
               ...
          }
          else if ( ... )

Functions

int i18n_plural_rules_create (i18n_plural_rules_h *plural_rules)
 Creates a plural rules object.
int i18n_plural_rules_destroy (i18n_plural_rules_h plural_rules)
 Destroys the plural rules object.
int i18n_plural_rules_clone (i18n_plural_rules_h plural_rules, i18n_plural_rules_h *clone)
 Creates a polymorphic clone of the given plural_rules object.
int i18n_plural_rules_create_rules_from_descr (const char *description, i18n_plural_rules_h *plural_rules)
 Creates a plural rules object from a description.
int i18n_plural_rules_for_locale (const char *language, const char *country, i18n_uplural_type_e type, i18n_plural_rules_h *plural_rules) TIZEN_DEPRECATED_API
 Provides access to the predefined plural rules object for a given locale and the plural type.
int i18n_plural_rules_select_int32 (i18n_plural_rules_h plural_rules, int32_t number, int32_t output_buffer_size, i18n_uchar *output_buffer, int32_t *output_length)
 Returns the keyword of the first rule that applies to the given number.
int i18n_plural_rules_select_double (i18n_plural_rules_h plural_rules, double number, int32_t output_buffer_size, i18n_uchar *output_buffer, int32_t *output_length)
 Returns the keyword of the first rule that applies to the given number.
int i18n_plural_rules_get_keywords (i18n_plural_rules_h plural_rules, i18n_uenumeration_h *string_enum)
 Returns a list of all rule keywords used in this plural rules object.
int i18n_plural_rules_get_samples (i18n_plural_rules_h plural_rules, const char *keyword, double *dest, int32_t dest_capacity, int32_t *count)
 Gets sample values for which i18n_plural_rules_select_* functions would return the keyword.
int i18n_plural_rules_is_keyword (i18n_plural_rules_h plural_rules, const char *keyword, i18n_ubool *is_keyword)
 Checks if the given keyword is defined in a plural rules object.
int i18n_plural_rules_get_keyword_other (i18n_plural_rules_h plural_rules, int32_t output_buffer_size, i18n_uchar *output_buffer, int32_t *output_length)
 Returns keyword for default plural form.
int i18n_plural_rules_for_locale_id (const char *locale_id, i18n_uplural_type_e type, i18n_plural_rules_h *plural_rules)
 Provides access to the predefined plural rules object for a given locale and the plural type.

Typedefs

typedef void * i18n_plural_rules_h
 An i18n_plural_rules_h handle.

Typedef Documentation

typedef void* i18n_plural_rules_h

An i18n_plural_rules_h handle.

Use i18n_plural_rules_* functions to operate on i18n_plural_rules_h objects.

Since :
4.0

Enumeration Type Documentation

Type of plurals and plural rules objects.

Since :
4.0
Enumerator:
I18N_UPLURAL_TYPE_CARDINAL 

Plural rules for cardinal numbers: 1 file vs. 2 files

I18N_UPLURAL_TYPE_ORDINAL 

Plural rules for ordinal numbers: 1st file, 2nd file, 3rd file, 4th file, etc.


Function Documentation

Creates a polymorphic clone of the given plural_rules object.

Since :
4.0
Remarks:
The clone object should be released by the caller with the i18n_plural_rules_destroy() function.
Parameters:
[in]plural_rulesThe plural rules object to be cloned
[out]cloneThe created plural rules object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory

Creates a plural rules object.

Since :
4.0
Remarks:
The created object should be released by the caller with the i18n_plural_rules_destroy() function.
Parameters:
[out]plural_rulesThe created plural rules object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
int i18n_plural_rules_create_rules_from_descr ( const char *  description,
i18n_plural_rules_h plural_rules 
)

Creates a plural rules object from a description.

If the description is not parsable, plural_rules will be NULL.

Since :
4.0
Remarks:
The created object should be released by the caller with the i18n_plural_rules_destroy() function.
Parameters:
[in]descriptionRule description
[out]plural_rulesThe created plural rules object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

Destroys the plural rules object.

Since :
4.0
Parameters:
[in]plural_rulesThe plural rules object to destroy
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_plural_rules_for_locale ( const char *  language,
const char *  country,
i18n_uplural_type_e  type,
i18n_plural_rules_h plural_rules 
)

Provides access to the predefined plural rules object for a given locale and the plural type.

Deprecated:
Deprecated since 5.0. Use i18n_plural_rules_for_locale_id() instead.

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.

Since :
4.0
Remarks:
The created object should be released by the caller with the i18n_plural_rules_destroy() function.
Parameters:
[in]languageThe language of the locale
[in]countryThe country of the locale
[in]typeThe plural type (e.g., cardinal or ordinal)
[out]plural_rulesThe pointer to the plural rules object for given locale
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
int i18n_plural_rules_for_locale_id ( const char *  locale_id,
i18n_uplural_type_e  type,
i18n_plural_rules_h plural_rules 
)

Provides access to the predefined plural rules object for a given locale and the plural type.

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.

Since :
5.0
Remarks:
The created object should be released by the caller with the i18n_plural_rules_destroy() function.
Parameters:
[in]locale_idThe locale string containing language and country code
[in]typeThe plural type (e.g., cardinal or ordinal)
[out]plural_rulesThe pointer to the plural rules object for given locale
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory
int i18n_plural_rules_get_keyword_other ( i18n_plural_rules_h  plural_rules,
int32_t  output_buffer_size,
i18n_uchar output_buffer,
int32_t *  output_length 
)

Returns keyword for default plural form.

Since :
4.0
Parameters:
[in]plural_rulesThe plural rules object
[in]output_buffer_sizeThe size of the output_buffer buffer. If output_buffer_size <= 0 then output string is not insert to the output_buffer buffer and I18N_ERROR_BUFFER_OVERFLOW is returned.
[out]output_bufferThe buffer to which formatted string will be inserted. Can be NULL if output_buffer_size <= 0.
[out]output_lengthThe length of the output string
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer overflow
int i18n_plural_rules_get_keywords ( i18n_plural_rules_h  plural_rules,
i18n_uenumeration_h string_enum 
)

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

The rule 'other' is always present by default.

Since :
4.0
Remarks:
The obtained string_enum object should be released by the caller with the i18n_uenumeration_destroy() function.
Parameters:
[in]plural_rulesThe plural rules object
[out]string_enumString enumeration containing keywords
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_plural_rules_get_samples ( i18n_plural_rules_h  plural_rules,
const char *  keyword,
double *  dest,
int32_t  dest_capacity,
int32_t *  count 
)

Gets sample values for which i18n_plural_rules_select_* functions 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.

Since :
4.0
Parameters:
[in]plural_rulesThe plural rules object
[in]keywordThe keyword
[out]destArray into which to put the returned values. May be NULL if dest_capacity is 0
[in]dest_capacityThe capacity of the array, must be at least 0
[out]countThe count of values written. If more than dest_capacity samples are available, then only dest_capacity are written, and dest_capacity is returned as the count, rather than setting a I18N_ERROR_BUFFER_OVERFLOW. (The actual number of keyword values could be unlimited.)
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_plural_rules_is_keyword ( i18n_plural_rules_h  plural_rules,
const char *  keyword,
i18n_ubool is_keyword 
)

Checks if the given keyword is defined in a plural rules object.

Since :
4.0
Parameters:
[in]plural_rulesThe plural rules object
[in]keywordThe input keyword
[out]is_keywordBoolean value indicating if the given keyword is defined in plural_rules
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_plural_rules_select_double ( i18n_plural_rules_h  plural_rules,
double  number,
int32_t  output_buffer_size,
i18n_uchar output_buffer,
int32_t *  output_length 
)

Returns the keyword of the first rule that applies to the given number.

This function can be used with i18n_plural_rules_is_keyword() function to determine the keyword for default plural rules.

Since :
4.0
Parameters:
[in]plural_rulesThe plural rules object
[in]numberThe number for which the rule has to be determined
[in]output_buffer_sizeThe size of the output_buffer buffer. If output_buffer_size <= 0 then output string is not insert to the output_buffer buffer and I18N_ERROR_BUFFER_OVERFLOW is returned.
[out]output_bufferThe buffer to which formatted string will be inserted. Can be NULL if output_buffer_size <= 0.
[out]output_lengthThe length of the output string
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer overflow
int i18n_plural_rules_select_int32 ( i18n_plural_rules_h  plural_rules,
int32_t  number,
int32_t  output_buffer_size,
i18n_uchar output_buffer,
int32_t *  output_length 
)

Returns the keyword of the first rule that applies to the given number.

This function can be used with i18n_plural_rules_is_keyword() function to determine the keyword for default plural rules.

Since :
4.0
Parameters:
[in]plural_rulesThe plural rules object
[in]numberThe number for which the rule has to be determined
[in]output_buffer_sizeThe size of the output_buffer buffer. If output_buffer_size <= 0 then output string is not insert to the output_buffer buffer and I18N_ERROR_BUFFER_OVERFLOW is returned.
[out]output_bufferThe buffer to which formatted string will be inserted. Can be NULL if output_buffer_size <= 0.
[out]output_lengthThe length of the output string
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer overflow