xref: /aoo42x/main/sal/inc/rtl/string.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_STRING_H_
25 #define _RTL_STRING_H_
26 
27 #include <sal/types.h>
28 #include <osl/interlck.h>
29 #include <rtl/textcvt.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /* ======================================================================= */
36 
37 /** Return the length of a string.
38 
39     The length is equal to the number of 8-bit characters in the string,
40     without the terminating NUL character.
41 
42     @param str
43     a null-terminated string.
44 
45     @return
46     the length of the sequence of characters represented by this string,
47     excluding the terminating NUL character.
48  */
49 sal_Int32 SAL_CALL rtl_str_getLength( const sal_Char * str ) SAL_THROW_EXTERN_C();
50 
51 /** Compare two strings.
52 
53     The comparison is based on the numeric value of each character in the
54     strings and returns a value indicating their relationship.  This function
55     cannot be used for language-specific sorting.  Both strings must be
56     null-terminated.
57 
58     @param first
59     the first null-terminated string to be compared.
60 
61     @param second
62     the second null-terminated string which is compared with the first one.
63 
64     @return
65     0 if both strings are equal, a value less than 0 if the first string is
66     less than the second string, and a value greater than 0 if the first
67     string is greater than the second string.
68  */
69 sal_Int32 SAL_CALL rtl_str_compare( const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
70 
71 /** Compare two strings.
72 
73     The comparison is based on the numeric value of each character in the
74     strings and returns a value indicating their relationship.  This function
75     cannot be used for language-specific sorting.
76 
77     @param first
78     the first string to be compared.  Need not be null-terminated, but must be
79     at least as long as the specified firstLen.
80 
81     @param firstLen
82     the length of the first string.
83 
84     @param second
85     the second string which is compared with the first one.  Need not be
86     null-terminated, but must be at least as long as the specified secondLen.
87 
88     @param secondLen
89     the length of the second string.
90 
91     @return
92     0 if both strings are equal, a value less than 0 if the first string is
93     less than the second string, and a value greater than 0 if the first
94     string is greater than the second string.
95  */
96 sal_Int32 SAL_CALL rtl_str_compare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
97 
98 /** Compare two strings with a maximum count of characters.
99 
100     The comparison is based on the numeric value of each character in the
101     strings and returns a value indicating their relationship.  This function
102     cannot be used for language-specific sorting.
103 
104     @param first
105     the first string to be compared.  Need not be null-terminated, but must be
106     at least as long as the specified firstLen.
107 
108     @param firstLen
109     the length of the first string.
110 
111     @param second
112     the second string which is compared with the first one.  Need not be
113     null-terminated, but must be at least as long as the specified secondLen.
114 
115     @param secondLen
116     the length of the second string.
117 
118     @param shortenedLen
119     the maximum number of characters to compare.  This length can be greater
120     or smaller than the lengths of the two strings.
121 
122     @return
123     0 if both substrings are equal, a value less than 0 if the first substring
124     is less than the second substring, and a value greater than 0 if the first
125     substring is greater than the second substring.
126  */
127 sal_Int32 SAL_CALL rtl_str_shortenedCompare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
128 
129 /** Compare two strings from back to front.
130 
131     The comparison is based on the numeric value of each character in the
132     strings and returns a value indicating their relationship.  This function
133     cannot be used for language-specific sorting.
134 
135     @param first
136     the first string to be compared.  Need not be null-terminated, but must be
137     at least as long as the specified firstLen.
138 
139     @param firstLen
140     the length of the first string.
141 
142     @param second
143     the second string which is compared with the first one.  Need not be
144     null-terminated, but must be at least as long as the specified secondLen.
145 
146     @param secondLen
147     the length of the second string.
148 
149     @return
150     0 if both strings are equal, a value less than 0 if the first string
151     compares less than the second string, and a value greater than 0 if the
152     first string compares greater than the second string.
153  */
154 sal_Int32 SAL_CALL rtl_str_reverseCompare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
155 
156 /** Compare two strings, ignoring the case of ASCII characters.
157 
158     The comparison is based on the numeric value of each character in the
159     strings and returns a value indicating their relationship.  Character
160     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
161     and 122 (ASCII a--z).  This function cannot be used for language-specific
162     sorting.  Both strings must be null-terminated.
163 
164     @param first
165     the first null-terminated string to be compared.
166 
167     @param second
168     the second null-terminated string which is compared with the first one.
169 
170     @return
171     0 if both strings are equal, a value less than 0 if the first string is
172     less than the second string, and a value greater than 0 if the first
173     string is greater than the second string.
174  */
175 sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase( const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
176 
177 /** Compare two strings, ignoring the case of ASCII characters.
178 
179     The comparison is based on the numeric value of each character in the
180     strings and returns a value indicating their relationship.  Character
181     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
182     and 122 (ASCII a--z).  This function cannot be used for language-specific
183     sorting.
184 
185     @param first
186     the first string to be compared.  Need not be null-terminated, but must be
187     at least as long as the specified firstLen.
188 
189     @param firstLen
190     the length of the first string.
191 
192     @param second
193     the second string which is compared with the first one.  Need not be
194     null-terminated, but must be at least as long as the specified secondLen.
195 
196     @param secondLen
197     the length of the second string.
198 
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.
203  */
204 sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
205 
206 /** Compare two strings with a maximum count of characters, ignoring the case
207     of ASCII characters.
208 
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.
214 
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.
218 
219     @param firstLen
220     the length of the first string.
221 
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.
225 
226     @param secondLen
227     the length of the second string.
228 
229     @param shortenedLen
230     the maximum number of characters to compare.  This length can be greater
231     or smaller than the lengths of the two strings.
232 
233     @return
234     0 if both substrings are equal, a value less than 0 if the first substring
235     is less than the second substring, and a value greater than 0 if the first
236     substring is greater than the second substring.
237  */
238 sal_Int32 SAL_CALL rtl_str_shortenedCompareIgnoreAsciiCase_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
239 
240 /** Return a hash code for a string.
241 
242     It is not allowed to store the hash code persistently, because later
243     versions could return other hash codes.  The string must be
244     null-terminated.
245 
246     @param str
247     a null-terminated string.
248 
249     @return
250     a hash code for the given string.
251  */
252 sal_Int32 SAL_CALL rtl_str_hashCode( const sal_Char * str ) SAL_THROW_EXTERN_C();
253 
254 /** Return a hash code for a string.
255 
256     It is not allowed to store the hash code persistently, because later
257     versions could return other hash codes.
258 
259     @param str
260     a string.  Need not be null-terminated, but must be at least as long as
261     the specified len.
262 
263     @param len
264     the length of the string.
265 
266     @return
267     a hash code for the given string.
268  */
269 sal_Int32 SAL_CALL rtl_str_hashCode_WithLength( const sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
270 
271 /** Search for the first occurrence of a character within a string.
272 
273     The string must be null-terminated.
274 
275     @param str
276     a null-terminated string.
277 
278     @param ch
279     the character to be searched for.
280 
281     @return
282     the index (starting at 0) of the first occurrence of the character in the
283     string, or -1 if the character does not occur.
284  */
285 sal_Int32 SAL_CALL rtl_str_indexOfChar( const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C();
286 
287 /** Search for the first occurrence of a character within a string.
288 
289     @param str
290     a string.  Need not be null-terminated, but must be at least as long as
291     the specified len.
292 
293     @param len
294     the length of the string.
295 
296     @param ch
297     the character to be searched for.
298 
299     @return
300     the index (starting at 0) of the first occurrence of the character in the
301     string, or -1 if the character does not occur.
302  */
303 sal_Int32 SAL_CALL rtl_str_indexOfChar_WithLength( const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C();
304 
305 /** Search for the last occurrence of a character within a string.
306 
307     The string must be null-terminated.
308 
309     @param str
310     a null-terminated string.
311 
312     @param ch
313     the character to be searched for.
314 
315     @return
316     the index (starting at 0) of the last occurrence of the character in the
317     string, or -1 if the character does not occur.  The returned value is
318     always smaller than the string length.
319  */
320 sal_Int32 SAL_CALL rtl_str_lastIndexOfChar( const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C();
321 
322 /** Search for the last occurrence of a character within a string.
323 
324     @param str
325     a string.  Need not be null-terminated, but must be at least as long as
326     the specified len.
327 
328     @param len
329     the length of the string.
330 
331     @param ch
332     the character to be searched for.
333 
334     @return
335     the index (starting at 0) of the last occurrence of the character in the
336     string, or -1 if the character does not occur.  The returned value is
337     always smaller than the string length.
338  */
339 sal_Int32 SAL_CALL rtl_str_lastIndexOfChar_WithLength( const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C();
340 
341 /** Search for the first occurrence of a substring within a string.
342 
343     If subStr is empty, or both str and subStr are empty, -1 is returned.
344     Both strings must be null-terminated.
345 
346     @param str
347     a null-terminated string.
348 
349     @param subStr
350     the null-terminated substring to be searched for.
351 
352     @return
353     the index (starting at 0) of the first character of the first occurrence
354     of the substring within the string, or -1 if the substring does not occur.
355  */
356 sal_Int32 SAL_CALL rtl_str_indexOfStr( const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C();
357 
358 /** Search for the first occurrence of a substring within a string.
359 
360     If subStr is empty, or both str and subStr are empty, -1 is returned.
361 
362     @param str
363     a string.  Need not be null-terminated, but must be at least as long as
364     the specified len.
365 
366     @param len
367     the length of the string.
368 
369     @param subStr
370     the substring to be searched for.  Need not be null-terminated, but must
371     be at least as long as the specified subLen.
372 
373     @param subLen
374     the length of the substring.
375 
376     @return
377     the index (starting at 0) of the first character of the first occurrence
378     of the substring within the string, or -1 if the substring does not occur.
379  */
380 sal_Int32 SAL_CALL rtl_str_indexOfStr_WithLength( const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
381 
382 /** Search for the last occurrence of a substring within a string.
383 
384     If subStr is empty, or both str and subStr are empty, -1 is returned.
385     Both strings must be null-terminated.
386 
387     @param str
388     a null-terminated string.
389 
390     @param subStr
391     the null-terminated substring to be searched for.
392 
393     @return
394     the index (starting at 0) of the first character of the last occurrence
395     of the substring within the string, or -1 if the substring does not occur.
396  */
397 sal_Int32 SAL_CALL rtl_str_lastIndexOfStr( const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C();
398 
399 /** Search for the last occurrence of a substring within a string.
400 
401     If subStr is empty, or both str and subStr are empty, -1 is returned.
402 
403     @param str
404     a string.  Need not be null-terminated, but must be at least as long as
405     the specified len.
406 
407     @param len
408     the length of the string.
409 
410     @param subStr
411     the substring to be searched for.  Need not be null-terminated, but must
412     be at least as long as the specified subLen.
413 
414     @param subLen
415     the length of the substring.
416 
417     @return
418     the index (starting at 0) of the first character of the first occurrence
419     of the substring within the string, or -1 if the substring does not occur.
420  */
421 sal_Int32 SAL_CALL rtl_str_lastIndexOfStr_WithLength( const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
422 
423 /** Replace all occurrences of a single character within a string.
424 
425     If oldChar does not occur within str, then the string is not modified.
426     The string must be null-terminated.
427 
428     @param str
429     a null-terminated string.
430 
431     @param oldChar
432     the old character.
433 
434     @param newChar
435     the new character.
436  */
437 void SAL_CALL rtl_str_replaceChar( sal_Char * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
438 
439 /** Replace all occurrences of a single character within a string.
440 
441     If oldChar does not occur within str, then the string is not modified.
442 
443     @param str
444     a string.  Need not be null-terminated, but must be at least as long as
445     the specified len.
446 
447     @param len
448     the length of the string.
449 
450     @param oldChar
451     the old character.
452 
453     @param newChar
454     the new character.
455  */
456 void SAL_CALL rtl_str_replaceChar_WithLength( sal_Char * str, sal_Int32 len, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
457 
458 /** Convert all ASCII uppercase letters to lowercase within a string.
459 
460     The characters with values between 65 and 90 (ASCII A--Z) are replaced
461     with values between 97 and 122 (ASCII a--z).  The string must be
462     null-terminated.
463 
464     @param str
465     a null-terminated string.
466  */
467 void SAL_CALL rtl_str_toAsciiLowerCase( sal_Char * str ) SAL_THROW_EXTERN_C();
468 
469 /** Convert all ASCII uppercase letters to lowercase within a string.
470 
471     The characters with values between 65 and 90 (ASCII A--Z) are replaced
472     with values between 97 and 122 (ASCII a--z).
473 
474     @param str
475     a string.  Need not be null-terminated, but must be at least as long as
476     the specified len.
477 
478     @param len
479     the length of the string.
480  */
481 void SAL_CALL rtl_str_toAsciiLowerCase_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
482 
483 /** Convert all ASCII lowercase letters to uppercase within a string.
484 
485     The characters with values between 97 and 122 (ASCII a--z) are replaced
486     with values between 65 and 90 (ASCII A--Z).  The string must be
487     null-terminated.
488 
489     @param str
490     a null-terminated string.
491  */
492 void SAL_CALL rtl_str_toAsciiUpperCase( sal_Char * str ) SAL_THROW_EXTERN_C();
493 
494 /** Convert all ASCII lowercase letters to uppercase within a string.
495 
496     The characters with values between 97 and 122 (ASCII a--z) are replaced
497     with values between 65 and 90 (ASCII A--Z).
498 
499     @param str
500     a string.  Need not be null-terminated, but must be at least as long as
501     the specified len.
502 
503     @param len
504     the length of the string.
505  */
506 void SAL_CALL rtl_str_toAsciiUpperCase_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
507 
508 /** Remove white space from both ends of a string.
509 
510     All characters with values less than or equal to 32 (the space character)
511     are considered to be white space.  This function cannot be used for
512     language-specific operations.  The string must be null-terminated.
513 
514     @param str
515     a null-terminated string.
516 
517     @return
518     the new length of the string.
519  */
520 sal_Int32 SAL_CALL rtl_str_trim( sal_Char * str ) SAL_THROW_EXTERN_C();
521 
522 /** Remove white space from both ends of the string.
523 
524     All characters with values less than or equal to 32 (the space character)
525     are considered to be white space.  This function cannot be used for
526     language-specific operations.  The string must be null-terminated.
527 
528     @param str
529     a string.  Need not be null-terminated, but must be at least as long as
530     the specified len.
531 
532     @param len
533     the original length of the string.
534 
535     @return
536     the new length of the string.
537  */
538 sal_Int32 SAL_CALL rtl_str_trim_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
539 
540 /** Create the string representation of a boolean.
541 
542     If b is true, the buffer is filled with the string "true" and 5 is
543     returned.  If b is false, the buffer is filled with the string "false" and
544     6 is returned.  This function cannot be used for language-specific
545     operations.
546 
547     @param str
548     a buffer that is big enough to hold the result and the terminating NUL
549     character.  You should use the RTL_STR_MAX_VALUEOFBOOLEAN define to create
550     a buffer that is big enough.
551 
552     @param b
553     a boolean value.
554 
555     @return
556     the length of the string.
557  */
558 sal_Int32 SAL_CALL rtl_str_valueOfBoolean( sal_Char * str, sal_Bool b ) SAL_THROW_EXTERN_C();
559 #define RTL_STR_MAX_VALUEOFBOOLEAN 6
560 
561 /** Create the string representation of a character.
562 
563     @param str
564     a buffer that is big enough to hold the result and the terminating NUL
565     character.  You should use the RTL_STR_MAX_VALUEOFCHAR define to create a
566     buffer that is big enough.
567 
568     @param ch
569     a character value.
570 
571     @return
572     the length of the string.
573  */
574 sal_Int32 SAL_CALL rtl_str_valueOfChar( sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C();
575 #define RTL_STR_MAX_VALUEOFCHAR 2
576 
577 /** Create the string representation of an integer.
578 
579     This function cannot be used for language-specific operations.
580 
581     @param str
582     a buffer that is big enough to hold the result and the terminating NUL
583     character.  You should use the RTL_STR_MAX_VALUEOFINT32 define to create a
584     buffer that is big enough.
585 
586     @param i
587     an integer value.
588 
589     @param radix
590     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
591     (36), inclusive.
592 
593     @return
594     the length of the string.
595  */
596 sal_Int32 SAL_CALL rtl_str_valueOfInt32( sal_Char * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C();
597 #define RTL_STR_MIN_RADIX           2
598 #define RTL_STR_MAX_RADIX           36
599 #define RTL_STR_MAX_VALUEOFINT32    33
600 
601 /** Create the string representation of a long integer.
602 
603     This function cannot be used for language-specific operations.
604 
605     @param str
606     a buffer that is big enough to hold the result and the terminating NUL
607     character.  You should use the RTL_STR_MAX_VALUEOFINT64 define to create a
608     buffer that is big enough.
609 
610     @param l
611     a long integer value.
612 
613     @param radix
614     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
615     (36), inclusive.
616 
617     @return
618     the length of the string.
619  */
620 sal_Int32 SAL_CALL rtl_str_valueOfInt64( sal_Char * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
621 #define RTL_STR_MAX_VALUEOFINT64 65
622 
623 /** Create the string representation of a float.
624 
625     This function cannot be used for language-specific conversion.
626 
627     @param str
628     a buffer that is big enough to hold the result and the terminating NUL
629     character.  You should use the RTL_STR_MAX_VALUEOFFLOAT define to create a
630     buffer that is big enough.
631 
632     @param f
633     a float value.
634 
635     @return
636     the length of the string.
637  */
638 sal_Int32 SAL_CALL rtl_str_valueOfFloat( sal_Char * str, float f ) SAL_THROW_EXTERN_C();
639 #define RTL_STR_MAX_VALUEOFFLOAT 15
640 
641 /** Create the string representation of a double.
642 
643     This function cannot be used for language-specific conversion.
644 
645     @param str
646     a buffer that is big enough to hold the result and the terminating NUL
647     character.  You should use the RTL_STR_MAX_VALUEOFDOUBLE define to create
648     a buffer that is big enough.
649 
650     @param d
651     a double value.
652 
653     @return
654     the length of the string.
655  */
656 sal_Int32 SAL_CALL rtl_str_valueOfDouble( sal_Char * str, double d ) SAL_THROW_EXTERN_C();
657 #define RTL_STR_MAX_VALUEOFDOUBLE 25
658 
659 /** Interpret a string as a boolean.
660 
661     This function cannot be used for language-specific conversion.  The string
662     must be null-terminated.
663 
664     @param str
665     a null-terminated string.
666 
667     @return
668     true if the string is "1" or "true" in any ASCII case, false otherwise.
669  */
670 sal_Bool SAL_CALL rtl_str_toBoolean( const sal_Char * str ) SAL_THROW_EXTERN_C();
671 
672 /** Interpret a string as an integer.
673 
674     This function cannot be used for language-specific conversion.  The string
675     must be null-terminated.
676 
677     @param str
678     a null-terminated string.
679 
680     @param radix
681     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
682     (36), inclusive.
683 
684     @return
685     the integer value represented by the string, or 0 if the string does not
686     represent an integer.
687  */
688 sal_Int32 SAL_CALL rtl_str_toInt32( const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
689 
690 /** Interpret a string as a long integer.
691 
692     This function cannot be used for language-specific conversion.  The string
693     must be null-terminated.
694 
695     @param str
696     a null-terminated string.
697 
698     @param radix
699     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
700     (36), inclusive.
701 
702     @return
703     the long integer value represented by the string, or 0 if the string does
704     not represent a long integer.
705  */
706 sal_Int64 SAL_CALL rtl_str_toInt64( const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
707 
708 /** Interpret a string as a float.
709 
710     This function cannot be used for language-specific conversion.  The string
711     must be null-terminated.
712 
713     @param str
714     a null-terminated string.
715 
716     @return
717     the float value represented by the string, or 0.0 if the string does not
718     represent a float.
719  */
720 float SAL_CALL rtl_str_toFloat( const sal_Char * str ) SAL_THROW_EXTERN_C();
721 
722 /** Interpret a string as a double.
723 
724     This function cannot be used for language-specific conversion.  The string
725     must be null-terminated.
726 
727     @param str
728     a null-terminated string.
729 
730     @return
731     the float value represented by the string, or 0.0 if the string does not
732     represent a double.
733  */
734 double SAL_CALL rtl_str_toDouble( const sal_Char * str ) SAL_THROW_EXTERN_C();
735 
736 /* ======================================================================= */
737 
738 #ifdef SAL_W32
739 #	pragma pack(push, 8)
740 #elif defined(SAL_OS2)
741 #	pragma pack(push, 4)
742 #endif
743 
744 /** The implementation of a byte string.
745 
746     @internal
747  */
748 typedef struct _rtl_String
749 {
750     oslInterlockedCount refCount; /* opaque */
751     sal_Int32           length;
752     sal_Char            buffer[1];
753 } rtl_String;
754 
755 #if defined( SAL_W32) ||  defined(SAL_OS2)
756 #pragma pack(pop)
757 #endif
758 
759 /* ----------------------------------------------------------------------- */
760 
761 /** Increment the reference count of a string.
762 
763     @param str
764     a string.
765  */
766 void SAL_CALL rtl_string_acquire( rtl_String * str ) SAL_THROW_EXTERN_C();
767 
768 /** Decrement the reference count of a string.
769 
770     If the count goes to zero than the string data is deleted.
771 
772     @param str
773     a string.
774  */
775 void SAL_CALL rtl_string_release( rtl_String * str ) SAL_THROW_EXTERN_C();
776 
777 /** Allocate a new string containing no characters.
778 
779     @param newStr
780     pointer to the new string.  The pointed-to data must be null or a valid
781     string.
782  */
783 void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXTERN_C();
784 
785 /** Allocate a new string containing space for a given number of characters.
786 
787     If len is greater than zero, the reference count of the new string will be
788     1.  The values of all characters are set to 0 and the length of the string
789     is 0.  This function does not handle out-of-memory conditions.
790 
791     @param newStr
792     pointer to the new string.  The pointed-to data must be null or a valid
793     string.
794 
795     @param len
796     the number of characters.
797  */
798 void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C();
799 
800 /** Allocate a new string that contains a copy of another string.
801 
802     If the length of value is greater than zero, the reference count of the
803     new string will be 1.  This function does not handle out-of-memory
804     conditions.
805 
806     @param newStr
807     pointer to the new string.  The pointed-to data must be null or a valid
808     string.
809 
810     @param value
811     a valid string.
812  */
813 void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C();
814 
815 /** Allocate a new string that contains a copy of a character array.
816 
817     If the length of value is greater than zero, the reference count of the
818     new string will be 1.  This function does not handle out-of-memory
819     conditions.
820 
821     @param newStr
822     pointer to the new string.  The pointed-to data must be null or a valid
823     string.
824 
825     @param value
826     a null-terminated character array.
827  */
828 void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C();
829 
830 /** Allocate a new string that contains a copy of a character array.
831 
832     If the length of value is greater than zero, the reference count of the
833     new string will be 1.  This function does not handle out-of-memory
834     conditions.
835 
836     @param newStr
837     pointer to the new string.  The pointed-to data must be null or a valid
838     string.
839 
840     @param value
841     a character array.  Need not be null-terminated, but must be at least as
842     long as the specified len.
843 
844     @param len
845     the length of the character array.
846  */
847 void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const sal_Char * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
848 
849 /** Assign a new value to a string.
850 
851     First releases any value str might currently hold, then acquires
852     rightValue.
853 
854     @param str
855     pointer to the string.  The pointed-to data must be null or a valid
856     string.
857 
858     @param rightValue
859     a valid string.
860  */
861 void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C();
862 
863 /** Return the length of a string.
864 
865     The length is equal to the number of characters in the string.
866 
867     @param str
868     a valid string.
869 
870     @return
871     the length of the string.
872  */
873 sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C();
874 
875 /** Return a pointer to the underlying character array of a string.
876 
877     @param str
878     a valid string.
879 
880     @return
881     a pointer to the null-terminated character array.
882  */
883 sal_Char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C();
884 
885 /** Create a new string that is the concatenation of two other strings.
886 
887     The new string does not necessarily have a reference count of 1 (in cases
888     where one of the two other strings is empty), so it must not be modified
889     without checking the reference count.  This function does not handle
890     out-of-memory conditions.
891 
892     @param newStr
893     pointer to the new string.  The pointed-to data must be null or a valid
894     string.
895 
896     @param left
897     a valid string.
898 
899     @param right
900     a valid string.
901  */
902 void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C();
903 
904 /** Create a new string by replacing a substring of another string.
905 
906     The new string results from replacing a number of characters (count),
907     starting at the specified position (index) in the original string (str),
908     with some new substring (subStr).  If subStr is null, than only a number
909     of characters is deleted.
910 
911     The new string does not necessarily have a reference count of 1, so it
912     must not be modified without checking the reference count.  This function
913     does not handle out-of-memory conditions.
914 
915     @param newStr
916     pointer to the new string.  The pointed-to data must be null or a valid
917     string.
918 
919     @param str
920     a valid string.
921 
922     @param index
923     the index into str at which to start replacement.  Must be between 0 and
924     the length of str, inclusive.
925 
926     @param count
927     the number of charcters to remove.  Must not be negative, and the sum of
928     index and count must not exceed the length of str.
929 
930     @param subStr
931     either null or a valid string to be inserted.
932  */
933 void SAL_CALL rtl_string_newReplaceStrAt( rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C();
934 
935 /** Create a new string by replacing all occurrences of a single character
936     within another string.
937 
938     The new string results from replacing all occurrences of oldChar in str
939     with newChar.
940 
941     The new string does not necessarily have a reference count of 1 (in cases
942     where oldChar does not occur in str), so it must not be modified without
943     checking the reference count.  This function does not handle out-of-memory
944     conditions.
945 
946     @param newStr
947     pointer to the new string.  The pointed-to data must be null or a valid
948     string.
949 
950     @param str
951     a valid string.
952 
953     @param oldChar
954     the old character.
955 
956     @param newChar
957     the new character.
958  */
959 void SAL_CALL rtl_string_newReplace( rtl_String ** newStr, rtl_String * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
960 
961 /** Create a new string by converting all ASCII uppercase letters to lowercase
962     within another string.
963 
964     The new string results from replacing all characters with values between
965     65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
966 
967     This function cannot be used for language-specific conversion.  The new
968     string does not necessarily have a reference count of 1 (in cases where
969     no characters need to be converted), so it must not be modified without
970     checking the reference count.  This function does not handle out-of-memory
971     conditions.
972 
973     @param newStr
974     pointer to the new string.  The pointed-to data must be null or a valid
975     string.
976 
977     @param str
978     a valid string.
979  */
980 void SAL_CALL rtl_string_newToAsciiLowerCase( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
981 
982 /** Create a new string by converting all ASCII lowercase letters to uppercase
983     within another string.
984 
985     The new string results from replacing all characters with values between
986     97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z).
987 
988     This function cannot be used for language-specific conversion.  The new
989     string does not necessarily have a reference count of 1 (in cases where
990     no characters need to be converted), so it must not be modified without
991     checking the reference count.  This function does not handle out-of-memory
992     conditions.
993 
994     @param newStr
995     pointer to the new string.  The pointed-to data must be null or a valid
996     string.
997 
998     @param str
999     a valid string.
1000  */
1001 void SAL_CALL rtl_string_newToAsciiUpperCase( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1002 
1003 /** Create a new string by removing white space from both ends of another
1004     string.
1005 
1006     The new string results from removing all characters with values less than
1007     or equal to 32 (the space character) form both ends of str.
1008 
1009     This function cannot be used for language-specific conversion.  The new
1010     string does not necessarily have a reference count of 1 (in cases where
1011     no characters need to be removed), so it must not be modified without
1012     checking the reference count.  This function does not handle out-of-memory
1013     conditions.
1014 
1015     @param newStr
1016     pointer to the new string.  The pointed-to data must be null or a valid
1017     string.
1018 
1019     @param str
1020     a valid string.
1021  */
1022 void SAL_CALL rtl_string_newTrim( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1023 
1024 /** Create a new string by extracting a single token from another string.
1025 
1026     Starting at index, the token's next token is searched for.  If there is no
1027     such token, the result is an empty string.  Otherwise, all characters from
1028     the start of that token and up to, but not including the next occurrence
1029     of cTok make up the resulting token.  The return value is the position of
1030     the next token, or -1 if no more tokens follow.
1031 
1032     Example code could look like
1033       rtl_String * pToken = NULL;
1034       sal_Int32 nIndex = 0;
1035       do
1036       {
1037           ...
1038           nIndex = rtl_string_getToken(&pToken, pStr, 0, ';', nIndex);
1039           ...
1040       }
1041       while (nIndex >= 0);
1042 
1043     The new string does not necessarily have a reference count of 1, so it
1044     must not be modified without checking the reference count.  This function
1045     does not handle out-of-memory conditions.
1046 
1047     @param newStr
1048     pointer to the new string.  The pointed-to data must be null or a valid
1049     string.  If either token or index is negative, an empty token is stored in
1050     newStr (and -1 is returned).
1051 
1052     @param str
1053     a valid string.
1054 
1055     @param token
1056     the number of the token to return, starting at index.
1057 
1058     @param cTok
1059     the character that separates the tokens.
1060 
1061     @param index
1062     the position at which searching for the token starts.  Must not be greater
1063     than the length of str.
1064 
1065     @return
1066     the index of the next token, or -1 if no more tokens follow.
1067  */
1068 sal_Int32 SAL_CALL rtl_string_getToken( rtl_String ** newStr , rtl_String * str, sal_Int32 token, sal_Char cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
1069 
1070 /* ======================================================================= */
1071 
1072 /** Supply an ASCII string literal together with its length.
1073 
1074     This macro can be used to compute (some of) the arguments in function calls
1075     like rtl::OString(RTL_CONSTASCII_STRINGPARAM("foo")) or
1076     rtl::OUString::equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("foo")).
1077 
1078     @param constAsciiStr
1079     must be an expression of type "(possibly cv-qualified reference to) array of
1080     (possibly cv-qualified) char."  Each element of the referenced array must
1081     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1082     referenced array is not considered part of the represented ASCII string, and
1083     its value should be 0x00.  Depending on where this macro is used, the nature
1084     of the supplied expression might be further restricted.
1085 */
1086 #define RTL_CONSTASCII_STRINGPARAM( constAsciiStr ) constAsciiStr, ((sal_Int32)sizeof(constAsciiStr)-1)
1087 
1088 /** Supply the length of an ASCII string literal.
1089 
1090     This macro can be used to compute arguments in function calls like
1091     rtl::OUString::match(other, RTL_CONSTASCII_LENGTH("prefix")).
1092 
1093     @param constAsciiStr
1094     must be an expression of type "(possibly cv-qualified reference to) array of
1095     (possibly cv-qualified) char."  Each element of the referenced array must
1096     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1097     referenced array is not considered part of the represented ASCII string, and
1098     its value should be 0x00.  Depending on where this macro is used, the nature
1099     of the supplied expression might be further restricted.
1100 */
1101 #define RTL_CONSTASCII_LENGTH( constAsciiStr ) ((sal_Int32)(sizeof(constAsciiStr)-1))
1102 
1103 /* ======================================================================= */
1104 
1105 /* predefined constants for String-Conversion */
1106 #define OUSTRING_TO_OSTRING_CVTFLAGS    (RTL_UNICODETOTEXT_FLAGS_UNDEFINED_DEFAULT |\
1107                                          RTL_UNICODETOTEXT_FLAGS_INVALID_DEFAULT |\
1108                                          RTL_UNICODETOTEXT_FLAGS_UNDEFINED_REPLACE |\
1109                                          RTL_UNICODETOTEXT_FLAGS_PRIVATE_MAPTO0 |\
1110                                          RTL_UNICODETOTEXT_FLAGS_NOCOMPOSITE)
1111 
1112 /* ----------------------------------------------------------------------- */
1113 
1114 /** Create a new byte string by converting a Unicode string, using a specific
1115     text encoding.
1116 
1117     The lengths of the byte string and the Unicode string may differ (e.g.,
1118     for double-byte encodings, UTF-7, UTF-8).
1119 
1120     If the length of the Unicode string is greater than zero, the reference
1121     count of the new string will be 1.
1122 
1123     If an out-of-memory condition occurs, newStr will point to a null pointer
1124     upon return.
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 str
1131     a Unicode character array.  Need not be null-terminated, but must be at
1132     least as long as the specified len.
1133 
1134     @param len
1135     the length of the Unicode character array.
1136 
1137     @param encoding
1138     the text encoding to use for conversion.
1139 
1140     @param convertFlags
1141     flags which control the conversion.  Either use
1142     OUSTRING_TO_OSTRING_CVTFLAGS, or see
1143     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1144     details.
1145  */
1146 void SAL_CALL rtl_uString2String( rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
1147 
1148 /**
1149   Converts a Unicode string to a byte string, signalling failure.
1150 
1151   @param pTarget
1152   An out parameter receiving the converted string.  Must not be null itself, and
1153   must contain either null or a pointer to a valid rtl_String; the contents are
1154   not modified if conversion fails (rtl_convertUStringToString returns false).
1155 
1156   @param pSource
1157   The Unicode string.  May only be null if nLength is zero.
1158 
1159   @param nLength
1160   The length of the Unicode string.  Must be non-negative.
1161 
1162   @param nEncoding
1163   The text encoding to convert into.  Must be an octet encoding (i.e.,
1164   rtl_isOctetTextEncoding(nEncoding) must return true).
1165 
1166   @param nFlags
1167   A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the conversion
1168   (see rtl_convertUnicodeToText).  RTL_UNICODETOTEXT_FLAGS_FLUSH need not be
1169   included, it is implicitly assumed.  Typical uses are either
1170   RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
1171   RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot be
1172   converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS (make a
1173   best efforts conversion).
1174 
1175   @return
1176   True if the conversion succeeded, false otherwise.
1177  */
1178 sal_Bool SAL_CALL rtl_convertUStringToString(rtl_String ** pTarget,
1179                                              sal_Unicode const * pSource,
1180                                              sal_Int32 nLength,
1181                                              rtl_TextEncoding nEncoding,
1182                                              sal_uInt32 nFlags)
1183     SAL_THROW_EXTERN_C();
1184 
1185 #ifdef __cplusplus
1186 }
1187 #endif
1188 
1189 #endif /* _RTL_STRING_H_ */
1190