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/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 */ 27typedef 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 */ 46struct ULocaleDisplayNames; 47 48/** 49 * C typedef for struct ULocaleDisplayNames. 50 * @stable ICU 4.4 51 */ 52typedef 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 */ 68U_STABLE ULocaleDisplayNames * U_EXPORT2 69uldn_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 */ 78U_STABLE void U_EXPORT2 79uldn_close(ULocaleDisplayNames *ldn); 80 81#if U_SHOW_CPLUSPLUS_API 82 83U_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 */ 94U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close); 95 96U_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 */ 109U_STABLE const char * U_EXPORT2 110uldn_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 */ 118U_STABLE UDialectHandling U_EXPORT2 119uldn_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 */ 134U_STABLE int32_t U_EXPORT2 135uldn_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 */ 154U_STABLE int32_t U_EXPORT2 155uldn_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 */ 172U_STABLE int32_t U_EXPORT2 173uldn_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 */ 190U_STABLE int32_t U_EXPORT2 191uldn_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 */ 208U_STABLE int32_t U_EXPORT2 209uldn_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 */ 226U_STABLE int32_t U_EXPORT2 227uldn_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 */ 244U_STABLE int32_t U_EXPORT2 245uldn_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 */ 263U_STABLE int32_t U_EXPORT2 264uldn_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*/ 285U_STABLE ULocaleDisplayNames * U_EXPORT2 286uldn_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*/ 299U_STABLE UDisplayContext U_EXPORT2 300uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type, 301 UErrorCode *pErrorCode); 302 303#endif /* !UCONFIG_NO_FORMATTING */ 304#endif /* __ULDNAMES_H__ */ 305