1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4*****************************************************************************************
5* Copyright (C) 2010-2013, International Business Machines
6* Corporation and others. All Rights Reserved.
7*****************************************************************************************
8*/
9
10#ifndef UPLURALRULES_H
11#define UPLURALRULES_H
12
13#include "unicode/utypes.h"
14
15#if !UCONFIG_NO_FORMATTING
16
17#include "unicode/uenum.h"
18
19#if U_SHOW_CPLUSPLUS_API
20#include "unicode/localpointer.h"
21#endif // U_SHOW_CPLUSPLUS_API
22
23#ifndef U_HIDE_INTERNAL_API
24#include "unicode/unum.h"
25#endif /* U_HIDE_INTERNAL_API */
26
27// Forward-declaration
28struct UFormattedNumber;
29struct UFormattedNumberRange;
30
31/**
32 * \file
33 * \brief C API: Plural rules, select plural keywords for numeric values.
34 *
35 * A UPluralRules object defines rules for mapping non-negative numeric
36 * values onto a small set of keywords. Rules are constructed from a text
37 * description, consisting of a series of keywords and conditions.
38 * The uplrules_select function examines each condition in order and
39 * returns the keyword for the first condition that matches the number.
40 * If none match, the default rule(other) is returned.
41 *
42 * For more information, see the
43 * LDML spec, Part 3.5 Language Plural Rules:
44 * https://www.unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules
45 *
46 * Keywords: ICU locale data has 6 predefined values -
47 * 'zero', 'one', 'two', 'few', 'many' and 'other'. Callers need to check
48 * the value of keyword returned by the uplrules_select function.
49 *
50 * These are based on CLDR <i>Language Plural Rules</i>. For these
51 * predefined rules, see the CLDR page at
52 * https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html
53 */
54
55/**
56 * Type of plurals and PluralRules.
57 * @stable ICU 50
58 */
59enum UPluralType {
60 /**
61 * Plural rules for cardinal numbers: 1 file vs. 2 files.
62 * @stable ICU 50
63 */
64 UPLURAL_TYPE_CARDINAL,
65 /**
66 * Plural rules for ordinal numbers: 1st file, 2nd file, 3rd file, 4th file, etc.
67 * @stable ICU 50
68 */
69 UPLURAL_TYPE_ORDINAL,
70#ifndef U_HIDE_DEPRECATED_API
71 /**
72 * One more than the highest normal UPluralType value.
73 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
74 */
75 UPLURAL_TYPE_COUNT
76#endif /* U_HIDE_DEPRECATED_API */
77};
78/**
79 * @stable ICU 50
80 */
81typedef enum UPluralType UPluralType;
82
83/**
84 * Opaque UPluralRules object for use in C programs.
85 * @stable ICU 4.8
86 */
87struct UPluralRules;
88typedef struct UPluralRules UPluralRules; /**< C typedef for struct UPluralRules. @stable ICU 4.8 */
89
90/**
91 * Opens a new UPluralRules object using the predefined cardinal-number plural rules for a
92 * given locale.
93 * Same as uplrules_openForType(locale, UPLURAL_TYPE_CARDINAL, status).
94 * @param locale The locale for which the rules are desired.
95 * @param status A pointer to a UErrorCode to receive any errors.
96 * @return A UPluralRules for the specified locale, or NULL if an error occurred.
97 * @stable ICU 4.8
98 */
99U_CAPI UPluralRules* U_EXPORT2
100uplrules_open(const char *locale, UErrorCode *status);
101
102/**
103 * Opens a new UPluralRules object using the predefined plural rules for a
104 * given locale and the plural type.
105 * @param locale The locale for which the rules are desired.
106 * @param type The plural type (e.g., cardinal or ordinal).
107 * @param status A pointer to a UErrorCode to receive any errors.
108 * @return A UPluralRules for the specified locale, or NULL if an error occurred.
109 * @stable ICU 50
110 */
111U_CAPI UPluralRules* U_EXPORT2
112uplrules_openForType(const char *locale, UPluralType type, UErrorCode *status);
113
114/**
115 * Closes a UPluralRules object. Once closed it may no longer be used.
116 * @param uplrules The UPluralRules object to close.
117 * @stable ICU 4.8
118 */
119U_CAPI void U_EXPORT2
120uplrules_close(UPluralRules *uplrules);
121
122
123#if U_SHOW_CPLUSPLUS_API
124
125U_NAMESPACE_BEGIN
126
127/**
128 * \class LocalUPluralRulesPointer
129 * "Smart pointer" class, closes a UPluralRules via uplrules_close().
130 * For most methods see the LocalPointerBase base class.
131 *
132 * @see LocalPointerBase
133 * @see LocalPointer
134 * @stable ICU 4.8
135 */
136U_DEFINE_LOCAL_OPEN_POINTER(LocalUPluralRulesPointer, UPluralRules, uplrules_close);
137
138U_NAMESPACE_END
139
140#endif
141
142
143/**
144 * Given a floating-point number, returns the keyword of the first rule that
145 * applies to the number, according to the supplied UPluralRules object.
146 * @param uplrules The UPluralRules object specifying the rules.
147 * @param number The number for which the rule has to be determined.
148 * @param keyword An output buffer to write the keyword of the rule that
149 * applies to number.
150 * @param capacity The capacity of the keyword buffer.
151 * @param status A pointer to a UErrorCode to receive any errors.
152 * @return The length of the keyword.
153 * @stable ICU 4.8
154 */
155U_CAPI int32_t U_EXPORT2
156uplrules_select(const UPluralRules *uplrules,
157 double number,
158 UChar *keyword, int32_t capacity,
159 UErrorCode *status);
160
161/**
162 * Given a formatted number, returns the keyword of the first rule
163 * that applies to the number, according to the supplied UPluralRules object.
164 *
165 * A UFormattedNumber allows you to specify an exponent or trailing zeros,
166 * which can affect the plural category. To get a UFormattedNumber, see
167 * {@link UNumberFormatter}.
168 *
169 * @param uplrules The UPluralRules object specifying the rules.
170 * @param number The formatted number for which the rule has to be determined.
171 * @param keyword The destination buffer for the keyword of the rule that
172 * applies to the number.
173 * @param capacity The capacity of the keyword buffer.
174 * @param status A pointer to a UErrorCode to receive any errors.
175 * @return The length of the keyword.
176 * @stable ICU 64
177 */
178U_CAPI int32_t U_EXPORT2
179uplrules_selectFormatted(const UPluralRules *uplrules,
180 const struct UFormattedNumber* number,
181 UChar *keyword, int32_t capacity,
182 UErrorCode *status);
183
184/**
185 * Given a formatted number range, returns the overall plural form of the
186 * range. For example, "3-5" returns "other" in English.
187 *
188 * To get a UFormattedNumberRange, see UNumberRangeFormatter.
189 *
190 * @param uplrules The UPluralRules object specifying the rules.
191 * @param urange The number range onto which the rules will be applied.
192 * @param keyword The destination buffer for the keyword of the rule that
193 * applies to the number range.
194 * @param capacity The capacity of the keyword buffer.
195 * @param status A pointer to a UErrorCode to receive any errors.
196 * @return The length of the keyword.
197 * @stable ICU 68
198 */
199U_CAPI int32_t U_EXPORT2
200uplrules_selectForRange(const UPluralRules *uplrules,
201 const struct UFormattedNumberRange* urange,
202 UChar *keyword, int32_t capacity,
203 UErrorCode *status);
204
205#ifndef U_HIDE_INTERNAL_API
206/**
207 * Given a number, returns the keyword of the first rule that applies to the
208 * number, according to the UPluralRules object and given the number format
209 * specified by the UNumberFormat object.
210 * Note: This internal preview interface may be removed in the future if
211 * an architecturally cleaner solution reaches stable status.
212 * @param uplrules The UPluralRules object specifying the rules.
213 * @param number The number for which the rule has to be determined.
214 * @param fmt The UNumberFormat specifying how the number will be formatted
215 * (this can affect the plural form, e.g. "1 dollar" vs "1.0 dollars").
216 * If this is NULL, the function behaves like uplrules_select.
217 * @param keyword An output buffer to write the keyword of the rule that
218 * applies to number.
219 * @param capacity The capacity of the keyword buffer.
220 * @param status A pointer to a UErrorCode to receive any errors.
221 * @return The length of keyword.
222 * @internal ICU 59 technology preview, may be removed in the future
223 */
224U_CAPI int32_t U_EXPORT2
225uplrules_selectWithFormat(const UPluralRules *uplrules,
226 double number,
227 const UNumberFormat *fmt,
228 UChar *keyword, int32_t capacity,
229 UErrorCode *status);
230
231#endif /* U_HIDE_INTERNAL_API */
232
233/**
234 * Creates a string enumeration of all plural rule keywords used in this
235 * UPluralRules object. The rule "other" is always present by default.
236 * @param uplrules The UPluralRules object specifying the rules for
237 * a given locale.
238 * @param status A pointer to a UErrorCode to receive any errors.
239 * @return a string enumeration over plural rule keywords, or NULL
240 * upon error. The caller is responsible for closing the result.
241 * @stable ICU 59
242 */
243U_CAPI UEnumeration* U_EXPORT2
244uplrules_getKeywords(const UPluralRules *uplrules,
245 UErrorCode *status);
246
247#endif /* #if !UCONFIG_NO_FORMATTING */
248
249#endif
250

source code of include/unicode/upluralrules.h