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