1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 *******************************************************************************
6 * Copyright (C) 2005-2012, International Business Machines
7 * Corporation and others. All Rights Reserved.
9 *******************************************************************************
10 * file name: ucasemap.h
12 * tab size: 8 (not used)
15 * created on: 2005may06
16 * created by: Markus W. Scherer
18 * Case mapping service object and functions using it.
21 #ifndef __UCASEMAP_H__
22 #define __UCASEMAP_H__
24 #include "unicode/utypes.h"
25 #include "unicode/localpointer.h"
26 #include "unicode/ustring.h"
30 * \brief C API: Unicode case mapping functions using a UCaseMap service object.
32 * The service object takes care of memory allocations, data loading, and setup
33 * for the attributes, as usual.
35 * Currently, the functionality provided here does not overlap with uchar.h
36 * and ustring.h, except for ucasemap_toTitle().
38 * ucasemap_utf8XYZ() functions operate directly on UTF-8 strings.
42 * UCaseMap is an opaque service object for newer ICU case mapping functions.
43 * Older functions did not use a service object.
47 typedef struct UCaseMap UCaseMap
; /**< C typedef for struct UCaseMap. @stable ICU 3.4 */
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.
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.
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
71 U_STABLE UCaseMap
* U_EXPORT2
72 ucasemap_open(const char *locale
, uint32_t options
, UErrorCode
*pErrorCode
);
75 * Close a UCaseMap service object.
76 * @param csm Object to be closed.
79 U_STABLE
void U_EXPORT2
80 ucasemap_close(UCaseMap
*csm
);
82 #if U_SHOW_CPLUSPLUS_API
87 * \class LocalUCaseMapPointer
88 * "Smart pointer" class, closes a UCaseMap via ucasemap_close().
89 * For most methods see the LocalPointerBase base class.
91 * @see LocalPointerBase
95 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCaseMapPointer
, UCaseMap
, ucasemap_close
);
99 #endif // U_SHOW_CPLUSPLUS_API
102 * Get the locale ID that is used for language-dependent case mappings.
103 * @param csm UCaseMap service object.
107 U_STABLE
const char * U_EXPORT2
108 ucasemap_getLocale(const UCaseMap
*csm
);
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
116 U_STABLE
uint32_t U_EXPORT2
117 ucasemap_getOptions(const UCaseMap
*csm
);
120 * Set the locale ID that is used for language-dependent case mappings.
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.
130 U_STABLE
void U_EXPORT2
131 ucasemap_setLocale(UCaseMap
*csm
, const char *locale
, UErrorCode
*pErrorCode
);
134 * Set the options bit set that is used for case folding and string comparisons.
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.
144 U_STABLE
void U_EXPORT2
145 ucasemap_setOptions(UCaseMap
*csm
, uint32_t options
, UErrorCode
*pErrorCode
);
148 * Do not lowercase non-initial parts of words when titlecasing.
149 * Option bit for titlecasing APIs that take an options bit set.
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.
155 * @see ucasemap_setOptions
156 * @see ucasemap_toTitle
157 * @see ucasemap_utf8ToTitle
158 * @see UnicodeString::toTitle
161 #define U_TITLECASE_NO_LOWERCASE 0x100
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.
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.
172 * This follows Unicode 4 & 5 section 3.13 Default Case Operations:
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).
179 * @see ucasemap_setOptions
180 * @see ucasemap_toTitle
181 * @see ucasemap_utf8ToTitle
182 * @see UnicodeString::toTitle
183 * @see U_TITLECASE_NO_LOWERCASE
186 #define U_TITLECASE_NO_BREAK_ADJUSTMENT 0x200
189 * Omit unchanged text when case-mapping with Edits.
195 #define UCASEMAP_OMIT_UNCHANGED_TEXT 0x4000
197 #if !UCONFIG_NO_BREAK_ITERATION
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
206 U_STABLE
const UBreakIterator
* U_EXPORT2
207 ucasemap_getBreakIterator(const UCaseMap
*csm
);
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().
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.
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.
225 * @see ucasemap_toTitle
226 * @see ucasemap_utf8ToTitle
229 U_STABLE
void U_EXPORT2
230 ucasemap_setBreakIterator(UCaseMap
*csm
, UBreakIterator
*iterToAdopt
, UErrorCode
*pErrorCode
);
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.
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().)
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
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.
254 * This function uses only the setUText(), first(), next() and close() methods of the
255 * provided break iterator.
257 * The result may be longer or shorter than the original.
258 * The source string and the destination buffer must not overlap.
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.
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
);
284 #endif // UCONFIG_NO_BREAK_ITERATION
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.
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.
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
);
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.
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.
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
);
344 #if !UCONFIG_NO_BREAK_ITERATION
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().)
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
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.
364 * This function uses only the setUText(), first(), next() and close() methods of the
365 * provided break iterator.
367 * The result may be longer or shorter than the original.
368 * The source string and the destination buffer must not overlap.
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.
386 * @see U_TITLECASE_NO_LOWERCASE
387 * @see U_TITLECASE_NO_BREAK_ADJUSTMENT
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
);
399 * Case-folds the characters in a UTF-8 string.
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.
405 * The result may be longer or shorter than the original.
406 * The source string and the destination buffer must not overlap.
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.
423 * @see ucasemap_setOptions
424 * @see U_FOLD_CASE_DEFAULT
425 * @see U_FOLD_CASE_EXCLUDE_SPECIAL_I
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
);