icuSources/i18n/unicode/upluralrules.h

   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/localpointer.h"
  18 #include "unicode/uenum.h"
  19 #ifndef U_HIDE_INTERNAL_API
  20 #include "unicode/unum.h"
  21 #endif  /* U_HIDE_INTERNAL_API */
  22
  23 /**
  24  * \file
  25  * \brief C API: Plural rules, select plural keywords for numeric values.
  26  *
  27  * A UPluralRules object defines rules for mapping non-negative numeric
  28  * values onto a small set of keywords. Rules are constructed from a text
  29  * description, consisting of a series of keywords and conditions.
  30  * The uplrules_select function examines each condition in order and
  31  * returns the keyword for the first condition that matches the number.
  32  * If none match, the default rule(other) is returned.
  33  *
  34  * For more information, see the LDML spec, C.11 Language Plural Rules:
  35  * http://www.unicode.org/reports/tr35/#Language_Plural_Rules
  36  *
  37  * Keywords: ICU locale data has 6 predefined values -
  38  * 'zero', 'one', 'two', 'few', 'many' and 'other'. Callers need to check
  39  * the value of keyword returned by the uplrules_select function.
  40  *
  41  * These are based on CLDR <i>Language Plural Rules</i>. For these
  42  * predefined rules, see the CLDR page at
  43  * http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html
  44  */
  45
  46 /**
  47  * Type of plurals and PluralRules.
  48  * @stable ICU 50
  49  */
  50 enum UPluralType {
  51     /**
  52      * Plural rules for cardinal numbers: 1 file vs. 2 files.
  53      * @stable ICU 50
  54      */
  55     UPLURAL_TYPE_CARDINAL,
  56     /**
  57      * Plural rules for ordinal numbers: 1st file, 2nd file, 3rd file, 4th file, etc.
  58      * @stable ICU 50
  59      */
  60     UPLURAL_TYPE_ORDINAL,
  61 #ifndef U_HIDE_DEPRECATED_API
  62     /**
  63      * One more than the highest normal UPluralType value.
  64      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
  65      */
  66     UPLURAL_TYPE_COUNT
  67 #endif  /* U_HIDE_DEPRECATED_API */
  68 };
  69 /**
  70  * @stable ICU 50
  71  */
  72 typedef enum UPluralType UPluralType;
  73
  74 /**
  75  * Opaque UPluralRules object for use in C programs.
  76  * @stable ICU 4.8
  77  */
  78 struct UPluralRules;
  79 typedef struct UPluralRules UPluralRules;  /**< C typedef for struct UPluralRules. @stable ICU 4.8 */
  80
  81 /**
  82  * Opens a new UPluralRules object using the predefined cardinal-number plural rules for a
  83  * given locale.
  84  * Same as uplrules_openForType(locale, UPLURAL_TYPE_CARDINAL, status).
  85  * @param locale The locale for which the rules are desired.
  86  * @param status A pointer to a UErrorCode to receive any errors.
  87  * @return A UPluralRules for the specified locale, or NULL if an error occurred.
  88  * @stable ICU 4.8
  89  */
  90 U_CAPI UPluralRules* U_EXPORT2
  91 uplrules_open(const char *locale, UErrorCode *status);
  92
  93 /**
  94  * Opens a new UPluralRules object using the predefined plural rules for a
  95  * given locale and the plural type.
  96  * @param locale The locale for which the rules are desired.
  97  * @param type The plural type (e.g., cardinal or ordinal).
  98  * @param status A pointer to a UErrorCode to receive any errors.
  99  * @return A UPluralRules for the specified locale, or NULL if an error occurred.
 100  * @stable ICU 50
 101  */
 102 U_CAPI UPluralRules* U_EXPORT2
 103 uplrules_openForType(const char *locale, UPluralType type, UErrorCode *status);
 104
 105 /**
 106  * Closes a UPluralRules object. Once closed it may no longer be used.
 107  * @param uplrules The UPluralRules object to close.
 108  * @stable ICU 4.8
 109  */
 110 U_CAPI void U_EXPORT2
 111 uplrules_close(UPluralRules *uplrules);
 112
 113
 114 #if U_SHOW_CPLUSPLUS_API
 115
 116 U_NAMESPACE_BEGIN
 117
 118 /**
 119  * \class LocalUPluralRulesPointer
 120  * "Smart pointer" class, closes a UPluralRules via uplrules_close().
 121  * For most methods see the LocalPointerBase base class.
 122  *
 123  * @see LocalPointerBase
 124  * @see LocalPointer
 125  * @stable ICU 4.8
 126  */
 127 U_DEFINE_LOCAL_OPEN_POINTER(LocalUPluralRulesPointer, UPluralRules, uplrules_close);
 128
 129 U_NAMESPACE_END
 130
 131 #endif // U_SHOW_CPLUSPLUS_API
 132
 133
 134 /**
 135  * Given a number, returns the keyword of the first rule that
 136  * applies to the number, according to the supplied UPluralRules object.
 137  * @param uplrules The UPluralRules object specifying the rules.
 138  * @param number The number for which the rule has to be determined.
 139  * @param keyword The keyword of the rule that applies to number.
 140  * @param capacity The capacity of keyword.
 141  * @param status A pointer to a UErrorCode to receive any errors.
 142  * @return The length of keyword.
 143  * @stable ICU 4.8
 144  */
 145 U_CAPI int32_t U_EXPORT2
 146 uplrules_select(const UPluralRules *uplrules,
 147                double number,
 148                UChar *keyword, int32_t capacity,
 149                UErrorCode *status);
 150
 151 #ifndef U_HIDE_INTERNAL_API
 152 /**
 153  * Given a number, returns the keyword of the first rule that applies to the
 154  * number, according to the UPluralRules object and given the number format
 155  * specified by the UNumberFormat object.
 156  * Note: This internal preview interface may be removed in the future if
 157  * an architecturally cleaner solution reaches stable status.
 158  * @param uplrules The UPluralRules object specifying the rules.
 159  * @param number The number for which the rule has to be determined.
 160  * @param fmt The UNumberFormat specifying how the number will be formatted
 161  *        (this can affect the plural form, e.g. "1 dollar" vs "1.0 dollars").
 162  *        If this is NULL, the function behaves like uplrules_select.
 163  * @param keyword The keyword of the rule that applies to number.
 164  * @param capacity The capacity of the keyword buffer.
 165  * @param status A pointer to a UErrorCode to receive any errors.
 166  * @return The length of keyword.
 167  * @internal ICU 59 technology preview, may be removed in the future
 168  */
 169 U_INTERNAL int32_t U_EXPORT2
 170 uplrules_selectWithFormat(const UPluralRules *uplrules,
 171                           double number,
 172                           const UNumberFormat *fmt,
 173                           UChar *keyword, int32_t capacity,
 174                           UErrorCode *status);
 175
 176 #endif  /* U_HIDE_INTERNAL_API */
 177
 178 /**
 179  * Creates a string enumeration of all plural rule keywords used in this
 180  * UPluralRules object. The rule "other" is always present by default.
 181  * @param uplrules The UPluralRules object specifying the rules for
 182  *        a given locale.
 183  * @param status A pointer to a UErrorCode to receive any errors.
 184  * @return a string enumeration over plural rule keywords, or NULL
 185  * upon error. The caller is responsible for closing the result.
 186  * @stable ICU 59
 187  */
 188 U_STABLE UEnumeration* U_EXPORT2
 189 uplrules_getKeywords(const UPluralRules *uplrules,
 190                      UErrorCode *status);
 191
 192 #endif /* #if !UCONFIG_NO_FORMATTING */
 193
 194 #endif