C API: Plural rules, select plural keywords for numeric values. More...

#include "unicode/utypes.h"
#include "unicode/uenum.h"
#include "unicode/localpointer.h"
#include "unicode/unum.h"

Namespaces
namespace	icu
	File coll.h.

Typedefs
typedef enum UPluralType	UPluralType

typedef struct UPluralRules	UPluralRules
	C typedef for struct UPluralRules.

Enumerations
enum	UPluralType { UPLURAL_TYPE_CARDINAL , UPLURAL_TYPE_ORDINAL , UPLURAL_TYPE_COUNT }
	Type of plurals and PluralRules. More...

Functions
U_CAPI UPluralRules *	uplrules_open (const char locale, UErrorCode status)
	Opens a new UPluralRules object using the predefined cardinal-number plural rules for a given locale.

U_CAPI UPluralRules *	uplrules_openForType (const char locale, UPluralType type, UErrorCode status)
	Opens a new UPluralRules object using the predefined plural rules for a given locale and the plural type.

U_CAPI void	uplrules_close (UPluralRules *uplrules)
	Closes a UPluralRules object.

U_CAPI int32_t	uplrules_select (const UPluralRules uplrules, double number, UChar keyword, int32_t capacity, UErrorCode *status)
	Given a floating-point number, returns the keyword of the first rule that applies to the number, according to the supplied UPluralRules object.

U_CAPI int32_t	uplrules_selectFormatted (const UPluralRules uplrules, const struct UFormattedNumber number, UChar keyword, int32_t capacity, UErrorCode status)
	Given a formatted number, returns the keyword of the first rule that applies to the number, according to the supplied UPluralRules object.

U_CAPI int32_t	uplrules_selectForRange (const UPluralRules uplrules, const struct UFormattedNumberRange urange, UChar keyword, int32_t capacity, UErrorCode status)
	Given a formatted number range, returns the overall plural form of the range.

U_CAPI int32_t	uplrules_selectWithFormat (const UPluralRules uplrules, double number, const UNumberFormat fmt, UChar keyword, int32_t capacity, UErrorCode status)
	Given a number, returns the keyword of the first rule that applies to the number, according to the UPluralRules object and given the number format specified by the UNumberFormat object.

U_CAPI UEnumeration *	uplrules_getKeywords (const UPluralRules uplrules, UErrorCode status)
	Creates a string enumeration of all plural rule keywords used in this UPluralRules object.

Detailed Description

C API: Plural rules, select plural keywords for numeric values.

A UPluralRules object 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 uplrules_select function examines each condition in order and returns the keyword for the first condition that matches the number. If none match, the default rule(other) is returned.

For more information, see the LDML spec, Part 3.5 Language Plural Rules: https://www.unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules

Keywords: ICU locale data has 6 predefined values - 'zero', 'one', 'two', 'few', 'many' and 'other'. Callers need to check the value of keyword returned by the uplrules_select function.

These are based on CLDR Language Plural Rules. For these predefined rules, see the CLDR page at https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html

Definition in file upluralrules.h.

Typedef Documentation

◆ UPluralRules

typedef struct UPluralRules UPluralRules

C typedef for struct UPluralRules.

Stable:: ICU 4.8

Definition at line 88 of file upluralrules.h.

◆ UPluralType

typedef enum UPluralType UPluralType

Stable:: ICU 50

Definition at line 81 of file upluralrules.h.

Enumeration Type Documentation

◆ UPluralType

enum UPluralType

Type of plurals and PluralRules.

Stable:: ICU 50

Enumerator

UPLURAL_TYPE_CARDINAL

Plural rules for cardinal numbers: 1 file vs.

2 files.

Stable:: ICU 50

UPLURAL_TYPE_ORDINAL

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

Stable:: ICU 50

UPLURAL_TYPE_COUNT

One more than the highest normal UPluralType value.

Deprecated:: ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 59 of file upluralrules.h.

Function Documentation

◆ uplrules_close()

U_CAPI void uplrules_close ( UPluralRules * uplrules )

Closes a UPluralRules object.

Once closed it may no longer be used.

Parameters

uplrules The UPluralRules object to close.

Stable:: ICU 4.8

◆ uplrules_getKeywords()

U_CAPI UEnumeration * uplrules_getKeywords	(	const UPluralRules *	uplrules,
		UErrorCode *	status
	)

Creates a string enumeration of all plural rule keywords used in this UPluralRules object.

The rule "other" is always present by default.

Parameters

uplrules	The UPluralRules object specifying the rules for a given locale.
status	A pointer to a UErrorCode to receive any errors.

Returns: a string enumeration over plural rule keywords, or NULL upon error. The caller is responsible for closing the result.

Stable:: ICU 59

◆ uplrules_open()

U_CAPI UPluralRules * uplrules_open	(	const char *	locale,
		UErrorCode *	status
	)

Opens a new UPluralRules object using the predefined cardinal-number plural rules for a given locale.

Same as uplrules_openForType(locale, UPLURAL_TYPE_CARDINAL, status).

Parameters

locale	The locale for which the rules are desired.
status	A pointer to a UErrorCode to receive any errors.

Returns: A UPluralRules for the specified locale, or NULL if an error occurred.

Stable:: ICU 4.8

◆ uplrules_openForType()

U_CAPI UPluralRules * uplrules_openForType	(	const char *	locale,
		UPluralType	type,
		UErrorCode *	status
	)

Opens a new UPluralRules object using the predefined plural rules for a given locale and the plural type.

Parameters

locale	The locale for which the rules are desired.
type	The plural type (e.g., cardinal or ordinal).
status	A pointer to a UErrorCode to receive any errors.

Returns: A UPluralRules for the specified locale, or NULL if an error occurred.

Stable:: ICU 50

◆ uplrules_select()

U_CAPI int32_t uplrules_select	(	const UPluralRules *	uplrules,
		double	number,
		UChar *	keyword,
		int32_t	capacity,
		UErrorCode *	status
	)

Given a floating-point number, returns the keyword of the first rule that applies to the number, according to the supplied UPluralRules object.

Parameters

uplrules	The UPluralRules object specifying the rules.
number	The number for which the rule has to be determined.
keyword	An output buffer to write the keyword of the rule that applies to number.
capacity	The capacity of the keyword buffer.
status	A pointer to a UErrorCode to receive any errors.

Returns: The length of the keyword.

Stable:: ICU 4.8

◆ uplrules_selectFormatted()

U_CAPI int32_t uplrules_selectFormatted	(	const UPluralRules *	uplrules,
		const struct UFormattedNumber *	number,
		UChar *	keyword,
		int32_t	capacity,
		UErrorCode *	status
	)

Given a formatted number, returns the keyword of the first rule that applies to the number, according to the supplied UPluralRules object.

A UFormattedNumber allows you to specify an exponent or trailing zeros, which can affect the plural category. To get a UFormattedNumber, see UNumberFormatter.

Parameters

uplrules	The UPluralRules object specifying the rules.
number	The formatted number for which the rule has to be determined.
keyword	The destination buffer for the keyword of the rule that applies to the number.
capacity	The capacity of the keyword buffer.
status	A pointer to a UErrorCode to receive any errors.

Returns: The length of the keyword.

Stable:: ICU 64

◆ uplrules_selectForRange()

U_CAPI int32_t uplrules_selectForRange	(	const UPluralRules *	uplrules,
		const struct UFormattedNumberRange *	urange,
		UChar *	keyword,
		int32_t	capacity,
		UErrorCode *	status
	)

Given a formatted number range, returns the overall plural form of the range.

For example, "3-5" returns "other" in English.

To get a UFormattedNumberRange, see UNumberRangeFormatter.

Parameters

uplrules	The UPluralRules object specifying the rules.
urange	The number range onto which the rules will be applied.
keyword	The destination buffer for the keyword of the rule that applies to the number range.
capacity	The capacity of the keyword buffer.
status	A pointer to a UErrorCode to receive any errors.

Returns: The length of the keyword.

Stable:: ICU 68

◆ uplrules_selectWithFormat()

U_CAPI int32_t uplrules_selectWithFormat	(	const UPluralRules *	uplrules,
		double	number,
		const UNumberFormat *	fmt,
		UChar *	keyword,
		int32_t	capacity,
		UErrorCode *	status
	)

Given a number, returns the keyword of the first rule that applies to the number, according to the UPluralRules object and given the number format specified by the UNumberFormat object.

Note: This internal preview interface may be removed in the future if an architecturally cleaner solution reaches stable status.

Parameters

uplrules	The UPluralRules object specifying the rules.
number	The number for which the rule has to be determined.
fmt	The UNumberFormat specifying how the number will be formatted (this can affect the plural form, e.g. "1 dollar" vs "1.0 dollars"). If this is NULL, the function behaves like uplrules_select.
keyword	An output buffer to write the keyword of the rule that applies to number.
capacity	The capacity of the keyword buffer.
status	A pointer to a UErrorCode to receive any errors.

Returns: The length of keyword.

Internal:: Do not use. This API is for internal use only. ICU 59 technology preview, may be removed in the future

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ UPluralRules

◆ UPluralType

Enumeration Type Documentation

◆ UPluralType

Function Documentation

◆ uplrules_close()

◆ uplrules_getKeywords()

◆ uplrules_open()

◆ uplrules_openForType()

◆ uplrules_select()

◆ uplrules_selectFormatted()

◆ uplrules_selectForRange()

◆ uplrules_selectWithFormat()