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