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-2016, International Business Machines Corporation and 6 * others. All Rights Reserved. 7 ******************************************************************************* 8 */ 9 10 #ifndef __ULDNAMES_H__ 11 #define __ULDNAMES_H__ 12 13 /** 14 * @addtogroup icu4c ICU4C 15 * @{ 16 * \file 17 * \brief C API: Provides display names of Locale ids and their components. 18 */ 19 20 #include "unicode/utypes.h" 21 #include "unicode/uscript.h" 22 #include "unicode/udisplaycontext.h" 23 24 #if U_SHOW_CPLUSPLUS_API 25 #include "unicode/localpointer.h" 26 #endif // U_SHOW_CPLUSPLUS_API 27 28 /** 29 * Enum used in LocaleDisplayNames::createInstance. 30 * \xrefitem stable "Stable" "Stable List" ICU 4.4 31 */ 32 typedef enum { 33 /** 34 * Use standard names when generating a locale name, 35 * e.g. en_GB displays as 'English (United Kingdom)'. 36 * \xrefitem stable "Stable" "Stable List" ICU 4.4 37 */ 38 ULDN_STANDARD_NAMES = 0, 39 /** 40 * Use dialect names, when generating a locale name, 41 * e.g. en_GB displays as 'British English'. 42 * \xrefitem stable "Stable" "Stable List" ICU 4.4 43 */ 44 ULDN_DIALECT_NAMES 45 } UDialectHandling; 46 47 /** 48 * Opaque C service object type for the locale display names API 49 * \xrefitem stable "Stable" "Stable List" ICU 4.4 50 */ 51 struct ULocaleDisplayNames; 52 53 /** 54 * C typedef for struct ULocaleDisplayNames. 55 * \xrefitem stable "Stable" "Stable List" ICU 4.4 56 */ 57 typedef struct ULocaleDisplayNames ULocaleDisplayNames; 58 59 #if !UCONFIG_NO_FORMATTING 60 61 /** 62 * Returns an instance of LocaleDisplayNames that returns names 63 * formatted for the provided locale, using the provided 64 * dialectHandling. The usual value for dialectHandling is 65 * ULOC_STANDARD_NAMES. 66 * 67 * @param locale the display locale 68 * @param dialectHandling how to select names for locales 69 * @return a ULocaleDisplayNames instance 70 * @param pErrorCode the status code 71 * \xrefitem stable "Stable" "Stable List" ICU 4.4 72 */ 73 U_CAPI ULocaleDisplayNames * U_EXPORT2 74 uldn_open(const char * locale, 75 UDialectHandling dialectHandling, 76 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 77 78 79 80 /** 81 * Closes a ULocaleDisplayNames instance obtained from uldn_open(). 82 * @param ldn the ULocaleDisplayNames instance to be closed 83 * \xrefitem stable "Stable" "Stable List" ICU 4.4 84 */ 85 U_CAPI void U_EXPORT2 86 uldn_close(ULocaleDisplayNames *ldn) __INTRODUCED_IN(31); 87 88 89 90 #if U_SHOW_CPLUSPLUS_API 91 92 U_NAMESPACE_BEGIN 93 94 /** 95 * \class LocalULocaleDisplayNamesPointer 96 * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close(). 97 * For most methods see the LocalPointerBase base class. 98 * 99 * @see LocalPointerBase 100 * @see LocalPointer 101 * \xrefitem stable "Stable" "Stable List" ICU 4.4 102 */ 103 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close); 104 105 U_NAMESPACE_END 106 107 #endif 108 109 /* getters for state */ 110 111 /** 112 * Returns the locale used to determine the display names. This is 113 * not necessarily the same locale passed to {@link #uldn_open}. 114 * @param ldn the LocaleDisplayNames instance 115 * @return the display locale 116 * \xrefitem stable "Stable" "Stable List" ICU 4.4 117 */ 118 U_CAPI const char * U_EXPORT2 119 uldn_getLocale(const ULocaleDisplayNames *ldn) __INTRODUCED_IN(31); 120 121 122 123 /** 124 * Returns the dialect handling used in the display names. 125 * @param ldn the LocaleDisplayNames instance 126 * @return the dialect handling enum 127 * \xrefitem stable "Stable" "Stable List" ICU 4.4 128 */ 129 U_CAPI UDialectHandling U_EXPORT2 130 uldn_getDialectHandling(const ULocaleDisplayNames *ldn) __INTRODUCED_IN(31); 131 132 133 134 /* names for entire locales */ 135 136 /** 137 * Returns the display name of the provided locale. 138 * @param ldn the LocaleDisplayNames instance 139 * @param locale the locale whose display name to return 140 * @param result receives the display name 141 * @param maxResultSize the size of the result buffer 142 * @param pErrorCode the status code 143 * @return the actual buffer size needed for the display name. If it's 144 * greater than maxResultSize, the returned name will be truncated. 145 * \xrefitem stable "Stable" "Stable List" ICU 4.4 146 */ 147 U_CAPI int32_t U_EXPORT2 148 uldn_localeDisplayName(const ULocaleDisplayNames *ldn, 149 const char *locale, 150 UChar *result, 151 int32_t maxResultSize, 152 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 153 154 155 156 /* names for components of a locale */ 157 158 /** 159 * Returns the display name of the provided language code. 160 * @param ldn the LocaleDisplayNames instance 161 * @param lang the language code whose display name to return 162 * @param result receives the display name 163 * @param maxResultSize the size of the result buffer 164 * @param pErrorCode the status code 165 * @return the actual buffer size needed for the display name. If it's 166 * greater than maxResultSize, the returned name will be truncated. 167 * \xrefitem stable "Stable" "Stable List" ICU 4.4 168 */ 169 U_CAPI int32_t U_EXPORT2 170 uldn_languageDisplayName(const ULocaleDisplayNames *ldn, 171 const char *lang, 172 UChar *result, 173 int32_t maxResultSize, 174 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 175 176 177 178 /** 179 * Returns the display name of the provided script. 180 * @param ldn the LocaleDisplayNames instance 181 * @param script the script whose display name to return 182 * @param result receives the display name 183 * @param maxResultSize the size of the result buffer 184 * @param pErrorCode the status code 185 * @return the actual buffer size needed for the display name. If it's 186 * greater than maxResultSize, the returned name will be truncated. 187 * \xrefitem stable "Stable" "Stable List" ICU 4.4 188 */ 189 U_CAPI int32_t U_EXPORT2 190 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn, 191 const char *script, 192 UChar *result, 193 int32_t maxResultSize, 194 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 195 196 197 198 /** 199 * Returns the display name of the provided script code. 200 * @param ldn the LocaleDisplayNames instance 201 * @param scriptCode the script code whose display name to return 202 * @param result receives the display name 203 * @param maxResultSize the size of the result buffer 204 * @param pErrorCode the status code 205 * @return the actual buffer size needed for the display name. If it's 206 * greater than maxResultSize, the returned name will be truncated. 207 * \xrefitem stable "Stable" "Stable List" ICU 4.4 208 */ 209 U_CAPI int32_t U_EXPORT2 210 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn, 211 UScriptCode scriptCode, 212 UChar *result, 213 int32_t maxResultSize, 214 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 215 216 217 218 /** 219 * Returns the display name of the provided region code. 220 * @param ldn the LocaleDisplayNames instance 221 * @param region the region code whose display name to return 222 * @param result receives the display name 223 * @param maxResultSize the size of the result buffer 224 * @param pErrorCode the status code 225 * @return the actual buffer size needed for the display name. If it's 226 * greater than maxResultSize, the returned name will be truncated. 227 * \xrefitem stable "Stable" "Stable List" ICU 4.4 228 */ 229 U_CAPI int32_t U_EXPORT2 230 uldn_regionDisplayName(const ULocaleDisplayNames *ldn, 231 const char *region, 232 UChar *result, 233 int32_t maxResultSize, 234 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 235 236 237 238 /** 239 * Returns the display name of the provided variant 240 * @param ldn the LocaleDisplayNames instance 241 * @param variant the variant whose display name to return 242 * @param result receives the display name 243 * @param maxResultSize the size of the result buffer 244 * @param pErrorCode the status code 245 * @return the actual buffer size needed for the display name. If it's 246 * greater than maxResultSize, the returned name will be truncated. 247 * \xrefitem stable "Stable" "Stable List" ICU 4.4 248 */ 249 U_CAPI int32_t U_EXPORT2 250 uldn_variantDisplayName(const ULocaleDisplayNames *ldn, 251 const char *variant, 252 UChar *result, 253 int32_t maxResultSize, 254 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 255 256 257 258 /** 259 * Returns the display name of the provided locale key 260 * @param ldn the LocaleDisplayNames instance 261 * @param key the locale key whose display name to return 262 * @param result receives the display name 263 * @param maxResultSize the size of the result buffer 264 * @param pErrorCode the status code 265 * @return the actual buffer size needed for the display name. If it's 266 * greater than maxResultSize, the returned name will be truncated. 267 * \xrefitem stable "Stable" "Stable List" ICU 4.4 268 */ 269 U_CAPI int32_t U_EXPORT2 270 uldn_keyDisplayName(const ULocaleDisplayNames *ldn, 271 const char *key, 272 UChar *result, 273 int32_t maxResultSize, 274 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 275 276 277 278 /** 279 * Returns the display name of the provided value (used with the provided key). 280 * @param ldn the LocaleDisplayNames instance 281 * @param key the locale key 282 * @param value the locale key's value 283 * @param result receives the display name 284 * @param maxResultSize the size of the result buffer 285 * @param pErrorCode the status code 286 * @return the actual buffer size needed for the display name. If it's 287 * greater than maxResultSize, the returned name will be truncated. 288 * \xrefitem stable "Stable" "Stable List" ICU 4.4 289 */ 290 U_CAPI int32_t U_EXPORT2 291 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn, 292 const char *key, 293 const char *value, 294 UChar *result, 295 int32_t maxResultSize, 296 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 297 298 299 300 /** 301 * Returns an instance of LocaleDisplayNames that returns names formatted 302 * for the provided locale, using the provided UDisplayContext settings. 303 * 304 * @param locale The display locale 305 * @param contexts List of one or more context settings (e.g. for dialect 306 * handling, capitalization, etc. 307 * @param length Number of items in the contexts list 308 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates 309 * a failure status, the function will do nothing; otherwise this will be 310 * updated with any new status from the function. 311 * @return a ULocaleDisplayNames instance 312 * \xrefitem stable "Stable" "Stable List" ICU 51 313 */ 314 U_CAPI ULocaleDisplayNames * U_EXPORT2 315 uldn_openForContext(const char * locale, UDisplayContext *contexts, 316 int32_t length, UErrorCode *pErrorCode) __INTRODUCED_IN(31); 317 318 319 320 /** 321 * Returns the UDisplayContext value for the specified UDisplayContextType. 322 * @param ldn the ULocaleDisplayNames instance 323 * @param type the UDisplayContextType whose value to return 324 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates 325 * a failure status, the function will do nothing; otherwise this will be 326 * updated with any new status from the function. 327 * @return the UDisplayContextValue for the specified type. 328 * \xrefitem stable "Stable" "Stable List" ICU 51 329 */ 330 U_CAPI UDisplayContext U_EXPORT2 331 uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type, 332 UErrorCode *pErrorCode) __INTRODUCED_IN(31); 333 334 335 336 #endif /* !UCONFIG_NO_FORMATTING */ 337 #endif /* __ULDNAMES_H__ */ 338 339 /** @} */ // addtogroup 340