include/unicode/udisplayoptions.h

0001 // © 2022 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003
0004 #ifndef __UDISPLAYOPTIONS_H__
0005 #define __UDISPLAYOPTIONS_H__
0006
0007 #include "unicode/utypes.h"
0008
0009 #if !UCONFIG_NO_FORMATTING
0010
0011 /**
0012  * \file
0013  * \brief C API: Display options (enum types, values, helper functions)
0014  *
0015  * These display options are designed to be used in class DisplayOptions
0016  * as a more modern version of the UDisplayContext mechanism.
0017  */
0018
0019 #include "unicode/uversion.h"
0020
0021 /**
0022  * Represents all the grammatical cases that are supported by CLDR.
0023  *
0024  * @stable ICU 72
0025  */
0026 typedef enum UDisplayOptionsGrammaticalCase {
0027     /**
0028      * A possible setting for GrammaticalCase.
0029      * The grammatical case context to be used is unknown (this is the default value).
0030      * @stable ICU 72
0031      */
0032     UDISPOPT_GRAMMATICAL_CASE_UNDEFINED = 0,
0033     /** @stable ICU 72 */
0034     UDISPOPT_GRAMMATICAL_CASE_ABLATIVE = 1,
0035     /** @stable ICU 72 */
0036     UDISPOPT_GRAMMATICAL_CASE_ACCUSATIVE = 2,
0037     /** @stable ICU 72 */
0038     UDISPOPT_GRAMMATICAL_CASE_COMITATIVE = 3,
0039     /** @stable ICU 72 */
0040     UDISPOPT_GRAMMATICAL_CASE_DATIVE = 4,
0041     /** @stable ICU 72 */
0042     UDISPOPT_GRAMMATICAL_CASE_ERGATIVE = 5,
0043     /** @stable ICU 72 */
0044     UDISPOPT_GRAMMATICAL_CASE_GENITIVE = 6,
0045     /** @stable ICU 72 */
0046     UDISPOPT_GRAMMATICAL_CASE_INSTRUMENTAL = 7,
0047     /** @stable ICU 72 */
0048     UDISPOPT_GRAMMATICAL_CASE_LOCATIVE = 8,
0049     /** @stable ICU 72 */
0050     UDISPOPT_GRAMMATICAL_CASE_LOCATIVE_COPULATIVE = 9,
0051     /** @stable ICU 72 */
0052     UDISPOPT_GRAMMATICAL_CASE_NOMINATIVE = 10,
0053     /** @stable ICU 72 */
0054     UDISPOPT_GRAMMATICAL_CASE_OBLIQUE = 11,
0055     /** @stable ICU 72 */
0056     UDISPOPT_GRAMMATICAL_CASE_PREPOSITIONAL = 12,
0057     /** @stable ICU 72 */
0058     UDISPOPT_GRAMMATICAL_CASE_SOCIATIVE = 13,
0059     /** @stable ICU 72 */
0060     UDISPOPT_GRAMMATICAL_CASE_VOCATIVE = 14,
0061 } UDisplayOptionsGrammaticalCase;
0062
0063 /**
0064  * @param grammaticalCase The grammatical case.
0065  * @return the lowercase CLDR keyword string for the grammatical case.
0066  *
0067  * @stable ICU 72
0068  */
0069 U_CAPI const char * U_EXPORT2
0070 udispopt_getGrammaticalCaseIdentifier(UDisplayOptionsGrammaticalCase grammaticalCase);
0071
0072 /**
0073  * @param identifier in lower case such as "dative" or "nominative"
0074  * @return the plural category corresponding to the identifier, or `UDISPOPT_GRAMMATICAL_CASE_UNDEFINED`
0075  *
0076  * @stable ICU 72
0077  */
0078 U_CAPI UDisplayOptionsGrammaticalCase U_EXPORT2
0079 udispopt_fromGrammaticalCaseIdentifier(const char *identifier);
0080
0081 /**
0082  * Standard CLDR plural form/category constants.
0083  * See https://www.unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules
0084  *
0085  * @stable ICU 72
0086  */
0087 typedef enum UDisplayOptionsPluralCategory {
0088
0089     /**
0090      * A possible setting for PluralCategory.
0091      * The plural category case context to be used is unknown (this is the default value).
0092      *
0093      * @stable ICU 72
0094      */
0095     UDISPOPT_PLURAL_CATEGORY_UNDEFINED = 0,
0096     /** @stable ICU 72 */
0097     UDISPOPT_PLURAL_CATEGORY_ZERO = 1,
0098     /** @stable ICU 72 */
0099     UDISPOPT_PLURAL_CATEGORY_ONE = 2,
0100     /** @stable ICU 72 */
0101     UDISPOPT_PLURAL_CATEGORY_TWO = 3,
0102     /** @stable ICU 72 */
0103     UDISPOPT_PLURAL_CATEGORY_FEW = 4,
0104     /** @stable ICU 72 */
0105     UDISPOPT_PLURAL_CATEGORY_MANY = 5,
0106     /** @stable ICU 72 */
0107     UDISPOPT_PLURAL_CATEGORY_OTHER = 6,
0108 } UDisplayOptionsPluralCategory;
0109
0110 /**
0111  * @param pluralCategory The plural category.
0112  * @return the lowercase CLDR identifier string for the plural category.
0113  *
0114  * @stable ICU 72
0115  */
0116 U_CAPI const char * U_EXPORT2
0117 udispopt_getPluralCategoryIdentifier(UDisplayOptionsPluralCategory pluralCategory);
0118
0119 /**
0120  * @param identifier for example "few" or "other"
0121  * @return the plural category corresponding to the identifier (plural keyword),
0122  *         or `UDISPOPT_PLURAL_CATEGORY_UNDEFINED`
0123  *
0124  * @stable ICU 72
0125  */
0126 U_CAPI UDisplayOptionsPluralCategory U_EXPORT2
0127 udispopt_fromPluralCategoryIdentifier(const char *identifier);
0128
0129 /**
0130  * Represents all the grammatical noun classes that are supported by CLDR.
0131  *
0132  * @stable ICU 72.
0133  */
0134 typedef enum UDisplayOptionsNounClass {
0135     /**
0136      * A possible setting for NounClass.
0137      * The noun class case context to be used is unknown (this is the default value).
0138      *
0139      * @stable ICU 72
0140      */
0141     UDISPOPT_NOUN_CLASS_UNDEFINED = 0,
0142     /** @stable ICU 72 */
0143     UDISPOPT_NOUN_CLASS_OTHER = 1,
0144     /** @stable ICU 72 */
0145     UDISPOPT_NOUN_CLASS_NEUTER = 2,
0146     /** @stable ICU 72 */
0147     UDISPOPT_NOUN_CLASS_FEMININE = 3,
0148     /** @stable ICU 72 */
0149     UDISPOPT_NOUN_CLASS_MASCULINE = 4,
0150     /** @stable ICU 72 */
0151     UDISPOPT_NOUN_CLASS_ANIMATE = 5,
0152     /** @stable ICU 72 */
0153     UDISPOPT_NOUN_CLASS_INANIMATE = 6,
0154     /** @stable ICU 72 */
0155     UDISPOPT_NOUN_CLASS_PERSONAL = 7,
0156     /** @stable ICU 72 */
0157     UDISPOPT_NOUN_CLASS_COMMON = 8,
0158 } UDisplayOptionsNounClass;
0159
0160 /**
0161  * @param nounClass The noun class.
0162  * @return the lowercase CLDR keyword string for the noun class.
0163  *
0164  * @stable ICU 72
0165  */
0166 U_CAPI const char * U_EXPORT2
0167 udispopt_getNounClassIdentifier(UDisplayOptionsNounClass nounClass);
0168
0169 /**
0170  * @param identifier in lower case such as "feminine" or "masculine"
0171  * @return the plural category corresponding to the identifier, or `UDISPOPT_NOUN_CLASS_UNDEFINED`
0172  *
0173  * @stable ICU 72
0174  */
0175 U_CAPI UDisplayOptionsNounClass U_EXPORT2
0176 udispopt_fromNounClassIdentifier(const char *identifier);
0177
0178 /**
0179  * Represents all the capitalization options.
0180  *
0181  * @stable ICU 72
0182  */
0183 typedef enum UDisplayOptionsCapitalization {
0184     /**
0185      * A possible setting for Capitalization.
0186      * The capitalization context to be used is unknown (this is the default value).
0187      *
0188      * @stable ICU 72
0189      */
0190     UDISPOPT_CAPITALIZATION_UNDEFINED = 0,
0191
0192     /**
0193      * The capitalization context if a date, date symbol or display name is to be
0194      * formatted with capitalization appropriate for the beginning of a sentence.
0195      *
0196      * @stable ICU 72
0197      */
0198     UDISPOPT_CAPITALIZATION_BEGINNING_OF_SENTENCE = 1,
0199
0200     /**
0201      * The capitalization context if a date, date symbol or display name is to be
0202      * formatted with capitalization appropriate for the middle of a sentence.
0203      *
0204      * @stable ICU 72
0205      */
0206     UDISPOPT_CAPITALIZATION_MIDDLE_OF_SENTENCE = 2,
0207
0208     /**
0209      * The capitalization context if a date, date symbol or display name is to be
0210      * formatted with capitalization appropriate for stand-alone usage such as an
0211      * isolated name on a calendar page.
0212      *
0213      * @stable ICU 72
0214      */
0215     UDISPOPT_CAPITALIZATION_STANDALONE = 3,
0216
0217     /**
0218      * The capitalization context if a date, date symbol or display name is to be
0219      * formatted with capitalization appropriate for a user-interface list or menu item.
0220      *
0221      * @stable ICU 72
0222      */
0223     UDISPOPT_CAPITALIZATION_UI_LIST_OR_MENU = 4,
0224 } UDisplayOptionsCapitalization;
0225
0226 /**
0227  * Represents all the dialect handlings.
0228  *
0229  * @stable ICU 72
0230  */
0231 typedef enum UDisplayOptionsNameStyle {
0232     /**
0233      * A possible setting for NameStyle.
0234      * The NameStyle context to be used is unknown (this is the default value).
0235      *
0236      * @stable ICU 72
0237      */
0238     UDISPOPT_NAME_STYLE_UNDEFINED = 0,
0239
0240     /**
0241      * Use standard names when generating a locale name,
0242      * e.g. en_GB displays as 'English (United Kingdom)'.
0243      *
0244      * @stable ICU 72
0245      */
0246     UDISPOPT_NAME_STYLE_STANDARD_NAMES = 1,
0247
0248     /**
0249      * Use dialect names, when generating a locale name,
0250      * e.g. en_GB displays as 'British English'.
0251      *
0252      * @stable ICU 72
0253      */
0254     UDISPOPT_NAME_STYLE_DIALECT_NAMES = 2,
0255 } UDisplayOptionsNameStyle;
0256
0257 /**
0258  * Represents all the display lengths.
0259  *
0260  * @stable ICU 72
0261  */
0262 typedef enum UDisplayOptionsDisplayLength {
0263     /**
0264      * A possible setting for DisplayLength.
0265      * The DisplayLength context to be used is unknown (this is the default value).
0266      *
0267      * @stable ICU 72
0268      */
0269     UDISPOPT_DISPLAY_LENGTH_UNDEFINED = 0,
0270
0271     /**
0272      * Uses full names when generating a locale name,
0273      * e.g. "United States" for US.
0274      *
0275      * @stable ICU 72
0276      */
0277     UDISPOPT_DISPLAY_LENGTH_FULL = 1,
0278
0279     /**
0280      * Use short names when generating a locale name,
0281      * e.g. "U.S." for US.
0282      *
0283      * @stable ICU 72
0284      */
0285     UDISPOPT_DISPLAY_LENGTH_SHORT = 2,
0286 } UDisplayOptionsDisplayLength;
0287
0288 /**
0289  * Represents all the substitute handling.
0290  *
0291  * @stable ICU 72
0292  */
0293 typedef enum UDisplayOptionsSubstituteHandling {
0294
0295     /**
0296      * A possible setting for SubstituteHandling.
0297      * The SubstituteHandling context to be used is unknown (this is the default value).
0298      *
0299      * @stable ICU 72
0300      */
0301     UDISPOPT_SUBSTITUTE_HANDLING_UNDEFINED = 0,
0302
0303     /**
0304      * Returns a fallback value (e.g., the input code) when no data is available.
0305      * This is the default behaviour.
0306      *
0307      * @stable ICU 72
0308      */
0309     UDISPOPT_SUBSTITUTE_HANDLING_SUBSTITUTE = 1,
0310
0311     /**
0312      * Returns a null value when no data is available.
0313      *
0314      * @stable ICU 72
0315      */
0316     UDISPOPT_SUBSTITUTE_HANDLING_NO_SUBSTITUTE = 2,
0317 } UDisplayOptionsSubstituteHandling;
0318
0319 #endif /* #if !UCONFIG_NO_FORMATTING */
0320
0321 #endif // __UDISPLAYOPTIONS_H__