[apple/icu.git] / icuSources / common / unicode / ucasemap.h

/*
*******************************************************************************
*
*   Copyright (C) 2005, International Business Machines
*   Corporation and others.  All Rights Reserved.
*
*******************************************************************************
*   file name:  ucasemap.h
*   encoding:   US-ASCII
*   tab size:   8 (not used)
*   indentation:4
*
*   created on: 2005may06
*   created by: Markus W. Scherer
*
*   Case mapping service object and functions using it.
*/

#ifndef __UCASEMAP_H__
#define __UCASEMAP_H__

#include "unicode/utypes.h"
#include "unicode/ustring.h"

/**
 * \file
 * \brief C API: Unicode case mapping functions using a UCaseMap service object.
 *
 * The service object takes care of memory allocations, data loading, and setup
 * for the attributes, as usual.
 *
 * Currently, the functionality provided here does not overlap with uchar.h
 * and ustring.h.
 *
 * ucasemap_utf8ToLower() and ucasemap_utf8ToUpper() operate directly on
 * UTF-8 strings.
 */

/**
 * UCaseMap is an opaque service object for newer ICU case mapping functions.
 * Older functions did not use a service object.
 * @draft ICU 3.4
 */
struct UCaseMap;
typedef struct UCaseMap UCaseMap; /**< C typedef for struct UCaseMap. @draft ICU 3.4 */

/**
 * Open a UCaseMap service object for a locale and a set of options.
 * The locale ID and options are preprocessed so that functions using the
 * service object need not process them in each call.
 *
 * @param locale ICU locale ID, used for language-dependent
 *               upper-/lower-/title-casing according to the Unicode standard.
 *               Usual semantics: ""=root, NULL=default locale, etc.
 * @param options Options bit set, used for case folding and string comparisons.
 *                Same flags as for u_foldCase(), u_strFoldCase(),
 *                u_strCaseCompare(), etc.
 *                Use 0 or U_FOLD_CASE_DEFAULT for default behavior.
 * @param pErrorCode Must be a valid pointer to an error code value,
 *                   which must not indicate a failure before the function call.
 * @return Pointer to a UCaseMap service object, if successful.
 *
 * @draft ICU 3.4
 */
U_DRAFT UCaseMap * U_EXPORT2
ucasemap_open(const char *locale, uint32_t options, UErrorCode *pErrorCode);

/**
 * Close a UCaseMap service object.
 * @param csm Object to be closed.
 * @draft ICU 3.4
 */
U_DRAFT void U_EXPORT2
ucasemap_close(UCaseMap *csm);

/**
 * Get the locale ID that is used for language-dependent case mappings.
 * @param csm UCaseMap service object.
 * @return locale ID
 * @draft ICU 3.4
 */
U_DRAFT const char * U_EXPORT2
ucasemap_getLocale(const UCaseMap *csm);

/**
 * Get the options bit set that is used for case folding and string comparisons.
 * @param csm UCaseMap service object.
 * @return options bit set
 * @draft ICU 3.4
 */
U_DRAFT uint32_t U_EXPORT2
ucasemap_getOptions(const UCaseMap *csm);

/**
 * Set the locale ID that is used for language-dependent case mappings.
 *
 * @param csm UCaseMap service object.
 * @param locale Locale ID, see ucasemap_open().
 * @param pErrorCode Must be a valid pointer to an error code value,
 *                   which must not indicate a failure before the function call.
 *
 * @see ucasemap_open
 * @draft ICU 3.4
 */
U_DRAFT void U_EXPORT2
ucasemap_setLocale(UCaseMap *csm, const char *locale, UErrorCode *pErrorCode);

/**
 * Set the options bit set that is used for case folding and string comparisons.
 *
 * @param csm UCaseMap service object.
 * @param options Options bit set, see ucasemap_open().
 * @param pErrorCode Must be a valid pointer to an error code value,
 *                   which must not indicate a failure before the function call.
 *
 * @see ucasemap_open
 * @draft ICU 3.4
 */
U_DRAFT void U_EXPORT2
ucasemap_setOptions(UCaseMap *csm, uint32_t options, UErrorCode *pErrorCode);

/**
 * Lowercase the characters in a UTF-8 string.
 * Casing is locale-dependent and context-sensitive.
 * The result may be longer or shorter than the original.
 * The source string and the destination buffer must not overlap.
 *
 * @param csm       UCaseMap service object.
 * @param dest      A buffer for the result string. The result will be NUL-terminated if
 *                  the buffer is large enough.
 *                  The contents is undefined in case of failure.
 * @param destCapacity The size of the buffer (number of bytes). If it is 0, then
 *                  dest may be NULL and the function will only return the length of the result
 *                  without writing any of the result string.
 * @param src       The original string
 * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
 * @param pErrorCode Must be a valid pointer to an error code value,
 *                  which must not indicate a failure before the function call.
 * @return The length of the result string, if successful - or in case of a buffer overflow,
 *         in which case it will be greater than destCapacity.
 *
 * @see u_strToLower
 * @draft ICU 3.4
 */
U_DRAFT int32_t U_EXPORT2
ucasemap_utf8ToLower(const UCaseMap *csm,
                     char *dest, int32_t destCapacity,
                     const char *src, int32_t srcLength,
                     UErrorCode *pErrorCode);

/**
 * Uppercase the characters in a UTF-8 string.
 * Casing is locale-dependent and context-sensitive.
 * The result may be longer or shorter than the original.
 * The source string and the destination buffer must not overlap.
 *
 * @param csm       UCaseMap service object.
 * @param dest      A buffer for the result string. The result will be NUL-terminated if
 *                  the buffer is large enough.
 *                  The contents is undefined in case of failure.
 * @param destCapacity The size of the buffer (number of bytes). If it is 0, then
 *                  dest may be NULL and the function will only return the length of the result
 *                  without writing any of the result string.
 * @param src       The original string
 * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
 * @param pErrorCode Must be a valid pointer to an error code value,
 *                  which must not indicate a failure before the function call.
 * @return The length of the result string, if successful - or in case of a buffer overflow,
 *         in which case it will be greater than destCapacity.
 *
 * @see u_strToUpper
 * @draft ICU 3.4
 */
U_DRAFT int32_t U_EXPORT2
ucasemap_utf8ToUpper(const UCaseMap *csm,
                     char *dest, int32_t destCapacity,
                     const char *src, int32_t srcLength,
                     UErrorCode *pErrorCode);

#endif
Commit	Line	Data
73c04bcf A	1	/*
	2	*******************************************************************************
	3	*
	4	* Copyright (C) 2005, International Business Machines
	5	* Corporation and others. All Rights Reserved.
	6	*
	7	*******************************************************************************
	8	* file name: ucasemap.h
	9	* encoding: US-ASCII
	10	* tab size: 8 (not used)
	11	* indentation:4
	12	*
	13	* created on: 2005may06
	14	* created by: Markus W. Scherer
	15	*
	16	* Case mapping service object and functions using it.
	17	*/
	18
	19	#ifndef __UCASEMAP_H__
	20	#define __UCASEMAP_H__
	21
	22	#include "unicode/utypes.h"
	23	#include "unicode/ustring.h"
	24
	25	/**
	26	* \file
	27	* \brief C API: Unicode case mapping functions using a UCaseMap service object.
	28	*
	29	* The service object takes care of memory allocations, data loading, and setup
	30	* for the attributes, as usual.
	31	*
	32	* Currently, the functionality provided here does not overlap with uchar.h
	33	* and ustring.h.
	34	*
	35	* ucasemap_utf8ToLower() and ucasemap_utf8ToUpper() operate directly on
	36	* UTF-8 strings.
	37	*/
	38
	39	/**
	40	* UCaseMap is an opaque service object for newer ICU case mapping functions.
	41	* Older functions did not use a service object.
	42	* @draft ICU 3.4
	43	*/
	44	struct UCaseMap;
	45	typedef struct UCaseMap UCaseMap; /*< C typedef for struct UCaseMap. @draft ICU 3.4 /
	46
	47	/**
	48	* Open a UCaseMap service object for a locale and a set of options.
	49	* The locale ID and options are preprocessed so that functions using the
	50	* service object need not process them in each call.
	51	*
	52	* @param locale ICU locale ID, used for language-dependent
	53	* upper-/lower-/title-casing according to the Unicode standard.
	54	* Usual semantics: ""=root, NULL=default locale, etc.
	55	* @param options Options bit set, used for case folding and string comparisons.
	56	* Same flags as for u_foldCase(), u_strFoldCase(),
	57	* u_strCaseCompare(), etc.
	58	* Use 0 or U_FOLD_CASE_DEFAULT for default behavior.
	59	* @param pErrorCode Must be a valid pointer to an error code value,
	60	* which must not indicate a failure before the function call.
	61	* @return Pointer to a UCaseMap service object, if successful.
	62	*
	63	* @draft ICU 3.4
	64	*/
65	U_DRAFT UCaseMap * U_EXPORT2
66	ucasemap_open(const char locale, uint32_t options, UErrorCode pErrorCode);
67
68	/**
69	* Close a UCaseMap service object.
70	* @param csm Object to be closed.
71	* @draft ICU 3.4
72	*/
73	U_DRAFT void U_EXPORT2
74	ucasemap_close(UCaseMap *csm);
75
76	/**
77	* Get the locale ID that is used for language-dependent case mappings.
78	* @param csm UCaseMap service object.
79	* @return locale ID
80	* @draft ICU 3.4
81	*/
82	U_DRAFT const char * U_EXPORT2
83	ucasemap_getLocale(const UCaseMap *csm);
84
85	/**
86	* Get the options bit set that is used for case folding and string comparisons.
87	* @param csm UCaseMap service object.
88	* @return options bit set
89	* @draft ICU 3.4
90	*/
91	U_DRAFT uint32_t U_EXPORT2
92	ucasemap_getOptions(const UCaseMap *csm);
93
94	/**
95	* Set the locale ID that is used for language-dependent case mappings.
96	*
97	* @param csm UCaseMap service object.
98	* @param locale Locale ID, see ucasemap_open().
99	* @param pErrorCode Must be a valid pointer to an error code value,
100	* which must not indicate a failure before the function call.
101	*
102	* @see ucasemap_open
103	* @draft ICU 3.4
104	*/
105	U_DRAFT void U_EXPORT2
106	ucasemap_setLocale(UCaseMap csm, const char locale, UErrorCode *pErrorCode);
107
108	/**
109	* Set the options bit set that is used for case folding and string comparisons.
110	*
111	* @param csm UCaseMap service object.
112	* @param options Options bit set, see ucasemap_open().
113	* @param pErrorCode Must be a valid pointer to an error code value,
114	* which must not indicate a failure before the function call.
115	*
116	* @see ucasemap_open
117	* @draft ICU 3.4
118	*/
119	U_DRAFT void U_EXPORT2
120	ucasemap_setOptions(UCaseMap csm, uint32_t options, UErrorCode pErrorCode);
121
122	/**
123	* Lowercase the characters in a UTF-8 string.
124	* Casing is locale-dependent and context-sensitive.
125	* The result may be longer or shorter than the original.
126	* The source string and the destination buffer must not overlap.
127	*
128	* @param csm UCaseMap service object.
129	* @param dest A buffer for the result string. The result will be NUL-terminated if
130	* the buffer is large enough.
131	* The contents is undefined in case of failure.
132	* @param destCapacity The size of the buffer (number of bytes). If it is 0, then
133	* dest may be NULL and the function will only return the length of the result
134	* without writing any of the result string.
135	* @param src The original string
136	* @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
137	* @param pErrorCode Must be a valid pointer to an error code value,
138	* which must not indicate a failure before the function call.
139	* @return The length of the result string, if successful - or in case of a buffer overflow,
140	* in which case it will be greater than destCapacity.
141	*
142	* @see u_strToLower
143	* @draft ICU 3.4
144	*/
145	U_DRAFT int32_t U_EXPORT2
146	ucasemap_utf8ToLower(const UCaseMap *csm,
147	char *dest, int32_t destCapacity,
148	const char *src, int32_t srcLength,
149	UErrorCode *pErrorCode);
150
151	/**
152	* Uppercase the characters in a UTF-8 string.
153	* Casing is locale-dependent and context-sensitive.
154	* The result may be longer or shorter than the original.
155	* The source string and the destination buffer must not overlap.
156	*
157	* @param csm UCaseMap service object.
158	* @param dest A buffer for the result string. The result will be NUL-terminated if
159	* the buffer is large enough.
160	* The contents is undefined in case of failure.
161	* @param destCapacity The size of the buffer (number of bytes). If it is 0, then
162	* dest may be NULL and the function will only return the length of the result
163	* without writing any of the result string.
164	* @param src The original string
165	* @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
166	* @param pErrorCode Must be a valid pointer to an error code value,
167	* which must not indicate a failure before the function call.
168	* @return The length of the result string, if successful - or in case of a buffer overflow,
169	* in which case it will be greater than destCapacity.
170	*
171	* @see u_strToUpper
172	* @draft ICU 3.4
173	*/
174	U_DRAFT int32_t U_EXPORT2
175	ucasemap_utf8ToUpper(const UCaseMap *csm,
176	char *dest, int32_t destCapacity,
177	const char *src, int32_t srcLength,
178	UErrorCode *pErrorCode);
179
180	#endif