Tizen Native API
5.5
|
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
enum i18n_uplural_type_e |
Function Documentation
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.
- Since :
- 4.0
- Remarks:
- The clone object should be released by the caller with the i18n_plural_rules_destroy() function.
- Parameters:
-
[in] plural_rules The plural rules object to be cloned [out] clone The created plural rules object
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_OUT_OF_MEMORY Out of memory
int i18n_plural_rules_create | ( | i18n_plural_rules_h * | plural_rules | ) |
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_rules The created plural rules object
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_OUT_OF_MEMORY Out 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] description Rule description [out] plural_rules The created plural rules object
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter
int i18n_plural_rules_destroy | ( | i18n_plural_rules_h | plural_rules | ) |
Destroys the plural rules object.
- Since :
- 4.0
- Parameters:
-
[in] plural_rules The plural rules object to destroy
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid 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] language The language of the locale [in] country The country of the locale [in] type The plural type (e.g., cardinal or ordinal) [out] plural_rules The pointer to the plural rules object for given locale
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_OUT_OF_MEMORY Out 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_id The locale string containing language and country code [in] type The plural type (e.g., cardinal or ordinal) [out] plural_rules The pointer to the plural rules object for given locale
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_OUT_OF_MEMORY Out 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_rules The plural rules object [in] output_buffer_size The 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_buffer The buffer to which formatted string will be inserted. Can be NULL
ifoutput_buffer_size <= 0
.[out] output_length The length of the output string
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_BUFFER_OVERFLOW Buffer 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_rules The plural rules object [out] string_enum String enumeration containing keywords
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid 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_rules The plural rules object [in] keyword The keyword [out] dest Array into which to put the returned values. May be NULL
if dest_capacity is 0[in] dest_capacity The capacity of the array, must be at least 0 [out] count The 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_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid 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_rules The plural rules object [in] keyword The input keyword [out] is_keyword Boolean value indicating if the given keyword is defined in plural_rules
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid 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_rules The plural rules object [in] number The number for which the rule has to be determined [in] output_buffer_size The 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_buffer The buffer to which formatted string will be inserted. Can be NULL
ifoutput_buffer_size <= 0
.[out] output_length The length of the output string
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_BUFFER_OVERFLOW Buffer 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_rules The plural rules object [in] number The number for which the rule has to be determined [in] output_buffer_size The 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_buffer The buffer to which formatted string will be inserted. Can be NULL
ifoutput_buffer_size <= 0
.[out] output_length The length of the output string
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
I18N_ERROR_NONE Successful I18N_ERROR_INVALID_PARAMETER Invalid function parameter I18N_ERROR_BUFFER_OVERFLOW Buffer overflow