ulocale.h (6466B)
1 // © 2023 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 4 #ifndef ULOCALE_H 5 #define ULOCALE_H 6 7 #include "unicode/localpointer.h" 8 #include "unicode/uenum.h" 9 #include "unicode/utypes.h" 10 11 /** 12 * \file 13 * \brief C API: Locale ID functionality similar to C++ class Locale 14 */ 15 16 /** 17 * Opaque C service object type for the locale API 18 * @stable ICU 74 19 */ 20 struct ULocale; 21 22 /** 23 * C typedef for struct ULocale. 24 * @stable ICU 74 25 */ 26 typedef struct ULocale ULocale; 27 28 /** 29 * Constructs an ULocale from the locale ID. 30 * The created ULocale should be destroyed by calling 31 * ulocale_close(); 32 * @param localeID the locale, a const char * pointer (need not be terminated when 33 * the length is non-negative) 34 * @param length the length of the locale; if negative, then the locale need to be 35 * null terminated. 36 * @param err the error code 37 * @return the locale. 38 * 39 * @stable ICU 74 40 */ 41 U_CAPI ULocale* U_EXPORT2 42 ulocale_openForLocaleID(const char* localeID, int32_t length, UErrorCode* err); 43 44 /** 45 * Constructs an ULocale from the provided IETF BCP 47 language tag. 46 * The created ULocale should be destroyed by calling 47 * ulocale_close(); 48 * @param tag the language tag, defined as IETF BCP 47 language tag, const 49 * char* pointer (need not be terminated when the length is non-negative) 50 * @param length the length of the tag; if negative, then the tag need to be 51 * null terminated. 52 * @param err the error code 53 * @return the locale. 54 * 55 * @stable ICU 74 56 */ 57 U_CAPI ULocale* U_EXPORT2 58 ulocale_openForLanguageTag(const char* tag, int32_t length, UErrorCode* err); 59 60 /** 61 * Close the locale and destroy it's internal states. 62 * 63 * @param locale the locale 64 * @stable ICU 74 65 */ 66 U_CAPI void U_EXPORT2 67 ulocale_close(ULocale* locale); 68 69 /** 70 * Returns the locale's ISO-639 language code. 71 * 72 * @param locale the locale 73 * @return the language code of the locale. 74 * @stable ICU 74 75 */ 76 U_CAPI const char* U_EXPORT2 77 ulocale_getLanguage(const ULocale* locale); 78 79 /** 80 * Returns the locale's ISO-15924 abbreviation script code. 81 * 82 * @param locale the locale 83 * @return A pointer to the script. 84 * @stable ICU 74 85 */ 86 U_CAPI const char* U_EXPORT2 87 ulocale_getScript(const ULocale* locale); 88 89 /** 90 * Returns the locale's ISO-3166 region code. 91 * 92 * @param locale the locale 93 * @return A pointer to the region. 94 * @stable ICU 74 95 */ 96 U_CAPI const char* U_EXPORT2 97 ulocale_getRegion(const ULocale* locale); 98 99 /** 100 * Returns the locale's variant code. 101 * 102 * @param locale the locale 103 * @return A pointer to the variant. 104 * @stable ICU 74 105 */ 106 U_CAPI const char* U_EXPORT2 107 ulocale_getVariant(const ULocale* locale); 108 109 /** 110 * Returns the programmatic name of the entire locale, with the language, 111 * country and variant separated by underbars. If a field is missing, up 112 * to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN", 113 * "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO" 114 * 115 * @param locale the locale 116 * @return A pointer to "name". 117 * @stable ICU 74 118 */ 119 U_CAPI const char* U_EXPORT2 120 ulocale_getLocaleID(const ULocale* locale); 121 122 /** 123 * Returns the programmatic name of the entire locale as ulocale_getLocaleID() 124 * would return, but without keywords. 125 * 126 * @param locale the locale 127 * @return A pointer to "base name". 128 * @stable ICU 74 129 */ 130 U_CAPI const char* U_EXPORT2 131 ulocale_getBaseName(const ULocale* locale); 132 133 /** 134 * Gets the bogus state. Locale object can be bogus if it doesn't exist 135 * 136 * @param locale the locale 137 * @return false if it is a real locale, true if it is a bogus locale 138 * @stable ICU 74 139 */ 140 U_CAPI bool U_EXPORT2 141 ulocale_isBogus(const ULocale* locale); 142 143 /** 144 * Gets the list of keywords for the specified locale. 145 * 146 * @param locale the locale 147 * @param err the error code 148 * @return pointer to UEnumeration, or nullptr if there are no keywords. 149 * Client must call uenum_close() to dispose the returned value. 150 * @stable ICU 74 151 */ 152 U_CAPI UEnumeration* U_EXPORT2 153 ulocale_getKeywords(const ULocale* locale, UErrorCode *err); 154 155 /** 156 * Gets the list of unicode keywords for the specified locale. 157 * 158 * @param locale the locale 159 * @param err the error code 160 * @return pointer to UEnumeration, or nullptr if there are no keywords. 161 * Client must call uenum_close() to dispose the returned value. 162 * @stable ICU 74 163 */ 164 U_CAPI UEnumeration* U_EXPORT2 165 ulocale_getUnicodeKeywords(const ULocale* locale, UErrorCode *err); 166 167 /** 168 * Gets the value for a keyword. 169 * 170 * This uses legacy keyword=value pairs, like "collation=phonebook". 171 * 172 * @param locale the locale 173 * @param keyword the keyword, a const char * pointer (need not be 174 * terminated when the length is non-negative) 175 * @param keywordLength the length of the keyword; if negative, then the 176 * keyword need to be null terminated. 177 * @param valueBuffer The buffer to receive the value. 178 * @param valueBufferCapacity The capacity of receiving valueBuffer. 179 * @param err the error code 180 * @stable ICU 74 181 */ 182 U_CAPI int32_t U_EXPORT2 183 ulocale_getKeywordValue( 184 const ULocale* locale, const char* keyword, int32_t keywordLength, 185 char* valueBuffer, int32_t valueBufferCapacity, UErrorCode *err); 186 187 /** 188 * Gets the Unicode value for a Unicode keyword. 189 * 190 * This uses Unicode key-value pairs, like "co-phonebk". 191 * 192 * @param locale the locale 193 * @param keyword the Unicode keyword, a const char * pointer (need not be 194 * terminated when the length is non-negative) 195 * @param keywordLength the length of the Unicode keyword; if negative, 196 * then the keyword need to be null terminated. 197 * @param valueBuffer The buffer to receive the Unicode value. 198 * @param valueBufferCapacity The capacity of receiving valueBuffer. 199 * @param err the error code 200 * @stable ICU 74 201 */ 202 U_CAPI int32_t U_EXPORT2 203 ulocale_getUnicodeKeywordValue( 204 const ULocale* locale, const char* keyword, int32_t keywordLength, 205 char* valueBuffer, int32_t valueBufferCapacity, UErrorCode *err); 206 207 #if U_SHOW_CPLUSPLUS_API 208 209 U_NAMESPACE_BEGIN 210 211 /** 212 * \class LocalULocalePointer 213 * "Smart pointer" class, closes a ULocale via ulocale_close(). 214 * For most methods see the LocalPointerBase base class. 215 * 216 * @see LocalPointerBase 217 * @see LocalPointer 218 * @stable ICU 74 219 */ 220 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocalePointer, ULocale, ulocale_close); 221 222 U_NAMESPACE_END 223 224 #endif /* U_SHOW_CPLUSPLUS_API */ 225 226 #endif /*_ULOCALE */