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