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