include/unicode/upluralrules.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *****************************************************************************************
0005 * Copyright (C) 2010-2013, International Business Machines
0006 * Corporation and others. All Rights Reserved.
0007 *****************************************************************************************
0008 */
0009
0010 #ifndef UPLURALRULES_H
0011 #define UPLURALRULES_H
0012
0013 #include "unicode/utypes.h"
0014
0015 #if !UCONFIG_NO_FORMATTING
0016
0017 #include "unicode/uenum.h"
0018
0019 #if U_SHOW_CPLUSPLUS_API
0020 #include "unicode/localpointer.h"
0021 #endif   // U_SHOW_CPLUSPLUS_API
0022
0023 #ifndef U_HIDE_INTERNAL_API
0024 #include "unicode/unum.h"
0025 #endif  /* U_HIDE_INTERNAL_API */
0026
0027 // Forward-declaration
0028 struct UFormattedNumber;
0029 struct UFormattedNumberRange;
0030
0031 /**
0032  * \file
0033  * \brief C API: Plural rules, select plural keywords for numeric values.
0034  *
0035  * A UPluralRules object defines rules for mapping non-negative numeric
0036  * values onto a small set of keywords. Rules are constructed from a text
0037  * description, consisting of a series of keywords and conditions.
0038  * The uplrules_select function examines each condition in order and
0039  * returns the keyword for the first condition that matches the number.
0040  * If none match, the default rule(other) is returned.
0041  *
0042  * For more information, see the
0043  * LDML spec, Part 3.5 Language Plural Rules:
0044  * https://www.unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules
0045  *
0046  * Keywords: ICU locale data has 6 predefined values -
0047  * 'zero', 'one', 'two', 'few', 'many' and 'other'. Callers need to check
0048  * the value of keyword returned by the uplrules_select function.
0049  *
0050  * These are based on CLDR <i>Language Plural Rules</i>. For these
0051  * predefined rules, see the CLDR page at
0052  * https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html
0053  */
0054
0055 /**
0056  * Type of plurals and PluralRules.
0057  * @stable ICU 50
0058  */
0059 enum UPluralType {
0060     /**
0061      * Plural rules for cardinal numbers: 1 file vs. 2 files.
0062      * @stable ICU 50
0063      */
0064     UPLURAL_TYPE_CARDINAL,
0065     /**
0066      * Plural rules for ordinal numbers: 1st file, 2nd file, 3rd file, 4th file, etc.
0067      * @stable ICU 50
0068      */
0069     UPLURAL_TYPE_ORDINAL,
0070 #ifndef U_HIDE_DEPRECATED_API
0071     /**
0072      * One more than the highest normal UPluralType value.
0073      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
0074      */
0075     UPLURAL_TYPE_COUNT
0076 #endif  /* U_HIDE_DEPRECATED_API */
0077 };
0078 /**
0079  * @stable ICU 50
0080  */
0081 typedef enum UPluralType UPluralType;
0082
0083 /**
0084  * Opaque UPluralRules object for use in C programs.
0085  * @stable ICU 4.8
0086  */
0087 struct UPluralRules;
0088 typedef struct UPluralRules UPluralRules;  /**< C typedef for struct UPluralRules. @stable ICU 4.8 */
0089
0090 /**
0091  * Opens a new UPluralRules object using the predefined cardinal-number plural rules for a
0092  * given locale.
0093  * Same as uplrules_openForType(locale, UPLURAL_TYPE_CARDINAL, status).
0094  * @param locale The locale for which the rules are desired.
0095  * @param status A pointer to a UErrorCode to receive any errors.
0096  * @return A UPluralRules for the specified locale, or NULL if an error occurred.
0097  * @stable ICU 4.8
0098  */
0099 U_CAPI UPluralRules* U_EXPORT2
0100 uplrules_open(const char *locale, UErrorCode *status);
0101
0102 /**
0103  * Opens a new UPluralRules object using the predefined plural rules for a
0104  * given locale and the plural type.
0105  * @param locale The locale for which the rules are desired.
0106  * @param type The plural type (e.g., cardinal or ordinal).
0107  * @param status A pointer to a UErrorCode to receive any errors.
0108  * @return A UPluralRules for the specified locale, or NULL if an error occurred.
0109  * @stable ICU 50
0110  */
0111 U_CAPI UPluralRules* U_EXPORT2
0112 uplrules_openForType(const char *locale, UPluralType type, UErrorCode *status);
0113
0114 /**
0115  * Closes a UPluralRules object. Once closed it may no longer be used.
0116  * @param uplrules The UPluralRules object to close.
0117  * @stable ICU 4.8
0118  */
0119 U_CAPI void U_EXPORT2
0120 uplrules_close(UPluralRules *uplrules);
0121
0122
0123 #if U_SHOW_CPLUSPLUS_API
0124
0125 U_NAMESPACE_BEGIN
0126
0127 /**
0128  * \class LocalUPluralRulesPointer
0129  * "Smart pointer" class, closes a UPluralRules via uplrules_close().
0130  * For most methods see the LocalPointerBase base class.
0131  *
0132  * @see LocalPointerBase
0133  * @see LocalPointer
0134  * @stable ICU 4.8
0135  */
0136 U_DEFINE_LOCAL_OPEN_POINTER(LocalUPluralRulesPointer, UPluralRules, uplrules_close);
0137
0138 U_NAMESPACE_END
0139
0140 #endif
0141
0142
0143 /**
0144  * Given a floating-point number, returns the keyword of the first rule that
0145  * applies to the number, according to the supplied UPluralRules object.
0146  * @param uplrules The UPluralRules object specifying the rules.
0147  * @param number The number for which the rule has to be determined.
0148  * @param keyword An output buffer to write the keyword of the rule that
0149  *         applies to number.
0150  * @param capacity The capacity of the keyword buffer.
0151  * @param status A pointer to a UErrorCode to receive any errors.
0152  * @return The length of the keyword.
0153  * @stable ICU 4.8
0154  */
0155 U_CAPI int32_t U_EXPORT2
0156 uplrules_select(const UPluralRules *uplrules,
0157                double number,
0158                UChar *keyword, int32_t capacity,
0159                UErrorCode *status);
0160
0161 /**
0162  * Given a formatted number, returns the keyword of the first rule
0163  * that applies to the number, according to the supplied UPluralRules object.
0164  *
0165  * A UFormattedNumber allows you to specify an exponent or trailing zeros,
0166  * which can affect the plural category. To get a UFormattedNumber, see
0167  * {@link UNumberFormatter}.
0168  *
0169  * @param uplrules The UPluralRules object specifying the rules.
0170  * @param number The formatted number for which the rule has to be determined.
0171  * @param keyword The destination buffer for the keyword of the rule that
0172  *         applies to the number.
0173  * @param capacity The capacity of the keyword buffer.
0174  * @param status A pointer to a UErrorCode to receive any errors.
0175  * @return The length of the keyword.
0176  * @stable ICU 64
0177  */
0178 U_CAPI int32_t U_EXPORT2
0179 uplrules_selectFormatted(const UPluralRules *uplrules,
0180                const struct UFormattedNumber* number,
0181                UChar *keyword, int32_t capacity,
0182                UErrorCode *status);
0183
0184 /**
0185  * Given a formatted number range, returns the overall plural form of the
0186  * range. For example, "3-5" returns "other" in English.
0187  *
0188  * To get a UFormattedNumberRange, see UNumberRangeFormatter.
0189  *
0190  * @param uplrules The UPluralRules object specifying the rules.
0191  * @param urange The number range onto which the rules will be applied.
0192  * @param keyword The destination buffer for the keyword of the rule that
0193  *         applies to the number range.
0194  * @param capacity The capacity of the keyword buffer.
0195  * @param status A pointer to a UErrorCode to receive any errors.
0196  * @return The length of the keyword.
0197  * @stable ICU 68
0198  */
0199 U_CAPI int32_t U_EXPORT2
0200 uplrules_selectForRange(const UPluralRules *uplrules,
0201                const struct UFormattedNumberRange* urange,
0202                UChar *keyword, int32_t capacity,
0203                UErrorCode *status);
0204
0205 #ifndef U_HIDE_INTERNAL_API
0206 /**
0207  * Given a number, returns the keyword of the first rule that applies to the
0208  * number, according to the UPluralRules object and given the number format
0209  * specified by the UNumberFormat object.
0210  * Note: This internal preview interface may be removed in the future if
0211  * an architecturally cleaner solution reaches stable status.
0212  * @param uplrules The UPluralRules object specifying the rules.
0213  * @param number The number for which the rule has to be determined.
0214  * @param fmt The UNumberFormat specifying how the number will be formatted
0215  *        (this can affect the plural form, e.g. "1 dollar" vs "1.0 dollars").
0216  *        If this is NULL, the function behaves like uplrules_select.
0217  * @param keyword An output buffer to write the keyword of the rule that
0218  *         applies to number.
0219  * @param capacity The capacity of the keyword buffer.
0220  * @param status A pointer to a UErrorCode to receive any errors.
0221  * @return The length of keyword.
0222  * @internal ICU 59 technology preview, may be removed in the future
0223  */
0224 U_CAPI int32_t U_EXPORT2
0225 uplrules_selectWithFormat(const UPluralRules *uplrules,
0226                           double number,
0227                           const UNumberFormat *fmt,
0228                           UChar *keyword, int32_t capacity,
0229                           UErrorCode *status);
0230
0231 #endif  /* U_HIDE_INTERNAL_API */
0232
0233 /**
0234  * Creates a string enumeration of all plural rule keywords used in this
0235  * UPluralRules object. The rule "other" is always present by default.
0236  * @param uplrules The UPluralRules object specifying the rules for
0237  *        a given locale.
0238  * @param status A pointer to a UErrorCode to receive any errors.
0239  * @return a string enumeration over plural rule keywords, or NULL
0240  * upon error. The caller is responsible for closing the result.
0241  * @stable ICU 59
0242  */
0243 U_CAPI UEnumeration* U_EXPORT2
0244 uplrules_getKeywords(const UPluralRules *uplrules,
0245                      UErrorCode *status);
0246
0247 #endif /* #if !UCONFIG_NO_FORMATTING */
0248
0249 #endif