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