nss: upgrade to release 3.73
[LibreOffice.git] / include / rtl / ustring.h
blob9e61df9746184c4d66075fd99608a6755214735e
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 * This file incorporates work covered by the following license notice:
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
20 #ifndef INCLUDED_RTL_USTRING_H
21 #define INCLUDED_RTL_USTRING_H
23 #include "sal/config.h"
25 #include "osl/interlck.h"
26 #include "rtl/string.h"
27 #include "rtl/textenc.h"
28 #include "sal/saldllapi.h"
29 #include "sal/types.h"
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
35 /* ======================================================================= */
37 /** Return the length of a string.
39 The length is equal to the number of 16-bit Unicode characters in the
40 string, without the terminating NUL character.
42 @param str
43 a null-terminated string.
45 @return
46 the length of the sequence of characters represented by this string,
47 excluding the terminating NUL character.
49 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_getLength(
50 const sal_Unicode * str ) SAL_THROW_EXTERN_C();
52 /** Compare two strings.
54 The comparison is based on the numeric value of each character in the
55 strings and returns a value indicating their relationship. This function
56 cannot be used for language-specific sorting. Both strings must be
57 null-terminated.
59 @param first
60 the first null-terminated string to be compared.
62 @param second
63 the second null-terminated string which is compared with the first one.
65 @return
66 0 if both strings are equal, a value less than 0 if the first string is
67 less than the second string, and a value greater than 0 if the first
68 string is greater than the second string.
70 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compare(
71 const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C();
73 /** Compare two strings.
75 The comparison is based on the numeric value of each character in the
76 strings and returns a value indicating their relationship. This function
77 cannot be used for language-specific sorting.
79 @param first
80 the first string to be compared. Need not be null-terminated, but must be
81 at least as long as the specified firstLen.
83 @param firstLen
84 the length of the first string.
86 @param second
87 the second string which is compared with the first one. Need not be
88 null-terminated, but must be at least as long as the specified secondLen.
90 @param secondLen
91 the length of the second string.
93 @return
94 0 if both strings are equal, a value less than 0 if the first string is
95 less than the second string, and a value greater than 0 if the first
96 string is greater than the second string.
98 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compare_WithLength(
99 const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
101 /** Compare two strings with a maximum count of characters.
103 The comparison is based on the numeric value of each character in the
104 strings and returns a value indicating their relationship. This function
105 cannot be used for language-specific sorting.
107 @param first
108 the first string to be compared. Need not be null-terminated, but must be
109 at least as long as the specified firstLen.
111 @param firstLen
112 the length of the first string.
114 @param second
115 the second string which is compared with the first one. Need not be
116 null-terminated, but must be at least as long as the specified secondLen.
118 @param secondLen
119 the length of the second string.
121 @param shortenedLen
122 the maximum number of characters to compare. This length can be greater
123 or smaller than the lengths of the two strings.
125 @return
126 0 if both substrings are equal, a value less than 0 if the first substring
127 is less than the second substring, and a value greater than 0 if the first
128 substring is greater than the second substring.
130 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_shortenedCompare_WithLength(
131 const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
133 /** Compare two strings from back to front.
135 The comparison is based on the numeric value of each character in the
136 strings and returns a value indicating their relationship. This function
137 cannot be used for language-specific sorting.
139 @param first
140 the first string to be compared. Need not be null-terminated, but must be
141 at least as long as the specified firstLen.
143 @param firstLen
144 the length of the first string.
146 @param second
147 the second string which is compared with the first one. Need not be
148 null-terminated, but must be at least as long as the specified secondLen.
150 @param secondLen
151 the length of the second string.
153 @return
154 0 if both strings are equal, a value less than 0 if the first string
155 compares less than the second string, and a value greater than 0 if the
156 first string compares greater than the second string.
158 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_reverseCompare_WithLength(
159 const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
161 /** Compare two strings from back to front for equality.
163 The comparison is based on the numeric value of each character in the
164 strings and returns 'true' if, and only if, both strings are equal.
165 This function cannot be used for language-specific sorting.
167 @param first
168 the first string to be compared. Need not be null-terminated, but must be
169 at least as long as the specified len.
171 @param second
172 the second string which is compared with the first one. Need not be
173 null-terminated, but must be at least as long as the specified len.
175 @param len
176 the length of both strings.
178 @return
179 true if both strings are equal, false if they are not equal.
182 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_ustr_asciil_reverseEquals_WithLength(
183 const sal_Unicode * first, const char * second, sal_Int32 len ) SAL_THROW_EXTERN_C();
185 /** Compare two strings, ignoring the case of ASCII characters.
187 The comparison is based on the numeric value of each character in the
188 strings and returns a value indicating their relationship. Character
189 values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
190 and 122 (ASCII a--z). This function cannot be used for language-specific
191 sorting. Both strings must be null-terminated.
193 @param first
194 the first null-terminated string to be compared.
196 @param second
197 the second null-terminated string which is compared with the first one.
199 @return
200 0 if both strings are equal, a value less than 0 if the first string is
201 less than the second string, and a value greater than 0 if the first
202 string is greater than the second string.
204 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase(
205 const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C();
207 /** Compare two strings, ignoring the case of ASCII characters.
209 The comparison is based on the numeric value of each character in the
210 strings and returns a value indicating their relationship. Character
211 values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
212 and 122 (ASCII a--z). This function cannot be used for language-specific
213 sorting.
215 @param first
216 the first string to be compared. Need not be null-terminated, but must be
217 at least as long as the specified firstLen.
219 @param firstLen
220 the length of the first string.
222 @param second
223 the second string which is compared with the first one. Need not be
224 null-terminated, but must be at least as long as the specified secondLen.
226 @param secondLen
227 the length of the second string.
229 @return
230 0 if both strings are equal, a value less than 0 if the first string is
231 less than the second string, and a value greater than 0 if the first
232 string is greater than the second string.
234 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase_WithLength(
235 const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
237 /** Compare two strings with a maximum count of characters, ignoring the case
238 of ASCII characters.
240 The comparison is based on the numeric value of each character in the
241 strings and returns a value indicating their relationship. Character
242 values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
243 and 122 (ASCII a--z). This function cannot be used for language-specific
244 sorting.
246 @param first
247 the first string to be compared. Need not be null-terminated, but must be
248 at least as long as the specified firstLen.
250 @param firstLen
251 the length of the first string.
253 @param second
254 the second string which is compared with the first one. Need not be
255 null-terminated, but must be at least as long as the specified secondLen.
257 @param secondLen
258 the length of the second string.
260 @param shortenedLen
261 the maximum number of characters to compare. This length can be greater
262 or smaller than the lengths of the two strings.
264 @return
265 0 if both substrings are equal, a value less than 0 if the first substring
266 is less than the second substring, and a value greater than 0 if the first
267 substring is greater than the second substring.
269 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_shortenedCompareIgnoreAsciiCase_WithLength(
270 const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
272 /** Compare two strings.
274 The comparison is based on the numeric value of each character in the
275 strings and returns a value indicating their relationship. This function
276 cannot be used for language-specific sorting. Both strings must be
277 null-terminated.
279 Since this function is optimized for performance, the ASCII character
280 values are not converted in any way. The caller has to make sure that
281 all ASCII characters are in the allowed range of 0 and 127, inclusive.
283 @param first
284 the first null-terminated string to be compared.
286 @param second
287 the second null-terminated ASCII string which is compared with the first
288 one.
290 @return
291 0 if both substrings are equal, a value less than 0 if the first substring
292 is less than the second substring, and a value greater than 0 if the first
293 substring is greater than the second substring.
295 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compare(
296 const sal_Unicode * first, const char * second ) SAL_THROW_EXTERN_C();
298 /** Compare two strings.
300 The comparison is based on the numeric value of each character in the
301 strings and returns a value indicating their relationship. This function
302 cannot be used for language-specific sorting.
304 Since this function is optimized for performance, the ASCII character
305 values are not converted in any way. The caller has to make sure that
306 all ASCII characters are in the allowed range of 0 and 127, inclusive.
308 @param first
309 the first string to be compared. Need not be null-terminated, but must be
310 at least as long as the specified firstLen.
312 @param firstLen
313 the length of the first string.
315 @param second
316 the second null-terminated ASCII string which is compared with the first
317 one.
319 @return
320 0 if both substrings are equal, a value less than 0 if the first substring
321 is less than the second substring, and a value greater than 0 if the first
322 substring is greater than the second substring.
324 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compare_WithLength(
325 const sal_Unicode * first, sal_Int32 firstLen, const char * second ) SAL_THROW_EXTERN_C();
327 /** Compare two strings with a maximum count of characters.
329 The comparison is based on the numeric value of each character in the
330 strings and returns a value indicating their relationship. This function
331 cannot be used for language-specific sorting.
333 Since this function is optimized for performance, the ASCII character
334 values are not converted in any way. The caller has to make sure that
335 all ASCII characters are in the allowed range of 0 and 127, inclusive.
337 @param first
338 the first string to be compared. Need not be null-terminated, but must be
339 at least as long as the specified firstLen.
341 @param firstLen
342 the length of the first string.
344 @param second
345 the second null-terminated ASCII string which is compared with the first
346 one.
348 @param shortenedLen
349 the maximum number of characters to compare. This length can be greater
350 or smaller than the lengths of the two strings.
352 @return
353 0 if both substrings are equal, a value less than 0 if the first substring
354 is less than the second substring, and a value greater than 0 if the first
355 substring is greater than the second substring.
357 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompare_WithLength(
358 const sal_Unicode * first, sal_Int32 firstLen, const char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
360 /** Compare two strings from back to front.
362 The comparison is based on the numeric value of each character in the
363 strings and returns a value indicating their relationship. This function
364 cannot be used for language-specific sorting.
366 Since this function is optimized for performance, the ASCII character
367 values are not converted in any way. The caller has to make sure that
368 all ASCII characters are in the allowed range of 0 and 127, inclusive.
370 @param first
371 the first string to be compared. Need not be null-terminated, but must be
372 at least as long as the specified firstLen.
374 @param firstLen
375 the length of the first string.
377 @param second
378 the second ASCII string which is compared with the first one. Need not be
379 null-terminated, but must be at least as long as the specified secondLen.
381 @param secondLen
382 the length of the second string.
384 @return
385 0 if both strings are equal, a value less than 0 if the first string
386 compares less than the second string, and a value greater than 0 if the
387 first string compares greater than the second string.
389 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_asciil_reverseCompare_WithLength(
390 const sal_Unicode * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
392 /** Compare two strings, ignoring the case of ASCII characters.
394 The comparison is based on the numeric value of each character in the
395 strings and returns a value indicating their relationship. Character
396 values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
397 and 122 (ASCII a--z). This function cannot be used for language-specific
398 sorting. Both strings must be null-terminated.
400 Since this function is optimized for performance, the ASCII character
401 values are not converted in any way. The caller has to make sure that
402 all ASCII characters are in the allowed range of 0 and 127, inclusive.
404 @param first
405 the first null-terminated string to be compared.
407 @param second
408 the second null-terminated ASCII string which is compared with the first
409 one.
411 @return
412 0 if both strings are equal, a value less than 0 if the first string is
413 less than the second string, and a value greater than 0 if the first
414 string is greater than the second string.
416 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase(
417 const sal_Unicode * first, const char * second ) SAL_THROW_EXTERN_C();
419 /** Compare two strings, ignoring the case of ASCII characters.
421 The comparison is based on the numeric value of each character in the
422 strings and returns a value indicating their relationship. Character
423 values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
424 and 122 (ASCII a--z). This function cannot be used for language-specific
425 sorting.
427 Since this function is optimized for performance, the ASCII character
428 values are not converted in any way. The caller has to make sure that
429 all ASCII characters are in the allowed range of 0 and 127, inclusive.
431 @param first
432 the first string to be compared. Need not be null-terminated, but must be
433 at least as long as the specified firstLen.
435 @param firstLen
436 the length of the first string.
438 @param second
439 the second null-terminated ASCII string which is compared with the first
440 one.
442 @return
443 0 if both strings are equal, a value less than 0 if the first string is
444 less than the second string, and a value greater than 0 if the first
445 string is greater than the second string.
447 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength(
448 const sal_Unicode * first, sal_Int32 firstLen, const char * second ) SAL_THROW_EXTERN_C();
450 /** Compare two strings, ignoring the case of ASCII characters.
452 The comparison is based on the numeric value of each character in the
453 strings and returns a value indicating their relationship. Character
454 values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
455 and 122 (ASCII a--z). This function cannot be used for language-specific
456 sorting.
458 Since this function is optimized for performance, the ASCII character
459 values are not converted in any way. The caller has to make sure that
460 all ASCII characters are in the allowed range of 0 and 127, inclusive.
462 @param first
463 the first string to be compared. Need not be null-terminated, but must be
464 at least as long as the specified firstLen.
466 @param firstLen
467 the length of the first string.
469 @param second
470 the second string which is compared with the first one. Need not be
471 null-terminated, but must be at least as long as the specified secondLen.
473 @param secondLen
474 the length of the second string.
476 @return
477 0 if both strings are equal, a value less than 0 if the first string is
478 less than the second string, and a value greater than 0 if the first
479 string is greater than the second string.
481 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths(
482 sal_Unicode const * first, sal_Int32 firstLen,
483 char const * second, sal_Int32 secondLen) SAL_THROW_EXTERN_C();
485 /** Compare two strings with a maximum count of characters, ignoring the case
486 of ASCII characters.
488 The comparison is based on the numeric value of each character in the
489 strings and returns a value indicating their relationship. Character
490 values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
491 and 122 (ASCII a--z). This function cannot be used for language-specific
492 sorting.
494 Since this function is optimized for performance, the ASCII character
495 values are not converted in any way. The caller has to make sure that
496 all ASCII characters are in the allowed range of 0 and 127, inclusive.
498 @param first
499 the first string to be compared. Need not be null-terminated, but must be
500 at least as long as the specified firstLen.
502 @param firstLen
503 the length of the first string.
505 @param second
506 the second null-terminated ASCII string which is compared with the first
507 one.
509 @param shortenedLen
510 the maximum number of characters to compare. This length can be greater
511 or smaller than the lengths of the two strings.
513 @return
514 0 if both substrings are equal, a value less than 0 if the first substring
515 is less than the second substring, and a value greater than 0 if the first
516 substring is greater than the second substring.
518 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength(
519 const sal_Unicode * first, sal_Int32 firstLen, const char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
521 /** Return a hash code for a string.
523 It is not allowed to store the hash code persistently, because later
524 versions could return other hash codes. The string must be
525 null-terminated.
527 @param str
528 a null-terminated string.
530 @return
531 a hash code for the given string.
533 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_hashCode(
534 const sal_Unicode * str ) SAL_THROW_EXTERN_C();
536 /** Return a hash code for a string.
538 It is not allowed to store the hash code persistently, because later
539 versions could return other hash codes.
541 @param str
542 a string. Need not be null-terminated, but must be at least as long as
543 the specified len.
545 @param len
546 the length of the string.
548 @return
549 a hash code for the given string.
551 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_hashCode_WithLength(
552 const sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
554 /** Search for the first occurrence of a character within a string.
556 The string must be null-terminated.
558 @param str
559 a null-terminated string.
561 @param ch
562 the character to be searched for.
564 @return
565 the index (starting at 0) of the first occurrence of the character in the
566 string, or -1 if the character does not occur.
568 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfChar(
569 const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
571 /** Search for the first occurrence of a character within a string.
573 @param str
574 a string. Need not be null-terminated, but must be at least as long as
575 the specified len.
577 @param len
578 the length of the string.
580 @param ch
581 the character to be searched for.
583 @return
584 the index (starting at 0) of the first occurrence of the character in the
585 string, or -1 if the character does not occur.
587 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfChar_WithLength(
588 const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C();
590 /** Search for the last occurrence of a character within a string.
592 The string must be null-terminated.
594 @param str
595 a null-terminated string.
597 @param ch
598 the character to be searched for.
600 @return
601 the index (starting at 0) of the last occurrence of the character in the
602 string, or -1 if the character does not occur. The returned value is
603 always smaller than the string length.
605 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar(
606 const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
608 /** Search for the last occurrence of a character within a string.
610 @param str
611 a string. Need not be null-terminated, but must be at least as long as
612 the specified len.
614 @param len
615 the length of the string.
617 @param ch
618 the character to be searched for.
620 @return
621 the index (starting at 0) of the last occurrence of the character in the
622 string, or -1 if the character does not occur. The returned value is
623 always smaller than the string length.
625 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar_WithLength(
626 const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C();
628 /** Search for the first occurrence of a substring within a string.
630 If subStr is empty, or both str and subStr are empty, -1 is returned.
631 Both strings must be null-terminated.
633 @param str
634 a null-terminated string.
636 @param subStr
637 the null-terminated substring to be searched for.
639 @return
640 the index (starting at 0) of the first character of the first occurrence
641 of the substring within the string, or -1 if the substring does not occur.
643 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfStr(
644 const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C();
646 /** Search for the first occurrence of a substring within a string.
648 If subStr is empty, or both str and subStr are empty, -1 is returned.
650 @param str
651 a string. Need not be null-terminated, but must be at least as long as
652 the specified len.
654 @param len
655 the length of the string.
657 @param subStr
658 the substring to be searched for. Need not be null-terminated, but must
659 be at least as long as the specified subLen.
661 @param subLen
662 the length of the substring.
664 @return
665 the index (starting at 0) of the first character of the first occurrence
666 of the substring within the string, or -1 if the substring does not occur.
668 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfStr_WithLength(
669 const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
671 /** Search for the first occurrence of an ASCII substring within a string.
673 @param str
674 a string. Need not be null-terminated, but must be at least as long as
675 the specified len.
677 @param len
678 the length of the string; must be non-negative.
680 @param subStr
681 the substring to be searched for. Need not be null-terminated, but must
682 be at least as long as the specified subLen. Must only contain characters
683 in the ASCII range 0x00--7F.
685 @param subLen
686 the length of the substring; must be non-negative.
688 @return
689 the index (starting at 0) of the first character of the first occurrence
690 of the substring within the string, or -1 if the substring does not occur.
691 If subLen is zero, -1 is returned.
693 @since UDK 3.2.7
695 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfAscii_WithLength(
696 sal_Unicode const * str, sal_Int32 len,
697 char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C();
699 /** Search for the last occurrence of a substring within a string.
701 If subStr is empty, or both str and subStr are empty, -1 is returned.
702 Both strings must be null-terminated.
704 @param str
705 a null-terminated string.
707 @param subStr
708 the null-terminated substring to be searched for.
710 @return
711 the index (starting at 0) of the first character of the last occurrence
712 of the substring within the string, or -1 if the substring does not occur.
714 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr(
715 const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C();
717 /** Search for the last occurrence of a substring within a string.
719 If subStr is empty, or both str and subStr are empty, -1 is returned.
721 @param str
722 a string. Need not be null-terminated, but must be at least as long as
723 the specified len.
725 @param len
726 the length of the string.
728 @param subStr
729 the substring to be searched for. Need not be null-terminated, but must
730 be at least as long as the specified subLen.
732 @param subLen
733 the length of the substring.
735 @return
736 the index (starting at 0) of the first character of the first occurrence
737 of the substring within the string, or -1 if the substring does not occur.
739 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr_WithLength(
740 const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
742 /** Search for the last occurrence of an ASCII substring within a string.
744 @param str
745 a string. Need not be null-terminated, but must be at least as long as
746 the specified len.
748 @param len
749 the length of the string; must be non-negative.
751 @param subStr
752 the substring to be searched for. Need not be null-terminated, but must
753 be at least as long as the specified subLen. Must only contain characters
754 in the ASCII range 0x00--7F.
756 @param subLen
757 the length of the substring; must be non-negative.
759 @return
760 the index (starting at 0) of the first character of the last occurrence
761 of the substring within the string, or -1 if the substring does not occur.
762 If subLen is zero, -1 is returned.
764 @since UDK 3.2.7
766 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfAscii_WithLength(
767 sal_Unicode const * str, sal_Int32 len,
768 char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C();
770 /** Replace all occurrences of a single character within a string.
772 If oldChar does not occur within str, then the string is not modified.
773 The string must be null-terminated.
775 @param str
776 a null-terminated string.
778 @param oldChar
779 the old character.
781 @param newChar
782 the new character.
784 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_replaceChar(
785 sal_Unicode * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
787 /** Replace all occurrences of a single character within a string.
789 If oldChar does not occur within str, then the string is not modified.
791 @param str
792 a string. Need not be null-terminated, but must be at least as long as
793 the specified len.
795 @param len
796 the length of the string.
798 @param oldChar
799 the old character.
801 @param newChar
802 the new character.
804 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_replaceChar_WithLength(
805 sal_Unicode * str, sal_Int32 len, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
807 /** Convert all ASCII uppercase letters to lowercase within a string.
809 The characters with values between 65 and 90 (ASCII A--Z) are replaced
810 with values between 97 and 122 (ASCII a--z). The string must be
811 null-terminated.
813 @param str
814 a null-terminated string.
816 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiLowerCase(
817 sal_Unicode * str ) SAL_THROW_EXTERN_C();
819 /** Convert all ASCII uppercase letters to lowercase within a string.
821 The characters with values between 65 and 90 (ASCII A--Z) are replaced
822 with values between 97 and 122 (ASCII a--z).
824 @param str
825 a string. Need not be null-terminated, but must be at least as long as
826 the specified len.
828 @param len
829 the length of the string.
831 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiLowerCase_WithLength(
832 sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
834 /** Convert all ASCII lowercase letters to uppercase within a string.
836 The characters with values between 97 and 122 (ASCII a--z) are replaced
837 with values between 65 and 90 (ASCII A--Z). The string must be
838 null-terminated.
840 @param str
841 a null-terminated string.
843 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiUpperCase(
844 sal_Unicode * str ) SAL_THROW_EXTERN_C();
846 /** Convert all ASCII lowercase letters to uppercase within a string.
848 The characters with values between 97 and 122 (ASCII a--z) are replaced
849 with values between 65 and 90 (ASCII A--Z).
851 @param str
852 a string. Need not be null-terminated, but must be at least as long as
853 the specified len.
855 @param len
856 the length of the string.
858 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiUpperCase_WithLength(
859 sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
861 /** Remove white space from both ends of a string.
863 All characters with values less than or equal to 32 (the space character)
864 are considered to be white space. This function cannot be used for
865 language-specific operations. The string must be null-terminated.
867 @param str
868 a null-terminated string.
870 @return
871 the new length of the string.
873 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_trim(
874 sal_Unicode * str ) SAL_THROW_EXTERN_C();
876 /** Remove white space from both ends of the string.
878 All characters with values less than or equal to 32 (the space character)
879 are considered to be white space. This function cannot be used for
880 language-specific operations. The string must be null-terminated.
882 @param str
883 a string. Need not be null-terminated, but must be at least as long as
884 the specified len.
886 @param len
887 the original length of the string.
889 @return
890 the new length of the string.
892 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_trim_WithLength(
893 sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
895 /** Create the string representation of a boolean.
897 If b is true, the buffer is filled with the string "true" and 5 is
898 returned. If b is false, the buffer is filled with the string "false" and
899 6 is returned. This function cannot be used for language-specific
900 operations.
902 @param str
903 a buffer that is big enough to hold the result and the terminating NUL
904 character. You should use the RTL_USTR_MAX_VALUEOFBOOLEAN define to
905 create a buffer that is big enough.
907 @param b
908 a boolean value.
910 @return
911 the length of the string.
913 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfBoolean(
914 sal_Unicode * str, sal_Bool b ) SAL_THROW_EXTERN_C();
915 #define RTL_USTR_MAX_VALUEOFBOOLEAN RTL_STR_MAX_VALUEOFBOOLEAN
917 /** Create the string representation of a character.
919 @param str
920 a buffer that is big enough to hold the result and the terminating NUL
921 character. You should use the RTL_USTR_MAX_VALUEOFCHAR define to create a
922 buffer that is big enough.
924 @param ch
925 a character value.
927 @return
928 the length of the string.
930 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfChar(
931 sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
932 #define RTL_USTR_MAX_VALUEOFCHAR RTL_STR_MAX_VALUEOFCHAR
934 /** Create the string representation of an integer.
936 This function cannot be used for language-specific operations.
938 @param str
939 a buffer that is big enough to hold the result and the terminating NUL
940 character. You should use the RTL_USTR_MAX_VALUEOFINT32 define to create
941 a buffer that is big enough.
943 @param i
944 an integer value.
946 @param radix
947 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
948 (36), inclusive.
950 @return
951 the length of the string.
953 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfInt32(
954 sal_Unicode * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C();
955 #define RTL_USTR_MIN_RADIX RTL_STR_MIN_RADIX
956 #define RTL_USTR_MAX_RADIX RTL_STR_MAX_RADIX
957 #define RTL_USTR_MAX_VALUEOFINT32 RTL_STR_MAX_VALUEOFINT32
959 /** Create the string representation of a long integer.
961 This function cannot be used for language-specific operations.
963 @param str
964 a buffer that is big enough to hold the result and the terminating NUL
965 character. You should use the RTL_USTR_MAX_VALUEOFINT64 define to create
966 a buffer that is big enough.
968 @param l
969 a long integer value.
971 @param radix
972 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
973 (36), inclusive.
975 @return
976 the length of the string.
978 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfInt64(
979 sal_Unicode * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
980 #define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64
982 /** Create the string representation of an unsigned long integer.
984 This function cannot be used for language-specific operations.
986 @param str
987 a buffer that is big enough to hold the result and the terminating NUL
988 character. You should use the RTL_USTR_MAX_VALUEOFUINT64 define to create
989 a buffer that is big enough.
991 @param l
992 a long integer value.
994 @param radix
995 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
996 (36), inclusive.
998 @return
999 the length of the string.
1001 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfUInt64(
1002 sal_Unicode * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1003 #define RTL_USTR_MAX_VALUEOFUINT64 RTL_STR_MAX_VALUEOFUINT64
1005 /** Create the string representation of a float.
1007 This function cannot be used for language-specific conversion.
1009 @param str
1010 a buffer that is big enough to hold the result and the terminating NUL
1011 character. You should use the RTL_USTR_MAX_VALUEOFFLOAT define to create
1012 a buffer that is big enough.
1014 @param f
1015 a float value.
1017 @return
1018 the length of the string.
1020 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfFloat(
1021 sal_Unicode * str, float f ) SAL_THROW_EXTERN_C();
1022 #define RTL_USTR_MAX_VALUEOFFLOAT RTL_STR_MAX_VALUEOFFLOAT
1024 /** Create the string representation of a double.
1026 This function cannot be used for language-specific conversion.
1028 @param str
1029 a buffer that is big enough to hold the result and the terminating NUL
1030 character. You should use the RTL_USTR_MAX_VALUEOFDOUBLE define to create
1031 a buffer that is big enough.
1033 @param d
1034 a double value.
1036 @return
1037 the length of the string.
1039 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfDouble(
1040 sal_Unicode * str, double d ) SAL_THROW_EXTERN_C();
1041 #define RTL_USTR_MAX_VALUEOFDOUBLE RTL_STR_MAX_VALUEOFDOUBLE
1043 /** Interpret a string as a boolean.
1045 This function cannot be used for language-specific conversion. The string
1046 must be null-terminated.
1048 @param str
1049 a null-terminated string.
1051 @return
1052 true if the string is "1" or "true" in any ASCII case, false otherwise.
1054 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_ustr_toBoolean(
1055 const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1057 /** Interpret a string as an integer.
1059 This function cannot be used for language-specific conversion. The string
1060 must be null-terminated.
1062 @param str
1063 a null-terminated string.
1065 @param radix
1066 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1067 (36), inclusive.
1069 @return
1070 the integer value represented by the string, or 0 if the string does not
1071 represent an integer.
1073 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_toInt32(
1074 const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1076 /** Interpret a string as an unsigned integer.
1078 This function cannot be used for language-specific conversion. The string
1079 must be null-terminated.
1081 @param str
1082 a null-terminated string.
1084 @param radix
1085 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1086 (36), inclusive.
1088 @return
1089 the unsigned integer value represented by the string, or 0 if the string
1090 does not represent an unsigned integer.
1092 @since LibreOffice 4.2
1094 SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_ustr_toUInt32(
1095 const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1097 /** Interpret a string as a long integer.
1099 This function cannot be used for language-specific conversion. The string
1100 must be null-terminated.
1102 @param str
1103 a null-terminated string.
1105 @param radix
1106 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1107 (36), inclusive.
1109 @return
1110 the long integer value represented by the string, or 0 if the string does
1111 not represent a long integer.
1113 SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_ustr_toInt64(
1114 const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1116 /** Interpret a string as a long integer.
1118 This function cannot be used for language-specific conversion. The string
1119 must be null-terminated.
1121 @param str
1122 a null-terminated string.
1124 @param radix
1125 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1126 (36), inclusive.
1128 @param nStrLength
1129 number of chars to process
1131 @return
1132 the long integer value represented by the string, or 0 if the string does
1133 not represent a long integer.
1135 @internal
1136 @since LibreOffice 6.4
1138 SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_ustr_toInt64_WithLength(
1139 const sal_Unicode * str, sal_Int16 radix, sal_Int32 nStrLength ) SAL_THROW_EXTERN_C();
1141 /** Interpret a string as an unsigned long integer.
1143 This function cannot be used for language-specific conversion. The string
1144 must be null-terminated.
1146 @param str
1147 a null-terminated string.
1149 @param radix
1150 the radix. Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1151 (36), inclusive.
1153 @return
1154 the unsigned long integer value represented by the string, or 0 if the
1155 string does not represent an unsigned long integer.
1157 @since LibreOffice 4.1
1159 SAL_DLLPUBLIC sal_uInt64 SAL_CALL rtl_ustr_toUInt64(
1160 const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1162 /** Interpret a string as a float.
1164 This function cannot be used for language-specific conversion. The string
1165 must be null-terminated.
1167 @param str
1168 a null-terminated string.
1170 @return
1171 the float value represented by the string, or 0.0 if the string does not
1172 represent a float.
1174 SAL_DLLPUBLIC float SAL_CALL rtl_ustr_toFloat(
1175 const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1177 /** Interpret a string as a double.
1179 This function cannot be used for language-specific conversion. The string
1180 must be null-terminated.
1182 @param str
1183 a null-terminated string.
1185 @return
1186 the float value represented by the string, or 0.0 if the string does not
1187 represent a double.
1189 SAL_DLLPUBLIC double SAL_CALL rtl_ustr_toDouble(
1190 const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1192 /* ======================================================================= */
1194 #if defined(_WIN32)
1195 #pragma pack(push, 4)
1196 #endif
1198 /** @cond INTERNAL */
1199 /** The implementation of a Unicode string.
1201 typedef struct SAL_DLLPUBLIC_RTTI _rtl_uString
1203 oslInterlockedCount refCount; /* opaque */
1204 sal_Int32 length;
1205 sal_Unicode buffer[1];
1206 } rtl_uString;
1207 /** @endcond */
1209 #if defined(_WIN32)
1210 #pragma pack(pop)
1211 #endif
1213 /* ----------------------------------------------------------------------- */
1215 /** Increment the reference count of a string.
1217 @param str
1218 a string.
1220 SAL_DLLPUBLIC void SAL_CALL rtl_uString_acquire(
1221 rtl_uString * str ) SAL_THROW_EXTERN_C() SAL_HOT;
1223 /** Decrement the reference count of a string.
1225 If the count goes to zero than the string data is deleted.
1227 @param str
1228 a string.
1230 SAL_DLLPUBLIC void SAL_CALL rtl_uString_release(
1231 rtl_uString * str ) SAL_THROW_EXTERN_C() SAL_HOT;
1233 /** Allocate a new string containing no characters.
1235 @param newStr
1236 pointer to the new string. The pointed-to data must be null or a valid
1237 string.
1239 SAL_DLLPUBLIC void SAL_CALL rtl_uString_new(
1240 rtl_uString ** newStr ) SAL_THROW_EXTERN_C();
1242 /** Allocate a new string containing space for a given number of characters.
1244 The reference count of the new string will be 1. The length of the string
1245 will be nLen. This function does not handle out-of-memory conditions.
1247 For failed allocation this method returns NULL.
1249 The characters of the capacity are not cleared, and the length is set to
1250 nLen, unlike the similar method of rtl_uString_new_WithLength which
1251 zeros out the buffer, and sets the length to 0. So should be somewhat
1252 more efficient for allocating a new string.
1254 call rtl_uString_release to release the string
1255 alternatively pass ownership to an OUString with
1256 rtl::OUString(newStr, SAL_NO_ACQUIRE);
1258 @param[in] nLen the number of characters. Must be >= 0.
1260 @return pointer to the new string.
1262 @since LibreOffice 4.1
1264 SAL_DLLPUBLIC rtl_uString * SAL_CALL rtl_uString_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C();
1266 /** Allocate a new string containing space for a given number of characters.
1268 If len is greater than zero, the reference count of the new string will be
1269 1. The values of all characters are set to 0 and the length of the string
1270 is 0. This function does not handle out-of-memory conditions.
1272 @param newStr
1273 pointer to the new string. The pointed-to data must be null or a valid
1274 string.
1276 @param nLen
1277 the number of characters.
1279 SAL_DLLPUBLIC void SAL_CALL rtl_uString_new_WithLength(
1280 rtl_uString ** newStr, sal_Int32 nLen ) SAL_THROW_EXTERN_C();
1282 /** Allocate a new string that contains a copy of another string.
1284 If the length of value is greater than zero, the reference count of the
1285 new string will be 1. This function does not handle out-of-memory
1286 conditions.
1288 @param newStr
1289 pointer to the new string. The pointed-to data must be null or a valid
1290 string.
1292 @param value
1293 a valid string.
1295 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromString(
1296 rtl_uString ** newStr, const rtl_uString * value ) SAL_THROW_EXTERN_C();
1298 /** Allocate a new string that contains a copy of a character array.
1300 If the length of value is greater than zero, the reference count of the
1301 new string will be 1. This function does not handle out-of-memory
1302 conditions.
1304 @param newStr
1305 pointer to the new string. The pointed-to data must be null or a valid
1306 string.
1308 @param value
1309 a null-terminated character array.
1311 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr(
1312 rtl_uString ** newStr, const sal_Unicode * value ) SAL_THROW_EXTERN_C();
1314 /** Allocate a new string that contains a copy of a character array.
1316 If the length of value is greater than zero, the reference count of the
1317 new string will be 1. This function does not handle out-of-memory
1318 conditions.
1320 @param newStr
1321 pointer to the new string. The pointed-to data must be null or a valid
1322 string.
1324 @param value
1325 a character array. Need not be null-terminated, but must be at least as
1326 long as the specified len.
1328 @param len
1329 the length of the character array.
1331 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr_WithLength(
1332 rtl_uString ** newStr, const sal_Unicode * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
1334 /** Allocate a new string that is a substring of this string.
1336 The substring begins at the specified beginIndex and contains count
1337 characters. Meaningless combinations such as negative beginIndex,
1338 or beginIndex + count greater than the length of the string have
1339 undefined behaviour.
1341 @param[out] newStr the specified substring.
1342 @param[in] from the String to take the substring from.
1343 @param[in] beginIndex the beginning index, inclusive.
1344 @param[in] count the number of characters.
1345 @return the specified substring.
1347 @since LibreOffice 4.0
1349 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromSubString(
1350 rtl_uString ** newStr, const rtl_uString * from,
1351 sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C();
1353 /** Allocate a new string that contains a copy of a character array.
1355 If the length of value is greater than zero, the reference count of the
1356 new string will be 1. This function does not handle out-of-memory
1357 conditions.
1359 Since this function is optimized for performance, the ASCII character
1360 values are not converted in any way. The caller has to make sure that
1361 all ASCII characters are in the allowed range of 0 and 127, inclusive.
1363 @param newStr
1364 pointer to the new string. The pointed-to data must be null or a valid
1365 string.
1367 @param value
1368 a null-terminated ASCII character array.
1370 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromAscii(
1371 rtl_uString ** newStr, const char * value ) SAL_THROW_EXTERN_C();
1374 @internal
1375 @since LibreOffice 3.6
1377 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromLiteral(
1378 rtl_uString ** newStr, const char * value, sal_Int32 len,
1379 sal_Int32 allocExtra ) SAL_THROW_EXTERN_C();
1381 /** Allocate a new string from an array of Unicode code points.
1383 @param newString
1384 a non-null pointer to a (possibly null) rtl_uString pointer, which (if
1385 non-null) will have been passed to rtl_uString_release before the function
1386 returns. Upon return, points to the newly allocated string or to null if
1387 there was either an out-of-memory condition or the resulting number of
1388 UTF-16 code units would have been larger than SAL_MAX_INT32. The newly
1389 allocated string (if any) must ultimately be passed to rtl_uString_release.
1391 @param codePoints
1392 an array of at least codePointCount code points, which each must be in the
1393 range from 0 to 0x10FFFF, inclusive. May be null if codePointCount is zero.
1395 @param codePointCount
1396 the non-negative number of code points.
1398 @since UDK 3.2.7
1400 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromCodePoints(
1401 rtl_uString ** newString, sal_uInt32 const * codePoints,
1402 sal_Int32 codePointCount) SAL_THROW_EXTERN_C();
1404 /** Assign a new value to a string.
1406 First releases any value str might currently hold, then acquires
1407 rightValue.
1409 @param str
1410 pointer to the string. The pointed-to data must be null or a valid
1411 string.
1413 @param rightValue
1414 a valid string.
1416 SAL_DLLPUBLIC void SAL_CALL rtl_uString_assign(
1417 rtl_uString ** str, rtl_uString * rightValue ) SAL_THROW_EXTERN_C();
1419 /** Return the length of a string.
1421 The length is equal to the number of characters in the string.
1423 @param str
1424 a valid string.
1426 @return
1427 the length of the string.
1429 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uString_getLength(
1430 const rtl_uString * str ) SAL_THROW_EXTERN_C();
1432 /** Return a pointer to the underlying character array of a string.
1434 @param str
1435 a valid string.
1437 @return
1438 a pointer to the null-terminated character array.
1440 SAL_DLLPUBLIC sal_Unicode * SAL_CALL rtl_uString_getStr(
1441 rtl_uString * str ) SAL_THROW_EXTERN_C();
1443 /** Create a new string that is the concatenation of two other strings.
1445 The new string does not necessarily have a reference count of 1 (in cases
1446 where one of the two other strings is empty), so it must not be modified
1447 without checking the reference count. This function does not handle
1448 out-of-memory conditions.
1450 @param newStr
1451 pointer to the new string. The pointed-to data must be null or a valid
1452 string.
1454 @param left
1455 a valid string.
1457 @param right
1458 a valid string.
1460 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newConcat(
1461 rtl_uString ** newStr, rtl_uString * left, rtl_uString * right ) SAL_THROW_EXTERN_C();
1463 /** Create a new string that is the concatenation of two other strings.
1465 The new string does not necessarily have a reference count of 1 (in cases
1466 where the ASCII string is empty), so it must not be modified without
1467 checking the reference count.
1469 @param newString
1470 pointer to the new string. The pointed-to data must be null or a valid
1471 string.
1473 @param left
1474 a valid string.
1476 @param right must not be null and must point to memory of at least
1477 \p rightLength ASCII bytes
1479 @param rightLength the length of the \p right string; must be non-negative
1481 @since LibreOffice 5.1
1483 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newConcatAsciiL(
1484 rtl_uString ** newString, rtl_uString * left, char const * right,
1485 sal_Int32 rightLength);
1487 /** Create a new string that is the concatenation of two other strings.
1489 The new string does not necessarily have a reference count of 1 (in cases
1490 where the UTF-16 string is empty), so it must not be modified without
1491 checking the reference count.
1493 @param newString pointer to the new string. The pointed-to data must be null
1494 or a valid string.
1496 @param left a valid string.
1498 @param right must point to memory of at least \p rightLength UTF-16 code units; may be null if
1499 \p rigthLength is zero
1501 @param rightLength the length of the \p right string; must be non-negative
1503 @since LibreOffice 5.3
1505 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newConcatUtf16L(
1506 rtl_uString ** newString, rtl_uString * left, sal_Unicode const * right,
1507 sal_Int32 rightLength);
1509 /** Create a new string by replacing a substring of another string.
1511 The new string results from replacing a number of characters (count),
1512 starting at the specified position (index) in the original string (str),
1513 with some new substring (subStr). If subStr is null, then only a number
1514 of characters is deleted.
1516 The new string does not necessarily have a reference count of 1, so it
1517 must not be modified without checking the reference count. This function
1518 does not handle out-of-memory conditions.
1520 @param newStr
1521 pointer to the new string. The pointed-to data must be null or a valid
1522 string.
1524 @param str
1525 a valid string.
1527 @param idx
1528 the index into str at which to start replacement. Must be between 0 and
1529 the length of str, inclusive.
1531 @param count
1532 the number of characters to remove. Must not be negative, and the sum of
1533 index and count must not exceed the length of str.
1535 @param subStr
1536 either null or a valid string to be inserted.
1538 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceStrAt(
1539 rtl_uString ** newStr, rtl_uString * str, sal_Int32 idx, sal_Int32 count, rtl_uString * subStr ) SAL_THROW_EXTERN_C();
1541 /** Create a new string by replacing all occurrences of a single character
1542 within another string.
1544 The new string results from replacing all occurrences of oldChar in str
1545 with newChar.
1547 The new string does not necessarily have a reference count of 1 (in cases
1548 where oldChar does not occur in str), so it must not be modified without
1549 checking the reference count. This function does not handle out-of-memory
1550 conditions.
1552 @param newStr
1553 pointer to the new string. The pointed-to data must be null or a valid
1554 string.
1556 @param str
1557 a valid string.
1559 @param oldChar
1560 the old character.
1562 @param newChar
1563 the new character.
1565 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplace(
1566 rtl_uString ** newStr, rtl_uString * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
1568 /** Create a new string by replacing the first occurrence of a given substring
1569 with another substring.
1571 @param[in, out] newStr pointer to the new string; must not be null; must
1572 point to null or a valid rtl_uString
1574 @param str pointer to the original string; must not be null
1576 @param from pointer to the substring to be replaced; must not be null
1578 @param to pointer to the replacing substring; must not be null
1580 @param[in,out] index pointer to a start index, must not be null; upon entry
1581 to the function its value is the index into the original string at which to
1582 start searching for the \p from substring, the value must be non-negative
1583 and not greater than the original string's length; upon exit from the
1584 function its value is the index into the original string at which the
1585 replacement took place or -1 if no replacement took place
1587 @since LibreOffice 3.6
1589 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirst(
1590 rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1591 rtl_uString const * to, sal_Int32 * index) SAL_THROW_EXTERN_C();
1593 /** Create a new string by replacing the first occurrence of a given substring
1594 with another substring.
1596 @param[in, out] newStr pointer to the new string; must not be null; must
1597 point to null or a valid rtl_uString
1599 @param str pointer to the original string; must not be null
1601 @param from pointer to the substring to be replaced; must not be null and
1602 must point to memory of at least \p fromLength ASCII bytes
1604 @param fromLength the length of the \p from substring; must be non-negative
1606 @param to pointer to the replacing substring; must not be null
1608 @param[in,out] index pointer to a start index, must not be null; upon entry
1609 to the function its value is the index into the original string at which to
1610 start searching for the \p from substring, the value must be non-negative
1611 and not greater than the original string's length; upon exit from the
1612 function its value is the index into the original string at which the
1613 replacement took place or -1 if no replacement took place
1615 @since LibreOffice 3.6
1617 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstAsciiL(
1618 rtl_uString ** newStr, rtl_uString * str, char const * from,
1619 sal_Int32 fromLength, rtl_uString const * to, sal_Int32 * index)
1620 SAL_THROW_EXTERN_C();
1622 /** Create a new string by replacing the first occurrence of a given substring
1623 with another substring.
1625 @param[in, out] newStr pointer to the new string; must not be null; must
1626 point to null or a valid rtl_uString
1628 @param str pointer to the original string; must not be null
1630 @param from pointer to the substring to be replaced; must not be null
1632 @param to pointer to the replacing substring; must not be null and must
1633 point to memory of at least \p toLength ASCII bytes
1635 @param toLength the length of the \p to substring; must be non-negative
1637 @param[in,out] index pointer to a start index, must not be null; upon entry
1638 to the function its value is the index into the original string at which to
1639 start searching for the \p from substring, the value must be non-negative
1640 and not greater than the original string's length; upon exit from the
1641 function its value is the index into the original string at which the
1642 replacement took place or -1 if no replacement took place
1644 @since LibreOffice 5.1
1646 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstToAsciiL(
1647 rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1648 char const * to, sal_Int32 toLength, sal_Int32 * index)
1649 SAL_THROW_EXTERN_C();
1651 /** Create a new string by replacing the first occurrence of a given substring
1652 with another substring.
1654 @param[in, out] newStr pointer to the new string; must not be null; must
1655 point to null or a valid rtl_uString
1657 @param str pointer to the original string; must not be null
1659 @param from pointer to the substring to be replaced; must not be null and
1660 must point to memory of at least \p fromLength ASCII bytes
1662 @param fromLength the length of the \p from substring; must be non-negative
1664 @param to pointer to the substring to be replaced; must not be null and
1665 must point to memory of at least \p toLength ASCII bytes
1667 @param toLength the length of the \p to substring; must be non-negative
1669 @param[in,out] index pointer to a start index, must not be null; upon entry
1670 to the function its value is the index into the original string at which to
1671 start searching for the \p from substring, the value must be non-negative
1672 and not greater than the original string's length; upon exit from the
1673 function its value is the index into the original string at which the
1674 replacement took place or -1 if no replacement took place
1676 @since LibreOffice 3.6
1678 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstAsciiLAsciiL(
1679 rtl_uString ** newStr, rtl_uString * str, char const * from,
1680 sal_Int32 fromLength, char const * to, sal_Int32 toLength,
1681 sal_Int32 * index) SAL_THROW_EXTERN_C();
1683 /** Create a new string by replacing the first occurrence of a given substring
1684 with another substring.
1686 @param[in, out] newStr pointer to the new string; must not be null; must
1687 point to null or a valid rtl_uString; upon return, points to the newly
1688 allocated string or to null if there was either an out-of-memory condition
1689 or the resulting number of UTF-16 code units would have been larger than
1690 SAL_MAX_INT32
1692 @param str pointer to the original string; must not be null
1694 @param from pointer to the substring to be replaced; must not be null and
1695 must point to memory of at least \p fromLength ASCII bytes
1697 @param fromLength the length of the \p from substring; must be non-negative
1699 @param to pointer to the substring to be replaced; must not be null and
1700 must point to memory of at least \p toLength UTF-16 code units
1702 @param toLength the length of the \p to substring; must be non-negative
1704 @param[in,out] index pointer to a start index, must not be null; upon entry
1705 to the function its value is the index into the original string at which to
1706 start searching for the \p from substring, the value must be non-negative
1707 and not greater than the original string's length; upon exit from the
1708 function its value is the index into the original string at which the
1709 replacement took place (or would have taken place if \p newStr points to
1710 null upon return) or -1 if no replacement took place
1712 @since LibreOffice 5.3
1714 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstAsciiLUtf16L(
1715 rtl_uString ** newStr, rtl_uString * str, char const * from,
1716 sal_Int32 fromLength, sal_Unicode const * to, sal_Int32 toLength,
1717 sal_Int32 * index) SAL_THROW_EXTERN_C();
1719 /** Create a new string by replacing the first occurrence of a given substring
1720 with another substring.
1722 @param[in, out] newStr pointer to the new string; must not be null; must
1723 point to null or a valid rtl_uString; upon return, points to the newly
1724 allocated string or to null if there was either an out-of-memory condition
1725 or the resulting number of UTF-16 code units would have been larger than
1726 SAL_MAX_INT32
1728 @param str pointer to the original string; must not be null
1730 @param from pointer to the substring to be replaced; must not be null and
1731 must point to memory of at least \p fromLength UTF-16 code units
1733 @param fromLength the length of the \p from substring; must be non-negative
1735 @param to pointer to the substring to be replaced; must not be null and
1736 must point to memory of at least \p toLength ASCII bytes
1738 @param toLength the length of the \p to substring; must be non-negative
1740 @param[in,out] index pointer to a start index, must not be null; upon entry
1741 to the function its value is the index into the original string at which to
1742 start searching for the \p from substring, the value must be non-negative
1743 and not greater than the original string's length; upon exit from the
1744 function its value is the index into the original string at which the
1745 replacement took place (or would have taken place if \p newStr points to
1746 null upon return) or -1 if no replacement took place
1748 @since LibreOffice 5.3
1750 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstUtf16LAsciiL(
1751 rtl_uString ** newStr, rtl_uString * str, sal_Unicode const * from,
1752 sal_Int32 fromLength, char const * to, sal_Int32 toLength,
1753 sal_Int32 * index) SAL_THROW_EXTERN_C();
1755 /** Create a new string by replacing the first occurrence of a given substring
1756 with another substring.
1758 @param[in, out] newStr pointer to the new string; must not be null; must
1759 point to null or a valid rtl_uString; upon return, points to the newly
1760 allocated string or to null if there was either an out-of-memory condition
1761 or the resulting number of UTF-16 code units would have been larger than
1762 SAL_MAX_INT32
1764 @param str pointer to the original string; must not be null
1766 @param from pointer to the substring to be replaced; must point to memory of at least
1767 \p fromLength UTF-16 code units; may be null if \p toLength is zero
1769 @param fromLength the length of the \p from substring; must be non-negative
1771 @param to pointer to the substring to be replaced; must point to memory of at least \p toLength
1772 UTF-16 code units; may be null if \p toLength is zero
1774 @param toLength the length of the \p to substring; must be non-negative
1776 @param[in,out] index pointer to a start index, must not be null; upon entry
1777 to the function its value is the index into the original string at which to
1778 start searching for the \p from substring, the value must be non-negative
1779 and not greater than the original string's length; upon exit from the
1780 function its value is the index into the original string at which the
1781 replacement took place (or would have taken place if \p newStr points to
1782 null upon return) or -1 if no replacement took place
1784 @since LibreOffice 5.3
1786 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstUtf16LUtf16L(
1787 rtl_uString ** newStr, rtl_uString * str, sal_Unicode const * from,
1788 sal_Int32 fromLength, sal_Unicode const * to, sal_Int32 toLength,
1789 sal_Int32 * index) SAL_THROW_EXTERN_C();
1791 /** Create a new string by replacing all occurrences of a given substring with
1792 another substring.
1794 Replacing subsequent occurrences picks up only after a given replacement.
1795 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1797 @param[in, out] newStr pointer to the new string; must not be null; must
1798 point to null or a valid rtl_uString
1800 @param str pointer to the original string; must not be null
1802 @param from pointer to the substring to be replaced; must not be null
1804 @param to pointer to the replacing substring; must not be null
1806 @since LibreOffice 3.6
1808 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAll(
1809 rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1810 rtl_uString const * to) SAL_THROW_EXTERN_C();
1812 /** Create a new string by replacing all occurrences of a given substring with
1813 another substring.
1815 Replacing subsequent occurrences picks up only after a given replacement.
1816 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1818 @param[in, out] newStr pointer to the new string; must not be null; must
1819 point to null or a valid rtl_uString
1821 @param str pointer to the original string; must not be null
1823 @param from pointer to the substring to be replaced; must not be null
1825 @param to pointer to the replacing substring; must not be null
1827 @param fromIndex the position in the string where we will begin searching
1829 @since LibreOffice 4.0
1831 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllFromIndex(
1832 rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1833 rtl_uString const * to, sal_Int32 fromIndex) SAL_THROW_EXTERN_C();
1835 /** Create a new string by replacing all occurrences of a given substring with
1836 another substring.
1838 Replacing subsequent occurrences picks up only after a given replacement.
1839 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1841 @param[in, out] newStr pointer to the new string; must not be null; must
1842 point to null or a valid rtl_uString
1844 @param str pointer to the original string; must not be null
1846 @param from pointer to the substring to be replaced; must not be null and
1847 must point to memory of at least \p fromLength ASCII bytes
1849 @param fromLength the length of the \p from substring; must be non-negative
1851 @param to pointer to the replacing substring; must not be null
1853 @since LibreOffice 3.6
1855 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllAsciiL(
1856 rtl_uString ** newStr, rtl_uString * str, char const * from,
1857 sal_Int32 fromLength, rtl_uString const * to) SAL_THROW_EXTERN_C();
1859 /** Create a new string by replacing all occurrences of a given substring with
1860 another substring.
1862 Replacing subsequent occurrences picks up only after a given replacement.
1863 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1865 @param[in, out] newStr pointer to the new string; must not be null; must
1866 point to null or a valid rtl_uString
1868 @param str pointer to the original string; must not be null
1870 @param from pointer to the substring to be replaced; must not be null
1872 @param to pointer to the replacing substring; must not be null and must
1873 point to memory of at least \p toLength ASCII bytes
1875 @param toLength the length of the \p to substring; must be non-negative
1877 @since LibreOffice 5.1
1879 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllToAsciiL(
1880 rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1881 char const * to, sal_Int32 toLength) SAL_THROW_EXTERN_C();
1883 /** Create a new string by replacing all occurrences of a given substring with
1884 another substring.
1886 Replacing subsequent occurrences picks up only after a given replacement.
1887 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1889 @param[in, out] newStr pointer to the new string; must not be null; must
1890 point to null or a valid rtl_uString
1892 @param str pointer to the original string; must not be null
1894 @param from pointer to the substring to be replaced; must not be null and
1895 must point to memory of at least \p fromLength ASCII bytes
1897 @param fromLength the length of the \p from substring; must be non-negative
1899 @param to pointer to the substring to be replaced; must not be null and
1900 must point to memory of at least \p toLength ASCII bytes
1902 @param toLength the length of the \p to substring; must be non-negative
1904 @since LibreOffice 3.6
1906 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllAsciiLAsciiL(
1907 rtl_uString ** newStr, rtl_uString * str, char const * from,
1908 sal_Int32 fromLength, char const * to, sal_Int32 toLength)
1909 SAL_THROW_EXTERN_C();
1911 /** Create a new string by replacing all occurrences of a given substring with
1912 another substring.
1914 Replacing subsequent occurrences picks up only after a given replacement.
1915 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1917 @param[in, out] newStr pointer to the new string; must not be null; must
1918 point to null or a valid rtl_uString; upon return, points to the newly
1919 allocated string or to null if there was either an out-of-memory condition
1920 or the resulting number of UTF-16 code units would have been larger than
1921 SAL_MAX_INT32
1923 @param str pointer to the original string; must not be null
1925 @param from pointer to the substring to be replaced; must not be null and
1926 must point to memory of at least \p fromLength ASCII bytes
1928 @param fromLength the length of the \p from substring; must be non-negative
1930 @param to pointer to the substring to be replaced; must point to memory of at least \p toLength
1931 UTF-16 code units; may be null if \p toLength is zero
1933 @param toLength the length of the \p to substring; must be non-negative
1935 @since LibreOffice 3.6
1937 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllAsciiLUtf16L(
1938 rtl_uString ** newStr, rtl_uString * str, char const * from,
1939 sal_Int32 fromLength, sal_Unicode const * to, sal_Int32 toLength)
1940 SAL_THROW_EXTERN_C();
1942 /** Create a new string by replacing all occurrences of a given substring with
1943 another substring.
1945 Replacing subsequent occurrences picks up only after a given replacement.
1946 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1948 @param[in, out] newStr pointer to the new string; must not be null; must
1949 point to null or a valid rtl_uString; upon return, points to the newly
1950 allocated string or to null if there was either an out-of-memory condition
1951 or the resulting number of UTF-16 code units would have been larger than
1952 SAL_MAX_INT32
1954 @param str pointer to the original string; must not be null
1956 @param from pointer to the substring to be replaced; must not be null and
1957 must point to memory of at least \p fromLength UTF-16 code units
1959 @param fromLength the length of the \p from substring; must be non-negative
1961 @param to pointer to the substring to be replaced; must not be null and
1962 must point to memory of at least \p toLength ASCII bytes
1964 @param toLength the length of the \p to substring; must be non-negative
1966 @since LibreOffice 3.6
1968 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllUtf16LAsciiL(
1969 rtl_uString ** newStr, rtl_uString * str, sal_Unicode const * from,
1970 sal_Int32 fromLength, char const * to, sal_Int32 toLength)
1971 SAL_THROW_EXTERN_C();
1973 /** Create a new string by replacing all occurrences of a given substring with
1974 another substring.
1976 Replacing subsequent occurrences picks up only after a given replacement.
1977 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1979 @param[in, out] newStr pointer to the new string; must not be null; must
1980 point to null or a valid rtl_uString; upon return, points to the newly
1981 allocated string or to null if there was either an out-of-memory condition
1982 or the resulting number of UTF-16 code units would have been larger than
1983 SAL_MAX_INT32
1985 @param str pointer to the original string; must not be null
1987 @param from pointer to the substring to be replaced; must not be null and
1988 must point to memory of at least \p fromLength UTF-16 code units
1990 @param fromLength the length of the \p from substring; must be non-negative
1992 @param to pointer to the substring to be replaced; must not be null and
1993 must point to memory of at least \p toLength UTF-16 code units
1995 @param toLength the length of the \p to substring; must be non-negative
1997 @since LibreOffice 3.6
1999 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllUtf16LUtf16L(
2000 rtl_uString ** newStr, rtl_uString * str, sal_Unicode const * from,
2001 sal_Int32 fromLength, sal_Unicode const * to, sal_Int32 toLength)
2002 SAL_THROW_EXTERN_C();
2004 #if defined LIBO_INTERNAL_ONLY
2005 /** Create a new string by replacing all occurrences of a given substring with
2006 another substring.
2008 Replacing subsequent occurrences picks up only after a given replacement.
2009 That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
2011 @param[in, out] newStr pointer to the new string; must not be null; must
2012 point to null or a valid rtl_uString; upon return, points to the newly
2013 allocated string or to null if there was either an out-of-memory condition
2014 or the resulting number of UTF-16 code units would have been larger than
2015 SAL_MAX_INT32
2017 @param str pointer to the original string; must not be null
2019 @param from pointer to the substring to be replaced; must not be null and
2020 must point to memory of at least \p fromLength UTF-16 code units
2022 @param fromLength the length of the \p from substring; must be non-negative
2024 @param to pointer to the substring to be replaced; must not be null and
2025 must point to memory of at least \p toLength UTF-16 code units
2027 @param toLength the length of the \p to substring; must be non-negative
2029 @param fromIndex the position in the string where we will begin searching
2031 @since LibreOffice 7.1
2033 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllFromIndexUtf16LUtf16L(
2034 rtl_uString ** newStr, rtl_uString * str, sal_Unicode const * from,
2035 sal_Int32 fromLength, sal_Unicode const * to, sal_Int32 toLength, sal_Int32 fromIndex)
2036 SAL_THROW_EXTERN_C();
2037 #endif
2039 /** Create a new string by converting all ASCII uppercase letters to lowercase
2040 within another string.
2042 The new string results from replacing all characters with values between
2043 65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
2045 This function cannot be used for language-specific conversion. The new
2046 string does not necessarily have a reference count of 1 (in cases where
2047 no characters need to be converted), so it must not be modified without
2048 checking the reference count. This function does not handle out-of-memory
2049 conditions.
2051 @param newStr
2052 pointer to the new string. The pointed-to data must be null or a valid
2053 string.
2055 @param str
2056 a valid string.
2058 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newToAsciiLowerCase(
2059 rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
2061 /** Create a new string by converting all ASCII lowercase letters to uppercase
2062 within another string.
2064 The new string results from replacing all characters with values between
2065 97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z).
2067 This function cannot be used for language-specific conversion. The new
2068 string does not necessarily have a reference count of 1 (in cases where
2069 no characters need to be converted), so it must not be modified without
2070 checking the reference count. This function does not handle out-of-memory
2071 conditions.
2073 @param newStr
2074 pointer to the new string. The pointed-to data must be null or a valid
2075 string.
2077 @param str
2078 a valid string.
2080 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newToAsciiUpperCase(
2081 rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
2083 /** Create a new string by removing white space from both ends of another
2084 string.
2086 The new string results from removing all characters with values less than
2087 or equal to 32 (the space character), and also Unicode General Punctuation
2088 area Space and some Control characters, form both ends of str (see
2089 rtl_ImplIsWhitespace).
2091 This function cannot be used for language-specific conversion. The new
2092 string does not necessarily have a reference count of 1 (in cases where
2093 no characters need to be removed), so it must not be modified without
2094 checking the reference count. This function does not handle out-of-memory
2095 conditions.
2097 @param newStr
2098 pointer to the new string. The pointed-to data must be null or a valid
2099 string.
2101 @param str
2102 a valid string.
2104 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newTrim(
2105 rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
2107 /** Create a new string by extracting a single token from another string.
2109 Starting at index, the token's next token is searched for. If there is no
2110 such token, the result is an empty string. Otherwise, all characters from
2111 the start of that token and up to, but not including the next occurrence
2112 of cTok make up the resulting token. The return value is the position of
2113 the next token, or -1 if no more tokens follow.
2115 Example code could look like
2116 rtl_uString * pToken = NULL;
2117 sal_Int32 nIndex = 0;
2121 nIndex = rtl_uString_getToken(&pToken, pStr, 0, ';', nIndex);
2124 while (nIndex >= 0);
2126 The new string does not necessarily have a reference count of 1, so it
2127 must not be modified without checking the reference count. This function
2128 does not handle out-of-memory conditions.
2130 @param newStr
2131 pointer to the new string. The pointed-to data must be null or a valid
2132 string. If either token or index is negative, an empty token is stored in
2133 newStr (and -1 is returned).
2135 @param str
2136 a valid string.
2138 @param token
2139 the number of the token to return, starting at index.
2141 @param cTok
2142 the character that separates the tokens.
2144 @param idx
2145 the position at which searching for the token starts. Must not be greater
2146 than the length of str.
2148 @return
2149 the index of the next token, or -1 if no more tokens follow.
2151 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uString_getToken(
2152 rtl_uString ** newStr , rtl_uString * str, sal_Int32 token, sal_Unicode cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
2154 /* ======================================================================= */
2156 /** Supply an ASCII string literal together with its length and text encoding.
2158 This macro can be used to compute (some of) the arguments in function calls
2159 like rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("foo")).
2161 @param constAsciiStr
2162 must be an expression of type "(possibly cv-qualified reference to) array of
2163 (possibly cv-qualified) char." Each element of the referenced array must
2164 represent an ASCII value in the range 0x00--0x7F. The last element of the
2165 referenced array is not considered part of the represented ASCII string, and
2166 its value should be 0x00. Depending on where this macro is used, the nature
2167 of the supplied expression might be further restricted.
2169 // The &foo[0] trick is intentional, it makes sure the type is char* or const char*
2170 // (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed).
2171 // This is to avoid mistaken use with functions that accept string literals
2172 // (i.e. const char (&)[N]) where usage of this macro otherwise could match
2173 // the argument and a following int argument with a default value (e.g. OUString::match()).
2174 #define RTL_CONSTASCII_USTRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \
2175 ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1)), RTL_TEXTENCODING_ASCII_US
2177 /* ======================================================================= */
2179 /* predefined constants for String-Conversion */
2180 #define OSTRING_TO_OUSTRING_CVTFLAGS (RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_MAPTOPRIVATE |\
2181 RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_DEFAULT |\
2182 RTL_TEXTTOUNICODE_FLAGS_INVALID_DEFAULT)
2184 /* ----------------------------------------------------------------------- */
2186 /** Create a new Unicode string by converting a byte string, using a specific
2187 text encoding.
2189 The lengths of the byte string and the Unicode string may differ (e.g.,
2190 for double-byte encodings, UTF-7, UTF-8).
2192 If the length of the byte string is greater than zero, the reference count
2193 of the new string will be 1.
2195 If an out-of-memory condition occurs, newStr will point to a null pointer
2196 upon return.
2198 @param newStr
2199 pointer to the new string. The pointed-to data must be null or a valid
2200 string.
2202 @param str
2203 a byte character array. Need not be null-terminated, but must be at
2204 least as long as the specified len.
2206 @param len
2207 the length of the byte character array.
2209 @param encoding
2210 the text encoding to use for conversion.
2212 @param convertFlags
2213 flags which control the conversion. Either use
2214 OSTRING_TO_OUSTRING_CVTFLAGS, or see
2215 <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
2216 details.
2218 SAL_DLLPUBLIC void SAL_CALL rtl_string2UString(
2219 rtl_uString ** newStr, const char * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
2221 /* ======================================================================= */
2222 /* Interning methods */
2224 /** Return a canonical representation for a string.
2226 A pool of strings, initially empty is maintained privately
2227 by the string class. On invocation, if present in the pool
2228 the original string will be returned. Otherwise this string,
2229 or a copy thereof will be added to the pool and returned.
2231 @param newStr
2232 pointer to the new string. The pointed-to data must be null or a valid
2233 string.
2235 If an out-of-memory condition occurs, newStr will point to a null pointer
2236 upon return.
2238 @param str
2239 pointer to the string to be interned.
2241 @since UDK 3.2.7
2243 SAL_DLLPUBLIC void SAL_CALL rtl_uString_intern(
2244 rtl_uString ** newStr, rtl_uString * str) SAL_THROW_EXTERN_C();
2246 /** Return a canonical representation for a string.
2248 A pool of strings, initially empty is maintained privately
2249 by the string class. On invocation, if present in the pool
2250 the original string will be returned. Otherwise this string,
2251 or a copy thereof will be added to the pool and returned.
2253 @param newStr
2254 pointer to the new string. The pointed-to data must be null or a valid
2255 string.
2257 If an out-of-memory condition occurs, newStr will point to a null pointer
2258 upon return.
2260 @param str
2261 a byte character array. Need not be null-terminated, but must be at
2262 least as long as the specified len.
2264 @param len
2265 the length of the byte character array.
2267 @param encoding
2268 the text encoding to use for conversion.
2270 @param convertFlags
2271 flags which control the conversion. Either use
2272 OSTRING_TO_OUSTRING_CVTFLAGS, or see
2273 <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
2274 details.
2276 @param pInfo
2277 pointer to return conversion status in, or NULL.
2279 @since UDK 3.2.7
2281 SAL_DLLPUBLIC void SAL_CALL rtl_uString_internConvert(
2282 rtl_uString ** newStr,
2283 const char * str,
2284 sal_Int32 len,
2285 rtl_TextEncoding encoding,
2286 sal_uInt32 convertFlags,
2287 sal_uInt32 *pInfo) SAL_THROW_EXTERN_C();
2289 /** Iterate through a string based on code points instead of UTF-16 code units.
2291 See Chapter 3 of The Unicode Standard 5.0 (Addison--Wesley, 2006) for
2292 definitions of the various terms used in this description.
2294 The given string is interpreted as a sequence of zero or more UTF-16 code
2295 units. For each index into this sequence (from zero to one less than the
2296 length of the sequence, inclusive), a code point represented starting at the
2297 given index is computed as follows:
2299 - If the UTF-16 code unit addressed by the index constitutes a well-formed
2300 UTF-16 code unit sequence, the computed code point is the scalar value
2301 encoded by that UTF-16 code unit sequence.
2303 - Otherwise, if the index is at least two UTF-16 code units away from the
2304 end of the sequence, and the sequence of two UTF-16 code units addressed by
2305 the index constitutes a well-formed UTF-16 code unit sequence, the computed
2306 code point is the scalar value encoded by that UTF-16 code unit sequence.
2308 - Otherwise, the computed code point is the UTF-16 code unit addressed by
2309 the index. (This last case catches unmatched surrogates as well as indices
2310 pointing into the middle of surrogate pairs.)
2312 @param string
2313 pointer to a valid string; must not be null.
2315 @param indexUtf16
2316 pointer to a UTF-16 based index into the given string; must not be null. On
2317 entry, the index must be in the range from zero to the length of the string
2318 (in UTF-16 code units), inclusive. Upon successful return, the index will
2319 be updated to address the UTF-16 code unit that is the given
2320 incrementCodePoints away from the initial index.
2322 @param incrementCodePoints
2323 the number of code points to move the given *indexUtf16. If non-negative,
2324 moving is done after determining the code point at the index. If negative,
2325 moving is done before determining the code point at the (then updated)
2326 index. The value must be such that the resulting UTF-16 based index is in
2327 the range from zero to the length of the string (in UTF-16 code units),
2328 inclusive.
2330 @return
2331 the code point (an integer in the range from 0 to 0x10FFFF, inclusive) that
2332 is represented within the string starting at the index computed as follows:
2333 If incrementCodePoints is non-negative, the index is the initial value of
2334 *indexUtf16; if incrementCodePoints is negative, the index is the updated
2335 value of *indexUtf16. In either case, the computed index must be in the
2336 range from zero to one less than the length of the string (in UTF-16 code
2337 units), inclusive.
2339 @since UDK 3.2.7
2341 SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_uString_iterateCodePoints(
2342 rtl_uString const * string, sal_Int32 * indexUtf16,
2343 sal_Int32 incrementCodePoints);
2345 /** Converts a byte string to a Unicode string, signalling failure.
2347 @param target
2348 An out parameter receiving the converted string. Must not be null itself,
2349 and must contain either null or a pointer to a valid rtl_uString; the
2350 contents are unspecified if conversion fails (rtl_convertStringToUString
2351 returns false).
2353 @param source
2354 The byte string. May only be null if length is zero.
2356 @param length
2357 The length of the byte string. Must be non-negative.
2359 @param encoding
2360 The text encoding to convert from. Must be an octet encoding (i.e.,
2361 rtl_isOctetTextEncoding(encoding) must return true).
2363 @param flags
2364 A combination of RTL_TEXTTOUNICODE_FLAGS that detail how to do the
2365 conversion (see rtl_convertTextToUnicode). RTL_TEXTTOUNICODE_FLAGS_FLUSH
2366 need not be included, it is implicitly assumed. Typical uses are either
2367 RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_ERROR |
2368 RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_ERROR |
2369 RTL_TEXTTOUNICODE_FLAGS_INVALID_ERROR (fail if a byte or multi-byte sequence
2370 cannot be converted from the source encoding) or
2371 OSTRING_TO_OUSTRING_CVTFLAGS (make a best efforts conversion).
2373 @return
2374 True if the conversion succeeded, false otherwise.
2376 @since UDK 3.2.9
2378 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertStringToUString(
2379 rtl_uString ** target, char const * source, sal_Int32 length,
2380 rtl_TextEncoding encoding, sal_uInt32 flags) SAL_THROW_EXTERN_C();
2382 /** Ensure a string has enough space for a given number of characters.
2384 If the given string is large enough and has refcount of 1, it is not altered in any way.
2385 Otherwise it is replaced by a copy that has enough space for the given number of characters,
2386 data from the source string is copied to the beginning of it, the content of the remaining
2387 capacity undefined, the string has refcount of 1, and refcount of the original string is decreased.
2389 @param str
2390 pointer to the string. The pointed-to data must be a valid string.
2392 @param size
2393 the number of characters
2395 @since LibreOffice 4.1
2396 @internal
2398 SAL_DLLPUBLIC void SAL_CALL rtl_uString_ensureCapacity( rtl_uString ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();
2400 #ifdef __cplusplus
2402 #endif
2404 #endif // INCLUDED_RTL_USTRING_H
2406 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */