]> git.saurik.com Git - apple/icu.git/blame_incremental - icuSources/common/unicode/uldnames.h
ICU-57131.0.1.tar.gz
[apple/icu.git] / icuSources / common / unicode / uldnames.h
... / ...
CommitLineData
1/*
2*******************************************************************************
3* Copyright (C) 2010-2016, 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#include "unicode/udisplaycontext.h"
20
21/**
22 * Enum used in LocaleDisplayNames::createInstance.
23 * @stable ICU 4.4
24 */
25typedef enum {
26 /**
27 * Use standard names when generating a locale name,
28 * e.g. en_GB displays as 'English (United Kingdom)'.
29 * @stable ICU 4.4
30 */
31 ULDN_STANDARD_NAMES = 0,
32 /**
33 * Use dialect names, when generating a locale name,
34 * e.g. en_GB displays as 'British English'.
35 * @stable ICU 4.4
36 */
37 ULDN_DIALECT_NAMES
38} UDialectHandling;
39
40/**
41 * Opaque C service object type for the locale display names API
42 * @stable ICU 4.4
43 */
44struct ULocaleDisplayNames;
45
46/**
47 * C typedef for struct ULocaleDisplayNames.
48 * @stable ICU 4.4
49 */
50typedef struct ULocaleDisplayNames ULocaleDisplayNames;
51
52#if !UCONFIG_NO_FORMATTING
53
54/**
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.
59 *
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
64 * @stable ICU 4.4
65 */
66U_STABLE ULocaleDisplayNames * U_EXPORT2
67uldn_open(const char * locale,
68 UDialectHandling dialectHandling,
69 UErrorCode *pErrorCode);
70
71/**
72 * Closes a ULocaleDisplayNames instance obtained from uldn_open().
73 * @param ldn the ULocaleDisplayNames instance to be closed
74 * @stable ICU 4.4
75 */
76U_STABLE void U_EXPORT2
77uldn_close(ULocaleDisplayNames *ldn);
78
79#if U_SHOW_CPLUSPLUS_API
80
81U_NAMESPACE_BEGIN
82
83/**
84 * \class LocalULocaleDisplayNamesPointer
85 * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close().
86 * For most methods see the LocalPointerBase base class.
87 *
88 * @see LocalPointerBase
89 * @see LocalPointer
90 * @stable ICU 4.4
91 */
92U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close);
93
94U_NAMESPACE_END
95
96#endif
97
98/* getters for state */
99
100/**
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
105 * @stable ICU 4.4
106 */
107U_STABLE const char * U_EXPORT2
108uldn_getLocale(const ULocaleDisplayNames *ldn);
109
110/**
111 * Returns the dialect handling used in the display names.
112 * @param ldn the LocaleDisplayNames instance
113 * @return the dialect handling enum
114 * @stable ICU 4.4
115 */
116U_STABLE UDialectHandling U_EXPORT2
117uldn_getDialectHandling(const ULocaleDisplayNames *ldn);
118
119/* names for entire locales */
120
121/**
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.
130 * @stable ICU 4.4
131 */
132U_STABLE int32_t U_EXPORT2
133uldn_localeDisplayName(const ULocaleDisplayNames *ldn,
134 const char *locale,
135 UChar *result,
136 int32_t maxResultSize,
137 UErrorCode *pErrorCode);
138
139/* names for components of a locale */
140
141/**
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.
150 * @stable ICU 4.4
151 */
152U_STABLE int32_t U_EXPORT2
153uldn_languageDisplayName(const ULocaleDisplayNames *ldn,
154 const char *lang,
155 UChar *result,
156 int32_t maxResultSize,
157 UErrorCode *pErrorCode);
158
159/**
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.
168 * @stable ICU 4.4
169 */
170U_STABLE int32_t U_EXPORT2
171uldn_scriptDisplayName(const ULocaleDisplayNames *ldn,
172 const char *script,
173 UChar *result,
174 int32_t maxResultSize,
175 UErrorCode *pErrorCode);
176
177/**
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.
186 * @stable ICU 4.4
187 */
188U_STABLE int32_t U_EXPORT2
189uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn,
190 UScriptCode scriptCode,
191 UChar *result,
192 int32_t maxResultSize,
193 UErrorCode *pErrorCode);
194
195/**
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.
204 * @stable ICU 4.4
205 */
206U_STABLE int32_t U_EXPORT2
207uldn_regionDisplayName(const ULocaleDisplayNames *ldn,
208 const char *region,
209 UChar *result,
210 int32_t maxResultSize,
211 UErrorCode *pErrorCode);
212
213/**
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.
222 * @stable ICU 4.4
223 */
224U_STABLE int32_t U_EXPORT2
225uldn_variantDisplayName(const ULocaleDisplayNames *ldn,
226 const char *variant,
227 UChar *result,
228 int32_t maxResultSize,
229 UErrorCode *pErrorCode);
230
231/**
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.
240 * @stable ICU 4.4
241 */
242U_STABLE int32_t U_EXPORT2
243uldn_keyDisplayName(const ULocaleDisplayNames *ldn,
244 const char *key,
245 UChar *result,
246 int32_t maxResultSize,
247 UErrorCode *pErrorCode);
248
249/**
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.
259 * @stable ICU 4.4
260 */
261U_STABLE int32_t U_EXPORT2
262uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn,
263 const char *key,
264 const char *value,
265 UChar *result,
266 int32_t maxResultSize,
267 UErrorCode *pErrorCode);
268
269/**
270* Returns an instance of LocaleDisplayNames that returns names formatted
271* for the provided locale, using the provided UDisplayContext settings.
272*
273* @param locale The display locale
274* @param contexts List of one or more context settings (e.g. for dialect
275* handling, capitalization, etc.
276* @param length Number of items in the contexts list
277* @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
278* a failure status, the function will do nothing; otherwise this will be
279* updated with any new status from the function.
280* @return a ULocaleDisplayNames instance
281* @stable ICU 51
282*/
283U_STABLE ULocaleDisplayNames * U_EXPORT2
284uldn_openForContext(const char * locale, UDisplayContext *contexts,
285 int32_t length, UErrorCode *pErrorCode);
286
287/**
288* Returns the UDisplayContext value for the specified UDisplayContextType.
289* @param ldn the ULocaleDisplayNames instance
290* @param type the UDisplayContextType whose value to return
291* @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
292* a failure status, the function will do nothing; otherwise this will be
293* updated with any new status from the function.
294* @return the UDisplayContextValue for the specified type.
295* @stable ICU 51
296*/
297U_STABLE UDisplayContext U_EXPORT2
298uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type,
299 UErrorCode *pErrorCode);
300
301#endif /* !UCONFIG_NO_FORMATTING */
302#endif /* __ULDNAMES_H__ */