Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/uldnames.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
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__ */