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: http://www.unicode.org/draft/reports/tr35/tr35.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)
	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.
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

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

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.

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_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` if `output_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` if `output_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` if `output_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

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation