10596faeddefbf198de137d5e893708495ab1584cFredrik Roubert// © 2016 and later: Unicode, Inc. and others. 264339d36f8bd4db5025fe2988eda22b491a9219cFredrik Roubert// License & terms of use: http://www.unicode.org/copyright.html 3b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/* 4b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho***************************************************************************************** 58393335b955da7340c9f19b1b4b2d6c0c2c04be7Craig Cornelius* Copyright (C) 2010-2013, International Business Machines 6b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho* Corporation and others. All Rights Reserved. 7b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho***************************************************************************************** 8b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho*/ 9b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 10b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#ifndef UPLURALRULES_H 11b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#define UPLURALRULES_H 12b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 13b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#include "unicode/utypes.h" 14b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 15b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#if !UCONFIG_NO_FORMATTING 16b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 17b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#include "unicode/localpointer.h" 180596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#include "unicode/uenum.h" 190596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#ifndef U_HIDE_INTERNAL_API 200596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#include "unicode/unum.h" 210596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#endif /* U_HIDE_INTERNAL_API */ 22b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 23b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/** 24103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * \file 25103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * \brief C API: Plural rules, select plural keywords for numeric values. 26103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * 27b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * A UPluralRules object defines rules for mapping non-negative numeric 28b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * values onto a small set of keywords. Rules are constructed from a text 29b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * description, consisting of a series of keywords and conditions. 30b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * The uplrules_select function examines each condition in order and 31b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * returns the keyword for the first condition that matches the number. 32b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * If none match, the default rule(other) is returned. 33b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * 34b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * For more information, see the LDML spec, C.11 Language Plural Rules: 35b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * http://www.unicode.org/reports/tr35/#Language_Plural_Rules 36b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * 37b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * Keywords: ICU locale data has 6 predefined values - 38b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * 'zero', 'one', 'two', 'few', 'many' and 'other'. Callers need to check 39b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * the value of keyword returned by the uplrules_select function. 40b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * 41b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * These are based on CLDR <i>Language Plural Rules</i>. For these 42b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * predefined rules, see the CLDR page at 43b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * http://unicode.org/repos/cldr-tmp/trunk/diff/supplemental/language_plural_rules.html 44b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 45b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 46b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/** 4754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Type of plurals and PluralRules. 4859d709d503bab6e2b61931737e662dd293b40578ccornelius * @stable ICU 50 4954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 5054dcd9b6a06071f647dac967e9e267abb9410720Craig Corneliusenum UPluralType { 5154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius /** 5254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Plural rules for cardinal numbers: 1 file vs. 2 files. 5359d709d503bab6e2b61931737e662dd293b40578ccornelius * @stable ICU 50 5454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 5554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius UPLURAL_TYPE_CARDINAL, 5654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius /** 5754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Plural rules for ordinal numbers: 1st file, 2nd file, 3rd file, 4th file, etc. 5859d709d503bab6e2b61931737e662dd293b40578ccornelius * @stable ICU 50 5954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 6054dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius UPLURAL_TYPE_ORDINAL, 6164339d36f8bd4db5025fe2988eda22b491a9219cFredrik Roubert#ifndef U_HIDE_DEPRECATED_API 6254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius /** 6364339d36f8bd4db5025fe2988eda22b491a9219cFredrik Roubert * One more than the highest normal UPluralType value. 6464339d36f8bd4db5025fe2988eda22b491a9219cFredrik Roubert * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 6554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 6654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius UPLURAL_TYPE_COUNT 670596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#endif /* U_HIDE_DEPRECATED_API */ 6854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius}; 6954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius/** 7059d709d503bab6e2b61931737e662dd293b40578ccornelius * @stable ICU 50 7154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 7254dcd9b6a06071f647dac967e9e267abb9410720Craig Corneliustypedef enum UPluralType UPluralType; 7354dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius 7454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius/** 75b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * Opaque UPluralRules object for use in C programs. 76103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * @stable ICU 4.8 77b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 78b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2clairehostruct UPluralRules; 79103e9ffba2cba345d0078eb8b8db33249f81840aCraig Corneliustypedef struct UPluralRules UPluralRules; /**< C typedef for struct UPluralRules. @stable ICU 4.8 */ 80b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 81b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/** 8254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Opens a new UPluralRules object using the predefined cardinal-number plural rules for a 83b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * given locale. 8454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Same as uplrules_openForType(locale, UPLURAL_TYPE_CARDINAL, status). 85b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param locale The locale for which the rules are desired. 86b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param status A pointer to a UErrorCode to receive any errors. 8754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @return A UPluralRules for the specified locale, or NULL if an error occurred. 88103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * @stable ICU 4.8 89b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 900596faeddefbf198de137d5e893708495ab1584cFredrik RoubertU_CAPI UPluralRules* U_EXPORT2 9154dcd9b6a06071f647dac967e9e267abb9410720Craig Corneliusuplrules_open(const char *locale, UErrorCode *status); 9254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius 9354dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius/** 9454dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Opens a new UPluralRules object using the predefined plural rules for a 9554dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * given locale and the plural type. 9654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @param locale The locale for which the rules are desired. 9754dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @param type The plural type (e.g., cardinal or ordinal). 9854dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @param status A pointer to a UErrorCode to receive any errors. 9954dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * @return A UPluralRules for the specified locale, or NULL if an error occurred. 10059d709d503bab6e2b61931737e662dd293b40578ccornelius * @stable ICU 50 10154dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius */ 1020596faeddefbf198de137d5e893708495ab1584cFredrik RoubertU_CAPI UPluralRules* U_EXPORT2 10354dcd9b6a06071f647dac967e9e267abb9410720Craig Corneliusuplrules_openForType(const char *locale, UPluralType type, UErrorCode *status); 104b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 105b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/** 10654dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius * Closes a UPluralRules object. Once closed it may no longer be used. 107b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param uplrules The UPluralRules object to close. 108103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * @stable ICU 4.8 109b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 1100596faeddefbf198de137d5e893708495ab1584cFredrik RoubertU_CAPI void U_EXPORT2 111b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2clairehouplrules_close(UPluralRules *uplrules); 112b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 113b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 114b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#if U_SHOW_CPLUSPLUS_API 115b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 116b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2clairehoU_NAMESPACE_BEGIN 117b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 118b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/** 119b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * \class LocalUPluralRulesPointer 120b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * "Smart pointer" class, closes a UPluralRules via uplrules_close(). 121b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * For most methods see the LocalPointerBase base class. 122b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * 123b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @see LocalPointerBase 124b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @see LocalPointer 125103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * @stable ICU 4.8 126b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 127b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2clairehoU_DEFINE_LOCAL_OPEN_POINTER(LocalUPluralRulesPointer, UPluralRules, uplrules_close); 128b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 129b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2clairehoU_NAMESPACE_END 130b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 131b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#endif 132b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 133b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 134b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/** 135b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * Given a number, returns the keyword of the first rule that 136b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * applies to the number, according to the supplied UPluralRules object. 137b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param uplrules The UPluralRules object specifying the rules. 138b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param number The number for which the rule has to be determined. 139b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param keyword The keyword of the rule that applies to number. 140b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param capacity The capacity of keyword. 141b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param status A pointer to a UErrorCode to receive any errors. 142b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @return The length of keyword. 143103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * @stable ICU 4.8 144b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 1450596faeddefbf198de137d5e893708495ab1584cFredrik RoubertU_CAPI int32_t U_EXPORT2 146b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2clairehouplrules_select(const UPluralRules *uplrules, 147b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho double number, 148b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho UChar *keyword, int32_t capacity, 149b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho UErrorCode *status); 150b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 1510596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#ifndef U_HIDE_INTERNAL_API 1520596faeddefbf198de137d5e893708495ab1584cFredrik Roubert/** 1530596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * Given a number, returns the keyword of the first rule that applies to the 1540596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * number, according to the UPluralRules object and given the number format 1550596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * specified by the UNumberFormat object. 1560596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * Note: This internal preview interface may be removed in the future if 1570596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * an architecturally cleaner solution reaches stable status. 1580596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param uplrules The UPluralRules object specifying the rules. 1590596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param number The number for which the rule has to be determined. 1600596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param fmt The UNumberFormat specifying how the number will be formatted 1610596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * (this can affect the plural form, e.g. "1 dollar" vs "1.0 dollars"). 1620596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * If this is NULL, the function behaves like uplrules_select. 1630596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param keyword The keyword of the rule that applies to number. 1640596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param capacity The capacity of the keyword buffer. 1650596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param status A pointer to a UErrorCode to receive any errors. 1660596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @return The length of keyword. 1670596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @internal ICU 59 technology preview, may be removed in the future 1680596faeddefbf198de137d5e893708495ab1584cFredrik Roubert */ 1690596faeddefbf198de137d5e893708495ab1584cFredrik RoubertU_INTERNAL int32_t U_EXPORT2 1700596faeddefbf198de137d5e893708495ab1584cFredrik Roubertuplrules_selectWithFormat(const UPluralRules *uplrules, 1710596faeddefbf198de137d5e893708495ab1584cFredrik Roubert double number, 1720596faeddefbf198de137d5e893708495ab1584cFredrik Roubert const UNumberFormat *fmt, 1730596faeddefbf198de137d5e893708495ab1584cFredrik Roubert UChar *keyword, int32_t capacity, 1740596faeddefbf198de137d5e893708495ab1584cFredrik Roubert UErrorCode *status); 1750596faeddefbf198de137d5e893708495ab1584cFredrik Roubert 1760596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#endif /* U_HIDE_INTERNAL_API */ 1770596faeddefbf198de137d5e893708495ab1584cFredrik Roubert 1780596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#ifndef U_HIDE_DRAFT_API 1790596faeddefbf198de137d5e893708495ab1584cFredrik Roubert/** 1800596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * Creates a string enumeration of all plural rule keywords used in this 1810596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * UPluralRules object. The rule "other" is always present by default. 1820596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param uplrules The UPluralRules object specifying the rules for 1830596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * a given locale. 1840596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @param status A pointer to a UErrorCode to receive any errors. 1850596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @return a string enumeration over plural rule keywords, or NULL 1860596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * upon error. The caller is responsible for closing the result. 1870596faeddefbf198de137d5e893708495ab1584cFredrik Roubert * @draft ICU 59 1880596faeddefbf198de137d5e893708495ab1584cFredrik Roubert */ 1890596faeddefbf198de137d5e893708495ab1584cFredrik RoubertU_DRAFT UEnumeration* U_EXPORT2 1900596faeddefbf198de137d5e893708495ab1584cFredrik Roubertuplrules_getKeywords(const UPluralRules *uplrules, 1910596faeddefbf198de137d5e893708495ab1584cFredrik Roubert UErrorCode *status); 1920596faeddefbf198de137d5e893708495ab1584cFredrik Roubert#endif /* U_HIDE_DRAFT_API */ 1930596faeddefbf198de137d5e893708495ab1584cFredrik Roubert 194b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#endif /* #if !UCONFIG_NO_FORMATTING */ 195b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 196b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho#endif 197