xref: /trunk/main/sal/inc/rtl/ustring.h (revision 86e1cf34)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef _RTL_USTRING_H_
25 #define _RTL_USTRING_H_
26 
27 #include <sal/types.h>
28 #include <osl/interlck.h>
29 #include <rtl/string.h>
30 #include <rtl/textenc.h>
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 /* ======================================================================= */
37 
38 /** Return the length of a string.
39 
40     The length is equal to the number of 16-bit Unicode characters in the
41     string, without the terminating NUL character.
42 
43     @param str
44     a null-terminated string.
45 
46     @return
47     the length of the sequence of characters represented by this string,
48     excluding the terminating NUL character.
49  */
50 sal_Int32 SAL_CALL rtl_ustr_getLength( const sal_Unicode * str ) SAL_THROW_EXTERN_C();
51 
52 /** Compare two strings.
53 
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.
58 
59     @param first
60     the first null-terminated string to be compared.
61 
62     @param second
63     the second null-terminated string which is compared with the first one.
64 
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.
69  */
70 sal_Int32 SAL_CALL rtl_ustr_compare( const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C();
71 
72 /** Compare two strings.
73 
74     The comparison is based on the numeric value of each character in the
75     strings and returns a value indicating their relationship.  This function
76     cannot be used for language-specific sorting.
77 
78     @param first
79     the first string to be compared.  Need not be null-terminated, but must be
80     at least as long as the specified firstLen.
81 
82     @param firstLen
83     the length of the first string.
84 
85     @param second
86     the second string which is compared with the first one.  Need not be
87     null-terminated, but must be at least as long as the specified secondLen.
88 
89     @param secondLen
90     the length of the second string.
91 
92     @return
93     0 if both strings are equal, a value less than 0 if the first string is
94     less than the second string, and a value greater than 0 if the first
95     string is greater than the second string.
96  */
97 sal_Int32 SAL_CALL rtl_ustr_compare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
98 
99 /** Compare two strings with a maximum count of characters.
100 
101     The comparison is based on the numeric value of each character in the
102     strings and returns a value indicating their relationship.  This function
103     cannot be used for language-specific sorting.
104 
105     @param first
106     the first string to be compared.  Need not be null-terminated, but must be
107     at least as long as the specified firstLen.
108 
109     @param firstLen
110     the length of the first string.
111 
112     @param second
113     the second string which is compared with the first one.  Need not be
114     null-terminated, but must be at least as long as the specified secondLen.
115 
116     @param secondLen
117     the length of the second string.
118 
119     @param shortenedLen
120     the maximum number of characters to compare.  This length can be greater
121     or smaller than the lengths of the two strings.
122 
123     @return
124     0 if both substrings are equal, a value less than 0 if the first substring
125     is less than the second substring, and a value greater than 0 if the first
126     substring is greater than the second substring.
127  */
128 sal_Int32 SAL_CALL rtl_ustr_shortenedCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
129 
130 /** Compare two strings from back to front.
131 
132     The comparison is based on the numeric value of each character in the
133     strings and returns a value indicating their relationship.  This function
134     cannot be used for language-specific sorting.
135 
136     @param first
137     the first string to be compared.  Need not be null-terminated, but must be
138     at least as long as the specified firstLen.
139 
140     @param firstLen
141     the length of the first string.
142 
143     @param second
144     the second string which is compared with the first one.  Need not be
145     null-terminated, but must be at least as long as the specified secondLen.
146 
147     @param secondLen
148     the length of the second string.
149 
150     @return
151     0 if both strings are equal, a value less than 0 if the first string
152     compares less than the second string, and a value greater than 0 if the
153     first string compares greater than the second string.
154  */
155 sal_Int32 SAL_CALL rtl_ustr_reverseCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
156 
157 /** Compare two strings from back to front for equality.
158 
159     The comparison is based on the numeric value of each character in the
160     strings and returns 'true' if, ans only if, both strings are equal.
161 	This function cannot be used for language-specific sorting.
162 
163     @param first
164     the first string to be compared.  Need not be null-terminated, but must be
165     at least as long as the specified len.
166 
167     @param second
168     the second string which is compared with the first one.  Need not be
169     null-terminated, but must be at least as long as the specified len.
170 
171     @param len
172     the length of both strings.
173 
174     @return
175     true if both strings are equal, false if they are not equal.
176  */
177 
178 sal_Bool SAL_CALL rtl_ustr_asciil_reverseEquals_WithLength( const sal_Unicode * first, const sal_Char * second, sal_Int32 len ) SAL_THROW_EXTERN_C();
179 
180 /** Compare two strings, ignoring the case of ASCII characters.
181 
182     The comparison is based on the numeric value of each character in the
183     strings and returns a value indicating their relationship.  Character
184     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
185     and 122 (ASCII a--z).  This function cannot be used for language-specific
186     sorting.  Both strings must be null-terminated.
187 
188     @param first
189     the first null-terminated string to be compared.
190 
191     @param second
192     the second null-terminated string which is compared with the first one.
193 
194     @return
195     0 if both strings are equal, a value less than 0 if the first string is
196     less than the second string, and a value greater than 0 if the first
197     string is greater than the second string.
198  */
199 sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase( const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C();
200 
201 /** Compare two strings, ignoring the case of ASCII characters.
202 
203     The comparison is based on the numeric value of each character in the
204     strings and returns a value indicating their relationship.  Character
205     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
206     and 122 (ASCII a--z).  This function cannot be used for language-specific
207     sorting.
208 
209     @param first
210     the first string to be compared.  Need not be null-terminated, but must be
211     at least as long as the specified firstLen.
212 
213     @param firstLen
214     the length of the first string.
215 
216     @param second
217     the second string which is compared with the first one.  Need not be
218     null-terminated, but must be at least as long as the specified secondLen.
219 
220     @param secondLen
221     the length of the second string.
222 
223     @return
224     0 if both strings are equal, a value less than 0 if the first string is
225     less than the second string, and a value greater than 0 if the first
226     string is greater than the second string.
227  */
228 sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
229 
230 /** Compare two strings with a maximum count of characters, ignoring the case
231     of ASCII characters.
232 
233     The comparison is based on the numeric value of each character in the
234     strings and returns a value indicating their relationship.  Character
235     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
236     and 122 (ASCII a--z).  This function cannot be used for language-specific
237     sorting.
238 
239     @param first
240     the first string to be compared.  Need not be null-terminated, but must be
241     at least as long as the specified firstLen.
242 
243     @param firstLen
244     the length of the first string.
245 
246     @param second
247     the second string which is compared with the first one.  Need not be
248     null-terminated, but must be at least as long as the specified secondLen.
249 
250     @param secondLen
251     the length of the second string.
252 
253     @param shortenedLen
254     the maximum number of characters to compare.  This length can be greater
255     or smaller than the lengths of the two strings.
256 
257     @return
258     0 if both substrings are equal, a value less than 0 if the first substring
259     is less than the second substring, and a value greater than 0 if the first
260     substring is greater than the second substring.
261  */
262 sal_Int32 SAL_CALL rtl_ustr_shortenedCompareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
263 
264 /** Compare two strings.
265 
266     The comparison is based on the numeric value of each character in the
267     strings and returns a value indicating their relationship.  This function
268     cannot be used for language-specific sorting.  Both strings must be
269     null-terminated.
270 
271     Since this function is optimized for performance, the ASCII character
272     values are not converted in any way.  The caller has to make sure that
273     all ASCII characters are in the allowed range of 0 and 127, inclusive.
274 
275     @param first
276     the first null-terminated string to be compared.
277 
278     @param second
279     the second null-terminated ASCII string which is compared with the first
280     one.
281 
282     @return
283     0 if both substrings are equal, a value less than 0 if the first substring
284     is less than the second substring, and a value greater than 0 if the first
285     substring is greater than the second substring.
286  */
287 sal_Int32 SAL_CALL rtl_ustr_ascii_compare( const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
288 
289 /** Compare two strings.
290 
291     The comparison is based on the numeric value of each character in the
292     strings and returns a value indicating their relationship.  This function
293     cannot be used for language-specific sorting.
294 
295     Since this function is optimized for performance, the ASCII character
296     values are not converted in any way.  The caller has to make sure that
297     all ASCII characters are in the allowed range of 0 and 127, inclusive.
298 
299     @param first
300     the first string to be compared.  Need not be null-terminated, but must be
301     at least as long as the specified firstLen.
302 
303     @param firstLen
304     the length of the first string.
305 
306     @param second
307     the second null-terminated ASCII string which is compared with the first
308     one.
309 
310     @return
311     0 if both substrings are equal, a value less than 0 if the first substring
312     is less than the second substring, and a value greater than 0 if the first
313     substring is greater than the second substring.
314  */
315 sal_Int32 SAL_CALL rtl_ustr_ascii_compare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C();
316 
317 /** Compare two strings with a maximum count of characters.
318 
319     The comparison is based on the numeric value of each character in the
320     strings and returns a value indicating their relationship.  This function
321     cannot be used for language-specific sorting.
322 
323     Since this function is optimized for performance, the ASCII character
324     values are not converted in any way.  The caller has to make sure that
325     all ASCII characters are in the allowed range of 0 and 127, inclusive.
326 
327     @param first
328     the first string to be compared.  Need not be null-terminated, but must be
329     at least as long as the specified firstLen.
330 
331     @param firstLen
332     the length of the first string.
333 
334     @param second
335     the second null-terminated ASCII string which is compared with the first
336     one.
337 
338     @param shortenedLen
339     the maximum number of characters to compare.  This length can be greater
340     or smaller than the lengths of the two strings.
341 
342     @return
343     0 if both substrings are equal, a value less than 0 if the first substring
344     is less than the second substring, and a value greater than 0 if the first
345     substring is greater than the second substring.
346  */
347 sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
348 
349 /** Compare two strings from back to front.
350 
351     The comparison is based on the numeric value of each character in the
352     strings and returns a value indicating their relationship.  This function
353     cannot be used for language-specific sorting.
354 
355     Since this function is optimized for performance, the ASCII character
356     values are not converted in any way.  The caller has to make sure that
357     all ASCII characters are in the allowed range of 0 and 127, inclusive.
358 
359     @param first
360     the first string to be compared.  Need not be null-terminated, but must be
361     at least as long as the specified firstLen.
362 
363     @param firstLen
364     the length of the first string.
365 
366     @param second
367     the second ASCII string which is compared with the first one.  Need not be
368     null-terminated, but must be at least as long as the specified secondLen.
369 
370     @param secondLen
371     the length of the second string.
372 
373     @return
374     0 if both strings are equal, a value less than 0 if the first string
375     compares less than the second string, and a value greater than 0 if the
376     first string compares greater than the second string.
377  */
378 sal_Int32 SAL_CALL rtl_ustr_asciil_reverseCompare_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
379 
380 /** Compare two strings, ignoring the case of ASCII characters.
381 
382     The comparison is based on the numeric value of each character in the
383     strings and returns a value indicating their relationship.  Character
384     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
385     and 122 (ASCII a--z).  This function cannot be used for language-specific
386     sorting.  Both strings must be null-terminated.
387 
388     Since this function is optimized for performance, the ASCII character
389     values are not converted in any way.  The caller has to make sure that
390     all ASCII characters are in the allowed range of 0 and 127, inclusive.
391 
392     @param first
393     the first null-terminated string to be compared.
394 
395     @param second
396     the second null-terminated ASCII string which is compared with the first
397     one.
398 
399     @return
400     0 if both strings are equal, a value less than 0 if the first string is
401     less than the second string, and a value greater than 0 if the first
402     string is greater than the second string.
403  */
404 sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase( const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
405 
406 /** Compare two strings, ignoring the case of ASCII characters.
407 
408     The comparison is based on the numeric value of each character in the
409     strings and returns a value indicating their relationship.  Character
410     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
411     and 122 (ASCII a--z).  This function cannot be used for language-specific
412     sorting.
413 
414     Since this function is optimized for performance, the ASCII character
415     values are not converted in any way.  The caller has to make sure that
416     all ASCII characters are in the allowed range of 0 and 127, inclusive.
417 
418     @param first
419     the first string to be compared.  Need not be null-terminated, but must be
420     at least as long as the specified firstLen.
421 
422     @param firstLen
423     the length of the first string.
424 
425     @param second
426     the second null-terminated ASCII string which is compared with the first
427     one.
428 
429     @return
430     0 if both strings are equal, a value less than 0 if the first string is
431     less than the second string, and a value greater than 0 if the first
432     string is greater than the second string.
433  */
434 sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C();
435 
436 /** Compare two strings, ignoring the case of ASCII characters.
437 
438     The comparison is based on the numeric value of each character in the
439     strings and returns a value indicating their relationship.  Character
440     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
441     and 122 (ASCII a--z).  This function cannot be used for language-specific
442     sorting.
443 
444     Since this function is optimized for performance, the ASCII character
445     values are not converted in any way.  The caller has to make sure that
446     all ASCII characters are in the allowed range of 0 and 127, inclusive.
447 
448     @param first
449     the first string to be compared.  Need not be null-terminated, but must be
450     at least as long as the specified firstLen.
451 
452     @param firstLen
453     the length of the first string.
454 
455     @param second
456     the second string which is compared with the first one.  Need not be
457     null-terminated, but must be at least as long as the specified secondLen.
458 
459     @param secondLen
460     the length of the second string.
461 
462     @return
463     0 if both strings are equal, a value less than 0 if the first string is
464     less than the second string, and a value greater than 0 if the first
465     string is greater than the second string.
466  */
467 sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths(
468     sal_Unicode const * first, sal_Int32 firstLen,
469     char const * second, sal_Int32 secondLen) SAL_THROW_EXTERN_C();
470 
471 /** Compare two strings with a maximum count of characters, ignoring the case
472     of ASCII characters.
473 
474     The comparison is based on the numeric value of each character in the
475     strings and returns a value indicating their relationship.  Character
476     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
477     and 122 (ASCII a--z).  This function cannot be used for language-specific
478     sorting.
479 
480     Since this function is optimized for performance, the ASCII character
481     values are not converted in any way.  The caller has to make sure that
482     all ASCII characters are in the allowed range of 0 and 127, inclusive.
483 
484     @param first
485     the first string to be compared.  Need not be null-terminated, but must be
486     at least as long as the specified firstLen.
487 
488     @param firstLen
489     the length of the first string.
490 
491     @param second
492     the second null-terminated ASCII string which is compared with the first
493     one.
494 
495     @param shortenedLen
496     the maximum number of characters to compare.  This length can be greater
497     or smaller than the lengths of the two strings.
498 
499     @return
500     0 if both substrings are equal, a value less than 0 if the first substring
501     is less than the second substring, and a value greater than 0 if the first
502     substring is greater than the second substring.
503  */
504 sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength( const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
505 
506 /** Return a hash code for a string.
507 
508     It is not allowed to store the hash code persistently, because later
509     versions could return other hash codes.  The string must be
510     null-terminated.
511 
512     @param str
513     a null-terminated string.
514 
515     @return
516     a hash code for the given string.
517  */
518 sal_Int32 SAL_CALL rtl_ustr_hashCode( const sal_Unicode * str ) SAL_THROW_EXTERN_C();
519 
520 /** Return a hash code for a string.
521 
522     It is not allowed to store the hash code persistently, because later
523     versions could return other hash codes.
524 
525     @param str
526     a string.  Need not be null-terminated, but must be at least as long as
527     the specified len.
528 
529     @param len
530     the length of the string.
531 
532     @return
533     a hash code for the given string.
534  */
535 sal_Int32 SAL_CALL rtl_ustr_hashCode_WithLength( const sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
536 
537 /** Search for the first occurrence of a character within a string.
538 
539     The string must be null-terminated.
540 
541     @param str
542     a null-terminated string.
543 
544     @param ch
545     the character to be searched for.
546 
547     @return
548     the index (starting at 0) of the first occurrence of the character in the
549     string, or -1 if the character does not occur.
550  */
551 sal_Int32 SAL_CALL rtl_ustr_indexOfChar( const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
552 
553 /** Search for the first occurrence of a character within a string.
554 
555     @param str
556     a string.  Need not be null-terminated, but must be at least as long as
557     the specified len.
558 
559     @param len
560     the length of the string.
561 
562     @param ch
563     the character to be searched for.
564 
565     @return
566     the index (starting at 0) of the first occurrence of the character in the
567     string, or -1 if the character does not occur.
568  */
569 sal_Int32 SAL_CALL rtl_ustr_indexOfChar_WithLength( const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C();
570 
571 /** Search for the last occurrence of a character within a string.
572 
573     The string must be null-terminated.
574 
575     @param str
576     a null-terminated string.
577 
578     @param ch
579     the character to be searched for.
580 
581     @return
582     the index (starting at 0) of the last occurrence of the character in the
583     string, or -1 if the character does not occur.  The returned value is
584     always smaller than the string length.
585  */
586 sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar( const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
587 
588 /** Search for the last occurrence of a character within a string.
589 
590     @param str
591     a string.  Need not be null-terminated, but must be at least as long as
592     the specified len.
593 
594     @param len
595     the length of the string.
596 
597     @param ch
598     the character to be searched for.
599 
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.
604  */
605 sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar_WithLength( const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C();
606 
607 /** Search for the first occurrence of a substring within a string.
608 
609     If subStr is empty, or both str and subStr are empty, -1 is returned.
610     Both strings must be null-terminated.
611 
612     @param str
613     a null-terminated string.
614 
615     @param subStr
616     the null-terminated substring to be searched for.
617 
618     @return
619     the index (starting at 0) of the first character of the first occurrence
620     of the substring within the string, or -1 if the substring does not occur.
621  */
622 sal_Int32 SAL_CALL rtl_ustr_indexOfStr( const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C();
623 
624 /** Search for the first occurrence of a substring within a string.
625 
626     If subStr is empty, or both str and subStr are empty, -1 is returned.
627 
628     @param str
629     a string.  Need not be null-terminated, but must be at least as long as
630     the specified len.
631 
632     @param len
633     the length of the string.
634 
635     @param subStr
636     the substring to be searched for.  Need not be null-terminated, but must
637     be at least as long as the specified subLen.
638 
639     @param subLen
640     the length of the substring.
641 
642     @return
643     the index (starting at 0) of the first character of the first occurrence
644     of the substring within the string, or -1 if the substring does not occur.
645  */
646 sal_Int32 SAL_CALL rtl_ustr_indexOfStr_WithLength( const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
647 
648 /** Search for the first occurrence of an ASCII substring within a string.
649 
650     @param str
651     a string.  Need not be null-terminated, but must be at least as long as
652     the specified len.
653 
654     @param len
655     the length of the string; must be non-negative.
656 
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.  Must only contain characters
660     in the ASCII range 0x00--7F.
661 
662     @param subLen
663     the length of the substring; must be non-negative.
664 
665     @return
666     the index (starting at 0) of the first character of the first occurrence
667     of the substring within the string, or -1 if the substring does not occur.
668     If subLen is zero, -1 is returned.
669 
670     @since UDK 3.2.7
671 */
672 sal_Int32 SAL_CALL rtl_ustr_indexOfAscii_WithLength(
673     sal_Unicode const * str, sal_Int32 len,
674     char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C();
675 
676 /** Search for the last occurrence of a substring within a string.
677 
678     If subStr is empty, or both str and subStr are empty, -1 is returned.
679     Both strings must be null-terminated.
680 
681     @param str
682     a null-terminated string.
683 
684     @param subStr
685     the null-terminated substring to be searched for.
686 
687     @return
688     the index (starting at 0) of the first character of the last occurrence
689     of the substring within the string, or -1 if the substring does not occur.
690  */
691 sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr( const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C();
692 
693 /** Search for the last occurrence of a substring within a string.
694 
695     If subStr is empty, or both str and subStr are empty, -1 is returned.
696 
697     @param str
698     a string.  Need not be null-terminated, but must be at least as long as
699     the specified len.
700 
701     @param len
702     the length of the string.
703 
704     @param subStr
705     the substring to be searched for.  Need not be null-terminated, but must
706     be at least as long as the specified subLen.
707 
708     @param subLen
709     the length of the substring.
710 
711     @return
712     the index (starting at 0) of the first character of the first occurrence
713     of the substring within the string, or -1 if the substring does not occur.
714  */
715 sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr_WithLength( const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
716 
717 /** Search for the last occurrence of an ASCII substring within a string.
718 
719     @param str
720     a string.  Need not be null-terminated, but must be at least as long as
721     the specified len.
722 
723     @param len
724     the length of the string; must be non-negative.
725 
726     @param subStr
727     the substring to be searched for.  Need not be null-terminated, but must
728     be at least as long as the specified subLen.  Must only contain characters
729     in the ASCII range 0x00--7F.
730 
731     @param subLen
732     the length of the substring; must be non-negative.
733 
734     @return
735     the index (starting at 0) of the first character of the last occurrence
736     of the substring within the string, or -1 if the substring does not occur.
737     If subLen is zero, -1 is returned.
738 
739     @since UDK 3.2.7
740 */
741 sal_Int32 SAL_CALL rtl_ustr_lastIndexOfAscii_WithLength(
742     sal_Unicode const * str, sal_Int32 len,
743     char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C();
744 
745 /** Replace all occurrences of a single character within a string.
746 
747     If oldChar does not occur within str, then the string is not modified.
748     The string must be null-terminated.
749 
750     @param str
751     a null-terminated string.
752 
753     @param oldChar
754     the old character.
755 
756     @param newChar
757     the new character.
758  */
759 void SAL_CALL rtl_ustr_replaceChar( sal_Unicode * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
760 
761 /** Replace all occurrences of a single character within a string.
762 
763     If oldChar does not occur within str, then the string is not modified.
764 
765     @param str
766     a string.  Need not be null-terminated, but must be at least as long as
767     the specified len.
768 
769     @param len
770     the length of the string.
771 
772     @param oldChar
773     the old character.
774 
775     @param newChar
776     the new character.
777  */
778 void SAL_CALL rtl_ustr_replaceChar_WithLength( sal_Unicode * str, sal_Int32 len, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
779 
780 /** Convert all ASCII uppercase letters to lowercase within a string.
781 
782     The characters with values between 65 and 90 (ASCII A--Z) are replaced
783     with values between 97 and 122 (ASCII a--z).  The string must be
784     null-terminated.
785 
786     @param str
787     a null-terminated string.
788  */
789 void SAL_CALL rtl_ustr_toAsciiLowerCase( sal_Unicode * str ) SAL_THROW_EXTERN_C();
790 
791 /** Convert all ASCII uppercase letters to lowercase within a string.
792 
793     The characters with values between 65 and 90 (ASCII A--Z) are replaced
794     with values between 97 and 122 (ASCII a--z).
795 
796     @param str
797     a string.  Need not be null-terminated, but must be at least as long as
798     the specified len.
799 
800     @param len
801     the length of the string.
802  */
803 void SAL_CALL rtl_ustr_toAsciiLowerCase_WithLength( sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
804 
805 /** Convert all ASCII lowercase letters to uppercase within a string.
806 
807     The characters with values between 97 and 122 (ASCII a--z) are replaced
808     with values between 65 and 90 (ASCII A--Z).  The string must be
809     null-terminated.
810 
811     @param str
812     a null-terminated string.
813  */
814 void SAL_CALL rtl_ustr_toAsciiUpperCase( sal_Unicode * str ) SAL_THROW_EXTERN_C();
815 
816 /** Convert all ASCII lowercase letters to uppercase within a string.
817 
818     The characters with values between 97 and 122 (ASCII a--z) are replaced
819     with values between 65 and 90 (ASCII A--Z).
820 
821     @param str
822     a string.  Need not be null-terminated, but must be at least as long as
823     the specified len.
824 
825     @param len
826     the length of the string.
827  */
828 void SAL_CALL rtl_ustr_toAsciiUpperCase_WithLength( sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
829 
830 /** Remove white space from both ends of a string.
831 
832     All characters with values less than or equal to 32 (the space character)
833     are considered to be white space.  This function cannot be used for
834     language-specific operations.  The string must be null-terminated.
835 
836     @param str
837     a null-terminated string.
838 
839     @return
840     the new length of the string.
841  */
842 sal_Int32 SAL_CALL rtl_ustr_trim( sal_Unicode * str ) SAL_THROW_EXTERN_C();
843 
844 /** Remove white space from both ends of the string.
845 
846     All characters with values less than or equal to 32 (the space character)
847     are considered to be white space.  This function cannot be used for
848     language-specific operations.  The string must be null-terminated.
849 
850     @param str
851     a string.  Need not be null-terminated, but must be at least as long as
852     the specified len.
853 
854     @param len
855     the original length of the string.
856 
857     @return
858     the new length of the string.
859  */
860 sal_Int32 SAL_CALL rtl_ustr_trim_WithLength( sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
861 
862 /** Create the string representation of a boolean.
863 
864     If b is true, the buffer is filled with the string "true" and 5 is
865     returned.  If b is false, the buffer is filled with the string "false" and
866     6 is returned.  This function cannot be used for language-specific
867     operations.
868 
869     @param str
870     a buffer that is big enough to hold the result and the terminating NUL
871     character.  You should use the RTL_USTR_MAX_VALUEOFBOOLEAN define to
872     create a buffer that is big enough.
873 
874     @param b
875     a boolean value.
876 
877     @return
878     the length of the string.
879  */
880 sal_Int32 SAL_CALL rtl_ustr_valueOfBoolean( sal_Unicode * str, sal_Bool b ) SAL_THROW_EXTERN_C();
881 #define RTL_USTR_MAX_VALUEOFBOOLEAN RTL_STR_MAX_VALUEOFBOOLEAN
882 
883 /** Create the string representation of a character.
884 
885     @param str
886     a buffer that is big enough to hold the result and the terminating NUL
887     character.  You should use the RTL_USTR_MAX_VALUEOFCHAR define to create a
888     buffer that is big enough.
889 
890     @param ch
891     a character value.
892 
893     @return
894     the length of the string.
895  */
896 sal_Int32 SAL_CALL rtl_ustr_valueOfChar( sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
897 #define RTL_USTR_MAX_VALUEOFCHAR RTL_STR_MAX_VALUEOFCHAR
898 
899 /** Create the string representation of an integer.
900 
901     This function cannot be used for language-specific operations.
902 
903     @param str
904     a buffer that is big enough to hold the result and the terminating NUL
905     character.  You should use the RTL_USTR_MAX_VALUEOFINT32 define to create
906     a buffer that is big enough.
907 
908     @param i
909     an integer value.
910 
911     @param radix
912     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
913     (36), inclusive.
914 
915     @return
916     the length of the string.
917  */
918 sal_Int32 SAL_CALL rtl_ustr_valueOfInt32( sal_Unicode * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C();
919 #define RTL_USTR_MIN_RADIX          RTL_STR_MIN_RADIX
920 #define RTL_USTR_MAX_RADIX          RTL_STR_MAX_RADIX
921 #define RTL_USTR_MAX_VALUEOFINT32   RTL_STR_MAX_VALUEOFINT32
922 
923 /** Create the string representation of a long integer.
924 
925     This function cannot be used for language-specific operations.
926 
927     @param str
928     a buffer that is big enough to hold the result and the terminating NUL
929     character.  You should use the RTL_USTR_MAX_VALUEOFINT64 define to create
930     a buffer that is big enough.
931 
932     @param l
933     a long integer value.
934 
935     @param radix
936     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
937     (36), inclusive.
938 
939     @return
940     the length of the string.
941  */
942 sal_Int32 SAL_CALL rtl_ustr_valueOfInt64( sal_Unicode * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
943 #define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64
944 
945 /** Create the string representation of a float.
946 
947     This function cannot be used for language-specific conversion.
948 
949     @param str
950     a buffer that is big enough to hold the result and the terminating NUL
951     character.  You should use the RTL_USTR_MAX_VALUEOFFLOAT define to create
952     a buffer that is big enough.
953 
954     @param f
955     a float value.
956 
957     @return
958     the length of the string.
959  */
960 sal_Int32 SAL_CALL rtl_ustr_valueOfFloat( sal_Unicode * str, float f ) SAL_THROW_EXTERN_C();
961 #define RTL_USTR_MAX_VALUEOFFLOAT RTL_STR_MAX_VALUEOFFLOAT
962 
963 /** Create the string representation of a double.
964 
965     This function cannot be used for language-specific conversion.
966 
967     @param str
968     a buffer that is big enough to hold the result and the terminating NUL
969     character.  You should use the RTL_USTR_MAX_VALUEOFDOUBLE define to create
970     a buffer that is big enough.
971 
972     @param d
973     a double value.
974 
975     @return
976     the length of the string.
977  */
978 sal_Int32 SAL_CALL rtl_ustr_valueOfDouble( sal_Unicode * str, double d ) SAL_THROW_EXTERN_C();
979 #define RTL_USTR_MAX_VALUEOFDOUBLE RTL_STR_MAX_VALUEOFDOUBLE
980 
981 /** Interpret a string as a boolean.
982 
983     This function cannot be used for language-specific conversion.  The string
984     must be null-terminated.
985 
986     @param str
987     a null-terminated string.
988 
989     @return
990     true if the string is "1" or "true" in any ASCII case, false otherwise.
991  */
992 sal_Bool SAL_CALL rtl_ustr_toBoolean( const sal_Unicode * str ) SAL_THROW_EXTERN_C();
993 
994 /** Interpret a string as an integer.
995 
996     This function cannot be used for language-specific conversion.  The string
997     must be null-terminated.
998 
999     @param str
1000     a null-terminated string.
1001 
1002     @param radix
1003     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1004     (36), inclusive.
1005 
1006     @return
1007     the integer value represented by the string, or 0 if the string does not
1008     represent an integer.
1009  */
1010 sal_Int32 SAL_CALL rtl_ustr_toInt32( const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1011 
1012 /** Interpret a string as a long integer.
1013 
1014     This function cannot be used for language-specific conversion.  The string
1015     must be null-terminated.
1016 
1017     @param str
1018     a null-terminated string.
1019 
1020     @param radix
1021     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1022     (36), inclusive.
1023 
1024     @return
1025     the long integer value represented by the string, or 0 if the string does
1026     not represent a long integer.
1027  */
1028 sal_Int64 SAL_CALL rtl_ustr_toInt64( const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1029 
1030 /** Interpret a string as a float.
1031 
1032     This function cannot be used for language-specific conversion.  The string
1033     must be null-terminated.
1034 
1035     @param str
1036     a null-terminated string.
1037 
1038     @return
1039     the float value represented by the string, or 0.0 if the string does not
1040     represent a float.
1041  */
1042 float SAL_CALL rtl_ustr_toFloat( const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1043 
1044 /** Interpret a string as a double.
1045 
1046     This function cannot be used for language-specific conversion.  The string
1047     must be null-terminated.
1048 
1049     @param str
1050     a null-terminated string.
1051 
1052     @return
1053     the float value represented by the string, or 0.0 if the string does not
1054     represent a double.
1055  */
1056 double SAL_CALL rtl_ustr_toDouble( const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1057 
1058 /* ======================================================================= */
1059 
1060 #if defined( SAL_W32) ||  defined(SAL_OS2)
1061 #pragma pack(push, 4)
1062 #endif
1063 
1064 /** The implementation of a Unicode string.
1065 
1066     @internal
1067 */
1068 typedef struct _rtl_uString
1069 {
1070     oslInterlockedCount refCount; /* opaque */
1071     sal_Int32           length;
1072     sal_Unicode         buffer[1];
1073 } rtl_uString;
1074 
1075 #if defined( SAL_W32) ||  defined(SAL_OS2)
1076 #pragma pack(pop)
1077 #endif
1078 
1079 /* ----------------------------------------------------------------------- */
1080 
1081 /** Increment the reference count of a string.
1082 
1083     @param str
1084     a string.
1085  */
1086 void SAL_CALL rtl_uString_acquire( rtl_uString * str ) SAL_THROW_EXTERN_C();
1087 
1088 /** Decrement the reference count of a string.
1089 
1090     If the count goes to zero than the string data is deleted.
1091 
1092     @param str
1093     a string.
1094  */
1095 void SAL_CALL rtl_uString_release( rtl_uString * str ) SAL_THROW_EXTERN_C();
1096 
1097 /** Allocate a new string containing no characters.
1098 
1099     @param newStr
1100     pointer to the new string.  The pointed-to data must be null or a valid
1101     string.
1102  */
1103 void SAL_CALL rtl_uString_new( rtl_uString ** newStr ) SAL_THROW_EXTERN_C();
1104 
1105 /** Allocate a new string containing space for a given number of characters.
1106 
1107     If len is greater than zero, the reference count of the new string will be
1108     1.  The values of all characters are set to 0 and the length of the string
1109     is 0.  This function does not handle out-of-memory conditions.
1110 
1111     @param newStr
1112     pointer to the new string.  The pointed-to data must be null or a valid
1113     string.
1114 
1115     @param len
1116     the number of characters.
1117  */
1118 void SAL_CALL rtl_uString_new_WithLength( rtl_uString ** newStr, sal_Int32 nLen ) SAL_THROW_EXTERN_C();
1119 
1120 /** Allocate a new string that contains a copy of another string.
1121 
1122     If the length of value is greater than zero, the reference count of the
1123     new string will be 1.  This function does not handle out-of-memory
1124     conditions.
1125 
1126     @param newStr
1127     pointer to the new string.  The pointed-to data must be null or a valid
1128     string.
1129 
1130     @param value
1131     a valid string.
1132  */
1133 void SAL_CALL rtl_uString_newFromString( rtl_uString ** newStr, const rtl_uString * value ) SAL_THROW_EXTERN_C();
1134 
1135 /** Allocate a new string that contains a copy of a character array.
1136 
1137     If the length of value is greater than zero, the reference count of the
1138     new string will be 1.  This function does not handle out-of-memory
1139     conditions.
1140 
1141     @param newStr
1142     pointer to the new string.  The pointed-to data must be null or a valid
1143     string.
1144 
1145     @param value
1146     a null-terminated character array.
1147  */
1148 void SAL_CALL rtl_uString_newFromStr( rtl_uString ** newStr, const sal_Unicode * value ) SAL_THROW_EXTERN_C();
1149 
1150 /** Allocate a new string that contains a copy of a character array.
1151 
1152     If the length of value is greater than zero, the reference count of the
1153     new string will be 1.  This function does not handle out-of-memory
1154     conditions.
1155 
1156     @param newStr
1157     pointer to the new string.  The pointed-to data must be null or a valid
1158     string.
1159 
1160     @param value
1161     a character array.  Need not be null-terminated, but must be at least as
1162     long as the specified len.
1163 
1164     @param len
1165     the length of the character array.
1166  */
1167 void SAL_CALL rtl_uString_newFromStr_WithLength( rtl_uString ** newStr, const sal_Unicode * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
1168 
1169 /** Allocate a new string that contains a copy of a character array.
1170 
1171     If the length of value is greater than zero, the reference count of the
1172     new string will be 1.  This function does not handle out-of-memory
1173     conditions.
1174 
1175     Since this function is optimized for performance, the ASCII character
1176     values are not converted in any way.  The caller has to make sure that
1177     all ASCII characters are in the allowed range of 0 and 127, inclusive.
1178 
1179     @param newStr
1180     pointer to the new string.  The pointed-to data must be null or a valid
1181     string.
1182 
1183     @param value
1184     a null-terminated ASCII character array.
1185  */
1186 void SAL_CALL rtl_uString_newFromAscii( rtl_uString ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C();
1187 
1188 /** Allocate a new string from an array of Unicode code points.
1189 
1190     @param newString
1191     a non-null pointer to a (possibly null) rtl_uString pointer, which (if
1192     non-null) will have been passed to rtl_uString_release before the function
1193     returns.  Upon return, points to the newly allocated string or to null if
1194     there was either an out-of-memory condition or the resulting number of
1195     UTF-16 code units would have been larger than SAL_MAX_INT32.  The newly
1196     allocated string (if any) must ultimately be passed to rtl_uString_release.
1197 
1198     @param codePoints
1199     an array of at least codePointCount code points, which each must be in the
1200     range from 0 to 0x10FFFF, inclusive.  May be null if codePointCount is zero.
1201 
1202     @param codePointCount
1203     the non-negative number of code points.
1204 
1205     @since UDK 3.2.7
1206 */
1207 void SAL_CALL rtl_uString_newFromCodePoints(
1208     rtl_uString ** newString, sal_uInt32 const * codePoints,
1209     sal_Int32 codePointCount) SAL_THROW_EXTERN_C();
1210 
1211 /** Assign a new value to a string.
1212 
1213     First releases any value str might currently hold, then acquires
1214     rightValue.
1215 
1216     @param str
1217     pointer to the string.  The pointed-to data must be null or a valid
1218     string.
1219 
1220     @param rightValue
1221     a valid string.
1222  */
1223 void SAL_CALL rtl_uString_assign( rtl_uString ** str, rtl_uString * rightValue ) SAL_THROW_EXTERN_C();
1224 
1225 /** Return the length of a string.
1226 
1227     The length is equal to the number of characters in the string.
1228 
1229     @param str
1230     a valid string.
1231 
1232     @return
1233     the length of the string.
1234  */
1235 sal_Int32 SAL_CALL rtl_uString_getLength( const rtl_uString * str ) SAL_THROW_EXTERN_C();
1236 
1237 /** Return a pointer to the underlying character array of a string.
1238 
1239     @param str
1240     a valid string.
1241 
1242     @return
1243     a pointer to the null-terminated character array.
1244  */
1245 sal_Unicode * SAL_CALL rtl_uString_getStr( rtl_uString * str ) SAL_THROW_EXTERN_C();
1246 
1247 /** Create a new string that is the concatenation of two other strings.
1248 
1249     The new string does not necessarily have a reference count of 1 (in cases
1250     where one of the two other strings is empty), so it must not be modified
1251     without checking the reference count.  This function does not handle
1252     out-of-memory conditions.
1253 
1254     @param newStr
1255     pointer to the new string.  The pointed-to data must be null or a valid
1256     string.
1257 
1258     @param left
1259     a valid string.
1260 
1261     @param right
1262     a valid string.
1263  */
1264 void SAL_CALL rtl_uString_newConcat( rtl_uString ** newStr, rtl_uString * left, rtl_uString * right ) SAL_THROW_EXTERN_C();
1265 
1266 /** Create a new string by replacing a substring of another string.
1267 
1268     The new string results from replacing a number of characters (count),
1269     starting at the specified position (index) in the original string (str),
1270     with some new substring (subStr).  If subStr is null, than only a number
1271     of characters is deleted.
1272 
1273     The new string does not necessarily have a reference count of 1, so it
1274     must not be modified without checking the reference count.  This function
1275     does not handle out-of-memory conditions.
1276 
1277     @param newStr
1278     pointer to the new string.  The pointed-to data must be null or a valid
1279     string.
1280 
1281     @param str
1282     a valid string.
1283 
1284     @param index
1285     the index into str at which to start replacement.  Must be between 0 and
1286     the length of str, inclusive.
1287 
1288     @param count
1289     the number of charcters to remove.  Must not be negative, and the sum of
1290     index and count must not exceed the length of str.
1291 
1292     @param subStr
1293     either null or a valid string to be inserted.
1294  */
1295 void SAL_CALL rtl_uString_newReplaceStrAt( rtl_uString ** newStr, rtl_uString * str, sal_Int32 idx, sal_Int32 count, rtl_uString * subStr ) SAL_THROW_EXTERN_C();
1296 
1297 /** Create a new string by replacing all occurrences of a single character
1298     within another string.
1299 
1300     The new string results from replacing all occurrences of oldChar in str
1301     with newChar.
1302 
1303     The new string does not necessarily have a reference count of 1 (in cases
1304     where oldChar does not occur in str), so it must not be modified without
1305     checking the reference count.  This function does not handle out-of-memory
1306     conditions.
1307 
1308     @param newStr
1309     pointer to the new string.  The pointed-to data must be null or a valid
1310     string.
1311 
1312     @param str
1313     a valid string.
1314 
1315     @param oldChar
1316     the old character.
1317 
1318     @param newChar
1319     the new character.
1320  */
1321 void SAL_CALL rtl_uString_newReplace( rtl_uString ** newStr, rtl_uString * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
1322 
1323 /** Create a new string by converting all ASCII uppercase letters to lowercase
1324     within another string.
1325 
1326     The new string results from replacing all characters with values between
1327     65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
1328 
1329     This function cannot be used for language-specific conversion.  The new
1330     string does not necessarily have a reference count of 1 (in cases where
1331     no characters need to be converted), so it must not be modified without
1332     checking the reference count.  This function does not handle out-of-memory
1333     conditions.
1334 
1335     @param newStr
1336     pointer to the new string.  The pointed-to data must be null or a valid
1337     string.
1338 
1339     @param str
1340     a valid string.
1341  */
1342 void SAL_CALL rtl_uString_newToAsciiLowerCase( rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
1343 
1344 /** Create a new string by converting all ASCII lowercase letters to uppercase
1345     within another string.
1346 
1347     The new string results from replacing all characters with values between
1348     97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z).
1349 
1350     This function cannot be used for language-specific conversion.  The new
1351     string does not necessarily have a reference count of 1 (in cases where
1352     no characters need to be converted), so it must not be modified without
1353     checking the reference count.  This function does not handle out-of-memory
1354     conditions.
1355 
1356     @param newStr
1357     pointer to the new string.  The pointed-to data must be null or a valid
1358     string.
1359 
1360     @param str
1361     a valid string.
1362  */
1363 void SAL_CALL rtl_uString_newToAsciiUpperCase( rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
1364 
1365 /** Create a new string by removing white space from both ends of another
1366     string.
1367 
1368     The new string results from removing all characters with values less than
1369     or equal to 32 (the space character) form both ends of str.
1370 
1371     This function cannot be used for language-specific conversion.  The new
1372     string does not necessarily have a reference count of 1 (in cases where
1373     no characters need to be removed), so it must not be modified without
1374     checking the reference count.  This function does not handle out-of-memory
1375     conditions.
1376 
1377     @param newStr
1378     pointer to the new string.  The pointed-to data must be null or a valid
1379     string.
1380 
1381     @param str
1382     a valid string.
1383  */
1384 void SAL_CALL rtl_uString_newTrim( rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
1385 
1386 /** Create a new string by extracting a single token from another string.
1387 
1388     Starting at index, the token's next token is searched for.  If there is no
1389     such token, the result is an empty string.  Otherwise, all characters from
1390     the start of that token and up to, but not including the next occurrence
1391     of cTok make up the resulting token.  The return value is the position of
1392     the next token, or -1 if no more tokens follow.
1393 
1394     Example code could look like
1395       rtl_uString * pToken = NULL;
1396       sal_Int32 nIndex = 0;
1397       do
1398       {
1399           ...
1400           nIndex = rtl_uString_getToken(&pToken, pStr, 0, ';', nIndex);
1401           ...
1402       }
1403       while (nIndex >= 0);
1404 
1405     The new string does not necessarily have a reference count of 1, so it
1406     must not be modified without checking the reference count.  This function
1407     does not handle out-of-memory conditions.
1408 
1409     @param newStr
1410     pointer to the new string.  The pointed-to data must be null or a valid
1411     string.  If either token or index is negative, an empty token is stored in
1412     newStr (and -1 is returned).
1413 
1414     @param str
1415     a valid string.
1416 
1417     @param token
1418     the number of the token to return, starting at index.
1419 
1420     @param cTok
1421     the character that separates the tokens.
1422 
1423     @param index
1424     the position at which searching for the token starts.  Must not be greater
1425     than the length of str.
1426 
1427     @return
1428     the index of the next token, or -1 if no more tokens follow.
1429  */
1430 sal_Int32 SAL_CALL rtl_uString_getToken( rtl_uString ** newStr , rtl_uString * str, sal_Int32 token, sal_Unicode cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
1431 
1432 /* ======================================================================= */
1433 
1434 /** Supply an ASCII string literal together with its length and text encoding.
1435 
1436     This macro can be used to compute (some of) the arguments in function calls
1437     like rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("foo")).
1438 
1439     @param constAsciiStr
1440     must be an expression of type "(possibly cv-qualified reference to) array of
1441     (possibly cv-qualified) char."  Each element of the referenced array must
1442     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1443     referenced array is not considered part of the represented ASCII string, and
1444     its value should be 0x00.  Depending on where this macro is used, the nature
1445     of the supplied expression might be further restricted.
1446 */
1447 #define RTL_CONSTASCII_USTRINGPARAM( constAsciiStr ) constAsciiStr, ((sal_Int32)(sizeof(constAsciiStr)-1)), RTL_TEXTENCODING_ASCII_US
1448 
1449 /* ======================================================================= */
1450 
1451 /* predefined constants for String-Conversion */
1452 #define OSTRING_TO_OUSTRING_CVTFLAGS    (RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_MAPTOPRIVATE |\
1453                                          RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_DEFAULT |\
1454                                          RTL_TEXTTOUNICODE_FLAGS_INVALID_DEFAULT)
1455 
1456 /* ----------------------------------------------------------------------- */
1457 
1458 /** Create a new Unicode string by converting a byte string, using a specific
1459     text encoding.
1460 
1461     The lengths of the byte string and the Unicode string may differ (e.g.,
1462     for double-byte encodings, UTF-7, UTF-8).
1463 
1464     If the length of the byte string is greater than zero, the reference count
1465     of the new string will be 1.
1466 
1467     If an out-of-memory condition occurs, newStr will point to a null pointer
1468     upon return.
1469 
1470     @param newStr
1471     pointer to the new string.  The pointed-to data must be null or a valid
1472     string.
1473 
1474     @param str
1475     a byte character array.  Need not be null-terminated, but must be at
1476     least as long as the specified len.
1477 
1478     @param len
1479     the length of the byte character array.
1480 
1481     @param encoding
1482     the text encoding to use for conversion.
1483 
1484     @param convertFlags
1485     flags which control the conversion.  Either use
1486     OSTRING_TO_OUSTRING_CVTFLAGS, or see
1487     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1488     details.
1489  */
1490 void SAL_CALL rtl_string2UString( rtl_uString ** newStr, const sal_Char * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
1491 
1492 /* ======================================================================= */
1493 /* Interning methods */
1494 
1495 /** Return a canonical representation for a string.
1496 
1497     A pool of strings, initially empty is maintained privately
1498     by the string class. On invocation, if present in the pool
1499     the original string will be returned. Otherwise this string,
1500     or a copy thereof will be added to the pool and returned.
1501 
1502     @param newStr
1503     pointer to the new string.  The pointed-to data must be null or a valid
1504     string.
1505 
1506     If an out-of-memory condition occurs, newStr will point to a null pointer
1507     upon return.
1508 
1509     @param str
1510     pointer to the string to be interned.
1511 
1512     @since UDK 3.2.7
1513  */
1514 void SAL_CALL rtl_uString_intern( rtl_uString ** newStr,
1515                                   rtl_uString  * str) SAL_THROW_EXTERN_C();
1516 
1517 /** Return a canonical representation for a string.
1518 
1519     A pool of strings, initially empty is maintained privately
1520     by the string class. On invocation, if present in the pool
1521     the original string will be returned. Otherwise this string,
1522     or a copy thereof will be added to the pool and returned.
1523 
1524     @param newStr
1525     pointer to the new string.  The pointed-to data must be null or a valid
1526     string.
1527 
1528     If an out-of-memory condition occurs, newStr will point to a null pointer
1529     upon return.
1530 
1531     @param str
1532     a byte character array.  Need not be null-terminated, but must be at
1533     least as long as the specified len.
1534 
1535     @param len
1536     the length of the byte character array.
1537 
1538     @param encoding
1539     the text encoding to use for conversion.
1540 
1541     @param convertFlags
1542     flags which control the conversion.  Either use
1543     OSTRING_TO_OUSTRING_CVTFLAGS, or see
1544     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1545     details.
1546 
1547     @param pInfo
1548     pointer to return conversion status in, or NULL.
1549 
1550     @since UDK 3.2.7
1551  */
1552 void SAL_CALL rtl_uString_internConvert( rtl_uString   ** newStr,
1553                                          const sal_Char * str,
1554                                          sal_Int32        len,
1555                                          rtl_TextEncoding encoding,
1556                                          sal_uInt32       convertFlags,
1557                                          sal_uInt32      *pInfo) SAL_THROW_EXTERN_C();
1558 
1559 /** Iterate through a string based on code points instead of UTF-16 code units.
1560 
1561     See Chapter 3 of The Unicode Standard 5.0 (Addison--Wesley, 2006) for
1562     definitions of the various terms used in this description.
1563 
1564     The given string is interpreted as a sequence of zero or more UTF-16 code
1565     units.  For each index into this sequence (from zero to one less than the
1566     length of the sequence, inclusive), a code point represented starting at the
1567     given index is computed as follows:
1568 
1569     - If the UTF-16 code unit addressed by the index constitutes a well-formed
1570     UTF-16 code unit sequence, the computed code point is the scalar value
1571     encoded by that UTF-16 code unit sequence.
1572 
1573     - Otherwise, if the index is at least two UTF-16 code units away from the
1574     end of the sequence, and the sequence of two UTF-16 code units addressed by
1575     the index constitutes a well-formed UTF-16 code unit sequence, the computed
1576     code point is the scalar value encoded by that UTF-16 code unit sequence.
1577 
1578     - Otherwise, the computed code point is the UTF-16 code unit addressed by
1579     the index.  (This last case catches unmatched surrogates as well as indices
1580     pointing into the middle of surrogate pairs.)
1581 
1582     @param string
1583     pointer to a valid string; must not be null.
1584 
1585     @param indexUtf16
1586     pointer to a UTF-16 based index into the given string; must not be null.  On
1587     entry, the index must be in the range from zero to the length of the string
1588     (in UTF-16 code units), inclusive.  Upon successful return, the index will
1589     be updated to address the UTF-16 code unit that is the given
1590     incrementCodePoints away from the initial index.
1591 
1592     @param incrementCodePoints
1593     the number of code points to move the given *indexUtf16.  If non-negative,
1594     moving is done after determining the code point at the index.  If negative,
1595     moving is done before determining the code point at the (then updated)
1596     index.  The value must be such that the resulting UTF-16 based index is in
1597     the range from zero to the length of the string (in UTF-16 code units),
1598     inclusive.
1599 
1600     @return
1601     the code point (an integer in the range from 0 to 0x10FFFF, inclusive) that
1602     is represented within the string starting at the index computed as follows:
1603     If incrementCodePoints is non-negative, the index is the initial value of
1604     *indexUtf16; if incrementCodePoints is negative, the index is the updated
1605     value of *indexUtf16.  In either case, the computed index must be in the
1606     range from zero to one less than the length of the string (in UTF-16 code
1607     units), inclusive.
1608 
1609     @since UDK 3.2.7
1610 */
1611 sal_uInt32 SAL_CALL rtl_uString_iterateCodePoints(
1612     rtl_uString const * string, sal_Int32 * indexUtf16,
1613     sal_Int32 incrementCodePoints);
1614 
1615 /** Converts a byte string to a Unicode string, signalling failure.
1616 
1617     @param target
1618     An out parameter receiving the converted string.  Must not be null itself,
1619     and must contain either null or a pointer to a valid rtl_uString; the
1620     contents are unspecified if conversion fails (rtl_convertStringToUString
1621     returns false).
1622 
1623     @param source
1624     The byte string.  May only be null if length is zero.
1625 
1626     @param length
1627     The length of the byte string.  Must be non-negative.
1628 
1629     @param encoding
1630     The text encoding to convert from.  Must be an octet encoding (i.e.,
1631     rtl_isOctetTextEncoding(encoding) must return true).
1632 
1633     @param flags
1634     A combination of RTL_TEXTTOUNICODE_FLAGS that detail how to do the
1635     conversion (see rtl_convertTextToUnicode).  RTL_TEXTTOUNICODE_FLAGS_FLUSH
1636     need not be included, it is implicitly assumed.  Typical uses are either
1637     RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_ERROR |
1638     RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_ERROR |
1639     RTL_TEXTTOUNICODE_FLAGS_INVALID_ERROR (fail if a byte or multi-byte sequence
1640     cannot be converted from the source encoding) or
1641     OSTRING_TO_OUSTRING_CVTFLAGS (make a best efforts conversion).
1642 
1643     @return
1644     True if the conversion succeeded, false otherwise.
1645 
1646     @since UDK 3.2.9
1647 */
1648 sal_Bool SAL_CALL rtl_convertStringToUString(
1649     rtl_uString ** target, char const * source, sal_Int32 length,
1650     rtl_TextEncoding encoding, sal_uInt32 flags) SAL_THROW_EXTERN_C();
1651 
1652 #ifdef __cplusplus
1653 }
1654 #endif
1655 
1656 #endif /* _RTL_USTRING_H_ */
1657