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 * 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.
1105 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1107 * @param[out] dest A buffer for the result string.\n
1108 * The result will be zero-terminated if the buffer is large enough.
1109 * @param[in] dest_capacity The size of the buffer (number of chars)\n
1110 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1111 * result without writing any of the result string (pre-flighting).
1112 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1113 * If dest_len!=NULL then *dest_len is always set to the
1114 * number of output units corresponding to the transformation of
1115 * all the input units, even in case of a buffer overflow.
1116 * @param[in] src The original source string
1117 * @param[in] src_len The length of the original string.\n
1118 * If @c -1, then @a src must be zero-terminated.
1119 * @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.
1120 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1121 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1122 * @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.
1123 * @param[out] error_code Must be a valid pointer to an error code value,
1124 * which must not indicate a failure before the function call.
1125 * @return The pointer to destination buffer.
1126 * @exception #I18N_ERROR_NONE Success
1127 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1128 * @see i18n_ustring_to_UTF8()
1129 * @see i18n_ustring_from_UTF8_with_sub()
1131 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);
1134 * @brief Convert a UTF-8 string to UTF-16.
1135 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1137 * @param[out] dest A buffer for the result string.\n
1138 * The result will be zero-terminated if the buffer is large enough.
1139 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
1140 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1141 * result without writing any of the result string (pre-flighting).
1142 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1143 * If dest_len!=NULL then *dest_len is always set to the
1144 * number of output units corresponding to the transformation of
1145 * all the input units, even in case of a buffer overflow.
1146 * @param[in] src The original source string
1147 * @param[in] src_len The length of the original string.\n
1148 * If @c -1, then @a src must be zero-terminated.
1149 * @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.
1150 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1151 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1152 * @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.
1153 * @param[out] error_code Must be a valid pointer to an error code value,
1154 * which must not indicate a failure before the function call.
1155 * @return The pointer to destination buffer.
1156 * @exception #I18N_ERROR_NONE Success
1157 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1158 * @see i18n_ustring_from_UTF8()
1159 * @see i18n_ustring_from_UTF8_lenient()
1160 * @see i18n_ustring_to_UTF8_with_sub()
1162 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,
1163 int32_t *num_substitutions, i18n_error_code_e *error_code);
1166 * @brief Convert a UTF-8 string to UTF-16.
1167 * @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.
1168 * This function is intended for use in environments where UTF-8 text is expected to be well-formed.\n
1169 * Its semantics are:
1170 * - Well-formed UTF-8 text is correctly converted to well-formed UTF-16 text.\n
1171 * - The function will not read beyond the input string, nor write beyond the dest_capacity.\n
1172 * - 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
1173 * - Non-shortest forms are not detected and will result in "spoofing" output.\n
1174 * For further performance improvement, if src_len is given (>=0), then it must be dest_capacity>=src_len.\n
1175 * 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.
1176 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1178 * @param[out] dest A buffer for the result string.\n
1179 * The result will be zero-terminated if the buffer is large enough.
1180 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
1181 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1182 * result without writing any of the result string (pre-flighting).
1183 * Unlike for other I18N functions, if src_len>=0 then it must be dest_capacity>=src_len.
1184 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1185 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1186 * to the transformation of all the input units, even in case of a buffer overflow.
1187 * Unlike for other I18N functions, if src_len>=0 but dest_capacity<src_len, then *dest_len will be
1188 * set to src_len (and I18N_U_BUFFER_OVERFLOW_ERROR will be set) regardless of the actual result length.
1189 * @param[in] src The original source string
1190 * @param[in] src_len The length of the original string.\n
1191 * If @c -1, then @a src must be zero-terminated.
1192 * @param[out] error_code Must be a valid pointer to an error code value,
1193 * which must not indicate a failure before the function call.
1194 * @return The pointer to destination buffer.
1195 * @exception #I18N_ERROR_NONE Success
1196 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1197 * @see i18n_ustring_from_UTF8()
1198 * @see i18n_ustring_to_UTF8_with_sub()
1199 * @see i18n_ustring_from_UTF8_with_sub()
1201 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);
1204 * @brief Convert a UTF-16 string to UTF-32.
1205 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1206 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1208 * @param[out] dest A buffer for the result string.\n
1209 * The result will be zero-terminated if the buffer is large enough.
1210 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar32 characters)\n
1211 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1212 * result without writing any of the result string (pre-flighting).
1213 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1214 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1215 * to the transformation of all the input units, even in case of a buffer overflow.
1216 * @param[in] src The original source string
1217 * @param[in] src_len The length of the original string.\n
1218 * If @c -1, then @a src must be zero-terminated.
1219 * @param[out] error_code Must be a valid pointer to an error code value,
1220 * which must not indicate a failure before the function call.
1221 * @return The pointer to destination buffer.
1222 * @exception #I18N_ERROR_NONE Success
1223 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1224 * @see i18n_ustring_to_UTF32_with_sub()
1225 * @see i18n_ustring_from_UTF32()
1227 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);
1230 * @brief Convert a UTF-32 string to UTF-16.
1231 * @details If the input string is not well-formed, then the #I18N_ERROR_INVALID_CHAR_FOUND error code is set.
1232 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1234 * @param[out] dest A buffer for the result string.\n
1235 * The result will be zero-terminated if the buffer is large enough.
1236 * @param[in] dest_capacity The size of the buffer (number of #i18n_uchar characters)\n
1237 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1238 * result without writing any of the result string (pre-flighting).
1239 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1240 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1241 * to the transformation of all the input units, even in case of a buffer overflow.
1242 * @param[in] src The original source string
1243 * @param[in] src_len The length of the original string.\n
1244 * If @c -1, then @a src must be zero-terminated.
1245 * @param[out] error_code Must be a valid pointer to an error code value,
1246 * which must not indicate a failure before the function call.
1247 * @return The pointer to destination buffer.
1248 * @exception #I18N_ERROR_NONE Success
1249 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1250 * @see i18n_ustring_from_UTF32_with_sub()
1251 * @see i18n_ustring_to_UTF32()
1253 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);
1256 * @brief Convert a UTF-16 string to UTF-32.
1257 * @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.
1258 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1260 * @param[out] dest A buffer for the result string.\n
1261 * The result will be zero-terminated if the buffer is large enough.
1262 * @param[in] dest_capacity The size of the buffer (number of i18n_char32s)\n
1263 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1264 * result without writing any of the result string (pre-flighting).
1265 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1266 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1267 * to the transformation of all the input units, even in case of a buffer overflow.
1268 * @param[in] src The original source string
1269 * @param[in] src_len The length of the original string.\n
1270 * If @c -1, then @a src must be zero-terminated.
1271 * @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.
1272 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1273 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1274 * @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.
1275 * @param[out] error_code Must be a valid pointer to an error code value,
1276 * which must not indicate a failure before the function call.
1277 * @return The pointer to destination buffer.
1278 * @exception #I18N_ERROR_NONE Success
1279 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1280 * @see i18n_ustring_to_UTF32()
1281 * @see i18n_ustring_from_UTF32_with_sub()
1283 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,
1284 i18n_uchar32 sub_char, int32_t *num_substitutions, i18n_error_code_e *error_code);
1287 * @brief Convert a UTF-32 string to UTF-16.
1288 * 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.
1289 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1291 * @param[out] dest A buffer for the result string.\n
1292 * The result will be zero-terminated if the buffer is large enough.
1293 * @param[in] dest_capacity The size of the buffer (number of i18n_chars)\n
1294 * If it is @c 0, then @a dest may be @c NULL and the function will only return the length of the
1295 * result without writing any of the result string (pre-flighting).
1296 * @param[out] dest_len A pointer to receive the number of units written to the destination.\n
1297 * If dest_len!=NULL then *dest_len is always set to the number of output units corresponding
1298 * to the transformation of all the input units, even in case of a buffer overflow.
1299 * @param[in] src The original source string
1300 * @param[in] src_len The length of the original string.\n
1301 * If @c -1, then @a src must be zero-terminated.
1302 * @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.
1303 * A substitution character can be any valid Unicode code point (up to U+10FFFF) except for surrogate code points (U+D800..U+DFFF).
1304 * The recommended value is U+FFFD "REPLACEMENT CHARACTER".
1305 * @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.
1306 * @param[out] error_code Must be a valid pointer to an error code value,
1307 * which must not indicate a failure before the function call.
1308 * @return The pointer to destination buffer.
1310 * @exception #I18N_ERROR_NONE Success
1311 * @exception #I18N_ERROR_INVALID_PARAMETER Invalid function parameter
1312 * @see i18n_ustring_from_UTF32()
1313 * @see i18n_ustring_to_UTF32_with_sub()
1315 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);
1325 #endif /* __UTILS_I18N_USTRING_H__*/