[apple/icu.git] / icuSources / i18n / unicode / uldnames.h

/*
*******************************************************************************
*   Copyright (C) 2010-2012, 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/localpointer.h"
#include "unicode/uscript.h"
#include "unicode/udisplaycontext.h"

/**
 * 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE int32_t U_EXPORT2
uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn,
                         const char *key,
                         const char *value,
                         UChar *result,
                         int32_t maxResultSize,
                         UErrorCode *pErrorCode);

#ifndef U_HIDE_DRAFT_API
/**
* 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 
* @draft ICU 51
*/
U_DRAFT 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.
* @draft ICU 51
*/
U_DRAFT UDisplayContext U_EXPORT2
uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type,
                UErrorCode *pErrorCode);

#endif  /* U_HIDE_DRAFT_API */

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