uldnames.h (10733B)
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); 75 76 /** 77 * Closes a ULocaleDisplayNames instance obtained from uldn_open(). 78 * @param ldn the ULocaleDisplayNames instance to be closed 79 * @stable ICU 4.4 80 */ 81 U_CAPI void U_EXPORT2 82 uldn_close(ULocaleDisplayNames *ldn); 83 84 #if U_SHOW_CPLUSPLUS_API 85 86 U_NAMESPACE_BEGIN 87 88 /** 89 * \class LocalULocaleDisplayNamesPointer 90 * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close(). 91 * For most methods see the LocalPointerBase base class. 92 * 93 * @see LocalPointerBase 94 * @see LocalPointer 95 * @stable ICU 4.4 96 */ 97 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close); 98 99 U_NAMESPACE_END 100 101 #endif 102 103 /* getters for state */ 104 105 /** 106 * Returns the locale used to determine the display names. This is 107 * not necessarily the same locale passed to {@link #uldn_open}. 108 * @param ldn the LocaleDisplayNames instance 109 * @return the display locale 110 * @stable ICU 4.4 111 */ 112 U_CAPI const char * U_EXPORT2 113 uldn_getLocale(const ULocaleDisplayNames *ldn); 114 115 /** 116 * Returns the dialect handling used in the display names. 117 * @param ldn the LocaleDisplayNames instance 118 * @return the dialect handling enum 119 * @stable ICU 4.4 120 */ 121 U_CAPI UDialectHandling U_EXPORT2 122 uldn_getDialectHandling(const ULocaleDisplayNames *ldn); 123 124 /* names for entire locales */ 125 126 /** 127 * Returns the display name of the provided locale. 128 * @param ldn the LocaleDisplayNames instance 129 * @param locale the locale whose display name to return 130 * @param result receives the display name 131 * @param maxResultSize the size of the result buffer 132 * @param pErrorCode the status code 133 * @return the actual buffer size needed for the display name. If it's 134 * greater than maxResultSize, the returned name will be truncated. 135 * @stable ICU 4.4 136 */ 137 U_CAPI int32_t U_EXPORT2 138 uldn_localeDisplayName(const ULocaleDisplayNames *ldn, 139 const char *locale, 140 UChar *result, 141 int32_t maxResultSize, 142 UErrorCode *pErrorCode); 143 144 /* names for components of a locale */ 145 146 /** 147 * Returns the display name of the provided language code. 148 * @param ldn the LocaleDisplayNames instance 149 * @param lang the language code whose display name to return 150 * @param result receives the display name 151 * @param maxResultSize the size of the result buffer 152 * @param pErrorCode the status code 153 * @return the actual buffer size needed for the display name. If it's 154 * greater than maxResultSize, the returned name will be truncated. 155 * @stable ICU 4.4 156 */ 157 U_CAPI int32_t U_EXPORT2 158 uldn_languageDisplayName(const ULocaleDisplayNames *ldn, 159 const char *lang, 160 UChar *result, 161 int32_t maxResultSize, 162 UErrorCode *pErrorCode); 163 164 /** 165 * Returns the display name of the provided script. 166 * @param ldn the LocaleDisplayNames instance 167 * @param script the script whose display name to return 168 * @param result receives the display name 169 * @param maxResultSize the size of the result buffer 170 * @param pErrorCode the status code 171 * @return the actual buffer size needed for the display name. If it's 172 * greater than maxResultSize, the returned name will be truncated. 173 * @stable ICU 4.4 174 */ 175 U_CAPI int32_t U_EXPORT2 176 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn, 177 const char *script, 178 UChar *result, 179 int32_t maxResultSize, 180 UErrorCode *pErrorCode); 181 182 /** 183 * Returns the display name of the provided script code. 184 * @param ldn the LocaleDisplayNames instance 185 * @param scriptCode the script code whose display name to return 186 * @param result receives the display name 187 * @param maxResultSize the size of the result buffer 188 * @param pErrorCode the status code 189 * @return the actual buffer size needed for the display name. If it's 190 * greater than maxResultSize, the returned name will be truncated. 191 * @stable ICU 4.4 192 */ 193 U_CAPI int32_t U_EXPORT2 194 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn, 195 UScriptCode scriptCode, 196 UChar *result, 197 int32_t maxResultSize, 198 UErrorCode *pErrorCode); 199 200 /** 201 * Returns the display name of the provided region code. 202 * @param ldn the LocaleDisplayNames instance 203 * @param region the region code whose display name to return 204 * @param result receives the display name 205 * @param maxResultSize the size of the result buffer 206 * @param pErrorCode the status code 207 * @return the actual buffer size needed for the display name. If it's 208 * greater than maxResultSize, the returned name will be truncated. 209 * @stable ICU 4.4 210 */ 211 U_CAPI int32_t U_EXPORT2 212 uldn_regionDisplayName(const ULocaleDisplayNames *ldn, 213 const char *region, 214 UChar *result, 215 int32_t maxResultSize, 216 UErrorCode *pErrorCode); 217 218 /** 219 * Returns the display name of the provided variant 220 * @param ldn the LocaleDisplayNames instance 221 * @param variant the variant 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 * @stable ICU 4.4 228 */ 229 U_CAPI int32_t U_EXPORT2 230 uldn_variantDisplayName(const ULocaleDisplayNames *ldn, 231 const char *variant, 232 UChar *result, 233 int32_t maxResultSize, 234 UErrorCode *pErrorCode); 235 236 /** 237 * Returns the display name of the provided locale key 238 * @param ldn the LocaleDisplayNames instance 239 * @param key the locale key 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_keyDisplayName(const ULocaleDisplayNames *ldn, 249 const char *key, 250 UChar *result, 251 int32_t maxResultSize, 252 UErrorCode *pErrorCode); 253 254 /** 255 * Returns the display name of the provided value (used with the provided key). 256 * @param ldn the LocaleDisplayNames instance 257 * @param key the locale key 258 * @param value the locale key's value 259 * @param result receives the display name 260 * @param maxResultSize the size of the result buffer 261 * @param pErrorCode the status code 262 * @return the actual buffer size needed for the display name. If it's 263 * greater than maxResultSize, the returned name will be truncated. 264 * @stable ICU 4.4 265 */ 266 U_CAPI int32_t U_EXPORT2 267 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn, 268 const char *key, 269 const char *value, 270 UChar *result, 271 int32_t maxResultSize, 272 UErrorCode *pErrorCode); 273 274 /** 275 * Returns an instance of LocaleDisplayNames that returns names formatted 276 * for the provided locale, using the provided UDisplayContext settings. 277 * 278 * @param locale The display locale 279 * @param contexts List of one or more context settings (e.g. for dialect 280 * handling, capitalization, etc. 281 * @param length Number of items in the contexts list 282 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates 283 * a failure status, the function will do nothing; otherwise this will be 284 * updated with any new status from the function. 285 * @return a ULocaleDisplayNames instance 286 * @stable ICU 51 287 */ 288 U_CAPI ULocaleDisplayNames * U_EXPORT2 289 uldn_openForContext(const char * locale, UDisplayContext *contexts, 290 int32_t length, UErrorCode *pErrorCode); 291 292 /** 293 * Returns the UDisplayContext value for the specified UDisplayContextType. 294 * @param ldn the ULocaleDisplayNames instance 295 * @param type the UDisplayContextType whose value to return 296 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates 297 * a failure status, the function will do nothing; otherwise this will be 298 * updated with any new status from the function. 299 * @return the UDisplayContextValue for the specified type. 300 * @stable ICU 51 301 */ 302 U_CAPI UDisplayContext U_EXPORT2 303 uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type, 304 UErrorCode *pErrorCode); 305 306 #endif /* !UCONFIG_NO_FORMATTING */ 307 #endif /* __ULDNAMES_H__ */