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