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