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);
75 
76 /**
77  * Closes a ULocaleDisplayNames instance obtained from uldn_open().
78  * @param ldn the ULocaleDisplayNames instance to be closed
79  * @stable ICU 4.4
80  */
81 U_CAPI void U_EXPORT2
82 uldn_close(ULocaleDisplayNames *ldn);
83 
84 #if U_SHOW_CPLUSPLUS_API
85 
86 U_NAMESPACE_BEGIN
87 
88 /**
89  * \class LocalULocaleDisplayNamesPointer
90  * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close().
91  * For most methods see the LocalPointerBase base class.
92  *
93  * @see LocalPointerBase
94  * @see LocalPointer
95  * @stable ICU 4.4
96  */
97 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close);
98 
99 U_NAMESPACE_END
100 
101 #endif
102 
103 /* getters for state */
104 
105 /**
106  * Returns the locale used to determine the display names. This is
107  * not necessarily the same locale passed to {@link #uldn_open}.
108  * @param ldn the LocaleDisplayNames instance
109  * @return the display locale
110  * @stable ICU 4.4
111  */
112 U_CAPI const char * U_EXPORT2
113 uldn_getLocale(const ULocaleDisplayNames *ldn);
114 
115 /**
116  * Returns the dialect handling used in the display names.
117  * @param ldn the LocaleDisplayNames instance
118  * @return the dialect handling enum
119  * @stable ICU 4.4
120  */
121 U_CAPI UDialectHandling U_EXPORT2
122 uldn_getDialectHandling(const ULocaleDisplayNames *ldn);
123 
124 /* names for entire locales */
125 
126 /**
127  * Returns the display name of the provided locale.
128  * @param ldn the LocaleDisplayNames instance
129  * @param locale the locale whose display name to return
130  * @param result receives the display name
131  * @param maxResultSize the size of the result buffer
132  * @param pErrorCode the status code
133  * @return the actual buffer size needed for the display name.  If it's
134  * greater than maxResultSize, the returned name will be truncated.
135  * @stable ICU 4.4
136  */
137 U_CAPI int32_t U_EXPORT2
138 uldn_localeDisplayName(const ULocaleDisplayNames *ldn,
139                        const char *locale,
140                        UChar *result,
141                        int32_t maxResultSize,
142                        UErrorCode *pErrorCode);
143 
144 /* names for components of a locale */
145 
146 /**
147  * Returns the display name of the provided language code.
148  * @param ldn the LocaleDisplayNames instance
149  * @param lang the language code whose display name to return
150  * @param result receives the display name
151  * @param maxResultSize the size of the result buffer
152  * @param pErrorCode the status code
153  * @return the actual buffer size needed for the display name.  If it's
154  * greater than maxResultSize, the returned name will be truncated.
155  * @stable ICU 4.4
156  */
157 U_CAPI int32_t U_EXPORT2
158 uldn_languageDisplayName(const ULocaleDisplayNames *ldn,
159                          const char *lang,
160                          UChar *result,
161                          int32_t maxResultSize,
162                          UErrorCode *pErrorCode);
163 
164 /**
165  * Returns the display name of the provided script.
166  * @param ldn the LocaleDisplayNames instance
167  * @param script the script whose display name to return
168  * @param result receives the display name
169  * @param maxResultSize the size of the result buffer
170  * @param pErrorCode the status code
171  * @return the actual buffer size needed for the display name.  If it's
172  * greater than maxResultSize, the returned name will be truncated.
173  * @stable ICU 4.4
174  */
175 U_CAPI int32_t U_EXPORT2
176 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn,
177                        const char *script,
178                        UChar *result,
179                        int32_t maxResultSize,
180                        UErrorCode *pErrorCode);
181 
182 /**
183  * Returns the display name of the provided script code.
184  * @param ldn the LocaleDisplayNames instance
185  * @param scriptCode the script code whose display name to return
186  * @param result receives the display name
187  * @param maxResultSize the size of the result buffer
188  * @param pErrorCode the status code
189  * @return the actual buffer size needed for the display name.  If it's
190  * greater than maxResultSize, the returned name will be truncated.
191  * @stable ICU 4.4
192  */
193 U_CAPI int32_t U_EXPORT2
194 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn,
195                            UScriptCode scriptCode,
196                            UChar *result,
197                            int32_t maxResultSize,
198                            UErrorCode *pErrorCode);
199 
200 /**
201  * Returns the display name of the provided region code.
202  * @param ldn the LocaleDisplayNames instance
203  * @param region the region code whose display name to return
204  * @param result receives the display name
205  * @param maxResultSize the size of the result buffer
206  * @param pErrorCode the status code
207  * @return the actual buffer size needed for the display name.  If it's
208  * greater than maxResultSize, the returned name will be truncated.
209  * @stable ICU 4.4
210  */
211 U_CAPI int32_t U_EXPORT2
212 uldn_regionDisplayName(const ULocaleDisplayNames *ldn,
213                        const char *region,
214                        UChar *result,
215                        int32_t maxResultSize,
216                        UErrorCode *pErrorCode);
217 
218 /**
219  * Returns the display name of the provided variant
220  * @param ldn the LocaleDisplayNames instance
221  * @param variant the variant whose display name to return
222  * @param result receives the display name
223  * @param maxResultSize the size of the result buffer
224  * @param pErrorCode the status code
225  * @return the actual buffer size needed for the display name.  If it's
226  * greater than maxResultSize, the returned name will be truncated.
227  * @stable ICU 4.4
228  */
229 U_CAPI int32_t U_EXPORT2
230 uldn_variantDisplayName(const ULocaleDisplayNames *ldn,
231                         const char *variant,
232                         UChar *result,
233                         int32_t maxResultSize,
234                         UErrorCode *pErrorCode);
235 
236 /**
237  * Returns the display name of the provided locale key
238  * @param ldn the LocaleDisplayNames instance
239  * @param key the locale key 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_keyDisplayName(const ULocaleDisplayNames *ldn,
249                     const char *key,
250                     UChar *result,
251                     int32_t maxResultSize,
252                     UErrorCode *pErrorCode);
253 
254 /**
255  * Returns the display name of the provided value (used with the provided key).
256  * @param ldn the LocaleDisplayNames instance
257  * @param key the locale key
258  * @param value the locale key's value
259  * @param result receives the display name
260  * @param maxResultSize the size of the result buffer
261  * @param pErrorCode the status code
262  * @return the actual buffer size needed for the display name.  If it's
263  * greater than maxResultSize, the returned name will be truncated.
264  * @stable ICU 4.4
265  */
266 U_CAPI int32_t U_EXPORT2
267 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn,
268                          const char *key,
269                          const char *value,
270                          UChar *result,
271                          int32_t maxResultSize,
272                          UErrorCode *pErrorCode);
273 
274 /**
275 * Returns an instance of LocaleDisplayNames that returns names formatted
276 * for the provided locale, using the provided UDisplayContext settings.
277 *
278 * @param locale The display locale
279 * @param contexts List of one or more context settings (e.g. for dialect
280 *               handling, capitalization, etc.
281 * @param length Number of items in the contexts list
282 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
283 *               a failure status, the function will do nothing; otherwise this will be
284 *               updated with any new status from the function.
285 * @return a ULocaleDisplayNames instance
286 * @stable ICU 51
287 */
288 U_CAPI ULocaleDisplayNames * U_EXPORT2
289 uldn_openForContext(const char * locale, UDisplayContext *contexts,
290                     int32_t length, UErrorCode *pErrorCode);
291 
292 /**
293 * Returns the UDisplayContext value for the specified UDisplayContextType.
294 * @param ldn the ULocaleDisplayNames instance
295 * @param type the UDisplayContextType whose value to return
296 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
297 *               a failure status, the function will do nothing; otherwise this will be
298 *               updated with any new status from the function.
299 * @return the UDisplayContextValue for the specified type.
300 * @stable ICU 51
301 */
302 U_CAPI UDisplayContext U_EXPORT2
303 uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type,
304                 UErrorCode *pErrorCode);
305 
306 #endif  /* !UCONFIG_NO_FORMATTING */
307 #endif  /* __ULDNAMES_H__ */
308