include/rtl/ustring.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_RTL_USTRING_H
  21 #define INCLUDED_RTL_USTRING_H
  22
  23 #include <sal/config.h>
  24
  25 #include <osl/interlck.h>
  26 #include <rtl/string.h>
  27 #include <rtl/textenc.h>
  28 #include <sal/saldllapi.h>
  29 #include <sal/types.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /* ======================================================================= */
  36
  37 /** Return the length of a string.
  38
  39     The length is equal to the number of 16-bit Unicode characters in the
  40     string, without the terminating NUL character.
  41
  42     @param str
  43     a null-terminated string.
  44
  45     @return
  46     the length of the sequence of characters represented by this string,
  47     excluding the terminating NUL character.
  48  */
  49 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_getLength(
  50         const sal_Unicode * str ) SAL_THROW_EXTERN_C();
  51
  52 /** Compare two strings.
  53
  54     The comparison is based on the numeric value of each character in the
  55     strings and returns a value indicating their relationship.  This function
  56     cannot be used for language-specific sorting.  Both strings must be
  57     null-terminated.
  58
  59     @param first
  60     the first null-terminated string to be compared.
  61
  62     @param second
  63     the second null-terminated string which is compared with the first one.
  64
  65     @return
  66     0 if both strings are equal, a value less than 0 if the first string is
  67     less than the second string, and a value greater than 0 if the first
  68     string is greater than the second string.
  69  */
  70 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compare(
  71         const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C();
  72
  73 /** Compare two strings.
  74
  75     The comparison is based on the numeric value of each character in the
  76     strings and returns a value indicating their relationship.  This function
  77     cannot be used for language-specific sorting.
  78
  79     @param first
  80     the first string to be compared.  Need not be null-terminated, but must be
  81     at least as long as the specified firstLen.
  82
  83     @param firstLen
  84     the length of the first string.
  85
  86     @param second
  87     the second string which is compared with the first one.  Need not be
  88     null-terminated, but must be at least as long as the specified secondLen.
  89
  90     @param secondLen
  91     the length of the second string.
  92
  93     @return
  94     0 if both strings are equal, a value less than 0 if the first string is
  95     less than the second string, and a value greater than 0 if the first
  96     string is greater than the second string.
  97  */
  98 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compare_WithLength(
  99         const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 100
 101 /** Compare two strings with a maximum count of characters.
 102
 103     The comparison is based on the numeric value of each character in the
 104     strings and returns a value indicating their relationship.  This function
 105     cannot be used for language-specific sorting.
 106
 107     @param first
 108     the first string to be compared.  Need not be null-terminated, but must be
 109     at least as long as the specified firstLen.
 110
 111     @param firstLen
 112     the length of the first string.
 113
 114     @param second
 115     the second string which is compared with the first one.  Need not be
 116     null-terminated, but must be at least as long as the specified secondLen.
 117
 118     @param secondLen
 119     the length of the second string.
 120
 121     @param shortenedLen
 122     the maximum number of characters to compare.  This length can be greater
 123     or smaller than the lengths of the two strings.
 124
 125     @return
 126     0 if both substrings are equal, a value less than 0 if the first substring
 127     is less than the second substring, and a value greater than 0 if the first
 128     substring is greater than the second substring.
 129  */
 130 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_shortenedCompare_WithLength(
 131         const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
 132
 133 /** Compare two strings from back to front.
 134
 135     The comparison is based on the numeric value of each character in the
 136     strings and returns a value indicating their relationship.  This function
 137     cannot be used for language-specific sorting.
 138
 139     @param first
 140     the first string to be compared.  Need not be null-terminated, but must be
 141     at least as long as the specified firstLen.
 142
 143     @param firstLen
 144     the length of the first string.
 145
 146     @param second
 147     the second string which is compared with the first one.  Need not be
 148     null-terminated, but must be at least as long as the specified secondLen.
 149
 150     @param secondLen
 151     the length of the second string.
 152
 153     @return
 154     0 if both strings are equal, a value less than 0 if the first string
 155     compares less than the second string, and a value greater than 0 if the
 156     first string compares greater than the second string.
 157  */
 158 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_reverseCompare_WithLength(
 159         const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 160
 161 /** Compare two strings from back to front for equality.
 162
 163     The comparison is based on the numeric value of each character in the
 164     strings and returns 'true' if, ans only if, both strings are equal.
 165     This function cannot be used for language-specific sorting.
 166
 167     @param first
 168     the first string to be compared.  Need not be null-terminated, but must be
 169     at least as long as the specified len.
 170
 171     @param second
 172     the second string which is compared with the first one.  Need not be
 173     null-terminated, but must be at least as long as the specified len.
 174
 175     @param len
 176     the length of both strings.
 177
 178     @return
 179     true if both strings are equal, false if they are not equal.
 180  */
 181
 182 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_ustr_asciil_reverseEquals_WithLength(
 183         const sal_Unicode * first, const sal_Char * second, sal_Int32 len ) SAL_THROW_EXTERN_C();
 184
 185 /** Compare two strings, ignoring the case of ASCII characters.
 186
 187     The comparison is based on the numeric value of each character in the
 188     strings and returns a value indicating their relationship.  Character
 189     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 190     and 122 (ASCII a--z).  This function cannot be used for language-specific
 191     sorting.  Both strings must be null-terminated.
 192
 193     @param first
 194     the first null-terminated string to be compared.
 195
 196     @param second
 197     the second null-terminated string which is compared with the first one.
 198
 199     @return
 200     0 if both strings are equal, a value less than 0 if the first string is
 201     less than the second string, and a value greater than 0 if the first
 202     string is greater than the second string.
 203  */
 204 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase(
 205         const sal_Unicode * first, const sal_Unicode * second ) SAL_THROW_EXTERN_C();
 206
 207 /** Compare two strings, ignoring the case of ASCII characters.
 208
 209     The comparison is based on the numeric value of each character in the
 210     strings and returns a value indicating their relationship.  Character
 211     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 212     and 122 (ASCII a--z).  This function cannot be used for language-specific
 213     sorting.
 214
 215     @param first
 216     the first string to be compared.  Need not be null-terminated, but must be
 217     at least as long as the specified firstLen.
 218
 219     @param firstLen
 220     the length of the first string.
 221
 222     @param second
 223     the second string which is compared with the first one.  Need not be
 224     null-terminated, but must be at least as long as the specified secondLen.
 225
 226     @param secondLen
 227     the length of the second string.
 228
 229     @return
 230     0 if both strings are equal, a value less than 0 if the first string is
 231     less than the second string, and a value greater than 0 if the first
 232     string is greater than the second string.
 233  */
 234 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_compareIgnoreAsciiCase_WithLength(
 235         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_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_shortenedCompareIgnoreAsciiCase_WithLength(
 270         const sal_Unicode * first, sal_Int32 firstLen, const sal_Unicode * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
 271
 272 /** Compare two strings.
 273
 274     The comparison is based on the numeric value of each character in the
 275     strings and returns a value indicating their relationship.  This function
 276     cannot be used for language-specific sorting.  Both strings must be
 277     null-terminated.
 278
 279     Since this function is optimized for performance, the ASCII character
 280     values are not converted in any way.  The caller has to make sure that
 281     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 282
 283     @param first
 284     the first null-terminated string to be compared.
 285
 286     @param second
 287     the second null-terminated ASCII string which is compared with the first
 288     one.
 289
 290     @return
 291     0 if both substrings are equal, a value less than 0 if the first substring
 292     is less than the second substring, and a value greater than 0 if the first
 293     substring is greater than the second substring.
 294  */
 295 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compare(
 296         const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
 297
 298 /** Compare two strings.
 299
 300     The comparison is based on the numeric value of each character in the
 301     strings and returns a value indicating their relationship.  This function
 302     cannot be used for language-specific sorting.
 303
 304     Since this function is optimized for performance, the ASCII character
 305     values are not converted in any way.  The caller has to make sure that
 306     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 307
 308     @param first
 309     the first string to be compared.  Need not be null-terminated, but must be
 310     at least as long as the specified firstLen.
 311
 312     @param firstLen
 313     the length of the first string.
 314
 315     @param second
 316     the second null-terminated ASCII string which is compared with the first
 317     one.
 318
 319     @return
 320     0 if both substrings are equal, a value less than 0 if the first substring
 321     is less than the second substring, and a value greater than 0 if the first
 322     substring is greater than the second substring.
 323  */
 324 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compare_WithLength(
 325         const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C();
 326
 327 /** Compare two strings with a maximum count of characters.
 328
 329     The comparison is based on the numeric value of each character in the
 330     strings and returns a value indicating their relationship.  This function
 331     cannot be used for language-specific sorting.
 332
 333     Since this function is optimized for performance, the ASCII character
 334     values are not converted in any way.  The caller has to make sure that
 335     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 336
 337     @param first
 338     the first string to be compared.  Need not be null-terminated, but must be
 339     at least as long as the specified firstLen.
 340
 341     @param firstLen
 342     the length of the first string.
 343
 344     @param second
 345     the second null-terminated ASCII string which is compared with the first
 346     one.
 347
 348     @param shortenedLen
 349     the maximum number of characters to compare.  This length can be greater
 350     or smaller than the lengths of the two strings.
 351
 352     @return
 353     0 if both substrings are equal, a value less than 0 if the first substring
 354     is less than the second substring, and a value greater than 0 if the first
 355     substring is greater than the second substring.
 356  */
 357 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompare_WithLength(
 358         const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
 359
 360 /** Compare two strings from back to front.
 361
 362     The comparison is based on the numeric value of each character in the
 363     strings and returns a value indicating their relationship.  This function
 364     cannot be used for language-specific sorting.
 365
 366     Since this function is optimized for performance, the ASCII character
 367     values are not converted in any way.  The caller has to make sure that
 368     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 369
 370     @param first
 371     the first string to be compared.  Need not be null-terminated, but must be
 372     at least as long as the specified firstLen.
 373
 374     @param firstLen
 375     the length of the first string.
 376
 377     @param second
 378     the second ASCII string which is compared with the first one.  Need not be
 379     null-terminated, but must be at least as long as the specified secondLen.
 380
 381     @param secondLen
 382     the length of the second string.
 383
 384     @return
 385     0 if both strings are equal, a value less than 0 if the first string
 386     compares less than the second string, and a value greater than 0 if the
 387     first string compares greater than the second string.
 388  */
 389 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_asciil_reverseCompare_WithLength(
 390         const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 391
 392 /** Compare two strings, ignoring the case of ASCII characters.
 393
 394     The comparison is based on the numeric value of each character in the
 395     strings and returns a value indicating their relationship.  Character
 396     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 397     and 122 (ASCII a--z).  This function cannot be used for language-specific
 398     sorting.  Both strings must be null-terminated.
 399
 400     Since this function is optimized for performance, the ASCII character
 401     values are not converted in any way.  The caller has to make sure that
 402     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 403
 404     @param first
 405     the first null-terminated string to be compared.
 406
 407     @param second
 408     the second null-terminated ASCII string which is compared with the first
 409     one.
 410
 411     @return
 412     0 if both strings are equal, a value less than 0 if the first string is
 413     less than the second string, and a value greater than 0 if the first
 414     string is greater than the second string.
 415  */
 416 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase(
 417         const sal_Unicode * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
 418
 419 /** Compare two strings, ignoring the case of ASCII characters.
 420
 421     The comparison is based on the numeric value of each character in the
 422     strings and returns a value indicating their relationship.  Character
 423     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 424     and 122 (ASCII a--z).  This function cannot be used for language-specific
 425     sorting.
 426
 427     Since this function is optimized for performance, the ASCII character
 428     values are not converted in any way.  The caller has to make sure that
 429     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 430
 431     @param first
 432     the first string to be compared.  Need not be null-terminated, but must be
 433     at least as long as the specified firstLen.
 434
 435     @param firstLen
 436     the length of the first string.
 437
 438     @param second
 439     the second null-terminated ASCII string which is compared with the first
 440     one.
 441
 442     @return
 443     0 if both strings are equal, a value less than 0 if the first string is
 444     less than the second string, and a value greater than 0 if the first
 445     string is greater than the second string.
 446  */
 447 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLength(
 448         const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second ) SAL_THROW_EXTERN_C();
 449
 450 /** Compare two strings, ignoring the case of ASCII characters.
 451
 452     The comparison is based on the numeric value of each character in the
 453     strings and returns a value indicating their relationship.  Character
 454     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 455     and 122 (ASCII a--z).  This function cannot be used for language-specific
 456     sorting.
 457
 458     Since this function is optimized for performance, the ASCII character
 459     values are not converted in any way.  The caller has to make sure that
 460     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 461
 462     @param first
 463     the first string to be compared.  Need not be null-terminated, but must be
 464     at least as long as the specified firstLen.
 465
 466     @param firstLen
 467     the length of the first string.
 468
 469     @param second
 470     the second string which is compared with the first one.  Need not be
 471     null-terminated, but must be at least as long as the specified secondLen.
 472
 473     @param secondLen
 474     the length of the second string.
 475
 476     @return
 477     0 if both strings are equal, a value less than 0 if the first string is
 478     less than the second string, and a value greater than 0 if the first
 479     string is greater than the second string.
 480  */
 481 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_compareIgnoreAsciiCase_WithLengths(
 482     sal_Unicode const * first, sal_Int32 firstLen,
 483     char const * second, sal_Int32 secondLen) SAL_THROW_EXTERN_C();
 484
 485 /** Compare two strings with a maximum count of characters, ignoring the case
 486     of ASCII characters.
 487
 488     The comparison is based on the numeric value of each character in the
 489     strings and returns a value indicating their relationship.  Character
 490     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 491     and 122 (ASCII a--z).  This function cannot be used for language-specific
 492     sorting.
 493
 494     Since this function is optimized for performance, the ASCII character
 495     values are not converted in any way.  The caller has to make sure that
 496     all ASCII characters are in the allowed range of 0 and 127, inclusive.
 497
 498     @param first
 499     the first string to be compared.  Need not be null-terminated, but must be
 500     at least as long as the specified firstLen.
 501
 502     @param firstLen
 503     the length of the first string.
 504
 505     @param second
 506     the second null-terminated ASCII string which is compared with the first
 507     one.
 508
 509     @param shortenedLen
 510     the maximum number of characters to compare.  This length can be greater
 511     or smaller than the lengths of the two strings.
 512
 513     @return
 514     0 if both substrings are equal, a value less than 0 if the first substring
 515     is less than the second substring, and a value greater than 0 if the first
 516     substring is greater than the second substring.
 517  */
 518 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_ascii_shortenedCompareIgnoreAsciiCase_WithLength(
 519         const sal_Unicode * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
 520
 521 /** Return a hash code for a string.
 522
 523     It is not allowed to store the hash code persistently, because later
 524     versions could return other hash codes.  The string must be
 525     null-terminated.
 526
 527     @param str
 528     a null-terminated string.
 529
 530     @return
 531     a hash code for the given string.
 532  */
 533 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_hashCode(
 534         const sal_Unicode * str ) SAL_THROW_EXTERN_C();
 535
 536 /** Return a hash code for a string.
 537
 538     It is not allowed to store the hash code persistently, because later
 539     versions could return other hash codes.
 540
 541     @param str
 542     a string.  Need not be null-terminated, but must be at least as long as
 543     the specified len.
 544
 545     @param len
 546     the length of the string.
 547
 548     @return
 549     a hash code for the given string.
 550  */
 551 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_hashCode_WithLength(
 552         const sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 553
 554 /** Search for the first occurrence of a character within a string.
 555
 556     The string must be null-terminated.
 557
 558     @param str
 559     a null-terminated string.
 560
 561     @param ch
 562     the character to be searched for.
 563
 564     @return
 565     the index (starting at 0) of the first occurrence of the character in the
 566     string, or -1 if the character does not occur.
 567  */
 568 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfChar(
 569         const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
 570
 571 /** Search for the first occurrence of a character within a string.
 572
 573     @param str
 574     a string.  Need not be null-terminated, but must be at least as long as
 575     the specified len.
 576
 577     @param len
 578     the length of the string.
 579
 580     @param ch
 581     the character to be searched for.
 582
 583     @return
 584     the index (starting at 0) of the first occurrence of the character in the
 585     string, or -1 if the character does not occur.
 586  */
 587 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfChar_WithLength(
 588         const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C();
 589
 590 /** Search for the last occurrence of a character within a string.
 591
 592     The string must be null-terminated.
 593
 594     @param str
 595     a null-terminated string.
 596
 597     @param ch
 598     the character to be searched for.
 599
 600     @return
 601     the index (starting at 0) of the last occurrence of the character in the
 602     string, or -1 if the character does not occur.  The returned value is
 603     always smaller than the string length.
 604  */
 605 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar(
 606         const sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
 607
 608 /** Search for the last occurrence of a character within a string.
 609
 610     @param str
 611     a string.  Need not be null-terminated, but must be at least as long as
 612     the specified len.
 613
 614     @param len
 615     the length of the string.
 616
 617     @param ch
 618     the character to be searched for.
 619
 620     @return
 621     the index (starting at 0) of the last occurrence of the character in the
 622     string, or -1 if the character does not occur.  The returned value is
 623     always smaller than the string length.
 624  */
 625 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfChar_WithLength(
 626         const sal_Unicode * str, sal_Int32 len, sal_Unicode ch ) SAL_THROW_EXTERN_C();
 627
 628 /** Search for the first occurrence of a substring within a string.
 629
 630     If subStr is empty, or both str and subStr are empty, -1 is returned.
 631     Both strings must be null-terminated.
 632
 633     @param str
 634     a null-terminated string.
 635
 636     @param subStr
 637     the null-terminated substring to be searched for.
 638
 639     @return
 640     the index (starting at 0) of the first character of the first occurrence
 641     of the substring within the string, or -1 if the substring does not occur.
 642  */
 643 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfStr(
 644         const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C();
 645
 646 /** Search for the first occurrence of a substring within a string.
 647
 648     If subStr is empty, or both str and subStr are empty, -1 is returned.
 649
 650     @param str
 651     a string.  Need not be null-terminated, but must be at least as long as
 652     the specified len.
 653
 654     @param len
 655     the length of the string.
 656
 657     @param subStr
 658     the substring to be searched for.  Need not be null-terminated, but must
 659     be at least as long as the specified subLen.
 660
 661     @param subLen
 662     the length of the substring.
 663
 664     @return
 665     the index (starting at 0) of the first character of the first occurrence
 666     of the substring within the string, or -1 if the substring does not occur.
 667  */
 668 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfStr_WithLength(
 669         const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
 670
 671 /** Search for the first occurrence of an ASCII substring within a string.
 672
 673     @param str
 674     a string.  Need not be null-terminated, but must be at least as long as
 675     the specified len.
 676
 677     @param len
 678     the length of the string; must be non-negative.
 679
 680     @param subStr
 681     the substring to be searched for.  Need not be null-terminated, but must
 682     be at least as long as the specified subLen.  Must only contain characters
 683     in the ASCII range 0x00--7F.
 684
 685     @param subLen
 686     the length of the substring; must be non-negative.
 687
 688     @return
 689     the index (starting at 0) of the first character of the first occurrence
 690     of the substring within the string, or -1 if the substring does not occur.
 691     If subLen is zero, -1 is returned.
 692
 693     @since UDK 3.2.7
 694 */
 695 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_indexOfAscii_WithLength(
 696     sal_Unicode const * str, sal_Int32 len,
 697     char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C();
 698
 699 /** Search for the last occurrence of a substring within a string.
 700
 701     If subStr is empty, or both str and subStr are empty, -1 is returned.
 702     Both strings must be null-terminated.
 703
 704     @param str
 705     a null-terminated string.
 706
 707     @param subStr
 708     the null-terminated substring to be searched for.
 709
 710     @return
 711     the index (starting at 0) of the first character of the last occurrence
 712     of the substring within the string, or -1 if the substring does not occur.
 713  */
 714 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr(
 715         const sal_Unicode * str, const sal_Unicode * subStr ) SAL_THROW_EXTERN_C();
 716
 717 /** Search for the last occurrence of a substring within a string.
 718
 719     If subStr is empty, or both str and subStr are empty, -1 is returned.
 720
 721     @param str
 722     a string.  Need not be null-terminated, but must be at least as long as
 723     the specified len.
 724
 725     @param len
 726     the length of the string.
 727
 728     @param subStr
 729     the substring to be searched for.  Need not be null-terminated, but must
 730     be at least as long as the specified subLen.
 731
 732     @param subLen
 733     the length of the substring.
 734
 735     @return
 736     the index (starting at 0) of the first character of the first occurrence
 737     of the substring within the string, or -1 if the substring does not occur.
 738  */
 739 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfStr_WithLength(
 740         const sal_Unicode * str, sal_Int32 len, const sal_Unicode * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
 741
 742 /** Search for the last occurrence of an ASCII substring within a string.
 743
 744     @param str
 745     a string.  Need not be null-terminated, but must be at least as long as
 746     the specified len.
 747
 748     @param len
 749     the length of the string; must be non-negative.
 750
 751     @param subStr
 752     the substring to be searched for.  Need not be null-terminated, but must
 753     be at least as long as the specified subLen.  Must only contain characters
 754     in the ASCII range 0x00--7F.
 755
 756     @param subLen
 757     the length of the substring; must be non-negative.
 758
 759     @return
 760     the index (starting at 0) of the first character of the last occurrence
 761     of the substring within the string, or -1 if the substring does not occur.
 762     If subLen is zero, -1 is returned.
 763
 764     @since UDK 3.2.7
 765 */
 766 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_lastIndexOfAscii_WithLength(
 767     sal_Unicode const * str, sal_Int32 len,
 768     char const * subStr, sal_Int32 subLen) SAL_THROW_EXTERN_C();
 769
 770 /** Replace all occurrences of a single character within a string.
 771
 772     If oldChar does not occur within str, then the string is not modified.
 773     The string must be null-terminated.
 774
 775     @param str
 776     a null-terminated string.
 777
 778     @param oldChar
 779     the old character.
 780
 781     @param newChar
 782     the new character.
 783  */
 784 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_replaceChar(
 785         sal_Unicode * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
 786
 787 /** Replace all occurrences of a single character within a string.
 788
 789     If oldChar does not occur within str, then the string is not modified.
 790
 791     @param str
 792     a string.  Need not be null-terminated, but must be at least as long as
 793     the specified len.
 794
 795     @param len
 796     the length of the string.
 797
 798     @param oldChar
 799     the old character.
 800
 801     @param newChar
 802     the new character.
 803  */
 804 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_replaceChar_WithLength(
 805         sal_Unicode * str, sal_Int32 len, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
 806
 807 /** Convert all ASCII uppercase letters to lowercase within a string.
 808
 809     The characters with values between 65 and 90 (ASCII A--Z) are replaced
 810     with values between 97 and 122 (ASCII a--z).  The string must be
 811     null-terminated.
 812
 813     @param str
 814     a null-terminated string.
 815  */
 816 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiLowerCase(
 817         sal_Unicode * str ) SAL_THROW_EXTERN_C();
 818
 819 /** Convert all ASCII uppercase letters to lowercase within a string.
 820
 821     The characters with values between 65 and 90 (ASCII A--Z) are replaced
 822     with values between 97 and 122 (ASCII a--z).
 823
 824     @param str
 825     a string.  Need not be null-terminated, but must be at least as long as
 826     the specified len.
 827
 828     @param len
 829     the length of the string.
 830  */
 831 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiLowerCase_WithLength(
 832         sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 833
 834 /** Convert all ASCII lowercase letters to uppercase within a string.
 835
 836     The characters with values between 97 and 122 (ASCII a--z) are replaced
 837     with values between 65 and 90 (ASCII A--Z).  The string must be
 838     null-terminated.
 839
 840     @param str
 841     a null-terminated string.
 842  */
 843 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiUpperCase(
 844         sal_Unicode * str ) SAL_THROW_EXTERN_C();
 845
 846 /** Convert all ASCII lowercase letters to uppercase within a string.
 847
 848     The characters with values between 97 and 122 (ASCII a--z) are replaced
 849     with values between 65 and 90 (ASCII A--Z).
 850
 851     @param str
 852     a string.  Need not be null-terminated, but must be at least as long as
 853     the specified len.
 854
 855     @param len
 856     the length of the string.
 857  */
 858 SAL_DLLPUBLIC void SAL_CALL rtl_ustr_toAsciiUpperCase_WithLength(
 859         sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 860
 861 /** Remove white space from both ends of a string.
 862
 863     All characters with values less than or equal to 32 (the space character)
 864     are considered to be white space.  This function cannot be used for
 865     language-specific operations.  The string must be null-terminated.
 866
 867     @param str
 868     a null-terminated string.
 869
 870     @return
 871     the new length of the string.
 872  */
 873 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_trim(
 874         sal_Unicode * str ) SAL_THROW_EXTERN_C();
 875
 876 /** Remove white space from both ends of the string.
 877
 878     All characters with values less than or equal to 32 (the space character)
 879     are considered to be white space.  This function cannot be used for
 880     language-specific operations.  The string must be null-terminated.
 881
 882     @param str
 883     a string.  Need not be null-terminated, but must be at least as long as
 884     the specified len.
 885
 886     @param len
 887     the original length of the string.
 888
 889     @return
 890     the new length of the string.
 891  */
 892 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_trim_WithLength(
 893         sal_Unicode * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 894
 895 /** Create the string representation of a boolean.
 896
 897     If b is true, the buffer is filled with the string "true" and 5 is
 898     returned.  If b is false, the buffer is filled with the string "false" and
 899     6 is returned.  This function cannot be used for language-specific
 900     operations.
 901
 902     @param str
 903     a buffer that is big enough to hold the result and the terminating NUL
 904     character.  You should use the RTL_USTR_MAX_VALUEOFBOOLEAN define to
 905     create a buffer that is big enough.
 906
 907     @param b
 908     a boolean value.
 909
 910     @return
 911     the length of the string.
 912  */
 913 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfBoolean(
 914         sal_Unicode * str, sal_Bool b ) SAL_THROW_EXTERN_C();
 915 #define RTL_USTR_MAX_VALUEOFBOOLEAN RTL_STR_MAX_VALUEOFBOOLEAN
 916
 917 /** Create the string representation of a character.
 918
 919     @param str
 920     a buffer that is big enough to hold the result and the terminating NUL
 921     character.  You should use the RTL_USTR_MAX_VALUEOFCHAR define to create a
 922     buffer that is big enough.
 923
 924     @param ch
 925     a character value.
 926
 927     @return
 928     the length of the string.
 929  */
 930 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfChar(
 931         sal_Unicode * str, sal_Unicode ch ) SAL_THROW_EXTERN_C();
 932 #define RTL_USTR_MAX_VALUEOFCHAR RTL_STR_MAX_VALUEOFCHAR
 933
 934 /** Create the string representation of an integer.
 935
 936     This function cannot be used for language-specific operations.
 937
 938     @param str
 939     a buffer that is big enough to hold the result and the terminating NUL
 940     character.  You should use the RTL_USTR_MAX_VALUEOFINT32 define to create
 941     a buffer that is big enough.
 942
 943     @param i
 944     an integer value.
 945
 946     @param radix
 947     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
 948     (36), inclusive.
 949
 950     @return
 951     the length of the string.
 952  */
 953 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfInt32(
 954         sal_Unicode * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 955 #define RTL_USTR_MIN_RADIX          RTL_STR_MIN_RADIX
 956 #define RTL_USTR_MAX_RADIX          RTL_STR_MAX_RADIX
 957 #define RTL_USTR_MAX_VALUEOFINT32   RTL_STR_MAX_VALUEOFINT32
 958
 959 /** Create the string representation of a long integer.
 960
 961     This function cannot be used for language-specific operations.
 962
 963     @param str
 964     a buffer that is big enough to hold the result and the terminating NUL
 965     character.  You should use the RTL_USTR_MAX_VALUEOFINT64 define to create
 966     a buffer that is big enough.
 967
 968     @param l
 969     a long integer value.
 970
 971     @param radix
 972     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
 973     (36), inclusive.
 974
 975     @return
 976     the length of the string.
 977  */
 978 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfInt64(
 979         sal_Unicode * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 980 #define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64
 981
 982 /** Create the string representation of an unsigned long integer.
 983
 984     This function cannot be used for language-specific operations.
 985
 986     @param str
 987     a buffer that is big enough to hold the result and the terminating NUL
 988     character.  You should use the RTL_USTR_MAX_VALUEOFUINT64 define to create
 989     a buffer that is big enough.
 990
 991     @param l
 992     a long integer value.
 993
 994     @param radix
 995     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
 996     (36), inclusive.
 997
 998     @return
 999     the length of the string.
1000  */
1001 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfUInt64(
1002         sal_Unicode * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1003 #define RTL_USTR_MAX_VALUEOFINT64 RTL_STR_MAX_VALUEOFINT64
1004
1005 /** Create the string representation of a float.
1006
1007     This function cannot be used for language-specific conversion.
1008
1009     @param str
1010     a buffer that is big enough to hold the result and the terminating NUL
1011     character.  You should use the RTL_USTR_MAX_VALUEOFFLOAT define to create
1012     a buffer that is big enough.
1013
1014     @param f
1015     a float value.
1016
1017     @return
1018     the length of the string.
1019  */
1020 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfFloat(
1021         sal_Unicode * str, float f ) SAL_THROW_EXTERN_C();
1022 #define RTL_USTR_MAX_VALUEOFFLOAT RTL_STR_MAX_VALUEOFFLOAT
1023
1024 /** Create the string representation of a double.
1025
1026     This function cannot be used for language-specific conversion.
1027
1028     @param str
1029     a buffer that is big enough to hold the result and the terminating NUL
1030     character.  You should use the RTL_USTR_MAX_VALUEOFDOUBLE define to create
1031     a buffer that is big enough.
1032
1033     @param d
1034     a double value.
1035
1036     @return
1037     the length of the string.
1038  */
1039 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_valueOfDouble(
1040         sal_Unicode * str, double d ) SAL_THROW_EXTERN_C();
1041 #define RTL_USTR_MAX_VALUEOFDOUBLE RTL_STR_MAX_VALUEOFDOUBLE
1042
1043 /** Interpret a string as a boolean.
1044
1045     This function cannot be used for language-specific conversion.  The string
1046     must be null-terminated.
1047
1048     @param str
1049     a null-terminated string.
1050
1051     @return
1052     true if the string is "1" or "true" in any ASCII case, false otherwise.
1053  */
1054 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_ustr_toBoolean(
1055         const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1056
1057 /** Interpret a string as an integer.
1058
1059     This function cannot be used for language-specific conversion.  The string
1060     must be null-terminated.
1061
1062     @param str
1063     a null-terminated string.
1064
1065     @param radix
1066     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1067     (36), inclusive.
1068
1069     @return
1070     the integer value represented by the string, or 0 if the string does not
1071     represent an integer.
1072  */
1073 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_ustr_toInt32(
1074         const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1075
1076 /** Interpret a string as an unsigned integer.
1077
1078     This function cannot be used for language-specific conversion.  The string
1079     must be null-terminated.
1080
1081     @param str
1082     a null-terminated string.
1083
1084     @param radix
1085     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1086     (36), inclusive.
1087
1088     @return
1089     the unsigned integer value represented by the string, or 0 if the string
1090     does not represent an unsigned integer.
1091
1092     @since LibreOffice 4.2
1093  */
1094 SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_ustr_toUInt32(
1095         const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1096
1097 /** Interpret a string as a long integer.
1098
1099     This function cannot be used for language-specific conversion.  The string
1100     must be null-terminated.
1101
1102     @param str
1103     a null-terminated string.
1104
1105     @param radix
1106     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1107     (36), inclusive.
1108
1109     @return
1110     the long integer value represented by the string, or 0 if the string does
1111     not represent a long integer.
1112  */
1113 SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_ustr_toInt64(
1114         const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1115
1116 /** Interpret a string as an unsigned long integer.
1117
1118     This function cannot be used for language-specific conversion.  The string
1119     must be null-terminated.
1120
1121     @param str
1122     a null-terminated string.
1123
1124     @param radix
1125     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
1126     (36), inclusive.
1127
1128     @return
1129     the unsigned long integer value represented by the string, or 0 if the
1130     string does not represent an unsigned long integer.
1131
1132     @since LibreOffice 4.1
1133  */
1134 SAL_DLLPUBLIC sal_uInt64 SAL_CALL rtl_ustr_toUInt64(
1135         const sal_Unicode * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
1136
1137 /** Interpret a string as a float.
1138
1139     This function cannot be used for language-specific conversion.  The string
1140     must be null-terminated.
1141
1142     @param str
1143     a null-terminated string.
1144
1145     @return
1146     the float value represented by the string, or 0.0 if the string does not
1147     represent a float.
1148  */
1149 SAL_DLLPUBLIC float SAL_CALL rtl_ustr_toFloat(
1150         const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1151
1152 /** Interpret a string as a double.
1153
1154     This function cannot be used for language-specific conversion.  The string
1155     must be null-terminated.
1156
1157     @param str
1158     a null-terminated string.
1159
1160     @return
1161     the float value represented by the string, or 0.0 if the string does not
1162     represent a double.
1163  */
1164 SAL_DLLPUBLIC double SAL_CALL rtl_ustr_toDouble(
1165         const sal_Unicode * str ) SAL_THROW_EXTERN_C();
1166
1167 /* ======================================================================= */
1168
1169 #if defined(SAL_W32)
1170 #pragma pack(push, 4)
1171 #endif
1172
1173 /** @cond INTERNAL */
1174 /** The implementation of a Unicode string.
1175 */
1176 typedef struct SAL_DLLPUBLIC_RTTI _rtl_uString
1177 {
1178     oslInterlockedCount refCount; /* opaque */
1179     sal_Int32           length;
1180     sal_Unicode         buffer[1];
1181 } rtl_uString;
1182 /** @endcond */
1183
1184 #if defined(SAL_W32)
1185 #pragma pack(pop)
1186 #endif
1187
1188 /* ----------------------------------------------------------------------- */
1189
1190 /** Increment the reference count of a string.
1191
1192     @param str
1193     a string.
1194  */
1195 SAL_DLLPUBLIC void SAL_CALL rtl_uString_acquire(
1196         rtl_uString * str ) SAL_THROW_EXTERN_C();
1197
1198 /** Decrement the reference count of a string.
1199
1200     If the count goes to zero than the string data is deleted.
1201
1202     @param str
1203     a string.
1204  */
1205 SAL_DLLPUBLIC void SAL_CALL rtl_uString_release(
1206         rtl_uString * str ) SAL_THROW_EXTERN_C();
1207
1208 /** Allocate a new string containing no characters.
1209
1210     @param newStr
1211     pointer to the new string.  The pointed-to data must be null or a valid
1212     string.
1213  */
1214 SAL_DLLPUBLIC void SAL_CALL rtl_uString_new(
1215         rtl_uString ** newStr ) SAL_THROW_EXTERN_C();
1216
1217 /** Allocate a new string containing space for a given number of characters.
1218
1219     The reference count of the new string will be 1. The length of the string
1220     will be nLen. This function does not handle out-of-memory conditions.
1221
1222     For nLen < 0 or failed allocation this method returns NULL.
1223
1224     The characters of the capacity are not cleared, and the length is set to
1225     nLen, unlike the similar method of rtl_uString_new_WithLength which
1226     zeros out the buffer, and sets the length to 0. So should be somewhat
1227     more efficient for allocating a new string.
1228
1229     call rtl_uString_release to release the string
1230     alternatively pass ownership to an OUString with
1231     rtl::OUString(newStr, SAL_NO_ACQUIRE);
1232
1233     @param[in] nLen the number of characters.
1234     @return pointer to the new string.
1235
1236     @since LibreOffice 4.1
1237  */
1238 SAL_DLLPUBLIC rtl_uString * SAL_CALL rtl_uString_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C();
1239
1240 /** Allocate a new string containing space for a given number of characters.
1241
1242     If len is greater than zero, the reference count of the new string will be
1243     1.  The values of all characters are set to 0 and the length of the string
1244     is 0.  This function does not handle out-of-memory conditions.
1245
1246     @param newStr
1247     pointer to the new string.  The pointed-to data must be null or a valid
1248     string.
1249
1250     @param nLen
1251     the number of characters.
1252  */
1253 SAL_DLLPUBLIC void SAL_CALL rtl_uString_new_WithLength(
1254         rtl_uString ** newStr, sal_Int32 nLen ) SAL_THROW_EXTERN_C();
1255
1256 /** Allocate a new string that contains a copy of another string.
1257
1258     If the length of value is greater than zero, the reference count of the
1259     new string will be 1.  This function does not handle out-of-memory
1260     conditions.
1261
1262     @param newStr
1263     pointer to the new string.  The pointed-to data must be null or a valid
1264     string.
1265
1266     @param value
1267     a valid string.
1268  */
1269 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromString(
1270         rtl_uString ** newStr, const rtl_uString * value ) SAL_THROW_EXTERN_C();
1271
1272 /** Allocate a new string that contains a copy of a character array.
1273
1274     If the length of value is greater than zero, the reference count of the
1275     new string will be 1.  This function does not handle out-of-memory
1276     conditions.
1277
1278     @param newStr
1279     pointer to the new string.  The pointed-to data must be null or a valid
1280     string.
1281
1282     @param value
1283     a null-terminated character array.
1284  */
1285 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr(
1286         rtl_uString ** newStr, const sal_Unicode * value ) SAL_THROW_EXTERN_C();
1287
1288 /** Allocate a new string that contains a copy of a character array.
1289
1290     If the length of value is greater than zero, the reference count of the
1291     new string will be 1.  This function does not handle out-of-memory
1292     conditions.
1293
1294     @param newStr
1295     pointer to the new string.  The pointed-to data must be null or a valid
1296     string.
1297
1298     @param value
1299     a character array.  Need not be null-terminated, but must be at least as
1300     long as the specified len.
1301
1302     @param len
1303     the length of the character array.
1304  */
1305 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromStr_WithLength(
1306         rtl_uString ** newStr, const sal_Unicode * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
1307
1308 /** Allocate a new string that is a substring of this string.
1309
1310     The substring begins at the specified beginIndex and contains count
1311     characters. Meaningless combinations such as negative beginIndex,
1312     or beginIndex + count greater than the length of the string have
1313     undefined behaviour.
1314
1315     @param[out]    newStr       the specified substring.
1316     @param[in]     from         the String to take the substring from.
1317     @param[in]     beginIndex   the beginning index, inclusive.
1318     @param[in]     count        the number of characters.
1319     @return    the specified substring.
1320
1321     @since LibreOffice 4.0
1322  */
1323 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromSubString(
1324         rtl_uString ** newStr, const rtl_uString * from,
1325         sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C();
1326
1327 /** Allocate a new string that contains a copy of a character array.
1328
1329     If the length of value is greater than zero, the reference count of the
1330     new string will be 1.  This function does not handle out-of-memory
1331     conditions.
1332
1333     Since this function is optimized for performance, the ASCII character
1334     values are not converted in any way.  The caller has to make sure that
1335     all ASCII characters are in the allowed range of 0 and 127, inclusive.
1336
1337     @param newStr
1338     pointer to the new string.  The pointed-to data must be null or a valid
1339     string.
1340
1341     @param value
1342     a null-terminated ASCII character array.
1343  */
1344 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromAscii(
1345         rtl_uString ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C();
1346
1347 /**
1348  @internal
1349  @since LibreOffice 3.6
1350 */
1351 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromLiteral(
1352         rtl_uString ** newStr, const sal_Char * value, sal_Int32 len,
1353         sal_Int32 allocExtra ) SAL_THROW_EXTERN_C();
1354
1355 /** Allocate a new string from an array of Unicode code points.
1356
1357     @param newString
1358     a non-null pointer to a (possibly null) rtl_uString pointer, which (if
1359     non-null) will have been passed to rtl_uString_release before the function
1360     returns.  Upon return, points to the newly allocated string or to null if
1361     there was either an out-of-memory condition or the resulting number of
1362     UTF-16 code units would have been larger than SAL_MAX_INT32.  The newly
1363     allocated string (if any) must ultimately be passed to rtl_uString_release.
1364
1365     @param codePoints
1366     an array of at least codePointCount code points, which each must be in the
1367     range from 0 to 0x10FFFF, inclusive.  May be null if codePointCount is zero.
1368
1369     @param codePointCount
1370     the non-negative number of code points.
1371
1372     @since UDK 3.2.7
1373 */
1374 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newFromCodePoints(
1375     rtl_uString ** newString, sal_uInt32 const * codePoints,
1376     sal_Int32 codePointCount) SAL_THROW_EXTERN_C();
1377
1378 /** Assign a new value to a string.
1379
1380     First releases any value str might currently hold, then acquires
1381     rightValue.
1382
1383     @param str
1384     pointer to the string.  The pointed-to data must be null or a valid
1385     string.
1386
1387     @param rightValue
1388     a valid string.
1389  */
1390 SAL_DLLPUBLIC void SAL_CALL rtl_uString_assign(
1391         rtl_uString ** str, rtl_uString * rightValue ) SAL_THROW_EXTERN_C();
1392
1393 /** Return the length of a string.
1394
1395     The length is equal to the number of characters in the string.
1396
1397     @param str
1398     a valid string.
1399
1400     @return
1401     the length of the string.
1402  */
1403 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uString_getLength(
1404         const rtl_uString * str ) SAL_THROW_EXTERN_C();
1405
1406 /** Return a pointer to the underlying character array of a string.
1407
1408     @param str
1409     a valid string.
1410
1411     @return
1412     a pointer to the null-terminated character array.
1413  */
1414 SAL_DLLPUBLIC sal_Unicode * SAL_CALL rtl_uString_getStr(
1415         rtl_uString * str ) SAL_THROW_EXTERN_C();
1416
1417 /** Create a new string that is the concatenation of two other strings.
1418
1419     The new string does not necessarily have a reference count of 1 (in cases
1420     where one of the two other strings is empty), so it must not be modified
1421     without checking the reference count.  This function does not handle
1422     out-of-memory conditions.
1423
1424     @param newStr
1425     pointer to the new string.  The pointed-to data must be null or a valid
1426     string.
1427
1428     @param left
1429     a valid string.
1430
1431     @param right
1432     a valid string.
1433  */
1434 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newConcat(
1435         rtl_uString ** newStr, rtl_uString * left, rtl_uString * right ) SAL_THROW_EXTERN_C();
1436
1437 /** Create a new string by replacing a substring of another string.
1438
1439     The new string results from replacing a number of characters (count),
1440     starting at the specified position (index) in the original string (str),
1441     with some new substring (subStr).  If subStr is null, than only a number
1442     of characters is deleted.
1443
1444     The new string does not necessarily have a reference count of 1, so it
1445     must not be modified without checking the reference count.  This function
1446     does not handle out-of-memory conditions.
1447
1448     @param newStr
1449     pointer to the new string.  The pointed-to data must be null or a valid
1450     string.
1451
1452     @param str
1453     a valid string.
1454
1455     @param idx
1456     the index into str at which to start replacement.  Must be between 0 and
1457     the length of str, inclusive.
1458
1459     @param count
1460     the number of characters to remove.  Must not be negative, and the sum of
1461     index and count must not exceed the length of str.
1462
1463     @param subStr
1464     either null or a valid string to be inserted.
1465  */
1466 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceStrAt(
1467         rtl_uString ** newStr, rtl_uString * str, sal_Int32 idx, sal_Int32 count, rtl_uString * subStr ) SAL_THROW_EXTERN_C();
1468
1469 /** Create a new string by replacing all occurrences of a single character
1470     within another string.
1471
1472     The new string results from replacing all occurrences of oldChar in str
1473     with newChar.
1474
1475     The new string does not necessarily have a reference count of 1 (in cases
1476     where oldChar does not occur in str), so it must not be modified without
1477     checking the reference count.  This function does not handle out-of-memory
1478     conditions.
1479
1480     @param newStr
1481     pointer to the new string.  The pointed-to data must be null or a valid
1482     string.
1483
1484     @param str
1485     a valid string.
1486
1487     @param oldChar
1488     the old character.
1489
1490     @param newChar
1491     the new character.
1492  */
1493 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplace(
1494         rtl_uString ** newStr, rtl_uString * str, sal_Unicode oldChar, sal_Unicode newChar ) SAL_THROW_EXTERN_C();
1495
1496 /** Create a new string by replacing the first occurrence of a given substring
1497     with another substring.
1498
1499     @param[in, out] newStr  pointer to the new string; must not be null; must
1500     point to null or a valid rtl_uString
1501
1502     @param str  pointer to the original string; must not be null
1503
1504     @param from  pointer to the substring to be replaced; must not be null
1505
1506     @param to  pointer to the replacing substring; must not be null
1507
1508     @param[in,out] index  pointer to a start index, must not be null; upon entry
1509     to the function its value is the index into the original string at which to
1510     start searching for the \p from substring, the value must be non-negative
1511     and not greater than the original string's length; upon exit from the
1512     function its value is the index into the original string at which the
1513     replacement took place or -1 if no replacement took place
1514
1515     @since LibreOffice 3.6
1516 */
1517 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirst(
1518     rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1519     rtl_uString const * to, sal_Int32 * index) SAL_THROW_EXTERN_C();
1520
1521 /** Create a new string by replacing the first occurrence of a given substring
1522     with another substring.
1523
1524     @param[in, out] newStr  pointer to the new string; must not be null; must
1525     point to null or a valid rtl_uString
1526
1527     @param str  pointer to the original string; must not be null
1528
1529     @param from  pointer to the substring to be replaced; must not be null and
1530     must point to memory of at least \p fromLength ASCII bytes
1531
1532     @param fromLength  the length of the \p from substring; must be non-negative
1533
1534     @param to  pointer to the replacing substring; must not be null
1535
1536     @param[in,out] index  pointer to a start index, must not be null; upon entry
1537     to the function its value is the index into the original string at which to
1538     start searching for the \p from substring, the value must be non-negative
1539     and not greater than the original string's length; upon exit from the
1540     function its value is the index into the original string at which the
1541     replacement took place or -1 if no replacement took place
1542
1543     @since LibreOffice 3.6
1544 */
1545 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstAsciiL(
1546     rtl_uString ** newStr, rtl_uString * str, char const * from,
1547     sal_Int32 fromLength, rtl_uString const * to, sal_Int32 * index)
1548     SAL_THROW_EXTERN_C();
1549
1550 /** Create a new string by replacing the first occurrence of a given substring
1551     with another substring.
1552
1553     @param[in, out] newStr  pointer to the new string; must not be null; must
1554     point to null or a valid rtl_uString
1555
1556     @param str  pointer to the original string; must not be null
1557
1558     @param from  pointer to the substring to be replaced; must not be null and
1559     must point to memory of at least \p fromLength ASCII bytes
1560
1561     @param fromLength  the length of the \p from substring; must be non-negative
1562
1563     @param to  pointer to the substring to be replaced; must not be null and
1564     must point to memory of at least \p toLength ASCII bytes
1565
1566     @param toLength  the length of the \p to substring; must be non-negative
1567
1568     @param[in,out] index  pointer to a start index, must not be null; upon entry
1569     to the function its value is the index into the original string at which to
1570     start searching for the \p from substring, the value must be non-negative
1571     and not greater than the original string's length; upon exit from the
1572     function its value is the index into the original string at which the
1573     replacement took place or -1 if no replacement took place
1574
1575     @since LibreOffice 3.6
1576 */
1577 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceFirstAsciiLAsciiL(
1578     rtl_uString ** newStr, rtl_uString * str, char const * from,
1579     sal_Int32 fromLength, char const * to, sal_Int32 toLength,
1580     sal_Int32 * index) SAL_THROW_EXTERN_C();
1581
1582 /** Create a new string by replacing all occurrences of a given substring with
1583     another substring.
1584
1585     Replacing subsequent occurrences picks up only after a given replacement.
1586     That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1587
1588     @param[in, out] newStr  pointer to the new string; must not be null; must
1589     point to null or a valid rtl_uString
1590
1591     @param str  pointer to the original string; must not be null
1592
1593     @param from  pointer to the substring to be replaced; must not be null
1594
1595     @param to  pointer to the replacing substring; must not be null
1596
1597     @since LibreOffice 3.6
1598 */
1599 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAll(
1600     rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1601     rtl_uString const * to) SAL_THROW_EXTERN_C();
1602
1603 /** Create a new string by replacing all occurrences of a given substring with
1604     another substring.
1605
1606     Replacing subsequent occurrences picks up only after a given replacement.
1607     That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1608
1609     @param[in, out] newStr  pointer to the new string; must not be null; must
1610     point to null or a valid rtl_uString
1611
1612     @param str  pointer to the original string; must not be null
1613
1614     @param from  pointer to the substring to be replaced; must not be null
1615
1616     @param to  pointer to the replacing substring; must not be null
1617
1618     @param fromIndex  the position in the string where we will begin searching
1619
1620     @since LibreOffice 4.0
1621 */
1622 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllFromIndex(
1623     rtl_uString ** newStr, rtl_uString * str, rtl_uString const * from,
1624     rtl_uString const * to, sal_Int32 fromIndex) SAL_THROW_EXTERN_C();
1625
1626 /** Create a new string by replacing all occurrences of a given substring with
1627     another substring.
1628
1629     Replacing subsequent occurrences picks up only after a given replacement.
1630     That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1631
1632     @param[in, out] newStr  pointer to the new string; must not be null; must
1633     point to null or a valid rtl_uString
1634
1635     @param str  pointer to the original string; must not be null
1636
1637     @param from  pointer to the substring to be replaced; must not be null and
1638     must point to memory of at least \p fromLength ASCII bytes
1639
1640     @param fromLength  the length of the \p from substring; must be non-negative
1641
1642     @param to  pointer to the replacing substring; must not be null
1643
1644     @since LibreOffice 3.6
1645 */
1646 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllAsciiL(
1647     rtl_uString ** newStr, rtl_uString * str, char const * from,
1648     sal_Int32 fromLength, rtl_uString const * to) SAL_THROW_EXTERN_C();
1649
1650 /** Create a new string by replacing all occurrences of a given substring with
1651     another substring.
1652
1653     Replacing subsequent occurrences picks up only after a given replacement.
1654     That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1655
1656     @param[in, out] newStr  pointer to the new string; must not be null; must
1657     point to null or a valid rtl_uString
1658
1659     @param str  pointer to the original string; must not be null
1660
1661     @param from  pointer to the substring to be replaced; must not be null and
1662     must point to memory of at least \p fromLength ASCII bytes
1663
1664     @param fromLength  the length of the \p from substring; must be non-negative
1665
1666     @param to  pointer to the substring to be replaced; must not be null and
1667     must point to memory of at least \p toLength ASCII bytes
1668
1669     @param toLength  the length of the \p to substring; must be non-negative
1670
1671     @since LibreOffice 3.6
1672 */
1673 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newReplaceAllAsciiLAsciiL(
1674     rtl_uString ** newStr, rtl_uString * str, char const * from,
1675     sal_Int32 fromLength, char const * to, sal_Int32 toLength)
1676     SAL_THROW_EXTERN_C();
1677
1678 /** Create a new string by converting all ASCII uppercase letters to lowercase
1679     within another string.
1680
1681     The new string results from replacing all characters with values between
1682     65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
1683
1684     This function cannot be used for language-specific conversion.  The new
1685     string does not necessarily have a reference count of 1 (in cases where
1686     no characters need to be converted), so it must not be modified without
1687     checking the reference count.  This function does not handle out-of-memory
1688     conditions.
1689
1690     @param newStr
1691     pointer to the new string.  The pointed-to data must be null or a valid
1692     string.
1693
1694     @param str
1695     a valid string.
1696  */
1697 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newToAsciiLowerCase(
1698         rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
1699
1700 /** Create a new string by converting all ASCII lowercase letters to uppercase
1701     within another string.
1702
1703     The new string results from replacing all characters with values between
1704     97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z).
1705
1706     This function cannot be used for language-specific conversion.  The new
1707     string does not necessarily have a reference count of 1 (in cases where
1708     no characters need to be converted), so it must not be modified without
1709     checking the reference count.  This function does not handle out-of-memory
1710     conditions.
1711
1712     @param newStr
1713     pointer to the new string.  The pointed-to data must be null or a valid
1714     string.
1715
1716     @param str
1717     a valid string.
1718  */
1719 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newToAsciiUpperCase(
1720         rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
1721
1722 /** Create a new string by removing white space from both ends of another
1723     string.
1724
1725     The new string results from removing all characters with values less than
1726     or equal to 32 (the space character) form both ends of str.
1727
1728     This function cannot be used for language-specific conversion.  The new
1729     string does not necessarily have a reference count of 1 (in cases where
1730     no characters need to be removed), so it must not be modified without
1731     checking the reference count.  This function does not handle out-of-memory
1732     conditions.
1733
1734     @param newStr
1735     pointer to the new string.  The pointed-to data must be null or a valid
1736     string.
1737
1738     @param str
1739     a valid string.
1740  */
1741 SAL_DLLPUBLIC void SAL_CALL rtl_uString_newTrim(
1742         rtl_uString ** newStr, rtl_uString * str ) SAL_THROW_EXTERN_C();
1743
1744 /** Create a new string by extracting a single token from another string.
1745
1746     Starting at index, the token's next token is searched for.  If there is no
1747     such token, the result is an empty string.  Otherwise, all characters from
1748     the start of that token and up to, but not including the next occurrence
1749     of cTok make up the resulting token.  The return value is the position of
1750     the next token, or -1 if no more tokens follow.
1751
1752     Example code could look like
1753       rtl_uString * pToken = NULL;
1754       sal_Int32 nIndex = 0;
1755       do
1756       {
1757           ...
1758           nIndex = rtl_uString_getToken(&pToken, pStr, 0, ';', nIndex);
1759           ...
1760       }
1761       while (nIndex >= 0);
1762
1763     The new string does not necessarily have a reference count of 1, so it
1764     must not be modified without checking the reference count.  This function
1765     does not handle out-of-memory conditions.
1766
1767     @param newStr
1768     pointer to the new string.  The pointed-to data must be null or a valid
1769     string.  If either token or index is negative, an empty token is stored in
1770     newStr (and -1 is returned).
1771
1772     @param str
1773     a valid string.
1774
1775     @param token
1776     the number of the token to return, starting at index.
1777
1778     @param cTok
1779     the character that separates the tokens.
1780
1781     @param idx
1782     the position at which searching for the token starts.  Must not be greater
1783     than the length of str.
1784
1785     @return
1786     the index of the next token, or -1 if no more tokens follow.
1787  */
1788 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_uString_getToken(
1789         rtl_uString ** newStr , rtl_uString * str, sal_Int32 token, sal_Unicode cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
1790
1791 /* ======================================================================= */
1792
1793 /** Supply an ASCII string literal together with its length and text encoding.
1794
1795     This macro can be used to compute (some of) the arguments in function calls
1796     like rtl::OUString(RTL_CONSTASCII_USTRINGPARAM("foo")).
1797
1798     @param constAsciiStr
1799     must be an expression of type "(possibly cv-qualified reference to) array of
1800     (possibly cv-qualified) char."  Each element of the referenced array must
1801     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1802     referenced array is not considered part of the represented ASCII string, and
1803     its value should be 0x00.  Depending on where this macro is used, the nature
1804     of the supplied expression might be further restricted.
1805 */
1806 // The &foo[0] trick is intentional, it makes sure the type is char* or const char*
1807 // (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed).
1808 // This is to avoid mistaken use with functions that accept string literals
1809 // (i.e. const char (&)[N]) where usage of this macro otherwise could match
1810 // the argument and a following int argument with a default value (e.g. OUString::match()).
1811 #define RTL_CONSTASCII_USTRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \
1812     ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1)), RTL_TEXTENCODING_ASCII_US
1813
1814 /* ======================================================================= */
1815
1816 /* predefined constants for String-Conversion */
1817 #define OSTRING_TO_OUSTRING_CVTFLAGS    (RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_MAPTOPRIVATE |\
1818                                          RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_DEFAULT |\
1819                                          RTL_TEXTTOUNICODE_FLAGS_INVALID_DEFAULT)
1820
1821 /* ----------------------------------------------------------------------- */
1822
1823 /** Create a new Unicode string by converting a byte string, using a specific
1824     text encoding.
1825
1826     The lengths of the byte string and the Unicode string may differ (e.g.,
1827     for double-byte encodings, UTF-7, UTF-8).
1828
1829     If the length of the byte string is greater than zero, the reference count
1830     of the new string will be 1.
1831
1832     If an out-of-memory condition occurs, newStr will point to a null pointer
1833     upon return.
1834
1835     @param newStr
1836     pointer to the new string.  The pointed-to data must be null or a valid
1837     string.
1838
1839     @param str
1840     a byte character array.  Need not be null-terminated, but must be at
1841     least as long as the specified len.
1842
1843     @param len
1844     the length of the byte character array.
1845
1846     @param encoding
1847     the text encoding to use for conversion.
1848
1849     @param convertFlags
1850     flags which control the conversion.  Either use
1851     OSTRING_TO_OUSTRING_CVTFLAGS, or see
1852     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1853     details.
1854  */
1855 SAL_DLLPUBLIC void SAL_CALL rtl_string2UString(
1856         rtl_uString ** newStr, const sal_Char * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
1857
1858 /* ======================================================================= */
1859 /* Interning methods */
1860
1861 /** Return a canonical representation for a string.
1862
1863     A pool of strings, initially empty is maintained privately
1864     by the string class. On invocation, if present in the pool
1865     the original string will be returned. Otherwise this string,
1866     or a copy thereof will be added to the pool and returned.
1867
1868     @param newStr
1869     pointer to the new string.  The pointed-to data must be null or a valid
1870     string.
1871
1872     If an out-of-memory condition occurs, newStr will point to a null pointer
1873     upon return.
1874
1875     @param str
1876     pointer to the string to be interned.
1877
1878     @since UDK 3.2.7
1879  */
1880 SAL_DLLPUBLIC void SAL_CALL rtl_uString_intern(
1881         rtl_uString ** newStr, rtl_uString * str) SAL_THROW_EXTERN_C();
1882
1883 /** Return a canonical representation for a string.
1884
1885     A pool of strings, initially empty is maintained privately
1886     by the string class. On invocation, if present in the pool
1887     the original string will be returned. Otherwise this string,
1888     or a copy thereof will be added to the pool and returned.
1889
1890     @param newStr
1891     pointer to the new string.  The pointed-to data must be null or a valid
1892     string.
1893
1894     If an out-of-memory condition occurs, newStr will point to a null pointer
1895     upon return.
1896
1897     @param str
1898     a byte character array.  Need not be null-terminated, but must be at
1899     least as long as the specified len.
1900
1901     @param len
1902     the length of the byte character array.
1903
1904     @param encoding
1905     the text encoding to use for conversion.
1906
1907     @param convertFlags
1908     flags which control the conversion.  Either use
1909     OSTRING_TO_OUSTRING_CVTFLAGS, or see
1910     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1911     details.
1912
1913     @param pInfo
1914     pointer to return conversion status in, or NULL.
1915
1916     @since UDK 3.2.7
1917  */
1918 SAL_DLLPUBLIC void SAL_CALL rtl_uString_internConvert(
1919                                          rtl_uString   ** newStr,
1920                                          const sal_Char * str,
1921                                          sal_Int32        len,
1922                                          rtl_TextEncoding encoding,
1923                                          sal_uInt32       convertFlags,
1924                                          sal_uInt32      *pInfo) SAL_THROW_EXTERN_C();
1925
1926 /** Iterate through a string based on code points instead of UTF-16 code units.
1927
1928     See Chapter 3 of The Unicode Standard 5.0 (Addison--Wesley, 2006) for
1929     definitions of the various terms used in this description.
1930
1931     The given string is interpreted as a sequence of zero or more UTF-16 code
1932     units.  For each index into this sequence (from zero to one less than the
1933     length of the sequence, inclusive), a code point represented starting at the
1934     given index is computed as follows:
1935
1936     - If the UTF-16 code unit addressed by the index constitutes a well-formed
1937     UTF-16 code unit sequence, the computed code point is the scalar value
1938     encoded by that UTF-16 code unit sequence.
1939
1940     - Otherwise, if the index is at least two UTF-16 code units away from the
1941     end of the sequence, and the sequence of two UTF-16 code units addressed by
1942     the index constitutes a well-formed UTF-16 code unit sequence, the computed
1943     code point is the scalar value encoded by that UTF-16 code unit sequence.
1944
1945     - Otherwise, the computed code point is the UTF-16 code unit addressed by
1946     the index.  (This last case catches unmatched surrogates as well as indices
1947     pointing into the middle of surrogate pairs.)
1948
1949     @param string
1950     pointer to a valid string; must not be null.
1951
1952     @param indexUtf16
1953     pointer to a UTF-16 based index into the given string; must not be null.  On
1954     entry, the index must be in the range from zero to the length of the string
1955     (in UTF-16 code units), inclusive.  Upon successful return, the index will
1956     be updated to address the UTF-16 code unit that is the given
1957     incrementCodePoints away from the initial index.
1958
1959     @param incrementCodePoints
1960     the number of code points to move the given *indexUtf16.  If non-negative,
1961     moving is done after determining the code point at the index.  If negative,
1962     moving is done before determining the code point at the (then updated)
1963     index.  The value must be such that the resulting UTF-16 based index is in
1964     the range from zero to the length of the string (in UTF-16 code units),
1965     inclusive.
1966
1967     @return
1968     the code point (an integer in the range from 0 to 0x10FFFF, inclusive) that
1969     is represented within the string starting at the index computed as follows:
1970     If incrementCodePoints is non-negative, the index is the initial value of
1971     *indexUtf16; if incrementCodePoints is negative, the index is the updated
1972     value of *indexUtf16.  In either case, the computed index must be in the
1973     range from zero to one less than the length of the string (in UTF-16 code
1974     units), inclusive.
1975
1976     @since UDK 3.2.7
1977 */
1978 SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_uString_iterateCodePoints(
1979     rtl_uString const * string, sal_Int32 * indexUtf16,
1980     sal_Int32 incrementCodePoints);
1981
1982 /** Converts a byte string to a Unicode string, signalling failure.
1983
1984     @param target
1985     An out parameter receiving the converted string.  Must not be null itself,
1986     and must contain either null or a pointer to a valid rtl_uString; the
1987     contents are unspecified if conversion fails (rtl_convertStringToUString
1988     returns false).
1989
1990     @param source
1991     The byte string.  May only be null if length is zero.
1992
1993     @param length
1994     The length of the byte string.  Must be non-negative.
1995
1996     @param encoding
1997     The text encoding to convert from.  Must be an octet encoding (i.e.,
1998     rtl_isOctetTextEncoding(encoding) must return true).
1999
2000     @param flags
2001     A combination of RTL_TEXTTOUNICODE_FLAGS that detail how to do the
2002     conversion (see rtl_convertTextToUnicode).  RTL_TEXTTOUNICODE_FLAGS_FLUSH
2003     need not be included, it is implicitly assumed.  Typical uses are either
2004     RTL_TEXTTOUNICODE_FLAGS_UNDEFINED_ERROR |
2005     RTL_TEXTTOUNICODE_FLAGS_MBUNDEFINED_ERROR |
2006     RTL_TEXTTOUNICODE_FLAGS_INVALID_ERROR (fail if a byte or multi-byte sequence
2007     cannot be converted from the source encoding) or
2008     OSTRING_TO_OUSTRING_CVTFLAGS (make a best efforts conversion).
2009
2010     @return
2011     True if the conversion succeeded, false otherwise.
2012
2013     @since UDK 3.2.9
2014 */
2015 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertStringToUString(
2016     rtl_uString ** target, char const * source, sal_Int32 length,
2017     rtl_TextEncoding encoding, sal_uInt32 flags) SAL_THROW_EXTERN_C();
2018
2019 /** Ensure a string has enough space for a given number of characters.
2020
2021  If the given string is large enough and has refcount of 1, it is not altered in any way.
2022  Otherwise it is replaced by a copy that has enough space for the given number of characters,
2023  data from the source string is copied to the beginning of it, the content of the remaining
2024  capacity undefined, the string has refcount of 1, and refcount of the original string is decreased.
2025
2026  @param str
2027  pointer to the string.  The pointed-to data must be a valid string.
2028
2029  @param size
2030  the number of characters
2031
2032  @since LibreOffice 4.1
2033  @internal
2034  */
2035 SAL_DLLPUBLIC void SAL_CALL rtl_uString_ensureCapacity( rtl_uString ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();
2036
2037 #ifdef __cplusplus
2038 }
2039 #endif
2040
2041 #endif // INCLUDED_RTL_USTRING_H
2042
2043 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */