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 _WIN32
 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(_WIN32)
 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 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. Must be >= 0.
 901
 902     @return pointer to the new string.
 903
 904     @since LibreOffice 4.1
 905  */
 906 SAL_DLLPUBLIC rtl_String * SAL_CALL rtl_string_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C();
 907
 908 /** Allocate a new string containing space for a given number of characters.
 909
 910     If len is greater than zero, the reference count of the new string will be
 911     1.  The values of all characters are set to 0 and the length of the string
 912     is 0.  This function does not handle out-of-memory conditions.
 913
 914     @param newStr
 915     pointer to the new string.  The pointed-to data must be null or a valid
 916     string.
 917
 918     @param len
 919     the number of characters.
 920  */
 921 SAL_DLLPUBLIC void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C();
 922
 923 /** Allocate a new string that contains a copy of another string.
 924
 925     If the length of value is greater than zero, the reference count of the
 926     new string will be 1.  This function does not handle out-of-memory
 927     conditions.
 928
 929     @param newStr
 930     pointer to the new string.  The pointed-to data must be null or a valid
 931     string.
 932
 933     @param value
 934     a valid string.
 935  */
 936 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C();
 937
 938 /** Allocate a new string that contains a copy of a character array.
 939
 940     If the length of value is greater than zero, the reference count of the
 941     new string will be 1.  This function does not handle out-of-memory
 942     conditions.
 943
 944     @param newStr
 945     pointer to the new string.  The pointed-to data must be null or a valid
 946     string.
 947
 948     @param value
 949     a null-terminated character array.
 950  */
 951 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C();
 952
 953 /** Allocate a new string that contains a copy of a character array.
 954
 955     If the length of value is greater than zero, the reference count of the
 956     new string will be 1.  This function does not handle out-of-memory
 957     conditions.
 958
 959     @param newStr
 960     pointer to the new string.  The pointed-to data must be null or a valid
 961     string.
 962
 963     @param value
 964     a character array.  Need not be null-terminated, but must be at least as
 965     long as the specified len.
 966
 967     @param len
 968     the length of the character array.
 969  */
 970 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const sal_Char * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
 971
 972 /** Allocate a new string that is a substring of this string.
 973
 974     The substring begins at the specified beginIndex and contains count
 975     characters. Meaningless combinations such as negative beginIndex,
 976     or beginIndex + count greater than the length of the string have
 977     undefined behaviour.
 978
 979     @param[out]    newStr       the specified substring.
 980     @param[in]     from         the String to take the substring from.
 981     @param[in]     beginIndex   the beginning index, inclusive.
 982     @param[in]     count        the number of characters.
 983
 984     @since LibreOffice 4.0
 985  */
 986 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromSubString(
 987         rtl_String ** newStr, const rtl_String * from,
 988         sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C();
 989
 990 /**
 991  @internal
 992  @since LibreOffice 3.6
 993 */
 994 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();
 995
 996 /** Assign a new value to a string.
 997
 998     First releases any value str might currently hold, then acquires
 999     rightValue.
1000
1001     @param str
1002     pointer to the string.  The pointed-to data must be null or a valid
1003     string.
1004
1005     @param rightValue
1006     a valid string.
1007  */
1008 SAL_DLLPUBLIC void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C();
1009
1010 /** Return the length of a string.
1011
1012     The length is equal to the number of characters in the string.
1013
1014     @param str
1015     a valid string.
1016
1017     @return
1018     the length of the string.
1019  */
1020 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C();
1021
1022 /** Return a pointer to the underlying character array of a string.
1023
1024     @param str
1025     a valid string.
1026
1027     @return
1028     a pointer to the null-terminated character array.
1029  */
1030 SAL_DLLPUBLIC sal_Char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C();
1031
1032 /** Create a new string that is the concatenation of two other strings.
1033
1034     The new string does not necessarily have a reference count of 1 (in cases
1035     where one of the two other strings is empty), so it must not be modified
1036     without checking the reference count.  This function does not handle
1037     out-of-memory conditions.
1038
1039     @param newStr
1040     pointer to the new string.  The pointed-to data must be null or a valid
1041     string.
1042
1043     @param left
1044     a valid string.
1045
1046     @param right
1047     a valid string.
1048  */
1049 SAL_DLLPUBLIC void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C();
1050
1051 /** Create a new string by replacing a substring of another string.
1052
1053     The new string results from replacing a number of characters (count),
1054     starting at the specified position (index) in the original string (str),
1055     with some new substring (subStr).  If subStr is null, than only a number
1056     of characters is deleted.
1057
1058     The new string does not necessarily have a reference count of 1, so it
1059     must not be modified without checking the reference count.  This function
1060     does not handle out-of-memory conditions.
1061
1062     @param newStr
1063     pointer to the new string.  The pointed-to data must be null or a valid
1064     string.
1065
1066     @param str
1067     a valid string.
1068
1069     @param idx
1070     the index into str at which to start replacement.  Must be between 0 and
1071     the length of str, inclusive.
1072
1073     @param count
1074     the number of characters to remove.  Must not be negative, and the sum of
1075     index and count must not exceed the length of str.
1076
1077     @param subStr
1078     either null or a valid string to be inserted.
1079  */
1080 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceStrAt(
1081         rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C();
1082
1083 /** Create a new string by replacing all occurrences of a single character
1084     within another string.
1085
1086     The new string results from replacing all occurrences of oldChar in str
1087     with newChar.
1088
1089     The new string does not necessarily have a reference count of 1 (in cases
1090     where oldChar does not occur in str), so it must not be modified without
1091     checking the reference count.  This function does not handle out-of-memory
1092     conditions.
1093
1094     @param newStr
1095     pointer to the new string.  The pointed-to data must be null or a valid
1096     string.
1097
1098     @param str
1099     a valid string.
1100
1101     @param oldChar
1102     the old character.
1103
1104     @param newChar
1105     the new character.
1106  */
1107 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplace(
1108         rtl_String ** newStr, rtl_String * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
1109
1110 /** Create a new string by replacing the first occurrence of a given substring
1111     with another substring.
1112
1113     @param[in, out] newStr  pointer to the new string; must not be null; must
1114     point to null or a valid rtl_String
1115
1116     @param str  pointer to the original string; must not be null
1117
1118     @param from  pointer to the substring to be replaced; must not be null and
1119     must point to memory of at least \p fromLength bytes
1120
1121     @param fromLength  the length of the \p from substring; must be non-negative
1122
1123     @param to  pointer to the replacing substring; must not be null and must
1124     point to memory of at least \p toLength bytes
1125
1126     @param toLength  the length of the \p to substring; must be non-negative
1127
1128     @param[in,out] index  pointer to a start index, must not be null; upon entry
1129     to the function its value is the index into the original string at which to
1130     start searching for the \p from substring, the value must be non-negative
1131     and not greater than the original string's length; upon exit from the
1132     function its value is the index into the original string at which the
1133     replacement took place or -1 if no replacement took place
1134
1135     @since LibreOffice 3.6
1136 */
1137 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceFirst(
1138     rtl_String ** newStr, rtl_String * str, char const * from,
1139     sal_Int32 fromLength, char const * to, sal_Int32 toLength,
1140     sal_Int32 * index) SAL_THROW_EXTERN_C();
1141
1142 /** Create a new string by replacing all occurrences of a given substring with
1143     another substring.
1144
1145     Replacing subsequent occurrences picks up only after a given replacement.
1146     That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1147
1148     @param[in, out] newStr  pointer to the new string; must not be null; must
1149     point to null or a valid rtl_String
1150
1151     @param str  pointer to the original string; must not be null
1152
1153     @param from  pointer to the substring to be replaced; must not be null and
1154     must point to memory of at least \p fromLength bytes
1155
1156     @param fromLength  the length of the \p from substring; must be non-negative
1157
1158     @param to  pointer to the replacing substring; must not be null and must
1159     point to memory of at least \p toLength bytes
1160
1161     @param toLength  the length of the \p to substring; must be non-negative
1162
1163     @since LibreOffice 3.6
1164 */
1165 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceAll(
1166     rtl_String ** newStr, rtl_String * str, char const * from,
1167     sal_Int32 fromLength, char const * to, sal_Int32 toLength)
1168     SAL_THROW_EXTERN_C();
1169
1170 /** Create a new string by converting all ASCII uppercase letters to lowercase
1171     within another string.
1172
1173     The new string results from replacing all characters with values between
1174     65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
1175
1176     This function cannot be used for language-specific conversion.  The new
1177     string does not necessarily have a reference count of 1 (in cases where
1178     no characters need to be converted), so it must not be modified without
1179     checking the reference count.  This function does not handle out-of-memory
1180     conditions.
1181
1182     @param newStr
1183     pointer to the new string.  The pointed-to data must be null or a valid
1184     string.
1185
1186     @param str
1187     a valid string.
1188  */
1189 SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiLowerCase(
1190         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1191
1192 /** Create a new string by converting all ASCII lowercase letters to uppercase
1193     within another string.
1194
1195     The new string results from replacing all characters with values between
1196     97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z).
1197
1198     This function cannot be used for language-specific conversion.  The new
1199     string does not necessarily have a reference count of 1 (in cases where
1200     no characters need to be converted), so it must not be modified without
1201     checking the reference count.  This function does not handle out-of-memory
1202     conditions.
1203
1204     @param newStr
1205     pointer to the new string.  The pointed-to data must be null or a valid
1206     string.
1207
1208     @param str
1209     a valid string.
1210  */
1211 SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiUpperCase(
1212         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1213
1214 /** Create a new string by removing white space from both ends of another
1215     string.
1216
1217     The new string results from removing all characters with values less than
1218     or equal to 32 (the space character) form both ends of str.
1219
1220     This function cannot be used for language-specific conversion.  The new
1221     string does not necessarily have a reference count of 1 (in cases where
1222     no characters need to be removed), so it must not be modified without
1223     checking the reference count.  This function does not handle out-of-memory
1224     conditions.
1225
1226     @param newStr
1227     pointer to the new string.  The pointed-to data must be null or a valid
1228     string.
1229
1230     @param str
1231     a valid string.
1232  */
1233 SAL_DLLPUBLIC void SAL_CALL rtl_string_newTrim(
1234         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1235
1236 /** Create a new string by extracting a single token from another string.
1237
1238     Starting at index, the token's next token is searched for.  If there is no
1239     such token, the result is an empty string.  Otherwise, all characters from
1240     the start of that token and up to, but not including the next occurrence
1241     of cTok make up the resulting token.  The return value is the position of
1242     the next token, or -1 if no more tokens follow.
1243
1244     Example code could look like
1245       rtl_String * pToken = NULL;
1246       sal_Int32 nIndex = 0;
1247       do
1248       {
1249           ...
1250           nIndex = rtl_string_getToken(&pToken, pStr, 0, ';', nIndex);
1251           ...
1252       }
1253       while (nIndex >= 0);
1254
1255     The new string does not necessarily have a reference count of 1, so it
1256     must not be modified without checking the reference count.  This function
1257     does not handle out-of-memory conditions.
1258
1259     @param newStr
1260     pointer to the new string.  The pointed-to data must be null or a valid
1261     string.  If either token or index is negative, an empty token is stored in
1262     newStr (and -1 is returned).
1263
1264     @param str
1265     a valid string.
1266
1267     @param token
1268     the number of the token to return, starting at index.
1269
1270     @param cTok
1271     the character that separates the tokens.
1272
1273     @param idx
1274     the position at which searching for the token starts.  Must not be greater
1275     than the length of str.
1276
1277     @return
1278     the index of the next token, or -1 if no more tokens follow.
1279  */
1280 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getToken(
1281         rtl_String ** newStr , rtl_String * str, sal_Int32 token, sal_Char cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
1282
1283 /* ======================================================================= */
1284
1285 /** Supply an ASCII string literal together with its length.
1286
1287     This macro can be used to compute (some of) the arguments in function calls
1288     like rtl::OString(RTL_CONSTASCII_STRINGPARAM("foo")) or
1289     rtl::OUString::equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("foo")).
1290
1291     @param constAsciiStr
1292     must be an expression of type "(possibly cv-qualified reference to) array of
1293     (possibly cv-qualified) char."  Each element of the referenced array must
1294     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1295     referenced array is not considered part of the represented ASCII string, and
1296     its value should be 0x00.  Depending on where this macro is used, the nature
1297     of the supplied expression might be further restricted.
1298 */
1299 // The &foo[0] trick is intentional, it makes sure the type is char* or const char*
1300 // (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed).
1301 // This is to avoid mistaken use with functions that accept string literals
1302 // (i.e. const char (&)[N]) where usage of this macro otherwise could match
1303 // the argument and a following int argument with a default value (e.g. OString::match()).
1304 #define RTL_CONSTASCII_STRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \
1305     ((sal_Int32)SAL_N_ELEMENTS(constAsciiStr)-1)
1306
1307 /** Supply the length of an ASCII string literal.
1308
1309     This macro can be used to compute arguments in function calls like
1310     rtl::OUString::match(other, RTL_CONSTASCII_LENGTH("prefix")).
1311
1312     @param constAsciiStr
1313     must be an expression of type "(possibly cv-qualified reference to) array of
1314     (possibly cv-qualified) char."  Each element of the referenced array must
1315     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1316     referenced array is not considered part of the represented ASCII string, and
1317     its value should be 0x00.  Depending on where this macro is used, the nature
1318     of the supplied expression might be further restricted.
1319 */
1320 #define RTL_CONSTASCII_LENGTH( constAsciiStr ) ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1))
1321
1322 /* ======================================================================= */
1323
1324 /* predefined constants for String-Conversion */
1325 #define OUSTRING_TO_OSTRING_CVTFLAGS    (RTL_UNICODETOTEXT_FLAGS_UNDEFINED_DEFAULT |\
1326                                          RTL_UNICODETOTEXT_FLAGS_INVALID_DEFAULT |\
1327                                          RTL_UNICODETOTEXT_FLAGS_UNDEFINED_REPLACE |\
1328                                          RTL_UNICODETOTEXT_FLAGS_PRIVATE_MAPTO0)
1329
1330 /* ----------------------------------------------------------------------- */
1331
1332 /** Create a new byte string by converting a Unicode string, using a specific
1333     text encoding.
1334
1335     The lengths of the byte string and the Unicode string may differ (e.g.,
1336     for double-byte encodings, UTF-7, UTF-8).
1337
1338     If the length of the Unicode string is greater than zero, the reference
1339     count of the new string will be 1.
1340
1341     If an out-of-memory condition occurs, newStr will point to a null pointer
1342     upon return.
1343
1344     @param newStr
1345     pointer to the new string.  The pointed-to data must be null or a valid
1346     string.
1347
1348     @param str
1349     a Unicode character array.  Need not be null-terminated, but must be at
1350     least as long as the specified len.
1351
1352     @param len
1353     the length of the Unicode character array.
1354
1355     @param encoding
1356     the text encoding to use for conversion.
1357
1358     @param convertFlags
1359     flags which control the conversion.  Either use
1360     OUSTRING_TO_OSTRING_CVTFLAGS, or see
1361     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1362     details.
1363  */
1364 SAL_DLLPUBLIC void SAL_CALL rtl_uString2String(
1365         rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
1366
1367 /**
1368   Converts a Unicode string to a byte string, signalling failure.
1369
1370   @param pTarget
1371   An out parameter receiving the converted string.  Must not be null itself, and
1372   must contain either null or a pointer to a valid rtl_String; the contents are
1373   not modified if conversion fails (rtl_convertUStringToString returns false).
1374
1375   @param pSource
1376   The Unicode string.  May only be null if nLength is zero.
1377
1378   @param nLength
1379   The length of the Unicode string.  Must be non-negative.
1380
1381   @param nEncoding
1382   The text encoding to convert into.  Must be an octet encoding (i.e.,
1383   rtl_isOctetTextEncoding(nEncoding) must return true).
1384
1385   @param nFlags
1386   A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the conversion
1387   (see rtl_convertUnicodeToText).  RTL_UNICODETOTEXT_FLAGS_FLUSH need not be
1388   included, it is implicitly assumed.  Typical uses are either
1389   RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
1390   RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot be
1391   converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS (make a
1392   best efforts conversion).
1393
1394   @return
1395   True if the conversion succeeded, false otherwise.
1396  */
1397 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertUStringToString(
1398                                              rtl_String ** pTarget,
1399                                              sal_Unicode const * pSource,
1400                                              sal_Int32 nLength,
1401                                              rtl_TextEncoding nEncoding,
1402                                              sal_uInt32 nFlags)
1403     SAL_THROW_EXTERN_C();
1404
1405 /** Ensure a string has enough space for a given number of characters.
1406
1407  If the given string is large enough and has refcount of 1, it is not altered in any way.
1408  Otherwise it is replaced by a copy that has enough space for the given number of characters,
1409  data from the source string is copied to the beginning of it, the content of the remaining
1410  capacity undefined, the string has refcount of 1, and refcount of the original string is decreased.
1411
1412  @param str
1413  pointer to the string.  The pointed-to data must be a valid string.
1414
1415  @param size
1416  the number of characters
1417
1418  @since LibreOffice 4.1
1419  @internal
1420  */
1421 SAL_DLLPUBLIC void SAL_CALL rtl_string_ensureCapacity( rtl_String ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();
1422
1423 #ifdef __cplusplus
1424 }
1425 #endif
1426
1427 #endif // INCLUDED_RTL_STRING_H
1428
1429 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */