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