2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
16 * Copyright (C) 1998-2012, International Business Machines
17 * Corporation and others. All Rights Reserved.
20 #ifndef __UTILS_I18N_USTRING_H__
21 #define __UTILS_I18N_USTRING_H__
23 #include <utils_i18n_types.h>
26 * @file utils_i18n_ustring.h
28 * @brief utils_i18n_ustring
36 * @ingroup CAPI_BASE_UTILS_I18N_MODULE
37 * @defgroup CAPI_BASE_UTILS_I18N_USTRING_MODULE Ustring
38 * @brief The Ustring module provides general unicode string handling information.
40 * @section CAPI_BASE_UTILS_I18N_USTRING_MODULE_HEADER Required Header
41 * \#include <utils_i18n.h>
43 * @section CAPI_BASE_UTILS_I18N_USTRING_MODULE_OVERVIEW Overview
44 * @details The Ustring module provides general unicode string handling information.
46 * @section CAPI_BASE_UTILS_I18N_USTIRING_MODULE_SAMPLE_CODE_1 Sample Code 1
47 * @brief It converts a byte string to a unicode string and then to uppercase letters.
49 char str_1[64] = {0,};
50 i18n_uchar uchar_str_1[64] = {0,};
51 i18n_uchar uchar_str_2[64] = {0,};
53 i18n_uerror_code_e err_code = I18N_ERROR_NONE;
55 strcpy(str_1, "tizen");
56 dlog_print(DLOG_INFO, LOG_TAG, "str_1 is %s\n", str_1); // str_1 is tizen
58 // converts a byte string to a unicode string
59 i18n_ustring_copy_ua_n(uchar_str_1, str_1, strlen(str_1));
61 // converts to uppercase letters
62 i18n_ustring_to_upper(uchar_str_2, 64, uchar_str_1, i18n_ustring_get_length( uchar_str_1 ), "en_US", &err_code);
64 i18n_ustring_copy_au(str_1, uchar_str_2);
65 dlog_print(DLOG_INFO, LOG_TAG, "str_1 is %s\n", str_1); // str_1 is TIZEN
70 * @addtogroup CAPI_BASE_UTILS_I18N_USTRING_MODULE
75 * @brief Determines the length of an array of #i18n_uchar.
76 * @remarks The specific error code can be obtained using the get_last_result() method.
77 * Error codes are described in Exceptions section.
78 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
80 * @param[in] s The array of #i18n_uchar characters, @c NULL (U+0000) terminated.
82 * @return The number of #i18n_uchar characters in @c chars, minus the terminator
83 * @exception #I18N_ERROR_NONE Success
84 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
86 int32_t i18n_ustring_get_length ( const i18n_uchar *s );
89 * @brief Counts Unicode code points in the length #i18n_uchar code units of the string.
90 * @details A code point may occupy either one or two #i18n_uchar code units.
91 * Counting code points involves reading all code units.
92 * @remarks The specific error code can be obtained using the get_last_result() method.
93 * Error codes are described in Exceptions section.
94 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
96 * @param[in] s The input string.
97 * @param[in] length The number of #i18n_uchar code units to be checked, or @c -1 to count
98 * all code points before the first NULL (U+0000).
100 * @return The number of code points in the specified code units.
101 * @exception #I18N_ERROR_NONE Success
102 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
104 int32_t i18n_ustring_count_char32 ( const i18n_uchar *s, int32_t length );
107 * @brief Checks if the string contains more Unicode code points than a certain number.
108 * @details This is more efficient than counting all code points in the entire string and comparing that number with a threshold.
109 * This function may not need to scan the string at all if the length is known (not @c -1 for NULL-termination) and falls within a certain range,
110 * and never needs to count more than 'number+1' code points.
111 * Logically equivalent to ( i18n_ustring_count_char32 (s, length, &number_of_code_points); number_of_code_points > number ).
112 * A Unicode code point may occupy either one or two #i18n_uchar code units.
113 * @remarks The specific error code can be obtained using the get_last_result() method.
114 * Error codes are described in Exceptions section.
115 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
117 * @param[in] s The input string.
118 * @param[in] length The length of the string, or @c -1 if it is NULL-terminated.
119 * @param[in] number The number of code points in the string is compared against the @a number parameter.
121 * @return Boolean value for whether the string contains more Unicode code points than @a number. Same as ( i18n_ustring_count_char32 (s, length, &number_of_code_points); number_of_code_points > number).
122 * @exception #I18N_ERROR_NONE Success
123 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
125 i18n_ubool i18n_ustring_has_more_char32_than ( const i18n_uchar *s, int32_t length, int32_t number );
128 * @brief Concatenates two ustrings.
129 * @details Appends a copy of @a src, including the NULL terminator, to @a dest.
130 * The initial copied character from @a src overwrites the NULL terminator in @a dest.
131 * @remarks The specific error code can be obtained using the get_last_result() method.
132 * Error codes are described in Exceptions section.
133 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
135 * @param[out] dest The destination string.
136 * @param[in] src The source string.
138 * @return A pointer to @a dest.
139 * @exception #I18N_ERROR_NONE Success
140 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
142 i18n_uchar* i18n_ustring_cat ( i18n_uchar *dest, const i18n_uchar *src );
145 * @brief Concatenate two ustrings.
146 * @details Appends a copy of @a src, including the NULL terminator, to @a dest.
147 * The initial copied character from @a src overwrites the NULL terminator in @a dest.
148 * @remarks The specific error code can be obtained using the get_last_result() method.
149 * Error codes are described in Exceptions section.
150 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
152 * @param[out] dest The destination string.
153 * @param[in] src The source string.
154 * @param[in] n The maximum number of characters to append; no-op if <=0.
156 * @return A pointer to @a dest.
157 * @exception #I18N_ERROR_NONE Success
158 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
160 i18n_uchar* i18n_ustring_cat_n ( i18n_uchar *dest, const i18n_uchar *src, int32_t n );
163 * @brief Finds the first occurrence of a substring in a string.
164 * @details The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate
165 * or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text.
166 * Otherwise, the substring edge units would be matched against halves of surrogate pairs.
167 * @remarks The specific error code can be obtained using the get_last_result() method.
168 * Error codes are described in Exceptions section.
169 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
171 * @param[in] s The string to search (NULL-terminated).
172 * @param[in] sub_string The substring to find (NULL-terminated).
174 * @return A pointer to the first occurrence of @a sub_string in @a s,
175 * or @a s itself if the @a sub_string is empty,
176 * or @c NULL if @a sub_string is not in @a s.
178 * @exception #I18N_ERROR_NONE Success
179 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
181 * @see i18n_ustring_r_string()
182 * @see i18n_ustring_find_first()
183 * @see i18n_ustring_find_last()
185 i18n_uchar* i18n_ustring_string ( const i18n_uchar *s, const i18n_uchar *sub_string );
188 * @brief Finds the first occurrence of a substring in a string.
189 * @details The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate
190 * or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text.
191 * Otherwise, the substring edge units would be matched against halves of surrogate pairs.
192 * @remarks The specific error code can be obtained using the get_last_result() method.
193 * Error codes are described in Exceptions section.
194 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
196 * @param[in] s The string to search (NULL-terminated).
197 * @param[in] length The length of @a s (number of #i18n_uchar characters), or @c -1 if it is NULL-terminated.
198 * @param[in] sub_string The substring to find (NULL-terminated).
199 * @param[in] sub_length The length of substring (number of #i18n_uchar characters), or @c -1 if it is NULL-terminated.
201 * @return A pointer to the first occurrence of @a sub_string in @a s,
202 * or @a s itself if the @a sub_string is empty,
203 * or @c NULL if @a sub_string is not in @a s.
205 * @exception #I18N_ERROR_NONE Success
206 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
208 * @see i18n_ustring_string()
209 * @see i18n_ustring_find_last()
211 i18n_uchar* i18n_ustring_find_first ( const i18n_uchar *s, int32_t length, const i18n_uchar *sub_string, int32_t sub_length );
214 * @brief Finds the first occurrence of a BMP code point in a string.
215 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
216 * @remarks The specific error code can be obtained using the get_last_result() method.
217 * Error codes are described in Exceptions section.
218 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
220 * @param[in] s The string to search (NULL-terminated).
221 * @param[in] c The BMP code point to find.
223 * @return A pointer to the first occurrence of @a c in @a s
224 * or @c NULL if @a c is not in @a s.
225 * @exception #I18N_ERROR_NONE Success
226 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
227 * @see i18n_ustring_char32()
228 * @see i18n_ustring_mem_char()
229 * @see i18n_ustring_string()
230 * @see i18n_ustring_find_first()
232 i18n_uchar* i18n_ustring_char ( const i18n_uchar *s, i18n_uchar c );
235 * @brief Finds the first occurrence of a code point in a string.
236 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
237 * @remarks The specific error code can be obtained using the get_last_result() method.
238 * Error codes are described in Exceptions section.
239 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
241 * @param[in] s The string to search (NULL-terminated).
242 * @param[in] c The code point to find.
244 * @return A pointer to the first occurrence of @a c in @a s
245 * or @c NULL if @a c is not in @a s.
246 * @exception #I18N_ERROR_NONE Success
247 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
248 * @see i18n_ustring_char()
249 * @see i18n_ustring_mem_char32()
250 * @see i18n_ustring_string()
251 * @see i18n_ustring_find_first()
253 i18n_uchar* i18n_ustring_char32 ( const i18n_uchar *s, i18n_uchar32 c );
256 * @brief Finds the last occurrence of a substring in a string.
257 * @details The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate
258 * or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text.
259 * Otherwise, the substring edge units would be matched against halves of surrogate pairs.
260 * @remarks The specific error code can be obtained using the get_last_result() method.
261 * Error codes are described in Exceptions section.
262 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
264 * @param[in] s The string to search (NULL-terminated).
265 * @param[in] sub_string The substring to find (NULL-terminated).
267 * @return A pointer to the last occurrence of @a substring in @a s,
268 * or @a s itself if the @a sub_string is empty,
269 * or @c NULL if @a sub_string is not in @a s.
270 * @exception #I18N_ERROR_NONE Success
271 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
272 * @see i18n_ustring_string()
273 * @see i18n_ustring_find_first()
274 * @see i18n_ustring_find_last()
276 i18n_uchar* i18n_ustring_r_string ( const i18n_uchar *s, const i18n_uchar *sub_string );
279 * @brief Finds the last occurrence of a substring in a string.
280 * @details The substring is found at code point boundaries. That means that if the substring begins with a trail surrogate
281 * or ends with a lead surrogate, then it is found only if these surrogates stand alone in the text.
282 * Otherwise, the substring edge units would be matched against halves of surrogate pairs.
283 * @remarks The specific error code can be obtained using the get_last_result() method.
284 * Error codes are described in Exceptions section.
285 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
287 * @param[in] s The string to search.
288 * @param[in] length The length of s (number of #i18n_uchar), or @c -1 if it is NULL-terminated.
289 * @param[in] sub_string The sub_string to find (NULL-terminated).
290 * @param[in] sub_length The length of sub_string (number of #i18n_uchar), or @c -1 if it is NULL-terminated.
292 * @return A pointer to the last occurrence of @a sub_string in @a s,
293 * or @a s itself if the @a substring is empty,
294 * or @c NULL if @a sub_string is not in @a s.
295 * @exception #I18N_ERROR_NONE Success
296 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
297 * @see i18n_ustring_string()
298 * @see i18n_ustring_find_first()
300 i18n_uchar* i18n_ustring_find_last( const i18n_uchar *s, int32_t length, const i18n_uchar *sub_string, int32_t sub_length );
303 * @brief Finds the last occurrence of a BMP code point in a string.
304 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
305 * @remarks The specific error code can be obtained using the get_last_result() method.
306 * Error codes are described in Exceptions section.
307 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
309 * @param[in] s The string to search (NULL-terminated).
310 * @param[in] c The BMP code point to find.
312 * @return A pointer to the last occurrence of @a c in @a s
313 * or @c NULL if @a c is not in @a s.
314 * @exception #I18N_ERROR_NONE Success
315 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
316 * @see i18n_ustring_char32()
317 * @see i18n_ustring_mem_char()
318 * @see i18n_ustring_string()
319 * @see i18n_ustring_find_first()
321 i18n_uchar* i18n_ustring_r_char ( const i18n_uchar *s, i18n_uchar c );
324 * @brief Finds the last occurrence of a code point in a string.
325 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
326 * @remarks The specific error code can be obtained using the get_last_result() method.
327 * Error codes are described in Exceptions section.
328 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
330 * @param[in] s The string to search (NULL-terminated).
331 * @param[in] c The code point to find.
333 * @return A pointer to the last occurrence of @a c in @a s
334 * or @c NULL if @a c is not in @a s.
335 * @exception #I18N_ERROR_NONE Success
336 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
337 * @see i18n_ustring_char()
338 * @see i18n_ustring_mem_char32()
339 * @see i18n_ustring_string()
340 * @see i18n_ustring_find_first()
342 i18n_uchar* i18n_ustring_r_char32 ( const i18n_uchar *s, i18n_uchar32 c );
345 * @brief Locates the first occurrence in the string of any of the characters in the string matchSet.
346 * @details Works just like C's strpbrk but with Unicode.
347 * @remarks The specific error code can be obtained using the get_last_result() method.
348 * Error codes are described in Exceptions section.
349 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
351 * @param[in] string The string in which to search, NULL-terminated.
352 * @param[in] match_set A NULL-terminated string defining a set of code points for which to search in the text string.
354 * @exception #I18N_ERROR_NONE Success
355 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
356 * @return A pointer to the character in @a string that matches one of the
357 * characters in @a match_set, or NULL if no such character is found.
359 i18n_uchar* i18n_ustring_pbrk ( const i18n_uchar *string, const i18n_uchar *match_set );
362 * @brief Returns the number of consecutive characters in string, beginning with the first, that do not occur somewhere in match_set.
363 * @details Works just like C's strcspn but with Unicode.
364 * @remarks The specific error code can be obtained using the get_last_result() method.
365 * Error codes are described in Exceptions section.
366 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
368 * @param[in] string The string in which to search, NULL-terminated.
369 * @param[in] match_set A NULL-terminated string defining a set of code points for which to search in the text string.
371 * @exception #I18N_ERROR_NONE Success
372 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
373 * @return The number of initial characters in @a string that do not
374 * occur in @a match_set.
376 int32_t i18n_ustring_cspn ( const i18n_uchar *string, const i18n_uchar *match_set );
379 * @brief Returns the number of consecutive characters in string, beginning with the first, that occur somewhere in match_set.
380 * @details Works just like C's strspn but with Unicode.
381 * @remarks The specific error code can be obtained using the get_last_result() method.
382 * Error codes are described in Exceptions section.
383 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
385 * @param[in] string The string in which to search, NULL-terminated.
386 * @param[in] match_set A NULL-terminated string defining a set of code points for which to search in the text string.
387 * @return The number of initial characters in @a string that do
388 * occur in @a match_set.
389 * @exception #I18N_ERROR_NONE Success
390 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
391 * @see i18n_ustring_spn()
393 int32_t i18n_ustring_spn ( const i18n_uchar *string, const i18n_uchar *match_set );
396 * @brief The string tokenizer API allows an application to break a string into tokens.
397 * @details Works just like C's strspn but with Unicode.
398 * @remarks The specific error code can be obtained using the get_last_result() method.
399 * Error codes are described in Exceptions section.
400 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
402 * @param[in] src String containing token(s). This string will be modified. After the first call to #i18n_ustring_tokenizer_r(), this argument must be NULL to get to the next token.
403 * @param[in] delim Set of delimiter characters (Unicode code points).
404 * @param[out] save_state The current pointer within the original string, which is set by this function.
405 * The save_state parameter should the address of a local variable of type #i18n_uchar *.
406 * @return A pointer to the next token found in src, or NULL
407 * when there are no more tokens.
408 * @exception #I18N_ERROR_NONE Success
409 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
411 i18n_uchar* i18n_ustring_tokenizer_r ( i18n_uchar *src, const i18n_uchar *delim, i18n_uchar **save_state );
414 * @brief Compares two Unicode strings for bitwise equality (code unit order).
415 * @remarks The specific error code can be obtained using the get_last_result() method.
416 * Error codes are described in Exceptions section.
417 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
419 * @param[in] s1 A string to compare.
420 * @param[in] s2 A string to compare.
421 * @return 0 if @a s1 and @a s2 are bitwise equal; a negative
422 * value if @a s1 is bitwise less than @a s2; a positive
423 * value if @a s1 is bitwise greater than @a s2.
424 * @exception #I18N_ERROR_NONE Success
425 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
427 int32_t i18n_ustring_compare ( const i18n_uchar *s1, const i18n_uchar *s2 );
430 * @brief Compare two Unicode strings in code point order.
431 * @details See #i18n_ustring_compare() for details.
432 * @remarks The specific error code can be obtained using the get_last_result() method.
433 * Error codes are described in Exceptions section.
434 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
436 * @param[in] s1 A string to compare.
437 * @param[in] s2 A string to compare.
438 * @return a negative/zero/positive integer corresponding to whether
439 * the first string is less than/equal to/greater than the second one
440 * in code point order
441 * @exception #I18N_ERROR_NONE Success
442 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
444 int32_t i18n_ustring_compare_code_point_order( const i18n_uchar *s1, const i18n_uchar *s2 );
447 * @brief Compare two Unicode strings (binary order).
448 * @details The comparison can be done in code unit order or in code point order. They differ only in UTF-16 when comparing supplementary code points
449 * (U+10000..U+10ffff) to BMP code points near the end of the BMP (i.e., U+e000..U+ffff). In code unit order, high BMP code points sort after
450 * supplementary code points because they are stored as pairs of surrogates which are at U+d800..U+dfff.\n
451 * This functions works with strings of different explicitly specified lengths unlike the ANSI C-like #i18n_ustring_compare() and #i18n_ustring_mem_compare() etc.
452 * NULL-terminated strings are possible with length arguments of -1.
453 * @remarks The specific error code can be obtained using the get_last_result() method.
454 * Error codes are described in Exceptions section.
455 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
457 * @param[in] s1 First source string.
458 * @param[in] length1 Length of first source string, or @c -1 if NULL-terminated.
459 * @param[in] s2 Second source string.
460 * @param[in] length2 Length of second source string, or @c -1 if NULL-terminated.
461 * @param[in] code_point_order Choose between code unit order (false) and code point order (true).
462 * @return < 0, 0 or > 0 as usual for string comparisons
463 * @exception #I18N_ERROR_NONE Success
464 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
466 int32_t i18n_ustring_compare_binary_order( const i18n_uchar *s1, int32_t length1, const i18n_uchar *s2, int32_t length2, i18n_ubool code_point_order );
469 * @brief Compare two strings case-insensitively using full case folding.
470 * @details The comparison can be done in UTF-16 code unit order or in code point order. They differ only when comparing
471 * supplementary code points (U+10000..U+10ffff) to BMP code points near the end of the BMP (i.e., U+e000..U+ffff).
472 * In code unit order, high BMP code points sort after supplementary code points because they are stored as pairs of surrogates which are at U+d800..U+dfff.\n
473 * This functions works with strings of different explicitly specified lengths unlike the ANSI C-like #i18n_ustring_compare() and i18n_ustring_mem_compare() etc.
474 * NULL-terminated strings are possible with length arguments of -1.
475 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
477 * @param[in] s1 First source string.
478 * @param[in] length1 Length of first source string, or @c -1 if NULL-terminated.
479 * @param[in] s2 Second source string.
480 * @param[in] length2 Length of second source string, or @c -1 if NULL-terminated.
481 * @param[in] options A bit set of options:\n
482 * - #I18N_USTRING_U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.\n
483 * - #I18N_USTRING_U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see i18n_ustring_compare_code_pointer_order() for details).\n
484 * - #I18N_USTRING_U_FOLD_CASE_EXCLUDE_SPECIAL_I
485 * @param[out] error_code Must be a valid pointer to an error code value,
486 * which must not indicate a failure before the function call.
487 * @return <0 or 0 or >0 as usual for string comparisons
488 * @exception #I18N_ERROR_NONE Success
489 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
491 int32_t i18n_ustring_case_compare_with_length( const i18n_uchar *s1, int32_t length1, const i18n_uchar *s2, int32_t length2, uint32_t options, i18n_error_code_e *error_code );
494 * @brief Compare two ustrings for bitwise equality.
495 * @details Compares at most n characters.
496 * @remarks The specific error code can be obtained using the get_last_result() method.
497 * Error codes are described in Exceptions section.
498 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
500 * @param[in] s1 A string to compare (can be NULL/invalid if n<=0).
501 * @param[in] s2 A string to compare (can be NULL/invalid if n<=0).
502 * @param[in] n The maximum number of characters to compare; always returns 0 if n<=0.
503 * @return 0 if @a s1 and @a s2 are bitwise equal; a negative
504 * value if @a s1 is bitwise less than @a s2; a positive
505 * value if @a s1 is bitwise greater than @a s2.
506 * @exception #I18N_ERROR_NONE Success
507 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
509 int32_t i18n_ustring_compare_n( const i18n_uchar *s1, const i18n_uchar *s2, int32_t n );
512 * @brief Compare two Unicode strings in code point order.
513 * @details This is different in UTF-16 from #i18n_ustring_compare_n() if supplementary characters are present. For details, see #i18n_ustring_compare_binary_order().
514 * @remarks The specific error code can be obtained using the get_last_result() method.
515 * Error codes are described in Exceptions section.
516 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
518 * @param[in] s1 A string to compare.
519 * @param[in] s2 A string to compare.
520 * @param[in] n The maximum number of characters to compare.
521 * @return a negative/zero/positive integer corresponding to whether
522 * the first string is less than/equal to/greater than the second one
523 * in code point order
524 * @exception #I18N_ERROR_NONE Success
525 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
527 int32_t i18n_ustring_compare_n_code_point_order( const i18n_uchar *s1, const i18n_uchar *s2, int32_t n );
530 * @brief Compare two strings case-insensitively using full case folding.
531 * @remarks The specific error code can be obtained using the get_last_result() method.
532 * Error codes are described in Exceptions section.
533 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
535 * @param[in] s1 A string to compare.
536 * @param[in] s2 A string to compare.
537 * @param[in] options bit set of options:\n
538 * - #I18N_USTRING_U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.
539 * - #I18N_USTRING_U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see u_strCompare for details).
540 * - #I18N_USTRING_U_FOLD_CASE_EXCLUDE_SPECIAL_I
541 * @return A negative, zero, or positive integer indicating the comparison result.
542 * @exception #I18N_ERROR_NONE Success
543 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
545 int32_t i18n_ustring_case_compare( const i18n_uchar *s1, const i18n_uchar *s2, uint32_t options );
548 * @brief Compare two strings case-insensitively using full case folding.
549 * @remarks The specific error code can be obtained using the get_last_result() method.
550 * Error codes are described in Exceptions section.
551 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
553 * @param[in] s1 A string to compare.
554 * @param[in] s2 A string to compare.
555 * @param[in] n The maximum number of characters each string to case-fold and then compare.
556 * @param[in] options A bit set of options:\n
557 * - #I18N_USTRING_U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.
558 * - #I18N_USTRING_U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see u_strCompare for details).
559 * - #I18N_USTRING_U_FOLD_CASE_EXCLUDE_SPECIAL_I
560 * @return A negative, zero, or positive integer indicating the comparison result.
561 * @exception #I18N_ERROR_NONE Success
562 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
564 int32_t i18n_ustring_case_compare_n( const i18n_uchar *s1, const i18n_uchar *s2, int32_t n, uint32_t options );
567 * @brief Compare two strings case-insensitively using full case folding.
568 * @remarks The specific error code can be obtained using the get_last_result() method.
569 * Error codes are described in Exceptions section.
570 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
572 * @param[in] s1 A string to compare.
573 * @param[in] s2 A string to compare.
574 * @param[in] length The number of characters in each string to case-fold and then compare.
575 * @param[in] options A bit set of options:\n
576 * - #I18N_USTRING_U_FOLD_CASE_DEFAULT or 0 is used for default options: Comparison in code unit order with default case folding.
577 * - #I18N_USTRING_U_COMPARE_CODE_POINT_ORDER Set to choose code point order instead of code unit order (see u_strCompare for details).
578 * - #I18N_USTRING_U_FOLD_CASE_EXCLUDE_SPECIAL_I
579 * @return A negative, zero, or positive integer indicating the comparison result.
580 * @exception #I18N_ERROR_NONE Success
581 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
583 int32_t i18n_ustring_mem_case_compare( const i18n_uchar *s1, const i18n_uchar *s2, int32_t length, uint32_t options );
586 * @brief Copies a ustring. Adds a NULL terminator.
587 * @remarks The specific error code can be obtained using the get_last_result() method.
588 * Error codes are described in Exceptions section.
589 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
591 * @param[out] dest The destination string
592 * @param[in] src The source string
594 * @return A pointer to @a dest.
595 * @exception #I18N_ERROR_NONE Success
596 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
598 i18n_uchar* i18n_ustring_copy ( i18n_uchar *dest, const i18n_uchar *src );
601 * @brief Copies a ustring.
602 * @details Copies at most @a n characters. The result will be NULL terminated
603 * if the length of @a src is less than @a n.
604 * @remarks The specific error code can be obtained using the get_last_result() method.
605 * Error codes are described in Exceptions section.
606 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
608 * @param[out] dest The destination string
609 * @param[in] src The source string
610 * @param[in] n The maximum number of characters to copy
612 * @return A pointer to @a dest.
613 * @exception #I18N_ERROR_NONE Success
614 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
616 i18n_uchar* i18n_ustring_copy_n ( i18n_uchar *dest, const i18n_uchar *src, int32_t n );
619 * @brief Copies a byte string encoded in the default codepage to a ustring.
620 * @details Adds a NULL terminator. Performs a host byte to #i18n_uchar conversion.
621 * @remarks The specific error code can be obtained using the get_last_result() method.
622 * Error codes are described in Exceptions section.
623 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
625 * @param[out] dest The destination string
626 * @param[in] src The source string
628 * @return A pointer to @a dest.
629 * @exception #I18N_ERROR_NONE Success
630 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
632 i18n_uchar* i18n_ustring_copy_ua ( i18n_uchar *dest, const char *src );
635 * @brief Copies a byte string encoded in the default codepage to a ustring.
636 * @details Copies at most @a n characters. The result will be NULL terminated
637 * if the length of @a src is less than @a n.
638 * Performs a host byte to #i18n_uchar conversion.
639 * @remarks The specific error code can be obtained using the get_last_result() method.
640 * Error codes are described in Exceptions section.
641 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
643 * @param[out] dest The destination string
644 * @param[in] src The source string
645 * @param[in] n The maximum number of characters to copy
647 * @return A pointer to @a dest.
648 * @exception #I18N_ERROR_NONE Success
649 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
651 i18n_uchar* i18n_ustring_copy_ua_n ( i18n_uchar *dest, const char *src, int32_t n );
654 * @brief Copies a ustring to a byte string encoded in the default codepage.
655 * @details Adds a NULL terminator. Performs an #i18n_uchar to host byte conversion.
656 * @remarks The specific error code can be obtained using the get_last_result() method.
657 * Error codes are described in Exceptions section.
658 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
660 * @param[out] dest The destination string
661 * @param[in] src The source string
663 * @return A pointer to @a dest.
664 * @exception #I18N_ERROR_NONE Success
665 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
667 char* i18n_ustring_copy_au ( char *dest, const i18n_uchar *src );
670 * @brief Copies a ustring to a byte string encoded in the default codepage.
671 * @details Copies at most @a n characters. The result will be NULL terminated
672 * if the length of @a src is less than @a n.
673 * Performs an #i18n_uchar to host byte conversion.
674 * @remarks The specific error code can be obtained using the get_last_result() method.
675 * Error codes are described in Exceptions section.
676 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
678 * @param[out] dest The destination string
679 * @param[in] src The source string
680 * @param[in] n The maximum number of characters to copy
682 * @return A pointer to @a dest.
683 * @exception #I18N_ERROR_NONE Success
684 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
686 char* i18n_ustring_copy_au_n ( char *dest, const i18n_uchar *src, int32_t n );
689 * @brief Synonym for memcpy(), but with #i18n_uchar characters only.
690 * @remarks The specific error code can be obtained using the get_last_result() method.
691 * Error codes are described in Exceptions section.
692 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
694 * @param[out] dest The destination string
695 * @param[in] src The source string (can be NULL/invalid if count<=0)
696 * @param[in] count The number of characters to copy; no-op if <=0
698 * @return A pointer to @a dest
699 * @exception #I18N_ERROR_NONE Success
700 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
702 i18n_uchar* i18n_ustring_mem_copy ( i18n_uchar *dest, const i18n_uchar *src, int32_t count );
705 * @brief Synonym for memmove(), but with #i18n_uchar characters only.
706 * @remarks The specific error code can be obtained using the get_last_result() method.
707 * Error codes are described in Exceptions section.
708 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
710 * @param[out] dest The destination string
711 * @param[in] src The source string (can be NULL/invalid if count<=0)
712 * @param[in] count The number of characters to copy; no-op if <=0
714 * @return A pointer to @a dest
715 * @exception #I18N_ERROR_NONE Success
716 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
718 i18n_uchar* i18n_ustring_mem_move ( i18n_uchar *dest, const i18n_uchar *src, int32_t count );
721 * @brief Initialize count characters of dest to c.
722 * @remarks The specific error code can be obtained using the get_last_result() method.
723 * Error codes are described in Exceptions section.
724 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
726 * @param[out] dest The destination string
727 * @param[in] c The character to initialize the string.
728 * @param[in] count The maximum number of characters to set.
730 * @return A pointer to @a dest.
731 * @exception #I18N_ERROR_NONE Success
732 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
734 i18n_uchar* i18n_ustring_mem_set ( i18n_uchar *dest, const i18n_uchar c, int32_t count );
737 * @brief Compare the first count #i18n_uchar characters of each buffer.
738 * @remarks The specific error code can be obtained using the get_last_result() method.
739 * Error codes are described in Exceptions section.
740 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
742 * @param[in] buf1 The first string to compare.
743 * @param[in] buf2 The second string to compare.
744 * @param[in] count The maximum number of #i18n_uchar characters to compare.
745 * @return When buf1 < buf2, a negative number is returned.
746 * When buf1 == buf2, 0 is returned.
747 * When buf1 > buf2, a positive number is returned.
748 * @exception #I18N_ERROR_NONE Success
749 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
751 int32_t i18n_ustring_mem_compare ( const i18n_uchar *buf1, const i18n_uchar *buf2, int32_t count );
754 * @brief Compare two Unicode strings in code point order.
755 * @details This is different in UTF-16 from #i18n_ustring_mem_compare() if supplementary characters are present. For details, see #i18n_ustring_compare_binary_order().
756 * @remarks The specific error code can be obtained using the get_last_result() method.
757 * Error codes are described in Exceptions section.
758 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
760 * @param[in] s1 A string to compare.
761 * @param[in] s2 A string to compare.
762 * @param[in] count The maximum number of characters to compare.
763 * @return a negative/zero/positive integer corresponding to whether
764 * the first string is less than/equal to/greater than the second one
765 * in code point order
766 * @exception #I18N_ERROR_NONE Success
767 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
769 int32_t i18n_ustring_mem_compare_code_point_order ( const i18n_uchar *s1, const i18n_uchar *s2, int32_t count );
772 * @brief Finds the first occurrence of a BMP code point in a string.
773 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
774 * @remarks The specific error code can be obtained using the get_last_result() method.
775 * Error codes are described in Exceptions section.
776 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
778 * @param[in] s The string to search (contains count #i18n_uchar characters).
779 * @param[in] c The BMP code point to find.
780 * @param[in] count The length of the string.
781 * @return A pointer to the first occurrence of @a c in @a s
782 * or @c NULL if @a c is not in @a s.
783 * @exception #I18N_ERROR_NONE Success
784 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
785 * @see i18n_ustring_char()
786 * @see i18n_ustring_mem_char32()
787 * @see i18n_ustring_find_first()
789 i18n_uchar* i18n_ustring_mem_char ( const i18n_uchar *s, i18n_uchar c, int32_t count );
792 * @brief Finds the first occurrence of a code point in a string.
793 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
794 * @remarks The specific error code can be obtained using the get_last_result() method.
795 * Error codes are described in Exceptions section.
796 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
798 * @param[in] s The string to search (contains count #i18n_uchar characters).
799 * @param[in] c The code point to find.
800 * @param[in] count The length of the string.
801 * @return A pointer to the first occurrence of @a c in @a s
802 * or @c NULL if @a c is not in @a s.
803 * @exception #I18N_ERROR_NONE Success
804 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
806 i18n_uchar* i18n_ustring_mem_char32 ( const i18n_uchar *s, i18n_uchar32 c, int32_t count );
809 * @brief Finds the last occurrence of a BMP code point in a string.
810 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
811 * @remarks The specific error code can be obtained using the get_last_result() method.
812 * Error codes are described in Exceptions section.
813 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
815 * @param[in] s The string to search (contains count #i18n_uchar characters).
816 * @param[in] c The BMP code point to find.
817 * @param[in] count The length of the string.
818 * @return A pointer to the last occurrence of @a c in @a s
819 * or @c NULL if @a c is not in @a s.
820 * @exception #I18N_ERROR_NONE Success
821 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
822 * @see #i18n_ustring_r_char
823 * @see #i18n_ustring_mem_r_char32
824 * @see #i18n_ustring_find_last
826 i18n_uchar* i18n_ustring_mem_r_char ( const i18n_uchar *s, i18n_uchar c, int32_t count );
829 * @brief Finds the last occurrence of a code point in a string.
830 * @details A surrogate code point is found only if its match in the text is not part of a surrogate pair. A NULL character is found at the string terminator.
831 * @remarks The specific error code can be obtained using the get_last_result() method.
832 * Error codes are described in Exceptions section.
833 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
835 * @param[in] s The string to search (contains count #i18n_uchar characters).
836 * @param[in] c The code point to find.
837 * @param[in] count The length of the string.
838 * @return A pointer to the last occurrence of @a c in @a s
839 * or @c NULL if @a c is not in @a s.
840 * @exception #I18N_ERROR_NONE Success
841 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
842 * @see #i18n_ustring_r_char32
843 * @see #i18n_ustring_mem_r_char
844 * @see #i18n_ustring_find_last
846 i18n_uchar* i18n_ustring_mem_r_char32 ( const i18n_uchar *s, i18n_uchar32 c, int32_t count );
849 * @brief Unescape a string of characters and write the resulting Unicode characters to the destination buffer.
850 * @details The following escape sequences are recognized:\n
851 * \\uhhhh 4 hex digits; h in [0-9A-Fa-f] \\Uhhhhhhhh 8 hex digits \\xhh 1-2 hex digits \\x{h...} 1-8 hex digits \\ooo 1-3 octal digits; o in [0-7] \\cX control-X; X is masked with 0x1F\n
852 * as well as the standard ANSI C escapes:\n
853 * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A, \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B, \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C\n
854 * Anything else following a backslash is generically escaped. For example, "[a\-z]" returns "[a-z]".\n
855 * If an escape sequence is ill-formed, this method returns an empty string. An example of an ill-formed sequence is "\\u" followed by fewer than 4 hex digits.
856 * @remarks The specific error code can be obtained using the get_last_result() method.
857 * Error codes are described in Exceptions section.
858 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
860 * @param[in] src a zero-terminated string of invariant characters
861 * @param[in] dest pointer to buffer to receive converted and unescaped text and, if there is room, a zero terminator. May be NULL for preflighting, in which case no #i18n_uchar characters will be written,
862 * but the return value will still be valid. On error, an empty string is stored here (if possible).
863 * @param[in] dest_capacity the number of #i18n_uchar characters that may be written at dest. Ignored if dest == NULL.
864 * @return the length of unescaped string.
865 * @exception #I18N_ERROR_NONE Success
866 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
867 * @see i18n_ustring_unescape_at()
869 int32_t i18n_ustring_unescape ( const char *src, i18n_uchar *dest, int32_t dest_capacity );
872 * @brief Unescape a single sequence.
873 * @details The character at offset-1 is assumed (without checking) to be a backslash. This method takes a callback pointer to a function that returns the #i18n_uchar at a given offset.
874 * By varying this callback, I18N functions are able to unescape char* strings, and UnicodeString objects.\n
875 * If offset is out of range, or if the escape sequence is ill-formed, (i18n_uchar32)0xFFFFFFFF is returned.
876 * See documentation of #i18n_ustring_unescape() for a list of recognized sequences.
877 * @remarks The specific error code can be obtained using the get_last_result() method.
878 * Error codes are described in Exceptions section.
879 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
881 * @param[in] char_at callback function that returns a #i18n_uchar of the source text given an offset and a context pointer.
882 * @param[in] offset pointer to the offset that will be passed to char_at. The offset value will be updated upon return to point after the last parsed character of the escape sequence.
883 * On error the offset is unchanged.
884 * @param[in] length the number of #i18n_uchar characters that may be written at dest. Ignored if dest == NULL.
885 * @param[in] context an opaque pointer passed directly into char_at.
887 * @return the character represented by the escape sequence at
888 * offset, or (i18n_uchar32)0xFFFFFFFF on error.
889 * @exception #I18N_ERROR_NONE Success
890 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
891 * @see i18n_ustring_unescape()
893 i18n_uchar32 i18n_ustring_unescape_at ( i18n_ustring_unescape_char_at_cb char_at, int32_t *offset, int32_t length, void *context );
896 * @brief Uppercases the characters in a string.
897 * @details Casing is locale-dependent and context-sensitive.
898 * The result may be longer or shorter than the original.
899 * The source string and the destination buffer are allowed to overlap.
900 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
902 * @param[out] dest A buffer for the result string\n The result will be zero-terminated if
903 * the buffer is large enough.
904 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
905 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the result
906 * without writing any of the result string.
907 * @param[in] src The original string
908 * @param[in] src_len The length of the original string\n
909 * If @c -1, then @a src must be zero-terminated.
910 * @param[in] locale The locale to consider, or "" for the root locale or @c NULL for the default locale.
911 * @param[out] error_code Must be a valid pointer to an error code value,
912 * which must not indicate a failure before the function call.
913 * @return The length of the result string. It may be greater than destCapacity. In that case,
914 * only some of the result was written to the destination buffer.
915 * @exception #I18N_ERROR_NONE Success
916 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
918 int32_t i18n_ustring_to_upper ( i18n_uchar *dest, int32_t dest_capacity, const i18n_uchar *src, int32_t src_len, const char *locale, i18n_error_code_e *error_code );
921 * @brief Lowercase the characters in a string.
922 * @details Casing is locale-dependent and context-sensitive. The result may be longer or shorter than the original. The source string and the destination buffer are allowed to overlap.
923 * The result may be longer or shorter than the original.
924 * The source string and the destination buffer are allowed to overlap.
925 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
927 * @param[out] dest A buffer for the result string. The result will be zero-terminated if the buffer is large enough.
928 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
929 * 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.
930 * @param[in] src The original string
931 * @param[in] src_len The length of the original string.\n
932 * If @c -1, then @a src must be zero-terminated.
933 * @param[in] locale The locale to consider, or "" for the root locale or @c NULL for the default locale.
934 * @param[out] error_code Must be a valid pointer to an error code value,
935 * which must not indicate a failure before the function call.
936 * @return The length of the result string. It may be greater than destCapacity. In that case,
937 * only some of the result was written to the destination buffer.
938 * @exception #I18N_ERROR_NONE Success
939 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
941 int32_t i18n_ustring_to_lower ( i18n_uchar *dest, int32_t dest_capacity, const i18n_uchar *src, int32_t src_len, const char *locale, i18n_error_code_e *error_code );
944 * @brief Titlecases a string.
945 * @details Casing is locale-dependent and context-sensitive.
946 * Titlecasing uses a break iterator to find the first characters of words
947 * that are to be titlecased. It titlecases those characters and lowercases
950 * @remarks The specific error code can be obtained using the get_last_result() method.
951 * Error codes are described in Exceptions section and in #i18n_error_code_e description.
953 * The titlecase break iterator can be provided to customize arbitrary
954 * styles, using rules and dictionaries beyond the standard iterators.
955 * It may be more efficient to always provide an iterator to avoid
956 * opening and closing one for each string.
957 * The standard titlecase iterator for the root locale implements the
958 * algorithm of Unicode TR 21.\n
959 * The result may be longer or shorter than the original.
960 * The source string and the destination buffer are allowed to overlap.
963 * @param[out] dest A buffer for the result string.\n
964 * The result will be zero-terminated if the buffer is large enough.
965 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters.\n
966 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the result
967 * without writing any of the result string.
968 * @param[in] src The original string
969 * @param[in] src_len The length of the original string.\n If @c -1, then @a src must be zero-terminated.
970 * @param[in] title_iter A break iterator to find the first characters of words
971 * that are to be titlecased.\n
972 * If none are provided (@c NULL), then a standard titlecase
973 * break iterator is opened.
974 * @param[in] locale The locale to consider, or "" for the root locale or @c NULL for the default locale.
975 * @return The length of the result string. It may be greater than dest_capacity. In that case,
976 * only some of the result were written to the destination buffer.
977 * @exception #I18N_ERROR_NONE Success
978 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
980 int32_t i18n_ustring_to_title_new ( i18n_uchar *dest, int32_t dest_capacity, const i18n_uchar *src, int32_t src_len, i18n_ubreak_iterator_h title_iter, const char *locale);
983 * @brief Case-folds the characters in a string.
984 * @details Case-folding is locale-independent and not context-sensitive,
985 * but there is an option for whether to include or exclude mappings for dotted I and dotless i.\n
986 * The result may be longer or shorter than the original.
987 * The source string and the destination buffer are allowed to overlap.
988 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
990 * @param[out] dest A buffer for the result string\n
991 * The result will be zero-terminated if the buffer is large enough.
992 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
993 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the result
994 * without writing any of the result string.
995 * @param[in] src The original string
996 * @param[in] src_len The length of the original string.\n If @c -1, then @a src must be zero-terminated.
997 * @param[in] options Either #I18N_USTRING_U_FOLD_CASE_DEFAULT or #I18N_USTRING_U_FOLD_CASE_EXCLUDE_SPECIAL_I
998 * @param[out] error_code Must be a valid pointer to an error code value,
999 * which must not indicate a failure before the function call.
1000 * @return The length of the result string. It may be greater than destCapacity. In that case,
1001 * only some of the result was written to the destination buffer.
1002 * @exception #I18N_ERROR_NONE Success
1003 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1005 int32_t i18n_ustring_fold_case ( i18n_uchar *dest, int32_t dest_capacity, const i18n_uchar *src, int32_t src_len, uint32_t options, i18n_error_code_e *error_code );
1008 * @brief Convert a UTF-16 string to a wchar_t string.
1009 * @details If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then this function simply calls the fast, dedicated function for that.
1010 * Otherwise, two conversions UTF-16 -> default charset -> wchar_t* are performed.
1011 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1013 * @param[out] dest A buffer for the result string. The result will be zero-terminated if the buffer is large enough.
1014 * @param[in] dest_capacity The size of the buffer (number of wchar_t's).\n
1015 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the result
1016 * without writing any of the result string (pre-flighting).
1017 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1018 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
1019 * @param[in] src The original source string.
1020 * @param[in] src_len The length of the original string.\n If @c -1, then @a src must be zero-terminated.
1021 * @param[out] error_code Must be a valid pointer to an error code value,
1022 * which must not indicate a failure before the function call.
1023 * @return The pointer to destination buffer.
1024 * @exception #I18N_ERROR_NONE Success
1025 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1027 wchar_t* i18n_ustring_to_WCS ( wchar_t *dest, int32_t dest_capacity, int32_t *dest_len, const i18n_uchar *src, int32_t src_len, i18n_error_code_e *error_code );
1030 * @brief Convert a wchar_t string to UTF-16.
1031 * @details If it is known at compile time that wchar_t strings are in UTF-16 or UTF-32, then this function simply calls the fast, dedicated function for that.
1032 * Otherwise, two conversions wchar_t* -> default charset -> UTF-16 are performed.
1033 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1035 * @param[out] dest A buffer for the result string. The result will be zero-terminated if the buffer is large enough.
1036 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters).\n
1037 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the result
1038 * without writing any of the result string (pre-flighting).
1039 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1040 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding to the transformation of all the input units, even in case of a buffer overflow.
1041 * @param[in] src The original source string.
1042 * @param[in] src_len The length of the original string.\n If @c -1, then @a src must be zero-terminated.
1043 * @param[out] error_code Must be a valid pointer to an error code value,
1044 * which must not indicate a failure before the function call.
1045 * @return The pointer to destination buffer.
1046 * @exception #I18N_ERROR_NONE Success
1047 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1049 i18n_uchar* i18n_ustring_from_WCS ( i18n_uchar *dest, int32_t dest_capacity, int32_t *dest_len, const wchar_t *src, int32_t src_len, i18n_error_code_e *error_code );
1052 * @brief Converts a UTF-16 string to UTF-8.
1053 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1054 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1056 * @param[out] dest A buffer for the result string.\n
1057 * The result will be zero-terminated if the buffer is large enough.
1058 * @param[in] dest_capacity The size of the buffer (number of chars)\n
1059 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1060 * result without writing any of the result string (pre-flighting).
1061 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1062 * If dest_len!=NULL then *dest_len is always set to the
1063 * number of output units corresponding to the transformation of
1064 * all the input units, even in case of a buffer overflow.
1065 * @param[in] src The original source string
1066 * @param[in] src_len The length of the original string.\n
1067 * If @c -1, then @a src must be zero-terminated.
1068 * @param[out] error_code Must be a valid pointer to an error code value,
1069 * which must not indicate a failure before the function call.
1070 * @return The pointer to destination buffer.
1071 * @exception #I18N_ERROR_NONE Success
1072 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1073 * @see i18n_ustring_from_UTF8()
1075 char* i18n_ustring_to_UTF8 ( char *dest, int32_t dest_capacity, int32_t *dest_len, const i18n_uchar *src, int32_t src_len, i18n_error_code_e *error_code );
1078 * @brief Converts a UTF-8 string to UTF-16.
1079 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1080 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1082 * @param[out] dest A buffer for the result string.\n
1083 * The result will be zero-terminated if the buffer is large enough.
1084 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
1085 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1086 * result without writing any of the result string (pre-flighting).
1087 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1088 * If dest_len!=NULL then *dest_len is always set to the
1089 * number of output units corresponding to the transformation of
1090 * all the input units, even in case of a buffer overflow.
1091 * @param[in] src The original source string
1092 * @param[in] src_len The length of the original string.\n
1093 * If @c -1, then @a src must be zero-terminated.
1094 * @param[out] error_code Must be a valid pointer to an error code value,
1095 * which must not indicate a failure before the function call.
1096 * @return The pointer to destination buffer.
1097 * @exception #I18N_ERROR_NONE Success
1098 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1100 i18n_uchar* i18n_ustring_from_UTF8 ( i18n_uchar *dest, int32_t dest_capacity, int32_t *dest_len, const char *src, int32_t src_len, i18n_error_code_e *error_code );
1103 * @brief Convert a UTF-16 string to UTF-8.
1104 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1105 * Same as #i18n_ustring_to_UTF8() except for the additional sub_char which is output for illegal input sequences, instead of stopping with the #I18N_ERROR_INVALID_CHAR_FOUND error code.
1106 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1108 * @param[out] dest A buffer for the result string.\n
1109 * The result will be zero-terminated if the buffer is large enough.
1110 * @param[in] dest_capacity The size of the buffer (number of chars)\n
1111 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1112 * result without writing any of the result string (pre-flighting).
1113 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1114 * If dest_len!=NULL then *dest_len is always set to the
1115 * number of output units corresponding to the transformation of
1116 * all the input units, even in case of a buffer overflow.
1117 * @param[in] src The original source string
1118 * @param[in] src_len The length of the original string.\n
1119 * If @c -1, then @a src must be zero-terminated.
1120 * @param[in] sub_char The substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with #I18N_ERROR_INVALID_CHAR_FOUND instead.
1121 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1122 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1123 * @param[out] num_substitutions Output parameter receiving the number of substitutions if sub_char>=0. Set to 0 if no substitutions occur or sub_char<0. num_substitutions can be NULL.
1124 * @param[out] error_code Pointer to a standard ICU error code. Its input value must
1125 * pass the U_SUCCESS() test, or else the function returns
1126 * immediately. Check for U_FAILURE() on output or use with
1127 * function chaining. (See User Guide for details.)
1128 * @return The pointer to destination buffer.
1129 * @exception #I18N_ERROR_NONE Success
1130 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1131 * @see i18n_ustring_to_UTF8()
1132 * @see i18n_ustring_from_UTF8_with_sub()
1134 char* i18n_ustring_to_UTF8_with_sub ( char *dest, int32_t dest_capacity, int32_t *dest_len, const i18n_uchar *src, int32_t src_len, i18n_uchar32 sub_char, int32_t *num_substitutions, i18n_error_code_e *error_code );
1137 * @brief Convert a UTF-8 string to UTF-16.
1138 * @details Same as #i18n_ustring_from_UTF8() except for the additional sub_char which is output for illegal input sequences, instead of stopping with the #I18N_ERROR_INVALID_CHAR_FOUND error code.
1139 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1141 * @param[out] dest A buffer for the result string.\n
1142 * The result will be zero-terminated if the buffer is large enough.
1143 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
1144 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1145 * result without writing any of the result string (pre-flighting).
1146 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1147 * If dest_len!=NULL then *dest_len is always set to the
1148 * number of output units corresponding to the transformation of
1149 * all the input units, even in case of a buffer overflow.
1150 * @param[in] src The original source string
1151 * @param[in] src_len The length of the original string.\n
1152 * If @c -1, then @a src must be zero-terminated.
1153 * @param[in] sub_char The substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with #I18N_ERROR_INVALID_CHAR_FOUND instead.
1154 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1155 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1156 * @param[out] num_substitutions Output parameter receiving the number of substitutions if sub_char>=0. Set to 0 if no substitutions occur or sub_char<0. num_substitutions can be NULL.
1157 * @param[out] error_code Pointer to a standard ICU error code. Its input value must
1158 * pass the U_SUCCESS() test, or else the function returns
1159 * immediately. Check for U_FAILURE() on output or use with
1160 * function chaining. (See User Guide for details.)
1161 * @return The pointer to destination buffer.
1162 * @exception #I18N_ERROR_NONE Success
1163 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1164 * @see i18n_ustring_from_UTF8()
1165 * @see i18n_ustring_from_UTF8_lenient()
1166 * @see i18n_ustring_to_UTF8_with_sub()
1168 i18n_uchar* i18n_ustring_from_UTF8_with_sub ( i18n_uchar *dest, int32_t dest_capacity, int32_t *dest_len, const char *src, int32_t src_len, i18n_uchar32 sub_char,
1169 int32_t *num_substitutions, i18n_error_code_e *error_code );
1172 * @brief Convert a UTF-8 string to UTF-16.
1173 * @details Same as i18n_ustring_from_UTF8() except that this function is designed to be very fast, which it achieves by being lenient about malformed UTF-8 sequences.
1174 * This function is intended for use in environments where UTF-8 text is expected to be well-formed.\n
1175 * Its semantics are:
1176 * - Well-formed UTF-8 text is correctly converted to well-formed UTF-16 text.\n
1177 * - The function will not read beyond the input string, nor write beyond the dest_capacity.\n
1178 * - Malformed UTF-8 results in "garbage" 16-bit Unicode strings which may not be well-formed UTF-16. The function will resynchronize to valid code point boundaries within a small number of code points after an illegal sequence.\n
1179 * - Non-shortest forms are not detected and will result in "spoofing" output.\n
1180 * For further performance improvement, if src_len is given (>=0), then it must be dest_capacity>=src_len.\n
1181 * There is no inverse i18n_ustring_to_UTF8_lenient() function because there is practically no performance gain from not checking that a UTF-16 string is well-formed.
1182 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1184 * @param[out] dest A buffer for the result string.\n
1185 * The result will be zero-terminated if the buffer is large enough.
1186 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
1187 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1188 * result without writing any of the result string (pre-flighting).
1189 * Unlike for other I18N functions, if src_len>=0 then it must be dest_capacity>=src_len.
1190 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1191 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1192 * to the transformation of all the input units, even in case of a buffer overflow.
1193 * Unlike for other I18N functions, if src_len>=0 but dest_capacity<src_len, then *dest_len will be
1194 * set to src_len (and I18N_U_BUFFER_OVERFLOW_ERROR will be set) regardless of the actual result length.
1195 * @param[in] src The original source string
1196 * @param[in] src_len The length of the original string.\n
1197 * If @c -1, then @a src must be zero-terminated.
1198 * @param[out] error_code Pointer to a standard ICU error code. Its input value must
1199 * pass the U_SUCCESS() test, or else the function returns
1200 * immediately. Check for U_FAILURE() on output or use with
1201 * function chaining. (See User Guide for details.)
1202 * @return The pointer to destination buffer.
1203 * @exception #I18N_ERROR_NONE Success
1204 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1205 * @see i18n_ustring_from_UTF8()
1206 * @see i18n_ustring_to_UTF8_with_sub()
1207 * @see i18n_ustring_from_UTF8_with_sub()
1209 i18n_uchar* i18n_ustring_from_UTF8_lenient ( i18n_uchar *dest, int32_t dest_capacity, int32_t *dest_len, const char *src, int32_t src_len, i18n_error_code_e *error_code );
1212 * @brief Convert a UTF-16 string to UTF-32.
1213 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1214 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1216 * @param[out] dest A buffer for the result string.\n
1217 * The result will be zero-terminated if the buffer is large enough.
1218 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar32 characters)\n
1219 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1220 * result without writing any of the result string (pre-flighting).
1221 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1222 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1223 * to the transformation of all the input units, even in case of a buffer overflow.
1224 * @param[in] src The original source string
1225 * @param[in] src_len The length of the original string.\n
1226 * If @c -1, then @a src must be zero-terminated.
1227 * @param[out] error_code Must be a valid pointer to an error code value,
1228 * which must not indicate a failure before the function call.
1229 * @return The pointer to destination buffer.
1230 * @exception #I18N_ERROR_NONE Success
1231 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1232 * @see i18n_ustring_to_UTF32_with_sub()
1233 * @see i18n_ustring_from_UTF32()
1235 i18n_uchar32* i18n_ustring_to_UTF32 ( i18n_uchar32 *dest, int32_t dest_capacity, int32_t *dest_len, const i18n_uchar *src, int32_t src_len, i18n_error_code_e *error_code );
1238 * @brief Convert a UTF-32 string to UTF-16.
1239 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1240 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1242 * @param[out] dest A buffer for the result string.\n
1243 * The result will be zero-terminated if the buffer is large enough.
1244 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
1245 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1246 * result without writing any of the result string (pre-flighting).
1247 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1248 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1249 * to the transformation of all the input units, even in case of a buffer overflow.
1250 * @param[in] src The original source string
1251 * @param[in] src_len The length of the original string.\n
1252 * If @c -1, then @a src must be zero-terminated.
1254 * @param[out] error_code Must be a valid pointer to an error code value,
1255 * which must not indicate a failure before the function call.
1256 * @return The pointer to destination buffer.
1257 * @exception #I18N_ERROR_NONE Success
1258 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1259 * @see i18n_ustring_from_UTF32_with_sub()
1260 * @see i18n_ustring_to_UTF32()
1262 i18n_uchar* i18n_ustring_from_UTF32 ( i18n_uchar *dest, int32_t dest_capacity, int32_t *dest_len, const i18n_uchar32 *src, int32_t src_len, i18n_error_code_e *error_code );
1265 * @brief Convert a UTF-16 string to UTF-32.
1266 * @details Same as #i18n_ustring_to_UTF32() except for the additional sub_char which is output for illegal input sequences, instead of stopping with the #I18N_ERROR_INVALID_CHAR_FOUND error code.
1267 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1269 * @param[out] dest A buffer for the result string.\n
1270 * The result will be zero-terminated if the buffer is large enough.
1271 * @param[in] dest_capacity The size of the buffer (number of i18n_char32s)\n
1272 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1273 * result without writing any of the result string (pre-flighting).
1274 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1275 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1276 * to the transformation of all the input units, even in case of a buffer overflow.
1277 * @param[in] src The original source string
1278 * @param[in] src_len The length of the original string.\n
1279 * If @c -1, then @a src must be zero-terminated.
1280 * @param[in] sub_char The substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with #I18N_ERROR_INVALID_CHAR_FOUND instead.
1281 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1282 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1283 * @param[out] num_substitutions Output parameter receiving the number of substitutions if sub_char>=0. Set to 0 if no substitutions occur or sub_char<0. num_substitutions can be NULL.
1284 * @param[out] error_code Pointer to a standard ICU error code. Its input value must
1285 * pass the U_SUCCESS() test, or else the function returns
1286 * immediately. Check for U_FAILURE() on output or use with
1287 * function chaining. (See User Guide for details.)
1288 * @return The pointer to destination buffer.
1289 * @exception #I18N_ERROR_NONE Success
1290 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1291 * @see i18n_ustring_to_UTF32()
1292 * @see i18n_ustring_from_UTF32_with_sub()
1294 i18n_uchar32* i18n_ustring_to_UTF32_with_sub ( i18n_uchar32 *dest, int32_t dest_capacity, int32_t *dest_len, const i18n_uchar *src, int32_t src_len,
1295 i18n_uchar32 sub_char, int32_t *num_substitutions, i18n_error_code_e *error_code );
1298 * @brief Convert a UTF-32 string to UTF-16.
1299 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1300 * Same as #i18n_ustring_from_UTF32() except for the additional sub_char which is output for illegal input sequences, instead of stopping with the #I18N_ERROR_INVALID_CHAR_FOUND error code.
1301 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1303 * @param[out] dest A buffer for the result string.\n
1304 * The result will be zero-terminated if the buffer is large enough.
1305 * @param[in] dest_capacity The size of the buffer (number of i18n_chars)\n
1306 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1307 * result without writing any of the result string (pre-flighting).
1308 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1309 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1310 * to the transformation of all the input units, even in case of a buffer overflow.
1311 * @param[in] src The original source string
1312 * @param[in] src_len The length of the original string.\n
1313 * If @c -1, then @a src must be zero-terminated.
1314 * @param[in] sub_char The substitution character to use in place of an illegal input sequence, or U_SENTINEL if the function is to return with #I18N_ERROR_INVALID_CHAR_FOUND instead.
1315 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1316 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1317 * @param[out] num_substitutions Output parameter receiving the number of substitutions if sub_char>=0. Set to 0 if no substitutions occur or sub_char<0. num_substitutions can be NULL.
1318 * @param[out] error_code Pointer to a standard ICU error code. Its input value must
1319 * pass the U_SUCCESS() test, or else the function returns
1320 * immediately. Check for U_FAILURE() on output or use with
1321 * function chaining. (See User Guide for details.)
1322 * @return[out] The pointer to destination buffer.
1324 * @exception #I18N_ERROR_NONE Success
1325 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1326 * @see i18n_ustring_from_UTF32()
1327 * @see i18n_ustring_to_UTF32_with_sub()
1329 i18n_uchar* i18n_ustring_from_UTF32_with_sub ( i18n_uchar *dest, int32_t dest_capacity, int32_t *dest_len, const i18n_uchar32 *src, int32_t src_len, i18n_uchar32 sub_char, int32_t *num_substitutions, i18n_error_code_e *error_code );
1339 #endif /* __UTILS_I18N_USTRING_H__*/