include/unicode/ulocale.h

0001 // © 2023 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003
0004 #ifndef ULOCALE_H
0005 #define ULOCALE_H
0006
0007 #include "unicode/localpointer.h"
0008 #include "unicode/uenum.h"
0009 #include "unicode/utypes.h"
0010
0011 /**
0012  * \file
0013  * \brief C API: Locale ID functionality similar to C++ class Locale
0014  */
0015
0016 #ifndef U_HIDE_DRAFT_API
0017 /**
0018  * Opaque C service object type for the locale API
0019  * @draft ICU 74
0020  */
0021 struct ULocale;
0022
0023 /**
0024  * C typedef for struct ULocale.
0025  * @draft ICU 74
0026  */
0027 typedef struct ULocale ULocale;
0028
0029 /**
0030  * Constructs an ULocale from the locale ID.
0031  * The created ULocale should be destroyed by calling
0032  * ulocale_close();
0033  * @param localeID the locale, a const char * pointer (need not be terminated when
0034  *               the length is non-negative)
0035  * @param length the length of the locale; if negative, then the locale need to be
0036  *               null terminated.
0037  * @param err the error code
0038  * @return the locale.
0039  *
0040  * @draft ICU 74
0041  */
0042 U_CAPI ULocale* U_EXPORT2
0043 ulocale_openForLocaleID(const char* localeID, int32_t length, UErrorCode* err);
0044
0045 /**
0046  * Constructs an ULocale from the provided IETF BCP 47 language tag.
0047  * The created ULocale should be destroyed by calling
0048  * ulocale_close();
0049  * @param tag the language tag, defined as IETF BCP 47 language tag, const
0050  *            char* pointer (need not be terminated when the length is non-negative)
0051  * @param length the length of the tag; if negative, then the tag need to be
0052  *               null terminated.
0053  * @param err the error code
0054  * @return the locale.
0055  *
0056  * @draft ICU 74
0057  */
0058 U_CAPI ULocale* U_EXPORT2
0059 ulocale_openForLanguageTag(const char* tag, int32_t length, UErrorCode* err);
0060
0061 /**
0062  * Close the locale and destroy it's internal states.
0063  *
0064  * @param locale the locale
0065  * @draft ICU 74
0066  */
0067 U_CAPI void U_EXPORT2
0068 ulocale_close(ULocale* locale);
0069
0070 /**
0071  * Returns the locale's ISO-639 language code.
0072  *
0073  * @param locale the locale
0074  * @return      the language code of the locale.
0075  * @draft ICU 74
0076  */
0077 U_CAPI const char* U_EXPORT2
0078 ulocale_getLanguage(const ULocale* locale);
0079
0080 /**
0081  * Returns the locale's ISO-15924 abbreviation script code.
0082  *
0083  * @param locale the locale
0084  * @return      A pointer to the script.
0085  * @draft ICU 74
0086  */
0087 U_CAPI const char* U_EXPORT2
0088 ulocale_getScript(const ULocale* locale);
0089
0090 /**
0091  * Returns the locale's ISO-3166 region code.
0092  *
0093  * @param locale the locale
0094  * @return      A pointer to the region.
0095  * @draft ICU 74
0096  */
0097 U_CAPI const char* U_EXPORT2
0098 ulocale_getRegion(const ULocale* locale);
0099
0100 /**
0101  * Returns the locale's variant code.
0102  *
0103  * @param locale the locale
0104  * @return      A pointer to the variant.
0105  * @draft ICU 74
0106  */
0107 U_CAPI const char* U_EXPORT2
0108 ulocale_getVariant(const ULocale* locale);
0109
0110 /**
0111  * Returns the programmatic name of the entire locale, with the language,
0112  * country and variant separated by underbars. If a field is missing, up
0113  * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN",
0114  * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"
0115  *
0116  * @param locale the locale
0117  * @return      A pointer to "name".
0118  * @draft ICU 74
0119  */
0120 U_CAPI const char* U_EXPORT2
0121 ulocale_getLocaleID(const ULocale* locale);
0122
0123 /**
0124  * Returns the programmatic name of the entire locale as ulocale_getLocaleID()
0125  * would return, but without keywords.
0126  *
0127  * @param locale the locale
0128  * @return      A pointer to "base name".
0129  * @draft ICU 74
0130  */
0131 U_CAPI const char* U_EXPORT2
0132 ulocale_getBaseName(const ULocale* locale);
0133
0134 /**
0135  * Gets the bogus state. Locale object can be bogus if it doesn't exist
0136  *
0137  * @param locale the locale
0138  * @return false if it is a real locale, true if it is a bogus locale
0139  * @draft ICU 74
0140  */
0141 U_CAPI bool U_EXPORT2
0142 ulocale_isBogus(const ULocale* locale);
0143
0144 /**
0145  * Gets the list of keywords for the specified locale.
0146  *
0147  * @param locale the locale
0148  * @param err the error code
0149  * @return pointer to UEnumeration, or nullptr if there are no keywords.
0150  * Client must call uenum_close() to dispose the returned value.
0151  * @draft ICU 74
0152  */
0153 U_CAPI UEnumeration* U_EXPORT2
0154 ulocale_getKeywords(const ULocale* locale, UErrorCode *err);
0155
0156 /**
0157  * Gets the list of unicode keywords for the specified locale.
0158  *
0159  * @param locale the locale
0160  * @param err the error code
0161  * @return pointer to UEnumeration, or nullptr if there are no keywords.
0162  * Client must call uenum_close() to dispose the returned value.
0163  * @draft ICU 74
0164  */
0165 U_CAPI UEnumeration* U_EXPORT2
0166 ulocale_getUnicodeKeywords(const ULocale* locale, UErrorCode *err);
0167
0168 /**
0169  * Gets the value for a keyword.
0170  *
0171  * This uses legacy keyword=value pairs, like "collation=phonebook".
0172  *
0173  * @param locale the locale
0174  * @param keyword the keyword, a const char * pointer (need not be
0175  *                terminated when the length is non-negative)
0176  * @param keywordLength the length of the keyword; if negative, then the
0177  *                      keyword need to be null terminated.
0178  * @param valueBuffer The buffer to receive the value.
0179  * @param valueBufferCapacity The capacity of receiving valueBuffer.
0180  * @param err the error code
0181  * @draft ICU 74
0182  */
0183 U_CAPI int32_t U_EXPORT2
0184 ulocale_getKeywordValue(
0185     const ULocale* locale, const char* keyword, int32_t keywordLength,
0186     char* valueBuffer, int32_t valueBufferCapacity, UErrorCode *err);
0187
0188 /**
0189  * Gets the Unicode value for a Unicode keyword.
0190  *
0191  * This uses Unicode key-value pairs, like "co-phonebk".
0192  *
0193  * @param locale the locale
0194  * @param keyword the Unicode keyword, a const char * pointer (need not be
0195  *                terminated when the length is non-negative)
0196  * @param keywordLength the length of the Unicode keyword; if negative,
0197  *                      then the keyword need to be null terminated.
0198  * @param valueBuffer The buffer to receive the Unicode value.
0199  * @param valueBufferCapacity The capacity of receiving valueBuffer.
0200  * @param err the error code
0201  * @draft ICU 74
0202  */
0203 U_CAPI int32_t U_EXPORT2
0204 ulocale_getUnicodeKeywordValue(
0205     const ULocale* locale, const char* keyword, int32_t keywordLength,
0206     char* valueBuffer, int32_t valueBufferCapacity, UErrorCode *err);
0207
0208 #if U_SHOW_CPLUSPLUS_API
0209
0210 U_NAMESPACE_BEGIN
0211
0212 /**
0213  * \class LocalULocalePointer
0214  * "Smart pointer" class, closes a ULocale via ulocale_close().
0215  * For most methods see the LocalPointerBase base class.
0216  *
0217  * @see LocalPointerBase
0218  * @see LocalPointer
0219  * @draft ICU 74
0220  */
0221 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocalePointer, ULocale, ulocale_close);
0222
0223 U_NAMESPACE_END
0224
0225 #endif  /* U_SHOW_CPLUSPLUS_API */
0226
0227 #endif /* U_HIDE_DRAFT_API */
0228
0229 #endif /*_ULOCALE */