include/rtl/string.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 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_RTL_STRING_H
  25 #define INCLUDED_RTL_STRING_H
  26
  27 #include "sal/config.h"
  28
  29 #include "osl/interlck.h"
  30 #include "rtl/textcvt.h"
  31 #include "sal/saldllapi.h"
  32 #include "sal/types.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /* ======================================================================= */
  39
  40 /** Return the length of a string.
  41
  42     The length is equal to the number of 8-bit characters in the string,
  43     without the terminating NUL character.
  44
  45     @param str
  46     a null-terminated string.
  47
  48     @return
  49     the length of the sequence of characters represented by this string,
  50     excluding the terminating NUL character.
  51  */
  52 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_getLength(
  53         const char * str ) SAL_THROW_EXTERN_C();
  54
  55 /** Compare two strings.
  56
  57     The comparison is based on the numeric value of each character in the
  58     strings and returns a value indicating their relationship.  This function
  59     cannot be used for language-specific sorting.  Both strings must be
  60     null-terminated.
  61
  62     @param first
  63     the first null-terminated string to be compared.
  64
  65     @param second
  66     the second null-terminated string which is compared with the first one.
  67
  68     @return
  69     0 if both strings are equal, a value less than 0 if the first string is
  70     less than the second string, and a value greater than 0 if the first
  71     string is greater than the second string.
  72  */
  73 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compare(
  74         const char * first, const char * second ) SAL_THROW_EXTERN_C();
  75
  76 /** Compare two strings.
  77
  78     The comparison is based on the numeric value of each character in the
  79     strings and returns a value indicating their relationship.  This function
  80     cannot be used for language-specific sorting.
  81
  82     @param first
  83     the first string to be compared.  Need not be null-terminated, but must be
  84     at least as long as the specified firstLen.
  85
  86     @param firstLen
  87     the length of the first string.
  88
  89     @param second
  90     the second string which is compared with the first one.  Need not be
  91     null-terminated, but must be at least as long as the specified secondLen.
  92
  93     @param secondLen
  94     the length of the second string.
  95
  96     @return
  97     0 if both strings are equal, a value less than 0 if the first string is
  98     less than the second string, and a value greater than 0 if the first
  99     string is greater than the second string.
 100  */
 101 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compare_WithLength(
 102         const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 103
 104 /** Compare two strings with a maximum count of characters.
 105
 106     The comparison is based on the numeric value of each character in the
 107     strings and returns a value indicating their relationship.  This function
 108     cannot be used for language-specific sorting.
 109
 110     @param first
 111     the first string to be compared.  Need not be null-terminated, but must be
 112     at least as long as the specified firstLen.
 113
 114     @param firstLen
 115     the length of the first string.
 116
 117     @param second
 118     the second string which is compared with the first one.  Need not be
 119     null-terminated, but must be at least as long as the specified secondLen.
 120
 121     @param secondLen
 122     the length of the second string.
 123
 124     @param shortenedLen
 125     the maximum number of characters to compare.  This length can be greater
 126     or smaller than the lengths of the two strings.
 127
 128     @return
 129     0 if both substrings are equal, a value less than 0 if the first substring
 130     is less than the second substring, and a value greater than 0 if the first
 131     substring is greater than the second substring.
 132  */
 133 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_shortenedCompare_WithLength(
 134         const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
 135
 136 /** Compare two strings from back to front.
 137
 138     The comparison is based on the numeric value of each character in the
 139     strings and returns a value indicating their relationship.  This function
 140     cannot be used for language-specific sorting.
 141
 142     @param first
 143     the first string to be compared.  Need not be null-terminated, but must be
 144     at least as long as the specified firstLen.
 145
 146     @param firstLen
 147     the length of the first string.
 148
 149     @param second
 150     the second string which is compared with the first one.  Need not be
 151     null-terminated, but must be at least as long as the specified secondLen.
 152
 153     @param secondLen
 154     the length of the second string.
 155
 156     @return
 157     0 if both strings are equal, a value less than 0 if the first string
 158     compares less than the second string, and a value greater than 0 if the
 159     first string compares greater than the second string.
 160  */
 161 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_reverseCompare_WithLength(
 162         const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 163
 164 /** Compare two strings, ignoring the case of ASCII characters.
 165
 166     The comparison is based on the numeric value of each character in the
 167     strings and returns a value indicating their relationship.  Character
 168     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 169     and 122 (ASCII a--z).  This function cannot be used for language-specific
 170     sorting.  Both strings must be null-terminated.
 171
 172     @param first
 173     the first null-terminated string to be compared.
 174
 175     @param second
 176     the second null-terminated string which is compared with the first one.
 177
 178     @return
 179     0 if both strings are equal, a value less than 0 if the first string is
 180     less than the second string, and a value greater than 0 if the first
 181     string is greater than the second string.
 182  */
 183 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase(
 184         const char * first, const char * second ) SAL_THROW_EXTERN_C();
 185
 186 /** Compare two strings, ignoring the case of ASCII characters.
 187
 188     The comparison is based on the numeric value of each character in the
 189     strings and returns a value indicating their relationship.  Character
 190     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 191     and 122 (ASCII a--z).  This function cannot be used for language-specific
 192     sorting.
 193
 194     @param first
 195     the first string to be compared.  Need not be null-terminated, but must be
 196     at least as long as the specified firstLen.
 197
 198     @param firstLen
 199     the length of the first string.
 200
 201     @param second
 202     the second string which is compared with the first one.  Need not be
 203     null-terminated, but must be at least as long as the specified secondLen.
 204
 205     @param secondLen
 206     the length of the second string.
 207
 208     @return
 209     0 if both strings are equal, a value less than 0 if the first string is
 210     less than the second string, and a value greater than 0 if the first
 211     string is greater than the second string.
 212  */
 213 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase_WithLength(
 214         const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 215
 216 /** Compare two strings with a maximum count of characters, ignoring the case
 217     of ASCII characters.
 218
 219     The comparison is based on the numeric value of each character in the
 220     strings and returns a value indicating their relationship.  Character
 221     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 222     and 122 (ASCII a--z).  This function cannot be used for language-specific
 223     sorting.
 224
 225     @param first
 226     the first string to be compared.  Need not be null-terminated, but must be
 227     at least as long as the specified firstLen.
 228
 229     @param firstLen
 230     the length of the first string.
 231
 232     @param second
 233     the second string which is compared with the first one.  Need not be
 234     null-terminated, but must be at least as long as the specified secondLen.
 235
 236     @param secondLen
 237     the length of the second string.
 238
 239     @param shortenedLen
 240     the maximum number of characters to compare.  This length can be greater
 241     or smaller than the lengths of the two strings.
 242
 243     @return
 244     0 if both substrings are equal, a value less than 0 if the first substring
 245     is less than the second substring, and a value greater than 0 if the first
 246     substring is greater than the second substring.
 247  */
 248 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_shortenedCompareIgnoreAsciiCase_WithLength(
 249         const char * first, sal_Int32 firstLen, const char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
 250
 251 /** Return a hash code for a string.
 252
 253     It is not allowed to store the hash code persistently, because later
 254     versions could return other hash codes.  The string must be
 255     null-terminated.
 256
 257     @param str
 258     a null-terminated string.
 259
 260     @return
 261     a hash code for the given string.
 262  */
 263 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_hashCode(
 264         const char * str ) SAL_THROW_EXTERN_C();
 265
 266 /** Return a hash code for a string.
 267
 268     It is not allowed to store the hash code persistently, because later
 269     versions could return other hash codes.
 270
 271     @param str
 272     a string.  Need not be null-terminated, but must be at least as long as
 273     the specified len.
 274
 275     @param len
 276     the length of the string.
 277
 278     @return
 279     a hash code for the given string.
 280  */
 281 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_hashCode_WithLength(
 282         const char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 283
 284 /** Search for the first occurrence of a character within a string.
 285
 286     The string must be null-terminated.
 287
 288     @param str
 289     a null-terminated string.
 290
 291     @param ch
 292     the character to be searched for.
 293
 294     @return
 295     the index (starting at 0) of the first occurrence of the character in the
 296     string, or -1 if the character does not occur.
 297  */
 298 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfChar(
 299         const char * str, char ch ) SAL_THROW_EXTERN_C();
 300
 301 /** Search for the first occurrence of a character within a string.
 302
 303     @param str
 304     a string.  Need not be null-terminated, but must be at least as long as
 305     the specified len.
 306
 307     @param len
 308     the length of the string.
 309
 310     @param ch
 311     the character to be searched for.
 312
 313     @return
 314     the index (starting at 0) of the first occurrence of the character in the
 315     string, or -1 if the character does not occur.
 316  */
 317 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfChar_WithLength(
 318         const char * str, sal_Int32 len, char ch ) SAL_THROW_EXTERN_C();
 319
 320 /** Search for the last occurrence of a character within a string.
 321
 322     The string must be null-terminated.
 323
 324     @param str
 325     a null-terminated string.
 326
 327     @param ch
 328     the character to be searched for.
 329
 330     @return
 331     the index (starting at 0) of the last occurrence of the character in the
 332     string, or -1 if the character does not occur.  The returned value is
 333     always smaller than the string length.
 334  */
 335 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfChar(
 336         const char * str, char ch ) SAL_THROW_EXTERN_C();
 337
 338 /** Search for the last occurrence of a character within a string.
 339
 340     @param str
 341     a string.  Need not be null-terminated, but must be at least as long as
 342     the specified len.
 343
 344     @param len
 345     the length of the string.
 346
 347     @param ch
 348     the character to be searched for.
 349
 350     @return
 351     the index (starting at 0) of the last occurrence of the character in the
 352     string, or -1 if the character does not occur.  The returned value is
 353     always smaller than the string length.
 354  */
 355 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfChar_WithLength(
 356         const char * str, sal_Int32 len, char ch ) SAL_THROW_EXTERN_C();
 357
 358 /** Search for the first occurrence of a substring within a string.
 359
 360     If subStr is empty, or both str and subStr are empty, -1 is returned.
 361     Both strings must be null-terminated.
 362
 363     @param str
 364     a null-terminated string.
 365
 366     @param subStr
 367     the null-terminated substring to be searched for.
 368
 369     @return
 370     the index (starting at 0) of the first character of the first occurrence
 371     of the substring within the string, or -1 if the substring does not occur.
 372  */
 373 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfStr(
 374         const char * str, const char * subStr ) SAL_THROW_EXTERN_C();
 375
 376 /** Search for the first occurrence of a substring within a string.
 377
 378     If subStr is empty, or both str and subStr are empty, -1 is returned.
 379
 380     @param str
 381     a string.  Need not be null-terminated, but must be at least as long as
 382     the specified len.
 383
 384     @param len
 385     the length of the string.
 386
 387     @param subStr
 388     the substring to be searched for.  Need not be null-terminated, but must
 389     be at least as long as the specified subLen.
 390
 391     @param subLen
 392     the length of the substring.
 393
 394     @return
 395     the index (starting at 0) of the first character of the first occurrence
 396     of the substring within the string, or -1 if the substring does not occur.
 397  */
 398 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_indexOfStr_WithLength(
 399         const char * str, sal_Int32 len, const char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
 400
 401 /** Search for the last occurrence of a substring within a string.
 402
 403     If subStr is empty, or both str and subStr are empty, -1 is returned.
 404     Both strings must be null-terminated.
 405
 406     @param str
 407     a null-terminated string.
 408
 409     @param subStr
 410     the null-terminated substring to be searched for.
 411
 412     @return
 413     the index (starting at 0) of the first character of the last occurrence
 414     of the substring within the string, or -1 if the substring does not occur.
 415  */
 416 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfStr(
 417         const char * str, const char * subStr ) SAL_THROW_EXTERN_C();
 418
 419 /** Search for the last occurrence of a substring within a string.
 420
 421     If subStr is empty, or both str and subStr are empty, -1 is returned.
 422
 423     @param str
 424     a string.  Need not be null-terminated, but must be at least as long as
 425     the specified len.
 426
 427     @param len
 428     the length of the string.
 429
 430     @param subStr
 431     the substring to be searched for.  Need not be null-terminated, but must
 432     be at least as long as the specified subLen.
 433
 434     @param subLen
 435     the length of the substring.
 436
 437     @return
 438     the index (starting at 0) of the first character of the first occurrence
 439     of the substring within the string, or -1 if the substring does not occur.
 440  */
 441 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_lastIndexOfStr_WithLength(
 442         const char * str, sal_Int32 len, const char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
 443
 444 /** Replace all occurrences of a single character within a string.
 445
 446     If oldChar does not occur within str, then the string is not modified.
 447     The string must be null-terminated.
 448
 449     @param str
 450     a null-terminated string.
 451
 452     @param oldChar
 453     the old character.
 454
 455     @param newChar
 456     the new character.
 457  */
 458 SAL_DLLPUBLIC void SAL_CALL rtl_str_replaceChar(
 459         char * str, char oldChar, char newChar ) SAL_THROW_EXTERN_C();
 460
 461 /** Replace all occurrences of a single character within a string.
 462
 463     If oldChar does not occur within str, then the string is not modified.
 464
 465     @param str
 466     a string.  Need not be null-terminated, but must be at least as long as
 467     the specified len.
 468
 469     @param len
 470     the length of the string.
 471
 472     @param oldChar
 473     the old character.
 474
 475     @param newChar
 476     the new character.
 477  */
 478 SAL_DLLPUBLIC void SAL_CALL rtl_str_replaceChar_WithLength(
 479         char * str, sal_Int32 len, char oldChar, char newChar ) SAL_THROW_EXTERN_C();
 480
 481 /** Convert all ASCII uppercase letters to lowercase within a string.
 482
 483     The characters with values between 65 and 90 (ASCII A--Z) are replaced
 484     with values between 97 and 122 (ASCII a--z).  The string must be
 485     null-terminated.
 486
 487     @param str
 488     a null-terminated string.
 489  */
 490 SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiLowerCase(
 491         char * str ) SAL_THROW_EXTERN_C();
 492
 493 /** Convert all ASCII uppercase letters to lowercase within a string.
 494
 495     The characters with values between 65 and 90 (ASCII A--Z) are replaced
 496     with values between 97 and 122 (ASCII a--z).
 497
 498     @param str
 499     a string.  Need not be null-terminated, but must be at least as long as
 500     the specified len.
 501
 502     @param len
 503     the length of the string.
 504  */
 505 SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiLowerCase_WithLength(
 506         char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 507
 508 /** Convert all ASCII lowercase letters to uppercase within a string.
 509
 510     The characters with values between 97 and 122 (ASCII a--z) are replaced
 511     with values between 65 and 90 (ASCII A--Z).  The string must be
 512     null-terminated.
 513
 514     @param str
 515     a null-terminated string.
 516  */
 517 SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiUpperCase(
 518         char * str ) SAL_THROW_EXTERN_C();
 519
 520 /** Convert all ASCII lowercase letters to uppercase within a string.
 521
 522     The characters with values between 97 and 122 (ASCII a--z) are replaced
 523     with values between 65 and 90 (ASCII A--Z).
 524
 525     @param str
 526     a string.  Need not be null-terminated, but must be at least as long as
 527     the specified len.
 528
 529     @param len
 530     the length of the string.
 531  */
 532 SAL_DLLPUBLIC void SAL_CALL rtl_str_toAsciiUpperCase_WithLength(
 533         char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 534
 535 /** Remove white space from both ends of a string.
 536
 537     All characters with values less than or equal to 32 (the space character)
 538     are considered to be white space.  This function cannot be used for
 539     language-specific operations.  The string must be null-terminated.
 540
 541     @param str
 542     a null-terminated string.
 543
 544     @return
 545     the new length of the string.
 546  */
 547 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_trim(
 548         char * str ) SAL_THROW_EXTERN_C();
 549
 550 /** Remove white space from both ends of the string.
 551
 552     All characters with values less than or equal to 32 (the space character)
 553     are considered to be white space.  This function cannot be used for
 554     language-specific operations.  The string must be null-terminated.
 555
 556     @param str
 557     a string.  Need not be null-terminated, but must be at least as long as
 558     the specified len.
 559
 560     @param len
 561     the original length of the string.
 562
 563     @return
 564     the new length of the string.
 565  */
 566 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_trim_WithLength(
 567         char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 568
 569 /** Create the string representation of a boolean.
 570
 571     If b is true, the buffer is filled with the string "true" and 5 is
 572     returned.  If b is false, the buffer is filled with the string "false" and
 573     6 is returned.  This function cannot be used for language-specific
 574     operations.
 575
 576     @param str
 577     a buffer that is big enough to hold the result and the terminating NUL
 578     character.  You should use the RTL_STR_MAX_VALUEOFBOOLEAN define to create
 579     a buffer that is big enough.
 580
 581     @param b
 582     a boolean value.
 583
 584     @return
 585     the length of the string.
 586  */
 587 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfBoolean(
 588         char * str, sal_Bool b ) SAL_THROW_EXTERN_C();
 589 #define RTL_STR_MAX_VALUEOFBOOLEAN 6
 590
 591 /** Create the string representation of a character.
 592
 593     @param str
 594     a buffer that is big enough to hold the result and the terminating NUL
 595     character.  You should use the RTL_STR_MAX_VALUEOFCHAR define to create a
 596     buffer that is big enough.
 597
 598     @param ch
 599     a character value.
 600
 601     @return
 602     the length of the string.
 603  */
 604 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfChar(
 605         char * str, char ch ) SAL_THROW_EXTERN_C();
 606 #define RTL_STR_MAX_VALUEOFCHAR 2
 607
 608 /** Create the string representation of an integer.
 609
 610     This function cannot be used for language-specific operations.
 611
 612     @param str
 613     a buffer that is big enough to hold the result and the terminating NUL
 614     character.  You should use the RTL_STR_MAX_VALUEOFINT32 define to create a
 615     buffer that is big enough.
 616
 617     @param i
 618     an integer value.
 619
 620     @param radix
 621     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 622     (36), inclusive.
 623
 624     @return
 625     the length of the string.
 626  */
 627 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfInt32(
 628         char * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 629 #define RTL_STR_MIN_RADIX           2
 630 #define RTL_STR_MAX_RADIX           36
 631 #define RTL_STR_MAX_VALUEOFINT32    33
 632
 633 /** Create the string representation of a long integer.
 634
 635     This function cannot be used for language-specific operations.
 636
 637     @param str
 638     a buffer that is big enough to hold the result and the terminating NUL
 639     character.  You should use the RTL_STR_MAX_VALUEOFINT64 define to create a
 640     buffer that is big enough.
 641
 642     @param l
 643     a long integer value.
 644
 645     @param radix
 646     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 647     (36), inclusive.
 648
 649     @return
 650     the length of the string.
 651  */
 652 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfInt64(
 653         char * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 654 #define RTL_STR_MAX_VALUEOFINT64 65
 655
 656 /** Create the string representation of an unsigned long integer.
 657
 658     This function cannot be used for language-specific operations.
 659
 660     @param str
 661     a buffer that is big enough to hold the result and the terminating NUL
 662     character.  You should use the RTL_STR_MAX_VALUEOFUINT64 define to create a
 663     buffer that is big enough.
 664
 665     @param l
 666     a long integer value.
 667
 668     @param radix
 669     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 670     (36), inclusive.
 671
 672     @return
 673     the length of the string.
 674  */
 675 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfUInt64(
 676         char * str, sal_uInt64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 677 #define RTL_STR_MAX_VALUEOFUINT64 65
 678
 679 /** Create the string representation of a float.
 680
 681     This function cannot be used for language-specific conversion.
 682
 683     @param str
 684     a buffer that is big enough to hold the result and the terminating NUL
 685     character.  You should use the RTL_STR_MAX_VALUEOFFLOAT define to create a
 686     buffer that is big enough.
 687
 688     @param f
 689     a float value.
 690
 691     @return
 692     the length of the string.
 693  */
 694 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfFloat(
 695         char * str, float f ) SAL_THROW_EXTERN_C();
 696 #define RTL_STR_MAX_VALUEOFFLOAT 15
 697
 698 /** Create the string representation of a double.
 699
 700     This function cannot be used for language-specific conversion.
 701
 702     @param str
 703     a buffer that is big enough to hold the result and the terminating NUL
 704     character.  You should use the RTL_STR_MAX_VALUEOFDOUBLE define to create
 705     a buffer that is big enough.
 706
 707     @param d
 708     a double value.
 709
 710     @return
 711     the length of the string.
 712  */
 713 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_valueOfDouble(
 714         char * str, double d ) SAL_THROW_EXTERN_C();
 715 #define RTL_STR_MAX_VALUEOFDOUBLE 25
 716
 717 /** Interpret a string as a boolean.
 718
 719     This function cannot be used for language-specific conversion.  The string
 720     must be null-terminated.
 721
 722     @param str
 723     a null-terminated string.
 724
 725     @return
 726     true if the string is "1" or "true" in any ASCII case, false otherwise.
 727  */
 728 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_str_toBoolean(
 729         const char * str ) SAL_THROW_EXTERN_C();
 730
 731 /** Interpret a string as an integer.
 732
 733     This function cannot be used for language-specific conversion.  The string
 734     must be null-terminated.
 735
 736     @param str
 737     a null-terminated string.
 738
 739     @param radix
 740     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 741     (36), inclusive.
 742
 743     @return
 744     the integer value represented by the string, or 0 if the string does not
 745     represent an integer.
 746  */
 747 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_str_toInt32(
 748         const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 749
 750 /** Interpret a string as an unsigned integer.
 751
 752     This function cannot be used for language-specific conversion.  The string
 753     must be null-terminated.
 754
 755     @param str
 756     a null-terminated string.
 757
 758     @param radix
 759     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
 760     (36), inclusive.
 761
 762     @return
 763     the unsigned integer value represented by the string, or 0 if the string
 764     does not represent an unsigned integer.
 765
 766     @since LibreOffice 4.2
 767  */
 768 SAL_DLLPUBLIC sal_uInt32 SAL_CALL rtl_str_toUInt32(
 769         const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 770
 771 /** Interpret a string as a long integer.
 772
 773     This function cannot be used for language-specific conversion.  The string
 774     must be null-terminated.
 775
 776     @param str
 777     a null-terminated string.
 778
 779     @param radix
 780     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 781     (36), inclusive.
 782
 783     @return
 784     the long integer value represented by the string, or 0 if the string does
 785     not represent a long integer.
 786  */
 787 SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_str_toInt64(
 788         const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 789
 790 /** Interpret a string as a long integer.
 791
 792     This function cannot be used for language-specific conversion.
 793
 794     @param str
 795     a string.
 796
 797     @param radix
 798     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 799     (36), inclusive.
 800
 801     @param nStrLength
 802     number of chars to process
 803
 804     @return
 805     the long integer value represented by the string, or 0 if the string does
 806     not represent a long integer.
 807
 808     @internal
 809     @since LibreOffice 6.4
 810 */
 811 SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_str_toInt64_WithLength(
 812         const char * str, sal_Int16 radix, sal_Int32 nStrLength ) SAL_THROW_EXTERN_C();
 813
 814 /** Interpret a string as an unsigned long integer.
 815
 816     This function cannot be used for language-specific conversion.  The string
 817     must be null-terminated.
 818
 819     @param str
 820     a null-terminated string.
 821
 822     @param radix
 823     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
 824     (36), inclusive.
 825
 826     @return
 827     the unsigned long integer value represented by the string, or 0 if the
 828     string does not represent an unsigned long integer.
 829
 830     @since LibreOffice 4.1
 831  */
 832 SAL_DLLPUBLIC sal_uInt64 SAL_CALL rtl_str_toUInt64(
 833         const char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 834
 835 /** Interpret a string as a float.
 836
 837     This function cannot be used for language-specific conversion.  The string
 838     must be null-terminated.
 839
 840     @param str
 841     a null-terminated string.
 842
 843     @return
 844     the float value represented by the string, or 0.0 if the string does not
 845     represent a float.
 846  */
 847 SAL_DLLPUBLIC float SAL_CALL rtl_str_toFloat(
 848         const char * str ) SAL_THROW_EXTERN_C();
 849
 850 /** Interpret a string as a double.
 851
 852     This function cannot be used for language-specific conversion.  The string
 853     must be null-terminated.
 854
 855     @param str
 856     a null-terminated string.
 857
 858     @return
 859     the float value represented by the string, or 0.0 if the string does not
 860     represent a double.
 861  */
 862 SAL_DLLPUBLIC double SAL_CALL rtl_str_toDouble(
 863         const char * str ) SAL_THROW_EXTERN_C();
 864
 865 /* ======================================================================= */
 866
 867 #ifdef _WIN32
 868 #   pragma pack(push, 8)
 869 #endif
 870
 871 /** @cond INTERNAL */
 872 /** The implementation of a byte string.
 873  */
 874 typedef struct _rtl_String
 875 {
 876     oslInterlockedCount refCount; /* opaque */
 877     sal_Int32           length;
 878     char            buffer[1];
 879 } rtl_String;
 880 /** @endcond */
 881
 882 #if defined(_WIN32)
 883 #pragma pack(pop)
 884 #endif
 885
 886 /* ----------------------------------------------------------------------- */
 887
 888 /** Increment the reference count of a string.
 889
 890     @param str
 891     a string.
 892  */
 893 SAL_DLLPUBLIC void SAL_CALL rtl_string_acquire( rtl_String * str ) SAL_THROW_EXTERN_C();
 894
 895 /** Decrement the reference count of a string.
 896
 897     If the count goes to zero than the string data is deleted.
 898
 899     @param str
 900     a string.
 901  */
 902 SAL_DLLPUBLIC void SAL_CALL rtl_string_release( rtl_String * str ) SAL_THROW_EXTERN_C();
 903
 904 /** Allocate a new string containing no characters.
 905
 906     @param newStr
 907     pointer to the new string.  The pointed-to data must be null or a valid
 908     string.
 909  */
 910 SAL_DLLPUBLIC void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXTERN_C();
 911
 912 /** Allocate a new string containing space for a given number of characters.
 913
 914     The reference count of the new string will be 1. The length of the string
 915     will be nLen. This function does not handle out-of-memory conditions.
 916
 917     For failed allocation this method returns NULL.
 918
 919     The characters of the capacity are not cleared, and the length is set to
 920     nLen, unlike the similar method of rtl_String_new_WithLength which
 921     zeros out the buffer, and sets the length to 0. So should be somewhat
 922     more efficient for allocating a new string.
 923
 924     call rtl_String_release to release the string
 925     alternatively pass ownership to an OUString with
 926     rtl::OUString(newStr, SAL_NO_ACQUIRE);
 927
 928     @param[out] nLen the number of characters. Must be >= 0.
 929
 930     @return pointer to the new string.
 931
 932     @since LibreOffice 4.1
 933  */
 934 SAL_DLLPUBLIC rtl_String * SAL_CALL rtl_string_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C();
 935
 936 /** Allocate a new string containing space for a given number of characters.
 937
 938     If len is greater than zero, the reference count of the new string will be
 939     1.  The values of all characters are set to 0 and the length of the string
 940     is 0.  This function does not handle out-of-memory conditions.
 941
 942     @param newStr
 943     pointer to the new string.  The pointed-to data must be null or a valid
 944     string.
 945
 946     @param len
 947     the number of characters.
 948  */
 949 SAL_DLLPUBLIC void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C();
 950
 951 /** Allocate a new string that contains a copy of another string.
 952
 953     If the length of value is greater than zero, the reference count of the
 954     new string will be 1.  This function does not handle out-of-memory
 955     conditions.
 956
 957     @param newStr
 958     pointer to the new string.  The pointed-to data must be null or a valid
 959     string.
 960
 961     @param value
 962     a valid string.
 963  */
 964 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C();
 965
 966 /** Allocate a new string that contains a copy of a character array.
 967
 968     If the length of value is greater than zero, the reference count of the
 969     new string will be 1.  This function does not handle out-of-memory
 970     conditions.
 971
 972     @param newStr
 973     pointer to the new string.  The pointed-to data must be null or a valid
 974     string.
 975
 976     @param value
 977     a null-terminated character array.
 978  */
 979 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const char * value ) SAL_THROW_EXTERN_C();
 980
 981 /** Allocate a new string that contains a copy of a character array.
 982
 983     If the length of value is greater than zero, the reference count of the
 984     new string will be 1.  This function does not handle out-of-memory
 985     conditions.
 986
 987     @param newStr
 988     pointer to the new string.  The pointed-to data must be null or a valid
 989     string.
 990
 991     @param value
 992     a character array.  Need not be null-terminated, but must be at least as
 993     long as the specified len.
 994
 995     @param len
 996     the length of the character array.
 997  */
 998 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const char * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
 999
1000 /** Allocate a new string that is a substring of this string.
1001
1002     The substring begins at the specified beginIndex and contains count
1003     characters. Meaningless combinations such as negative beginIndex,
1004     or beginIndex + count greater than the length of the string have
1005     undefined behaviour.
1006
1007     @param[out]    newStr       the specified substring.
1008     @param[in]     from         the String to take the substring from.
1009     @param[in]     beginIndex   the beginning index, inclusive.
1010     @param[in]     count        the number of characters.
1011
1012     @since LibreOffice 4.0
1013  */
1014 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromSubString(
1015         rtl_String ** newStr, const rtl_String * from,
1016         sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C();
1017
1018 /**
1019  @internal
1020  @since LibreOffice 3.6
1021 */
1022 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromLiteral( rtl_String ** newStr, const char * value, sal_Int32 len, sal_Int32 allocExtra ) SAL_THROW_EXTERN_C();
1023
1024 /** Assign a new value to a string.
1025
1026     First releases any value str might currently hold, then acquires
1027     rightValue.
1028
1029     @param str
1030     pointer to the string.  The pointed-to data must be null or a valid
1031     string.
1032
1033     @param rightValue
1034     a valid string.
1035  */
1036 SAL_DLLPUBLIC void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C();
1037
1038 /** Return the length of a string.
1039
1040     The length is equal to the number of characters in the string.
1041
1042     @param str
1043     a valid string.
1044
1045     @return
1046     the length of the string.
1047  */
1048 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C();
1049
1050 /** Return a pointer to the underlying character array of a string.
1051
1052     @param str
1053     a valid string.
1054
1055     @return
1056     a pointer to the null-terminated character array.
1057  */
1058 SAL_DLLPUBLIC char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C();
1059
1060 /** Create a new string that is the concatenation of two other strings.
1061
1062     The new string does not necessarily have a reference count of 1 (in cases
1063     where one of the two other strings is empty), so it must not be modified
1064     without checking the reference count.  This function does not handle
1065     out-of-memory conditions.
1066
1067     @param newStr
1068     pointer to the new string.  The pointed-to data must be null or a valid
1069     string.
1070
1071     @param left
1072     a valid string.
1073
1074     @param right
1075     a valid string.
1076  */
1077 SAL_DLLPUBLIC void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C();
1078
1079 /** Create a new string by replacing a substring of another string.
1080
1081     The new string results from replacing a number of characters (count),
1082     starting at the specified position (index) in the original string (str),
1083     with some new substring (subStr).  If subStr is null, then only a number
1084     of characters is deleted.
1085
1086     The new string does not necessarily have a reference count of 1, so it
1087     must not be modified without checking the reference count.  This function
1088     does not handle out-of-memory conditions.
1089
1090     @param newStr
1091     pointer to the new string.  The pointed-to data must be null or a valid
1092     string.
1093
1094     @param str
1095     a valid string.
1096
1097     @param idx
1098     the index into str at which to start replacement.  Must be between 0 and
1099     the length of str, inclusive.
1100
1101     @param count
1102     the number of characters to remove.  Must not be negative, and the sum of
1103     index and count must not exceed the length of str.
1104
1105     @param subStr
1106     either null or a valid string to be inserted.
1107  */
1108 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceStrAt(
1109         rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C();
1110
1111 #ifdef LIBO_INTERNAL_ONLY
1112 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceStrAt_WithLength (
1113         rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, char const * subStr, sal_Int32 substrLen ) SAL_THROW_EXTERN_C();
1114 #endif
1115
1116 /** Create a new string by replacing all occurrences of a single character
1117     within another string.
1118
1119     The new string results from replacing all occurrences of oldChar in str
1120     with newChar.
1121
1122     The new string does not necessarily have a reference count of 1 (in cases
1123     where oldChar does not occur in str), so it must not be modified without
1124     checking the reference count.  This function does not handle out-of-memory
1125     conditions.
1126
1127     @param newStr
1128     pointer to the new string.  The pointed-to data must be null or a valid
1129     string.
1130
1131     @param str
1132     a valid string.
1133
1134     @param oldChar
1135     the old character.
1136
1137     @param newChar
1138     the new character.
1139  */
1140 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplace(
1141         rtl_String ** newStr, rtl_String * str, char oldChar, char newChar ) SAL_THROW_EXTERN_C();
1142
1143 /** Create a new string by replacing the first occurrence of a given substring
1144     with another substring.
1145
1146     @param[in, out] newStr  pointer to the new string; must not be null; must
1147     point to null or a valid rtl_String
1148
1149     @param str  pointer to the original string; must not be null
1150
1151     @param from  pointer to the substring to be replaced; must not be null and
1152     must point to memory of at least \p fromLength bytes
1153
1154     @param fromLength  the length of the \p from substring; must be non-negative
1155
1156     @param to  pointer to the replacing substring; must not be null and must
1157     point to memory of at least \p toLength bytes
1158
1159     @param toLength  the length of the \p to substring; must be non-negative
1160
1161     @param[in,out] index  pointer to a start index, must not be null; upon entry
1162     to the function its value is the index into the original string at which to
1163     start searching for the \p from substring, the value must be non-negative
1164     and not greater than the original string's length; upon exit from the
1165     function its value is the index into the original string at which the
1166     replacement took place or -1 if no replacement took place
1167
1168     @since LibreOffice 3.6
1169 */
1170 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceFirst(
1171     rtl_String ** newStr, rtl_String * str, char const * from,
1172     sal_Int32 fromLength, char const * to, sal_Int32 toLength,
1173     sal_Int32 * index) SAL_THROW_EXTERN_C();
1174
1175 /** Create a new string by replacing all occurrences of a given substring with
1176     another substring.
1177
1178     Replacing subsequent occurrences picks up only after a given replacement.
1179     That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1180
1181     @param[in, out] newStr  pointer to the new string; must not be null; must
1182     point to null or a valid rtl_String
1183
1184     @param str  pointer to the original string; must not be null
1185
1186     @param from  pointer to the substring to be replaced; must not be null and
1187     must point to memory of at least \p fromLength bytes
1188
1189     @param fromLength  the length of the \p from substring; must be non-negative
1190
1191     @param to  pointer to the replacing substring; must not be null and must
1192     point to memory of at least \p toLength bytes
1193
1194     @param toLength  the length of the \p to substring; must be non-negative
1195
1196     @since LibreOffice 3.6
1197 */
1198 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceAll(
1199     rtl_String ** newStr, rtl_String * str, char const * from,
1200     sal_Int32 fromLength, char const * to, sal_Int32 toLength)
1201     SAL_THROW_EXTERN_C();
1202
1203 /** Create a new string by converting all ASCII uppercase letters to lowercase
1204     within another string.
1205
1206     The new string results from replacing all characters with values between
1207     65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
1208
1209     This function cannot be used for language-specific conversion.  The new
1210     string does not necessarily have a reference count of 1 (in cases where
1211     no characters need to be converted), so it must not be modified without
1212     checking the reference count.  This function does not handle out-of-memory
1213     conditions.
1214
1215     @param newStr
1216     pointer to the new string.  The pointed-to data must be null or a valid
1217     string.
1218
1219     @param str
1220     a valid string.
1221  */
1222 SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiLowerCase(
1223         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1224
1225 /** Create a new string by converting all ASCII lowercase letters to uppercase
1226     within another string.
1227
1228     The new string results from replacing all characters with values between
1229     97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z).
1230
1231     This function cannot be used for language-specific conversion.  The new
1232     string does not necessarily have a reference count of 1 (in cases where
1233     no characters need to be converted), so it must not be modified without
1234     checking the reference count.  This function does not handle out-of-memory
1235     conditions.
1236
1237     @param newStr
1238     pointer to the new string.  The pointed-to data must be null or a valid
1239     string.
1240
1241     @param str
1242     a valid string.
1243  */
1244 SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiUpperCase(
1245         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1246
1247 /** Create a new string by removing white space from both ends of another
1248     string.
1249
1250     The new string results from removing all characters with values less than
1251     or equal to 32 (the space character) form both ends of str.
1252
1253     This function cannot be used for language-specific conversion.  The new
1254     string does not necessarily have a reference count of 1 (in cases where
1255     no characters need to be removed), so it must not be modified without
1256     checking the reference count.  This function does not handle out-of-memory
1257     conditions.
1258
1259     @param newStr
1260     pointer to the new string.  The pointed-to data must be null or a valid
1261     string.
1262
1263     @param str
1264     a valid string.
1265  */
1266 SAL_DLLPUBLIC void SAL_CALL rtl_string_newTrim(
1267         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1268
1269 /** Create a new string by extracting a single token from another string.
1270
1271     Starting at index, the next token is searched for.  If there is no
1272     such token, the result is an empty string.  Otherwise, all characters from
1273     the start of that token and up to, but not including the next occurrence
1274     of cTok make up the resulting token.  The return value is the position of
1275     the next token, or -1 if no more tokens follow.
1276
1277     Example code could look like
1278       rtl_String * pToken = NULL;
1279       sal_Int32 nIndex = 0;
1280       do
1281       {
1282           ...
1283           nIndex = rtl_string_getToken(&pToken, pStr, 0, ';', nIndex);
1284           ...
1285       }
1286       while (nIndex >= 0);
1287
1288     The new string does not necessarily have a reference count of 1, so it
1289     must not be modified without checking the reference count.  This function
1290     does not handle out-of-memory conditions.
1291
1292     @param newStr
1293     pointer to the new string.  The pointed-to data must be null or a valid
1294     string.  If either token or index is negative, an empty token is stored in
1295     newStr (and -1 is returned).
1296
1297     @param str
1298     a valid string.
1299
1300     @param token
1301     the number of the token to return, starting at index.
1302
1303     @param cTok
1304     the character that separates the tokens.
1305
1306     @param idx
1307     the position at which searching for the token starts.  Must not be greater
1308     than the length of str.
1309
1310     @return
1311     the index of the next token, or -1 if no more tokens follow.
1312  */
1313 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getToken(
1314         rtl_String ** newStr , rtl_String * str, sal_Int32 token, char cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
1315
1316 /* ======================================================================= */
1317
1318 /** Supply an ASCII string literal together with its length.
1319
1320     This macro can be used to compute (some of) the arguments in function calls
1321     like rtl::OString(RTL_CONSTASCII_STRINGPARAM("foo")) or
1322     rtl::OUString::equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("foo")).
1323
1324     @param constAsciiStr
1325     must be an expression of type "(possibly cv-qualified reference to) array of
1326     (possibly cv-qualified) char."  Each element of the referenced array must
1327     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1328     referenced array is not considered part of the represented ASCII string, and
1329     its value should be 0x00.  Depending on where this macro is used, the nature
1330     of the supplied expression might be further restricted.
1331 */
1332 // The &foo[0] trick is intentional, it makes sure the type is char* or const char*
1333 // (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed).
1334 // This is to avoid mistaken use with functions that accept string literals
1335 // (i.e. const char (&)[N]) where usage of this macro otherwise could match
1336 // the argument and a following int argument with a default value (e.g. OString::match()).
1337 #define RTL_CONSTASCII_STRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \
1338     ((sal_Int32)SAL_N_ELEMENTS(constAsciiStr)-1)
1339
1340 /** Supply the length of an ASCII string literal.
1341
1342     This macro can be used to compute arguments in function calls like
1343     rtl::OUString::match(other, RTL_CONSTASCII_LENGTH("prefix")).
1344
1345     @param constAsciiStr
1346     must be an expression of type "(possibly cv-qualified reference to) array of
1347     (possibly cv-qualified) char."  Each element of the referenced array must
1348     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1349     referenced array is not considered part of the represented ASCII string, and
1350     its value should be 0x00.  Depending on where this macro is used, the nature
1351     of the supplied expression might be further restricted.
1352 */
1353 #define RTL_CONSTASCII_LENGTH( constAsciiStr ) ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1))
1354
1355 /* ======================================================================= */
1356
1357 /* predefined constants for String-Conversion */
1358 #define OUSTRING_TO_OSTRING_CVTFLAGS    (RTL_UNICODETOTEXT_FLAGS_UNDEFINED_DEFAULT |\
1359                                          RTL_UNICODETOTEXT_FLAGS_INVALID_DEFAULT |\
1360                                          RTL_UNICODETOTEXT_FLAGS_UNDEFINED_REPLACE |\
1361                                          RTL_UNICODETOTEXT_FLAGS_PRIVATE_MAPTO0)
1362
1363 /* ----------------------------------------------------------------------- */
1364
1365 /** Create a new byte string by converting a Unicode string, using a specific
1366     text encoding.
1367
1368     The lengths of the byte string and the Unicode string may differ (e.g.,
1369     for double-byte encodings, UTF-7, UTF-8).
1370
1371     If the length of the Unicode string is greater than zero, the reference
1372     count of the new string will be 1.
1373
1374     If an out-of-memory condition occurs, newStr will point to a null pointer
1375     upon return.
1376
1377     @param newStr
1378     pointer to the new string.  The pointed-to data must be null or a valid
1379     string.
1380
1381     @param str
1382     a Unicode character array.  Need not be null-terminated, but must be at
1383     least as long as the specified len.
1384
1385     @param len
1386     the length of the Unicode character array.
1387
1388     @param encoding
1389     the text encoding to use for conversion.
1390
1391     @param convertFlags
1392     flags which control the conversion.  Either use
1393     OUSTRING_TO_OSTRING_CVTFLAGS, or see
1394     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1395     details.
1396  */
1397 SAL_DLLPUBLIC void SAL_CALL rtl_uString2String(
1398         rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
1399
1400 /**
1401   Converts a Unicode string to a byte string, signalling failure.
1402
1403   @param pTarget
1404   An out parameter receiving the converted string.  Must not be null itself, and
1405   must contain either null or a pointer to a valid rtl_String; the contents are
1406   not modified if conversion fails (rtl_convertUStringToString returns false).
1407
1408   @param pSource
1409   The Unicode string.  May only be null if nLength is zero.
1410
1411   @param nLength
1412   The length of the Unicode string.  Must be non-negative.
1413
1414   @param nEncoding
1415   The text encoding to convert into.  Must be an octet encoding (i.e.,
1416   rtl_isOctetTextEncoding(nEncoding) must return true).
1417
1418   @param nFlags
1419   A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the conversion
1420   (see rtl_convertUnicodeToText).  RTL_UNICODETOTEXT_FLAGS_FLUSH need not be
1421   included, it is implicitly assumed.  Typical uses are either
1422   RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
1423   RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot be
1424   converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS (make a
1425   best efforts conversion).
1426
1427   @return
1428   True if the conversion succeeded, false otherwise.
1429  */
1430 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertUStringToString(
1431                                              rtl_String ** pTarget,
1432                                              sal_Unicode const * pSource,
1433                                              sal_Int32 nLength,
1434                                              rtl_TextEncoding nEncoding,
1435                                              sal_uInt32 nFlags)
1436     SAL_THROW_EXTERN_C();
1437
1438 /** Ensure a string has enough space for a given number of characters.
1439
1440  If the given string is large enough and has refcount of 1, it is not altered in any way.
1441  Otherwise it is replaced by a copy that has enough space for the given number of characters,
1442  data from the source string is copied to the beginning of it, the content of the remaining
1443  capacity undefined, the string has refcount of 1, and refcount of the original string is decreased.
1444
1445  @param str
1446  pointer to the string.  The pointed-to data must be a valid string.
1447
1448  @param size
1449  the number of characters
1450
1451  @since LibreOffice 4.1
1452  @internal
1453  */
1454 SAL_DLLPUBLIC void SAL_CALL rtl_string_ensureCapacity( rtl_String ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();
1455
1456 #ifdef __cplusplus
1457 }
1458 #endif
1459
1460 #endif // INCLUDED_RTL_STRING_H
1461
1462 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */