ICU-59173.0.1.tar.gz
[apple/icu.git] / icuSources / common / unicode / ucasemap.h
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 *
6 * Copyright (C) 2005-2012, International Business Machines
7 * Corporation and others. All Rights Reserved.
8 *
9 *******************************************************************************
10 * file name: ucasemap.h
11 * encoding: UTF-8
12 * tab size: 8 (not used)
13 * indentation:4
14 *
15 * created on: 2005may06
16 * created by: Markus W. Scherer
17 *
18 * Case mapping service object and functions using it.
19 */
20
21 #ifndef __UCASEMAP_H__
22 #define __UCASEMAP_H__
23
24 #include "unicode/utypes.h"
25 #include "unicode/localpointer.h"
26 #include "unicode/ustring.h"
27
28 /**
29 * \file
30 * \brief C API: Unicode case mapping functions using a UCaseMap service object.
31 *
32 * The service object takes care of memory allocations, data loading, and setup
33 * for the attributes, as usual.
34 *
35 * Currently, the functionality provided here does not overlap with uchar.h
36 * and ustring.h, except for ucasemap_toTitle().
37 *
38 * ucasemap_utf8XYZ() functions operate directly on UTF-8 strings.
39 */
40
41 /**
42 * UCaseMap is an opaque service object for newer ICU case mapping functions.
43 * Older functions did not use a service object.
44 * @stable ICU 3.4
45 */
46 struct UCaseMap;
47 typedef struct UCaseMap UCaseMap; /**< C typedef for struct UCaseMap. @stable ICU 3.4 */
48
49 /**
50 * Open a UCaseMap service object for a locale and a set of options.
51 * The locale ID and options are preprocessed so that functions using the
52 * service object need not process them in each call.
53 *
54 * @param locale ICU locale ID, used for language-dependent
55 * upper-/lower-/title-casing according to the Unicode standard.
56 * Usual semantics: ""=root, NULL=default locale, etc.
57 * @param options Options bit set, used for case folding and string comparisons.
58 * Same flags as for u_foldCase(), u_strFoldCase(),
59 * u_strCaseCompare(), etc.
60 * Use 0 or U_FOLD_CASE_DEFAULT for default behavior.
61 * @param pErrorCode Must be a valid pointer to an error code value,
62 * which must not indicate a failure before the function call.
63 * @return Pointer to a UCaseMap service object, if successful.
64 *
65 * @see U_FOLD_CASE_DEFAULT
66 * @see U_FOLD_CASE_EXCLUDE_SPECIAL_I
67 * @see U_TITLECASE_NO_LOWERCASE
68 * @see U_TITLECASE_NO_BREAK_ADJUSTMENT
69 * @stable ICU 3.4
70 */
71 U_STABLE UCaseMap * U_EXPORT2
72 ucasemap_open(const char *locale, uint32_t options, UErrorCode *pErrorCode);
73
74 /**
75 * Close a UCaseMap service object.
76 * @param csm Object to be closed.
77 * @stable ICU 3.4
78 */
79 U_STABLE void U_EXPORT2
80 ucasemap_close(UCaseMap *csm);
81
82 #if U_SHOW_CPLUSPLUS_API
83
84 U_NAMESPACE_BEGIN
85
86 /**
87 * \class LocalUCaseMapPointer
88 * "Smart pointer" class, closes a UCaseMap via ucasemap_close().
89 * For most methods see the LocalPointerBase base class.
90 *
91 * @see LocalPointerBase
92 * @see LocalPointer
93 * @stable ICU 4.4
94 */
95 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCaseMapPointer, UCaseMap, ucasemap_close);
96
97 U_NAMESPACE_END
98
99 #endif // U_SHOW_CPLUSPLUS_API
100
101 /**
102 * Get the locale ID that is used for language-dependent case mappings.
103 * @param csm UCaseMap service object.
104 * @return locale ID
105 * @stable ICU 3.4
106 */
107 U_STABLE const char * U_EXPORT2
108 ucasemap_getLocale(const UCaseMap *csm);
109
110 /**
111 * Get the options bit set that is used for case folding and string comparisons.
112 * @param csm UCaseMap service object.
113 * @return options bit set
114 * @stable ICU 3.4
115 */
116 U_STABLE uint32_t U_EXPORT2
117 ucasemap_getOptions(const UCaseMap *csm);
118
119 /**
120 * Set the locale ID that is used for language-dependent case mappings.
121 *
122 * @param csm UCaseMap service object.
123 * @param locale Locale ID, see ucasemap_open().
124 * @param pErrorCode Must be a valid pointer to an error code value,
125 * which must not indicate a failure before the function call.
126 *
127 * @see ucasemap_open
128 * @stable ICU 3.4
129 */
130 U_STABLE void U_EXPORT2
131 ucasemap_setLocale(UCaseMap *csm, const char *locale, UErrorCode *pErrorCode);
132
133 /**
134 * Set the options bit set that is used for case folding and string comparisons.
135 *
136 * @param csm UCaseMap service object.
137 * @param options Options bit set, see ucasemap_open().
138 * @param pErrorCode Must be a valid pointer to an error code value,
139 * which must not indicate a failure before the function call.
140 *
141 * @see ucasemap_open
142 * @stable ICU 3.4
143 */
144 U_STABLE void U_EXPORT2
145 ucasemap_setOptions(UCaseMap *csm, uint32_t options, UErrorCode *pErrorCode);
146
147 /**
148 * Do not lowercase non-initial parts of words when titlecasing.
149 * Option bit for titlecasing APIs that take an options bit set.
150 *
151 * By default, titlecasing will titlecase the first cased character
152 * of a word and lowercase all other characters.
153 * With this option, the other characters will not be modified.
154 *
155 * @see ucasemap_setOptions
156 * @see ucasemap_toTitle
157 * @see ucasemap_utf8ToTitle
158 * @see UnicodeString::toTitle
159 * @stable ICU 3.8
160 */
161 #define U_TITLECASE_NO_LOWERCASE 0x100
162
163 /**
164 * Do not adjust the titlecasing indexes from BreakIterator::next() indexes;
165 * titlecase exactly the characters at breaks from the iterator.
166 * Option bit for titlecasing APIs that take an options bit set.
167 *
168 * By default, titlecasing will take each break iterator index,
169 * adjust it by looking for the next cased character, and titlecase that one.
170 * Other characters are lowercased.
171 *
172 * This follows Unicode 4 & 5 section 3.13 Default Case Operations:
173 *
174 * R3 toTitlecase(X): Find the word boundaries based on Unicode Standard Annex
175 * #29, "Text Boundaries." Between each pair of word boundaries, find the first
176 * cased character F. If F exists, map F to default_title(F); then map each
177 * subsequent character C to default_lower(C).
178 *
179 * @see ucasemap_setOptions
180 * @see ucasemap_toTitle
181 * @see ucasemap_utf8ToTitle
182 * @see UnicodeString::toTitle
183 * @see U_TITLECASE_NO_LOWERCASE
184 * @stable ICU 3.8
185 */
186 #define U_TITLECASE_NO_BREAK_ADJUSTMENT 0x200
187
188 /**
189 * Omit unchanged text when case-mapping with Edits.
190 *
191 * @see CaseMap
192 * @see Edits
193 * @draft ICU 59
194 */
195 #define UCASEMAP_OMIT_UNCHANGED_TEXT 0x4000
196
197 #if !UCONFIG_NO_BREAK_ITERATION
198
199 /**
200 * Get the break iterator that is used for titlecasing.
201 * Do not modify the returned break iterator.
202 * @param csm UCaseMap service object.
203 * @return titlecasing break iterator
204 * @stable ICU 3.8
205 */
206 U_STABLE const UBreakIterator * U_EXPORT2
207 ucasemap_getBreakIterator(const UCaseMap *csm);
208
209 /**
210 * Set the break iterator that is used for titlecasing.
211 * The UCaseMap service object releases a previously set break iterator
212 * and "adopts" this new one, taking ownership of it.
213 * It will be released in a subsequent call to ucasemap_setBreakIterator()
214 * or ucasemap_close().
215 *
216 * Break iterator operations are not thread-safe. Therefore, titlecasing
217 * functions use non-const UCaseMap objects. It is not possible to titlecase
218 * strings concurrently using the same UCaseMap.
219 *
220 * @param csm UCaseMap service object.
221 * @param iterToAdopt Break iterator to be adopted for titlecasing.
222 * @param pErrorCode Must be a valid pointer to an error code value,
223 * which must not indicate a failure before the function call.
224 *
225 * @see ucasemap_toTitle
226 * @see ucasemap_utf8ToTitle
227 * @stable ICU 3.8
228 */
229 U_STABLE void U_EXPORT2
230 ucasemap_setBreakIterator(UCaseMap *csm, UBreakIterator *iterToAdopt, UErrorCode *pErrorCode);
231
232 /**
233 * Titlecase a UTF-16 string. This function is almost a duplicate of u_strToTitle(),
234 * except that it takes ucasemap_setOptions() into account and has performance
235 * advantages from being able to use a UCaseMap object for multiple case mapping
236 * operations, saving setup time.
237 *
238 * Casing is locale-dependent and context-sensitive.
239 * Titlecasing uses a break iterator to find the first characters of words
240 * that are to be titlecased. It titlecases those characters and lowercases
241 * all others. (This can be modified with ucasemap_setOptions().)
242 *
243 * Note: This function takes a non-const UCaseMap pointer because it will
244 * open a default break iterator if no break iterator was set yet,
245 * and effectively call ucasemap_setBreakIterator();
246 * also because the break iterator is stateful and will be modified during
247 * the iteration.
248 *
249 * The titlecase break iterator can be provided to customize for arbitrary
250 * styles, using rules and dictionaries beyond the standard iterators.
251 * The standard titlecase iterator for the root locale implements the
252 * algorithm of Unicode TR 21.
253 *
254 * This function uses only the setUText(), first(), next() and close() methods of the
255 * provided break iterator.
256 *
257 * The result may be longer or shorter than the original.
258 * The source string and the destination buffer must not overlap.
259 *
260 * @param csm UCaseMap service object. This pointer is non-const!
261 * See the note above for details.
262 * @param dest A buffer for the result string. The result will be NUL-terminated if
263 * the buffer is large enough.
264 * The contents is undefined in case of failure.
265 * @param destCapacity The size of the buffer (number of UChars). If it is 0, then
266 * dest may be NULL and the function will only return the length of the result
267 * without writing any of the result string.
268 * @param src The original string.
269 * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
270 * @param pErrorCode Must be a valid pointer to an error code value,
271 * which must not indicate a failure before the function call.
272 * @return The length of the result string, if successful - or in case of a buffer overflow,
273 * in which case it will be greater than destCapacity.
274 *
275 * @see u_strToTitle
276 * @stable ICU 3.8
277 */
278 U_STABLE int32_t U_EXPORT2
279 ucasemap_toTitle(UCaseMap *csm,
280 UChar *dest, int32_t destCapacity,
281 const UChar *src, int32_t srcLength,
282 UErrorCode *pErrorCode);
283
284 #endif // UCONFIG_NO_BREAK_ITERATION
285
286 /**
287 * Lowercase the characters in a UTF-8 string.
288 * Casing is locale-dependent and context-sensitive.
289 * The result may be longer or shorter than the original.
290 * The source string and the destination buffer must not overlap.
291 *
292 * @param csm UCaseMap service object.
293 * @param dest A buffer for the result string. The result will be NUL-terminated if
294 * the buffer is large enough.
295 * The contents is undefined in case of failure.
296 * @param destCapacity The size of the buffer (number of bytes). If it is 0, then
297 * dest may be NULL and the function will only return the length of the result
298 * without writing any of the result string.
299 * @param src The original string.
300 * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
301 * @param pErrorCode Must be a valid pointer to an error code value,
302 * which must not indicate a failure before the function call.
303 * @return The length of the result string, if successful - or in case of a buffer overflow,
304 * in which case it will be greater than destCapacity.
305 *
306 * @see u_strToLower
307 * @stable ICU 3.4
308 */
309 U_STABLE int32_t U_EXPORT2
310 ucasemap_utf8ToLower(const UCaseMap *csm,
311 char *dest, int32_t destCapacity,
312 const char *src, int32_t srcLength,
313 UErrorCode *pErrorCode);
314
315 /**
316 * Uppercase the characters in a UTF-8 string.
317 * Casing is locale-dependent and context-sensitive.
318 * The result may be longer or shorter than the original.
319 * The source string and the destination buffer must not overlap.
320 *
321 * @param csm UCaseMap service object.
322 * @param dest A buffer for the result string. The result will be NUL-terminated if
323 * the buffer is large enough.
324 * The contents is undefined in case of failure.
325 * @param destCapacity The size of the buffer (number of bytes). If it is 0, then
326 * dest may be NULL and the function will only return the length of the result
327 * without writing any of the result string.
328 * @param src The original string.
329 * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
330 * @param pErrorCode Must be a valid pointer to an error code value,
331 * which must not indicate a failure before the function call.
332 * @return The length of the result string, if successful - or in case of a buffer overflow,
333 * in which case it will be greater than destCapacity.
334 *
335 * @see u_strToUpper
336 * @stable ICU 3.4
337 */
338 U_STABLE int32_t U_EXPORT2
339 ucasemap_utf8ToUpper(const UCaseMap *csm,
340 char *dest, int32_t destCapacity,
341 const char *src, int32_t srcLength,
342 UErrorCode *pErrorCode);
343
344 #if !UCONFIG_NO_BREAK_ITERATION
345
346 /**
347 * Titlecase a UTF-8 string.
348 * Casing is locale-dependent and context-sensitive.
349 * Titlecasing uses a break iterator to find the first characters of words
350 * that are to be titlecased. It titlecases those characters and lowercases
351 * all others. (This can be modified with ucasemap_setOptions().)
352 *
353 * Note: This function takes a non-const UCaseMap pointer because it will
354 * open a default break iterator if no break iterator was set yet,
355 * and effectively call ucasemap_setBreakIterator();
356 * also because the break iterator is stateful and will be modified during
357 * the iteration.
358 *
359 * The titlecase break iterator can be provided to customize for arbitrary
360 * styles, using rules and dictionaries beyond the standard iterators.
361 * The standard titlecase iterator for the root locale implements the
362 * algorithm of Unicode TR 21.
363 *
364 * This function uses only the setUText(), first(), next() and close() methods of the
365 * provided break iterator.
366 *
367 * The result may be longer or shorter than the original.
368 * The source string and the destination buffer must not overlap.
369 *
370 * @param csm UCaseMap service object. This pointer is non-const!
371 * See the note above for details.
372 * @param dest A buffer for the result string. The result will be NUL-terminated if
373 * the buffer is large enough.
374 * The contents is undefined in case of failure.
375 * @param destCapacity The size of the buffer (number of bytes). If it is 0, then
376 * dest may be NULL and the function will only return the length of the result
377 * without writing any of the result string.
378 * @param src The original string.
379 * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
380 * @param pErrorCode Must be a valid pointer to an error code value,
381 * which must not indicate a failure before the function call.
382 * @return The length of the result string, if successful - or in case of a buffer overflow,
383 * in which case it will be greater than destCapacity.
384 *
385 * @see u_strToTitle
386 * @see U_TITLECASE_NO_LOWERCASE
387 * @see U_TITLECASE_NO_BREAK_ADJUSTMENT
388 * @stable ICU 3.8
389 */
390 U_STABLE int32_t U_EXPORT2
391 ucasemap_utf8ToTitle(UCaseMap *csm,
392 char *dest, int32_t destCapacity,
393 const char *src, int32_t srcLength,
394 UErrorCode *pErrorCode);
395
396 #endif
397
398 /**
399 * Case-folds the characters in a UTF-8 string.
400 *
401 * Case-folding is locale-independent and not context-sensitive,
402 * but there is an option for whether to include or exclude mappings for dotted I
403 * and dotless i that are marked with 'T' in CaseFolding.txt.
404 *
405 * The result may be longer or shorter than the original.
406 * The source string and the destination buffer must not overlap.
407 *
408 * @param csm UCaseMap service object.
409 * @param dest A buffer for the result string. The result will be NUL-terminated if
410 * the buffer is large enough.
411 * The contents is undefined in case of failure.
412 * @param destCapacity The size of the buffer (number of bytes). If it is 0, then
413 * dest may be NULL and the function will only return the length of the result
414 * without writing any of the result string.
415 * @param src The original string.
416 * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.
417 * @param pErrorCode Must be a valid pointer to an error code value,
418 * which must not indicate a failure before the function call.
419 * @return The length of the result string, if successful - or in case of a buffer overflow,
420 * in which case it will be greater than destCapacity.
421 *
422 * @see u_strFoldCase
423 * @see ucasemap_setOptions
424 * @see U_FOLD_CASE_DEFAULT
425 * @see U_FOLD_CASE_EXCLUDE_SPECIAL_I
426 * @stable ICU 3.8
427 */
428 U_STABLE int32_t U_EXPORT2
429 ucasemap_utf8FoldCase(const UCaseMap *csm,
430 char *dest, int32_t destCapacity,
431 const char *src, int32_t srcLength,
432 UErrorCode *pErrorCode);
433
434 #endif