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