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