1 /* 2 ******************************************************************************* 3 * Copyright (C) 2010, International Business Machines Corporation and * 4 * others. All Rights Reserved. * 5 ******************************************************************************* 6 */ 7 8 #ifndef __ULDNAMES_H__ 9 #define __ULDNAMES_H__ 10 11 /** 12 * \file 13 * \brief C++ API: Provides display names of Locale ids and their components. 14 */ 15 16 #include "unicode/utypes.h" 17 #include "unicode/localpointer.h" 18 #include "unicode/uscript.h" 19 20 /** 21 * Enum used in LocaleDisplayNames::createInstance. 22 * @stable ICU 4.4 23 */ 24 typedef enum { 25 /** 26 * Use standard names when generating a locale name, 27 * e.g. en_GB displays as 'English (United Kingdom)'. 28 * @stable ICU 4.4 29 */ 30 ULDN_STANDARD_NAMES = 0, 31 /** 32 * Use dialect names, when generating a locale name, 33 * e.g. en_GB displays as 'British English'. 34 * @stable ICU 4.4 35 */ 36 ULDN_DIALECT_NAMES 37 } UDialectHandling; 38 39 /** 40 * Opaque C service object type for the locale display names API 41 * @stable ICU 4.4 42 */ 43 struct ULocaleDisplayNames; 44 45 /** 46 * C typedef for struct ULocaleDisplayNames. 47 * @stable ICU 4.4 48 */ 49 typedef struct ULocaleDisplayNames ULocaleDisplayNames; 50 51 #if !UCONFIG_NO_FORMATTING 52 53 /** 54 * Returns an instance of LocaleDisplayNames that returns names 55 * formatted for the provided locale, using the provided 56 * dialectHandling. The usual value for dialectHandling is 57 * ULOC_STANDARD_NAMES. 58 * 59 * @param locale the display locale 60 * @param dialectHandling how to select names for locales 61 * @return a ULocaleDisplayNames instance 62 * @param pErrorCode the status code 63 * @stable ICU 4.4 64 */ 65 U_STABLE ULocaleDisplayNames * U_EXPORT2 66 uldn_open(const char * locale, 67 UDialectHandling dialectHandling, 68 UErrorCode *pErrorCode); 69 70 /** 71 * Closes a ULocaleDisplayNames instance obtained from uldn_open(). 72 * @param ldn the ULocaleDisplayNames instance to be closed 73 * @stable ICU 4.4 74 */ 75 U_STABLE void U_EXPORT2 76 uldn_close(ULocaleDisplayNames *ldn); 77 78 #if U_SHOW_CPLUSPLUS_API 79 80 U_NAMESPACE_BEGIN 81 82 /** 83 * \class LocalULocaleDisplayNamesPointer 84 * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close(). 85 * For most methods see the LocalPointerBase base class. 86 * 87 * @see LocalPointerBase 88 * @see LocalPointer 89 * @stable ICU 4.4 90 */ 91 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close); 92 93 U_NAMESPACE_END 94 95 #endif 96 97 /* getters for state */ 98 99 /** 100 * Returns the locale used to determine the display names. This is 101 * not necessarily the same locale passed to {@link #uldn_open}. 102 * @param ldn the LocaleDisplayNames instance 103 * @return the display locale 104 * @stable ICU 4.4 105 */ 106 U_STABLE const char * U_EXPORT2 107 uldn_getLocale(const ULocaleDisplayNames *ldn); 108 109 /** 110 * Returns the dialect handling used in the display names. 111 * @param ldn the LocaleDisplayNames instance 112 * @return the dialect handling enum 113 * @stable ICU 4.4 114 */ 115 U_STABLE UDialectHandling U_EXPORT2 116 uldn_getDialectHandling(const ULocaleDisplayNames *ldn); 117 118 /* names for entire locales */ 119 120 /** 121 * Returns the display name of the provided locale. 122 * @param ldn the LocaleDisplayNames instance 123 * @param locale the locale whose display name to return 124 * @param result receives the display name 125 * @param maxResultSize the size of the result buffer 126 * @param pErrorCode the status code 127 * @return the actual buffer size needed for the display name. If it's 128 * greater than maxResultSize, the returned name will be truncated. 129 * @stable ICU 4.4 130 */ 131 U_STABLE int32_t U_EXPORT2 132 uldn_localeDisplayName(const ULocaleDisplayNames *ldn, 133 const char *locale, 134 UChar *result, 135 int32_t maxResultSize, 136 UErrorCode *pErrorCode); 137 138 /* names for components of a locale */ 139 140 /** 141 * Returns the display name of the provided language code. 142 * @param ldn the LocaleDisplayNames instance 143 * @param lang the language code whose display name to return 144 * @param result receives the display name 145 * @param maxResultSize the size of the result buffer 146 * @param pErrorCode the status code 147 * @return the actual buffer size needed for the display name. If it's 148 * greater than maxResultSize, the returned name will be truncated. 149 * @stable ICU 4.4 150 */ 151 U_STABLE int32_t U_EXPORT2 152 uldn_languageDisplayName(const ULocaleDisplayNames *ldn, 153 const char *lang, 154 UChar *result, 155 int32_t maxResultSize, 156 UErrorCode *pErrorCode); 157 158 /** 159 * Returns the display name of the provided script. 160 * @param ldn the LocaleDisplayNames instance 161 * @param script the script 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 * @stable ICU 4.4 168 */ 169 U_STABLE int32_t U_EXPORT2 170 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn, 171 const char *script, 172 UChar *result, 173 int32_t maxResultSize, 174 UErrorCode *pErrorCode); 175 176 /** 177 * Returns the display name of the provided script code. 178 * @param ldn the LocaleDisplayNames instance 179 * @param scriptCode the script code 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_STABLE int32_t U_EXPORT2 188 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn, 189 UScriptCode scriptCode, 190 UChar *result, 191 int32_t maxResultSize, 192 UErrorCode *pErrorCode); 193 194 /** 195 * Returns the display name of the provided region code. 196 * @param ldn the LocaleDisplayNames instance 197 * @param region the region code whose display name to return 198 * @param result receives the display name 199 * @param maxResultSize the size of the result buffer 200 * @param pErrorCode the status code 201 * @return the actual buffer size needed for the display name. If it's 202 * greater than maxResultSize, the returned name will be truncated. 203 * @stable ICU 4.4 204 */ 205 U_STABLE int32_t U_EXPORT2 206 uldn_regionDisplayName(const ULocaleDisplayNames *ldn, 207 const char *region, 208 UChar *result, 209 int32_t maxResultSize, 210 UErrorCode *pErrorCode); 211 212 /** 213 * Returns the display name of the provided variant 214 * @param ldn the LocaleDisplayNames instance 215 * @param variant the variant whose display name to return 216 * @param result receives the display name 217 * @param maxResultSize the size of the result buffer 218 * @param pErrorCode the status code 219 * @return the actual buffer size needed for the display name. If it's 220 * greater than maxResultSize, the returned name will be truncated. 221 * @stable ICU 4.4 222 */ 223 U_STABLE int32_t U_EXPORT2 224 uldn_variantDisplayName(const ULocaleDisplayNames *ldn, 225 const char *variant, 226 UChar *result, 227 int32_t maxResultSize, 228 UErrorCode *pErrorCode); 229 230 /** 231 * Returns the display name of the provided locale key 232 * @param ldn the LocaleDisplayNames instance 233 * @param key the locale key whose display name to return 234 * @param result receives the display name 235 * @param maxResultSize the size of the result buffer 236 * @param pErrorCode the status code 237 * @return the actual buffer size needed for the display name. If it's 238 * greater than maxResultSize, the returned name will be truncated. 239 * @stable ICU 4.4 240 */ 241 U_STABLE int32_t U_EXPORT2 242 uldn_keyDisplayName(const ULocaleDisplayNames *ldn, 243 const char *key, 244 UChar *result, 245 int32_t maxResultSize, 246 UErrorCode *pErrorCode); 247 248 /** 249 * Returns the display name of the provided value (used with the provided key). 250 * @param ldn the LocaleDisplayNames instance 251 * @param key the locale key 252 * @param value the locale key's value 253 * @param result receives the display name 254 * @param maxResultSize the size of the result buffer 255 * @param pErrorCode the status code 256 * @return the actual buffer size needed for the display name. If it's 257 * greater than maxResultSize, the returned name will be truncated. 258 * @stable ICU 4.4 259 */ 260 U_STABLE int32_t U_EXPORT2 261 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn, 262 const char *key, 263 const char *value, 264 UChar *result, 265 int32_t maxResultSize, 266 UErrorCode *pErrorCode); 267 268 269 #endif /* !UCONFIG_NO_FORMATTING */ 270 #endif /* __ULDNAMES_H__ */ 271