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 _RTL_STRING_H_
  21 #define _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 a long 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_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 756     (36), inclusive.
 757
 758     @return
 759     the long integer value represented by the string, or 0 if the string does
 760     not represent a long integer.
 761  */
 762 SAL_DLLPUBLIC sal_Int64 SAL_CALL rtl_str_toInt64(
 763         const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 764
 765 /** Interpret a string as an unsigned long integer.
 766
 767     This function cannot be used for language-specific conversion.  The string
 768     must be null-terminated.
 769
 770     @param str
 771     a null-terminated string.
 772
 773     @param radix
 774     the radix.  Must be between RTL_USTR_MIN_RADIX (2) and RTL_USTR_MAX_RADIX
 775     (36), inclusive.
 776
 777     @return
 778     the unsigned long integer value represented by the string, or 0 if the
 779     string does not represent an unsigned long integer.
 780
 781     @since LibreOffice 4.1
 782  */
 783 SAL_DLLPUBLIC sal_uInt64 SAL_CALL rtl_str_toUInt64(
 784         const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 785
 786 /** Interpret a string as a float.
 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     @return
 795     the float value represented by the string, or 0.0 if the string does not
 796     represent a float.
 797  */
 798 SAL_DLLPUBLIC float SAL_CALL rtl_str_toFloat(
 799         const sal_Char * str ) SAL_THROW_EXTERN_C();
 800
 801 /** Interpret a string as a double.
 802
 803     This function cannot be used for language-specific conversion.  The string
 804     must be null-terminated.
 805
 806     @param str
 807     a null-terminated string.
 808
 809     @return
 810     the float value represented by the string, or 0.0 if the string does not
 811     represent a double.
 812  */
 813 SAL_DLLPUBLIC double SAL_CALL rtl_str_toDouble(
 814         const sal_Char * str ) SAL_THROW_EXTERN_C();
 815
 816 /* ======================================================================= */
 817
 818 #ifdef SAL_W32
 819 #   pragma pack(push, 8)
 820 #endif
 821
 822 /** @cond INTERNAL */
 823 /** The implementation of a byte string.
 824  */
 825 typedef struct _rtl_String
 826 {
 827     oslInterlockedCount refCount; /* opaque */
 828     sal_Int32           length;
 829     sal_Char            buffer[1];
 830 } rtl_String;
 831 /** @endcond */
 832
 833 #if defined(SAL_W32)
 834 #pragma pack(pop)
 835 #endif
 836
 837 /* ----------------------------------------------------------------------- */
 838
 839 /** Increment the reference count of a string.
 840
 841     @param str
 842     a string.
 843  */
 844 SAL_DLLPUBLIC void SAL_CALL rtl_string_acquire( rtl_String * str ) SAL_THROW_EXTERN_C();
 845
 846 /** Decrement the reference count of a string.
 847
 848     If the count goes to zero than the string data is deleted.
 849
 850     @param str
 851     a string.
 852  */
 853 SAL_DLLPUBLIC void SAL_CALL rtl_string_release( rtl_String * str ) SAL_THROW_EXTERN_C();
 854
 855 /** Allocate a new string containing no characters.
 856
 857     @param newStr
 858     pointer to the new string.  The pointed-to data must be null or a valid
 859     string.
 860  */
 861 SAL_DLLPUBLIC void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXTERN_C();
 862
 863 /** Allocate a new string containing space for a given number of characters.
 864
 865     The reference count of the new string will be 1. The length of the string
 866     will be nLen. This function does not handle out-of-memory conditions.
 867
 868     For nLen < 0 or failed allocation this method returns NULL.
 869
 870     The characters of the capacity are not cleared, and the length is set to
 871     nLen, unlike the similar method of rtl_String_new_WithLength which
 872     zeros out the buffer, and sets the length to 0. So should be somewhat
 873     more efficient for allocating a new string.
 874
 875     call rtl_String_release to release the string
 876     alternatively pass ownership to an OUString with
 877     rtl::OUString(newStr, SAL_NO_ACQUIRE);
 878
 879     @param[out] nLen the number of characters.
 880     @return pointer to the new string.
 881
 882     @since LibreOffice 4.1
 883  */
 884 SAL_DLLPUBLIC rtl_String * SAL_CALL rtl_string_alloc(sal_Int32 nLen) SAL_THROW_EXTERN_C();
 885
 886 /** Allocate a new string containing space for a given number of characters.
 887
 888     If len is greater than zero, the reference count of the new string will be
 889     1.  The values of all characters are set to 0 and the length of the string
 890     is 0.  This function does not handle out-of-memory conditions.
 891
 892     @param newStr
 893     pointer to the new string.  The pointed-to data must be null or a valid
 894     string.
 895
 896     @param len
 897     the number of characters.
 898  */
 899 SAL_DLLPUBLIC void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C();
 900
 901 /** Allocate a new string that contains a copy of another string.
 902
 903     If the length of value is greater than zero, the reference count of the
 904     new string will be 1.  This function does not handle out-of-memory
 905     conditions.
 906
 907     @param newStr
 908     pointer to the new string.  The pointed-to data must be null or a valid
 909     string.
 910
 911     @param value
 912     a valid string.
 913  */
 914 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C();
 915
 916 /** Allocate a new string that contains a copy of a character array.
 917
 918     If the length of value is greater than zero, the reference count of the
 919     new string will be 1.  This function does not handle out-of-memory
 920     conditions.
 921
 922     @param newStr
 923     pointer to the new string.  The pointed-to data must be null or a valid
 924     string.
 925
 926     @param value
 927     a null-terminated character array.
 928  */
 929 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C();
 930
 931 /** Allocate a new string that contains a copy of a character array.
 932
 933     If the length of value is greater than zero, the reference count of the
 934     new string will be 1.  This function does not handle out-of-memory
 935     conditions.
 936
 937     @param newStr
 938     pointer to the new string.  The pointed-to data must be null or a valid
 939     string.
 940
 941     @param value
 942     a character array.  Need not be null-terminated, but must be at least as
 943     long as the specified len.
 944
 945     @param len
 946     the length of the character array.
 947  */
 948 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const sal_Char * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
 949
 950 /** Allocate a new string that is a substring of this string.
 951
 952     The substring begins at the specified beginIndex and contains count
 953     characters. Meaningless combinations such as negative beginIndex,
 954     or beginIndex + count greater than the length of the string have
 955     undefined behaviour.
 956
 957     @param[out]    newStr       the specified substring.
 958     @param[in]     from         the String to take the substring from.
 959     @param[in]     beginIndex   the beginning index, inclusive.
 960     @param[in]     count        the number of characters.
 961
 962     @since LibreOffice 4.0
 963  */
 964 SAL_DLLPUBLIC void SAL_CALL rtl_string_newFromSubString(
 965         rtl_String ** newStr, const rtl_String * from,
 966         sal_Int32 beginIndex, sal_Int32 count ) SAL_THROW_EXTERN_C();
 967
 968 /**
 969  @internal
 970  @since LibreOffice 3.6
 971 */
 972 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();
 973
 974 /** Assign a new value to a string.
 975
 976     First releases any value str might currently hold, then acquires
 977     rightValue.
 978
 979     @param str
 980     pointer to the string.  The pointed-to data must be null or a valid
 981     string.
 982
 983     @param rightValue
 984     a valid string.
 985  */
 986 SAL_DLLPUBLIC void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C();
 987
 988 /** Return the length of a string.
 989
 990     The length is equal to the number of characters in the string.
 991
 992     @param str
 993     a valid string.
 994
 995     @return
 996     the length of the string.
 997  */
 998 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C();
 999
1000 /** Return a pointer to the underlying character array of a string.
1001
1002     @param str
1003     a valid string.
1004
1005     @return
1006     a pointer to the null-terminated character array.
1007  */
1008 SAL_DLLPUBLIC sal_Char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C();
1009
1010 /** Create a new string that is the concatenation of two other strings.
1011
1012     The new string does not necessarily have a reference count of 1 (in cases
1013     where one of the two other strings is empty), so it must not be modified
1014     without checking the reference count.  This function does not handle
1015     out-of-memory conditions.
1016
1017     @param newStr
1018     pointer to the new string.  The pointed-to data must be null or a valid
1019     string.
1020
1021     @param left
1022     a valid string.
1023
1024     @param right
1025     a valid string.
1026  */
1027 SAL_DLLPUBLIC void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C();
1028
1029 /** Create a new string by replacing a substring of another string.
1030
1031     The new string results from replacing a number of characters (count),
1032     starting at the specified position (index) in the original string (str),
1033     with some new substring (subStr).  If subStr is null, than only a number
1034     of characters is deleted.
1035
1036     The new string does not necessarily have a reference count of 1, so it
1037     must not be modified without checking the reference count.  This function
1038     does not handle out-of-memory conditions.
1039
1040     @param newStr
1041     pointer to the new string.  The pointed-to data must be null or a valid
1042     string.
1043
1044     @param str
1045     a valid string.
1046
1047     @param idx
1048     the index into str at which to start replacement.  Must be between 0 and
1049     the length of str, inclusive.
1050
1051     @param count
1052     the number of characters to remove.  Must not be negative, and the sum of
1053     index and count must not exceed the length of str.
1054
1055     @param subStr
1056     either null or a valid string to be inserted.
1057  */
1058 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceStrAt(
1059         rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C();
1060
1061 /** Create a new string by replacing all occurrences of a single character
1062     within another string.
1063
1064     The new string results from replacing all occurrences of oldChar in str
1065     with newChar.
1066
1067     The new string does not necessarily have a reference count of 1 (in cases
1068     where oldChar does not occur in str), so it must not be modified without
1069     checking the reference count.  This function does not handle out-of-memory
1070     conditions.
1071
1072     @param newStr
1073     pointer to the new string.  The pointed-to data must be null or a valid
1074     string.
1075
1076     @param str
1077     a valid string.
1078
1079     @param oldChar
1080     the old character.
1081
1082     @param newChar
1083     the new character.
1084  */
1085 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplace(
1086         rtl_String ** newStr, rtl_String * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
1087
1088 /** Create a new string by replacing the first occurrence of a given substring
1089     with another substring.
1090
1091     @param[in, out] newStr  pointer to the new string; must not be null; must
1092     point to null or a valid rtl_String
1093
1094     @param str  pointer to the original string; must not be null
1095
1096     @param from  pointer to the substring to be replaced; must not be null and
1097     must point to memory of at least \p fromLength bytes
1098
1099     @param fromLength  the length of the \p from substring; must be non-negative
1100
1101     @param to  pointer to the replacing substring; must not be null and must
1102     point to memory of at least \p toLength bytes
1103
1104     @param toLength  the length of the \p to substring; must be non-negative
1105
1106     @param[in,out] index  pointer to a start index, must not be null; upon entry
1107     to the function its value is the index into the original string at which to
1108     start searching for the \p from substring, the value must be non-negative
1109     and not greater than the original string's length; upon exit from the
1110     function its value is the index into the original string at which the
1111     replacement took place or -1 if no replacement took place
1112
1113     @since LibreOffice 3.6
1114 */
1115 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceFirst(
1116     rtl_String ** newStr, rtl_String * str, char const * from,
1117     sal_Int32 fromLength, char const * to, sal_Int32 toLength,
1118     sal_Int32 * index) SAL_THROW_EXTERN_C();
1119
1120 /** Create a new string by replacing all occurrences of a given substring with
1121     another substring.
1122
1123     Replacing subsequent occurrences picks up only after a given replacement.
1124     That is, replacing from "xa" to "xx" in "xaa" results in "xxa", not "xxx".
1125
1126     @param[in, out] newStr  pointer to the new string; must not be null; must
1127     point to null or a valid rtl_String
1128
1129     @param str  pointer to the original string; must not be null
1130
1131     @param from  pointer to the substring to be replaced; must not be null and
1132     must point to memory of at least \p fromLength bytes
1133
1134     @param fromLength  the length of the \p from substring; must be non-negative
1135
1136     @param to  pointer to the replacing substring; must not be null and must
1137     point to memory of at least \p toLength bytes
1138
1139     @param toLength  the length of the \p to substring; must be non-negative
1140
1141     @since LibreOffice 3.6
1142 */
1143 SAL_DLLPUBLIC void SAL_CALL rtl_string_newReplaceAll(
1144     rtl_String ** newStr, rtl_String * str, char const * from,
1145     sal_Int32 fromLength, char const * to, sal_Int32 toLength)
1146     SAL_THROW_EXTERN_C();
1147
1148 /** Create a new string by converting all ASCII uppercase letters to lowercase
1149     within another string.
1150
1151     The new string results from replacing all characters with values between
1152     65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
1153
1154     This function cannot be used for language-specific conversion.  The new
1155     string does not necessarily have a reference count of 1 (in cases where
1156     no characters need to be converted), so it must not be modified without
1157     checking the reference count.  This function does not handle out-of-memory
1158     conditions.
1159
1160     @param newStr
1161     pointer to the new string.  The pointed-to data must be null or a valid
1162     string.
1163
1164     @param str
1165     a valid string.
1166  */
1167 SAL_DLLPUBLIC void SAL_CALL rtl_string_newToAsciiLowerCase(
1168         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1169
1170 /** Create a new string by converting all ASCII lowercase letters to uppercase
1171     within another string.
1172
1173     The new string results from replacing all characters with values between
1174     97 and 122 (ASCII a--z) by values between 65 and 90 (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_newToAsciiUpperCase(
1190         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1191
1192 /** Create a new string by removing white space from both ends of another
1193     string.
1194
1195     The new string results from removing all characters with values less than
1196     or equal to 32 (the space character) form both ends of str.
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 removed), 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_newTrim(
1212         rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1213
1214 /** Create a new string by extracting a single token from another string.
1215
1216     Starting at index, the token's next token is searched for.  If there is no
1217     such token, the result is an empty string.  Otherwise, all characters from
1218     the start of that token and up to, but not including the next occurrence
1219     of cTok make up the resulting token.  The return value is the position of
1220     the next token, or -1 if no more tokens follow.
1221
1222     Example code could look like
1223       rtl_String * pToken = NULL;
1224       sal_Int32 nIndex = 0;
1225       do
1226       {
1227           ...
1228           nIndex = rtl_string_getToken(&pToken, pStr, 0, ';', nIndex);
1229           ...
1230       }
1231       while (nIndex >= 0);
1232
1233     The new string does not necessarily have a reference count of 1, so it
1234     must not be modified without checking the reference count.  This function
1235     does not handle out-of-memory conditions.
1236
1237     @param newStr
1238     pointer to the new string.  The pointed-to data must be null or a valid
1239     string.  If either token or index is negative, an empty token is stored in
1240     newStr (and -1 is returned).
1241
1242     @param str
1243     a valid string.
1244
1245     @param token
1246     the number of the token to return, starting at index.
1247
1248     @param cTok
1249     the character that separates the tokens.
1250
1251     @param idx
1252     the position at which searching for the token starts.  Must not be greater
1253     than the length of str.
1254
1255     @return
1256     the index of the next token, or -1 if no more tokens follow.
1257  */
1258 SAL_DLLPUBLIC sal_Int32 SAL_CALL rtl_string_getToken(
1259         rtl_String ** newStr , rtl_String * str, sal_Int32 token, sal_Char cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
1260
1261 /* ======================================================================= */
1262
1263 /** Supply an ASCII string literal together with its length.
1264
1265     This macro can be used to compute (some of) the arguments in function calls
1266     like rtl::OString(RTL_CONSTASCII_STRINGPARAM("foo")) or
1267     rtl::OUString::equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("foo")).
1268
1269     @param constAsciiStr
1270     must be an expression of type "(possibly cv-qualified reference to) array of
1271     (possibly cv-qualified) char."  Each element of the referenced array must
1272     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1273     referenced array is not considered part of the represented ASCII string, and
1274     its value should be 0x00.  Depending on where this macro is used, the nature
1275     of the supplied expression might be further restricted.
1276 */
1277 // The &foo[0] trick is intentional, it makes sure the type is char* or const char*
1278 // (plain cast to const char* would not work with non-const char foo[]="a", which seems to be allowed).
1279 // This is to avoid mistaken use with functions that accept string literals
1280 // (i.e. const char (&)[N]) where usage of this macro otherwise could match
1281 // the argument and a following int argument with a default value (e.g. OString::match()).
1282 #define RTL_CONSTASCII_STRINGPARAM( constAsciiStr ) (&(constAsciiStr)[0]), \
1283     ((sal_Int32)SAL_N_ELEMENTS(constAsciiStr)-1)
1284
1285 /** Supply the length of an ASCII string literal.
1286
1287     This macro can be used to compute arguments in function calls like
1288     rtl::OUString::match(other, RTL_CONSTASCII_LENGTH("prefix")).
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 #define RTL_CONSTASCII_LENGTH( constAsciiStr ) ((sal_Int32)(SAL_N_ELEMENTS(constAsciiStr)-1))
1299
1300 /* ======================================================================= */
1301
1302 /* predefined constants for String-Conversion */
1303 #define OUSTRING_TO_OSTRING_CVTFLAGS    (RTL_UNICODETOTEXT_FLAGS_UNDEFINED_DEFAULT |\
1304                                          RTL_UNICODETOTEXT_FLAGS_INVALID_DEFAULT |\
1305                                          RTL_UNICODETOTEXT_FLAGS_UNDEFINED_REPLACE |\
1306                                          RTL_UNICODETOTEXT_FLAGS_PRIVATE_MAPTO0 |\
1307                                          RTL_UNICODETOTEXT_FLAGS_NOCOMPOSITE)
1308
1309 /* ----------------------------------------------------------------------- */
1310
1311 /** Create a new byte string by converting a Unicode string, using a specific
1312     text encoding.
1313
1314     The lengths of the byte string and the Unicode string may differ (e.g.,
1315     for double-byte encodings, UTF-7, UTF-8).
1316
1317     If the length of the Unicode string is greater than zero, the reference
1318     count of the new string will be 1.
1319
1320     If an out-of-memory condition occurs, newStr will point to a null pointer
1321     upon return.
1322
1323     @param newStr
1324     pointer to the new string.  The pointed-to data must be null or a valid
1325     string.
1326
1327     @param str
1328     a Unicode character array.  Need not be null-terminated, but must be at
1329     least as long as the specified len.
1330
1331     @param len
1332     the length of the Unicode character array.
1333
1334     @param encoding
1335     the text encoding to use for conversion.
1336
1337     @param convertFlags
1338     flags which control the conversion.  Either use
1339     OUSTRING_TO_OSTRING_CVTFLAGS, or see
1340     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1341     details.
1342  */
1343 SAL_DLLPUBLIC void SAL_CALL rtl_uString2String(
1344         rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
1345
1346 /**
1347   Converts a Unicode string to a byte string, signalling failure.
1348
1349   @param pTarget
1350   An out parameter receiving the converted string.  Must not be null itself, and
1351   must contain either null or a pointer to a valid rtl_String; the contents are
1352   not modified if conversion fails (rtl_convertUStringToString returns false).
1353
1354   @param pSource
1355   The Unicode string.  May only be null if nLength is zero.
1356
1357   @param nLength
1358   The length of the Unicode string.  Must be non-negative.
1359
1360   @param nEncoding
1361   The text encoding to convert into.  Must be an octet encoding (i.e.,
1362   rtl_isOctetTextEncoding(nEncoding) must return true).
1363
1364   @param nFlags
1365   A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the conversion
1366   (see rtl_convertUnicodeToText).  RTL_UNICODETOTEXT_FLAGS_FLUSH need not be
1367   included, it is implicitly assumed.  Typical uses are either
1368   RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
1369   RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot be
1370   converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS (make a
1371   best efforts conversion).
1372
1373   @return
1374   True if the conversion succeeded, false otherwise.
1375  */
1376 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_convertUStringToString(
1377                                              rtl_String ** pTarget,
1378                                              sal_Unicode const * pSource,
1379                                              sal_Int32 nLength,
1380                                              rtl_TextEncoding nEncoding,
1381                                              sal_uInt32 nFlags)
1382     SAL_THROW_EXTERN_C();
1383
1384 /** Ensure a string has enough space for a given number of characters.
1385
1386  If the given string is large enough and has refcount of 1, it is not altered in any way.
1387  Otherwise it is replaced by a copy that has enough space for the given number of characters,
1388  data from the source string is copied to the beginning of it, the content of the remaining
1389  capacity undefined, the string has refcount of 1, and refcount of the original string is decreased.
1390
1391  @param str
1392  pointer to the string.  The pointed-to data must be a valid string.
1393
1394  @param size
1395  the number of characters
1396
1397  @since LibreOffice 4.1
1398  @internal
1399  */
1400 SAL_DLLPUBLIC void SAL_CALL rtl_string_ensureCapacity( rtl_String ** str, sal_Int32 size ) SAL_THROW_EXTERN_C();
1401
1402 #ifdef __cplusplus
1403 }
1404 #endif
1405
1406 #endif /* _RTL_STRING_H_ */
1407
1408 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */