sal/inc/rtl/ustring.h

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