2 *******************************************************************************
3 * Copyright (C) 2010-2012, International Business Machines Corporation and *
4 * others. All Rights Reserved. *
5 *******************************************************************************
13 * \brief C API: Provides display names of Locale ids and their components.
16 #include "unicode/utypes.h"
17 #include "unicode/localpointer.h"
18 #include "unicode/uscript.h"
19 #include "unicode/udisplaycontext.h"
22 * Enum used in LocaleDisplayNames::createInstance.
27 * Use standard names when generating a locale name,
28 * e.g. en_GB displays as 'English (United Kingdom)'.
31 ULDN_STANDARD_NAMES = 0,
33 * Use dialect names, when generating a locale name,
34 * e.g. en_GB displays as 'British English'.
41 * Opaque C service object type for the locale display names API
44 struct ULocaleDisplayNames;
47 * C typedef for struct ULocaleDisplayNames.
50 typedef struct ULocaleDisplayNames ULocaleDisplayNames;
52 #if !UCONFIG_NO_FORMATTING
55 * Returns an instance of LocaleDisplayNames that returns names
56 * formatted for the provided locale, using the provided
57 * dialectHandling. The usual value for dialectHandling is
58 * ULOC_STANDARD_NAMES.
60 * @param locale the display locale
61 * @param dialectHandling how to select names for locales
62 * @return a ULocaleDisplayNames instance
63 * @param pErrorCode the status code
66 U_STABLE ULocaleDisplayNames * U_EXPORT2
67 uldn_open(const char * locale,
68 UDialectHandling dialectHandling,
69 UErrorCode *pErrorCode);
72 * Closes a ULocaleDisplayNames instance obtained from uldn_open().
73 * @param ldn the ULocaleDisplayNames instance to be closed
76 U_STABLE void U_EXPORT2
77 uldn_close(ULocaleDisplayNames *ldn);
79 #if U_SHOW_CPLUSPLUS_API
84 * \class LocalULocaleDisplayNamesPointer
85 * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close().
86 * For most methods see the LocalPointerBase base class.
88 * @see LocalPointerBase
92 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close);
98 /* getters for state */
101 * Returns the locale used to determine the display names. This is
102 * not necessarily the same locale passed to {@link #uldn_open}.
103 * @param ldn the LocaleDisplayNames instance
104 * @return the display locale
107 U_STABLE const char * U_EXPORT2
108 uldn_getLocale(const ULocaleDisplayNames *ldn);
111 * Returns the dialect handling used in the display names.
112 * @param ldn the LocaleDisplayNames instance
113 * @return the dialect handling enum
116 U_STABLE UDialectHandling U_EXPORT2
117 uldn_getDialectHandling(const ULocaleDisplayNames *ldn);
119 /* names for entire locales */
122 * Returns the display name of the provided locale.
123 * @param ldn the LocaleDisplayNames instance
124 * @param locale the locale whose display name to return
125 * @param result receives the display name
126 * @param maxResultSize the size of the result buffer
127 * @param pErrorCode the status code
128 * @return the actual buffer size needed for the display name. If it's
129 * greater than maxResultSize, the returned name will be truncated.
132 U_STABLE int32_t U_EXPORT2
133 uldn_localeDisplayName(const ULocaleDisplayNames *ldn,
136 int32_t maxResultSize,
137 UErrorCode *pErrorCode);
139 /* names for components of a locale */
142 * Returns the display name of the provided language code.
143 * @param ldn the LocaleDisplayNames instance
144 * @param lang the language code whose display name to return
145 * @param result receives the display name
146 * @param maxResultSize the size of the result buffer
147 * @param pErrorCode the status code
148 * @return the actual buffer size needed for the display name. If it's
149 * greater than maxResultSize, the returned name will be truncated.
152 U_STABLE int32_t U_EXPORT2
153 uldn_languageDisplayName(const ULocaleDisplayNames *ldn,
156 int32_t maxResultSize,
157 UErrorCode *pErrorCode);
160 * Returns the display name of the provided script.
161 * @param ldn the LocaleDisplayNames instance
162 * @param script the script whose display name to return
163 * @param result receives the display name
164 * @param maxResultSize the size of the result buffer
165 * @param pErrorCode the status code
166 * @return the actual buffer size needed for the display name. If it's
167 * greater than maxResultSize, the returned name will be truncated.
170 U_STABLE int32_t U_EXPORT2
171 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn,
174 int32_t maxResultSize,
175 UErrorCode *pErrorCode);
178 * Returns the display name of the provided script code.
179 * @param ldn the LocaleDisplayNames instance
180 * @param scriptCode the script code whose display name to return
181 * @param result receives the display name
182 * @param maxResultSize the size of the result buffer
183 * @param pErrorCode the status code
184 * @return the actual buffer size needed for the display name. If it's
185 * greater than maxResultSize, the returned name will be truncated.
188 U_STABLE int32_t U_EXPORT2
189 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn,
190 UScriptCode scriptCode,
192 int32_t maxResultSize,
193 UErrorCode *pErrorCode);
196 * Returns the display name of the provided region code.
197 * @param ldn the LocaleDisplayNames instance
198 * @param region the region code whose display name to return
199 * @param result receives the display name
200 * @param maxResultSize the size of the result buffer
201 * @param pErrorCode the status code
202 * @return the actual buffer size needed for the display name. If it's
203 * greater than maxResultSize, the returned name will be truncated.
206 U_STABLE int32_t U_EXPORT2
207 uldn_regionDisplayName(const ULocaleDisplayNames *ldn,
210 int32_t maxResultSize,
211 UErrorCode *pErrorCode);
214 * Returns the display name of the provided variant
215 * @param ldn the LocaleDisplayNames instance
216 * @param variant the variant whose display name to return
217 * @param result receives the display name
218 * @param maxResultSize the size of the result buffer
219 * @param pErrorCode the status code
220 * @return the actual buffer size needed for the display name. If it's
221 * greater than maxResultSize, the returned name will be truncated.
224 U_STABLE int32_t U_EXPORT2
225 uldn_variantDisplayName(const ULocaleDisplayNames *ldn,
228 int32_t maxResultSize,
229 UErrorCode *pErrorCode);
232 * Returns the display name of the provided locale key
233 * @param ldn the LocaleDisplayNames instance
234 * @param key the locale key whose display name to return
235 * @param result receives the display name
236 * @param maxResultSize the size of the result buffer
237 * @param pErrorCode the status code
238 * @return the actual buffer size needed for the display name. If it's
239 * greater than maxResultSize, the returned name will be truncated.
242 U_STABLE int32_t U_EXPORT2
243 uldn_keyDisplayName(const ULocaleDisplayNames *ldn,
246 int32_t maxResultSize,
247 UErrorCode *pErrorCode);
250 * Returns the display name of the provided value (used with the provided key).
251 * @param ldn the LocaleDisplayNames instance
252 * @param key the locale key
253 * @param value the locale key's value
254 * @param result receives the display name
255 * @param maxResultSize the size of the result buffer
256 * @param pErrorCode the status code
257 * @return the actual buffer size needed for the display name. If it's
258 * greater than maxResultSize, the returned name will be truncated.
261 U_STABLE int32_t U_EXPORT2
262 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn,
266 int32_t maxResultSize,
267 UErrorCode *pErrorCode);
269 #ifndef U_HIDE_DRAFT_API
271 * Returns an instance of LocaleDisplayNames that returns names formatted
272 * for the provided locale, using the provided UDisplayContext settings.
274 * @param locale The display locale
275 * @param contexts List of one or more context settings (e.g. for dialect
276 * handling, capitalization, etc.
277 * @param length Number of items in the contexts list
278 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
279 * a failure status, the function will do nothing; otherwise this will be
280 * updated with any new status from the function.
281 * @return a ULocaleDisplayNames instance
284 U_DRAFT ULocaleDisplayNames * U_EXPORT2
285 uldn_openForContext(const char * locale, UDisplayContext *contexts,
286 int32_t length, UErrorCode *pErrorCode);
289 * Returns the UDisplayContext value for the specified UDisplayContextType.
290 * @param ldn the ULocaleDisplayNames instance
291 * @param type the UDisplayContextType whose value to return
292 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
293 * a failure status, the function will do nothing; otherwise this will be
294 * updated with any new status from the function.
295 * @return the UDisplayContextValue for the specified type.
298 U_DRAFT UDisplayContext U_EXPORT2
299 uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type,
300 UErrorCode *pErrorCode);
302 #endif /* U_HIDE_DRAFT_API */
304 #endif /* !UCONFIG_NO_FORMATTING */
305 #endif /* __ULDNAMES_H__ */