sal/inc/rtl/string.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: string.h,v $
  10  * $Revision: 1.17 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _RTL_STRING_H_
  32 #define _RTL_STRING_H_
  33
  34 #include <sal/types.h>
  35 #include <osl/interlck.h>
  36 #include <rtl/textcvt.h>
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /* ======================================================================= */
  43
  44 /** Return the length of a string.
  45
  46     The length is equal to the number of 8-bit characters in the string,
  47     without the terminating NUL character.
  48
  49     @param str
  50     a null-terminated string.
  51
  52     @return
  53     the length of the sequence of characters represented by this string,
  54     excluding the terminating NUL character.
  55  */
  56 sal_Int32 SAL_CALL rtl_str_getLength( const sal_Char * str ) SAL_THROW_EXTERN_C();
  57
  58 /** Compare two strings.
  59
  60     The comparison is based on the numeric value of each character in the
  61     strings and returns a value indicating their relationship.  This function
  62     cannot be used for language-specific sorting.  Both strings must be
  63     null-terminated.
  64
  65     @param first
  66     the first null-terminated string to be compared.
  67
  68     @param second
  69     the second null-terminated string which is compared with the first one.
  70
  71     @return
  72     0 if both strings are equal, a value less than 0 if the first string is
  73     less than the second string, and a value greater than 0 if the first
  74     string is greater than the second string.
  75  */
  76 sal_Int32 SAL_CALL rtl_str_compare( const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
  77
  78 /** Compare two strings.
  79
  80     The comparison is based on the numeric value of each character in the
  81     strings and returns a value indicating their relationship.  This function
  82     cannot be used for language-specific sorting.
  83
  84     @param first
  85     the first string to be compared.  Need not be null-terminated, but must be
  86     at least as long as the specified firstLen.
  87
  88     @param firstLen
  89     the length of the first string.
  90
  91     @param second
  92     the second string which is compared with the first one.  Need not be
  93     null-terminated, but must be at least as long as the specified secondLen.
  94
  95     @param secondLen
  96     the length of the second string.
  97
  98     @return
  99     0 if both strings are equal, a value less than 0 if the first string is
 100     less than the second string, and a value greater than 0 if the first
 101     string is greater than the second string.
 102  */
 103 sal_Int32 SAL_CALL rtl_str_compare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 104
 105 /** Compare two strings with a maximum count of characters.
 106
 107     The comparison is based on the numeric value of each character in the
 108     strings and returns a value indicating their relationship.  This function
 109     cannot be used for language-specific sorting.
 110
 111     @param first
 112     the first string to be compared.  Need not be null-terminated, but must be
 113     at least as long as the specified firstLen.
 114
 115     @param firstLen
 116     the length of the first string.
 117
 118     @param second
 119     the second string which is compared with the first one.  Need not be
 120     null-terminated, but must be at least as long as the specified secondLen.
 121
 122     @param secondLen
 123     the length of the second string.
 124
 125     @param shortenedLen
 126     the maximum number of characters to compare.  This length can be greater
 127     or smaller than the lengths of the two strings.
 128
 129     @return
 130     0 if both substrings are equal, a value less than 0 if the first substring
 131     is less than the second substring, and a value greater than 0 if the first
 132     substring is greater than the second substring.
 133  */
 134 sal_Int32 SAL_CALL rtl_str_shortenedCompare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen, sal_Int32 shortenedLen ) SAL_THROW_EXTERN_C();
 135
 136 /** Compare two strings from back to front.
 137
 138     The comparison is based on the numeric value of each character in the
 139     strings and returns a value indicating their relationship.  This function
 140     cannot be used for language-specific sorting.
 141
 142     @param first
 143     the first string to be compared.  Need not be null-terminated, but must be
 144     at least as long as the specified firstLen.
 145
 146     @param firstLen
 147     the length of the first string.
 148
 149     @param second
 150     the second string which is compared with the first one.  Need not be
 151     null-terminated, but must be at least as long as the specified secondLen.
 152
 153     @param secondLen
 154     the length of the second string.
 155
 156     @return
 157     0 if both strings are equal, a value less than 0 if the first string
 158     compares less than the second string, and a value greater than 0 if the
 159     first string compares greater than the second string.
 160  */
 161 sal_Int32 SAL_CALL rtl_str_reverseCompare_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 162
 163 /** Compare two strings, ignoring the case of ASCII characters.
 164
 165     The comparison is based on the numeric value of each character in the
 166     strings and returns a value indicating their relationship.  Character
 167     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 168     and 122 (ASCII a--z).  This function cannot be used for language-specific
 169     sorting.  Both strings must be null-terminated.
 170
 171     @param first
 172     the first null-terminated string to be compared.
 173
 174     @param second
 175     the second null-terminated string which is compared with the first one.
 176
 177     @return
 178     0 if both strings are equal, a value less than 0 if the first string is
 179     less than the second string, and a value greater than 0 if the first
 180     string is greater than the second string.
 181  */
 182 sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase( const sal_Char * first, const sal_Char * second ) SAL_THROW_EXTERN_C();
 183
 184 /** Compare two strings, ignoring the case of ASCII characters.
 185
 186     The comparison is based on the numeric value of each character in the
 187     strings and returns a value indicating their relationship.  Character
 188     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 189     and 122 (ASCII a--z).  This function cannot be used for language-specific
 190     sorting.
 191
 192     @param first
 193     the first string to be compared.  Need not be null-terminated, but must be
 194     at least as long as the specified firstLen.
 195
 196     @param firstLen
 197     the length of the first string.
 198
 199     @param second
 200     the second string which is compared with the first one.  Need not be
 201     null-terminated, but must be at least as long as the specified secondLen.
 202
 203     @param secondLen
 204     the length of the second string.
 205
 206     @return
 207     0 if both strings are equal, a value less than 0 if the first string is
 208     less than the second string, and a value greater than 0 if the first
 209     string is greater than the second string.
 210  */
 211 sal_Int32 SAL_CALL rtl_str_compareIgnoreAsciiCase_WithLength( const sal_Char * first, sal_Int32 firstLen, const sal_Char * second, sal_Int32 secondLen ) SAL_THROW_EXTERN_C();
 212
 213 /** Compare two strings with a maximum count of characters, ignoring the case
 214     of ASCII characters.
 215
 216     The comparison is based on the numeric value of each character in the
 217     strings and returns a value indicating their relationship.  Character
 218     values between 65 and 90 (ASCII A--Z) are interpreted as values between 97
 219     and 122 (ASCII a--z).  This function cannot be used for language-specific
 220     sorting.
 221
 222     @param first
 223     the first string to be compared.  Need not be null-terminated, but must be
 224     at least as long as the specified firstLen.
 225
 226     @param firstLen
 227     the length of the first string.
 228
 229     @param second
 230     the second string which is compared with the first one.  Need not be
 231     null-terminated, but must be at least as long as the specified secondLen.
 232
 233     @param secondLen
 234     the length of the second string.
 235
 236     @param shortenedLen
 237     the maximum number of characters to compare.  This length can be greater
 238     or smaller than the lengths of the two strings.
 239
 240     @return
 241     0 if both substrings are equal, a value less than 0 if the first substring
 242     is less than the second substring, and a value greater than 0 if the first
 243     substring is greater than the second substring.
 244  */
 245 sal_Int32 SAL_CALL rtl_str_shortenedCompareIgnoreAsciiCase_WithLength( 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_Int32 SAL_CALL rtl_str_hashCode( const sal_Char * str ) SAL_THROW_EXTERN_C();
 260
 261 /** Return a hash code for a string.
 262
 263     It is not allowed to store the hash code persistently, because later
 264     versions could return other hash codes.
 265
 266     @param str
 267     a string.  Need not be null-terminated, but must be at least as long as
 268     the specified len.
 269
 270     @param len
 271     the length of the string.
 272
 273     @return
 274     a hash code for the given string.
 275  */
 276 sal_Int32 SAL_CALL rtl_str_hashCode_WithLength( const sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 277
 278 /** Search for the first occurrence of a character within a string.
 279
 280     The string must be null-terminated.
 281
 282     @param str
 283     a null-terminated string.
 284
 285     @param ch
 286     the character to be searched for.
 287
 288     @return
 289     the index (starting at 0) of the first occurrence of the character in the
 290     string, or -1 if the character does not occur.
 291  */
 292 sal_Int32 SAL_CALL rtl_str_indexOfChar( const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C();
 293
 294 /** Search for the first occurrence of a character within a string.
 295
 296     @param str
 297     a string.  Need not be null-terminated, but must be at least as long as
 298     the specified len.
 299
 300     @param len
 301     the length of the string.
 302
 303     @param ch
 304     the character to be searched for.
 305
 306     @return
 307     the index (starting at 0) of the first occurrence of the character in the
 308     string, or -1 if the character does not occur.
 309  */
 310 sal_Int32 SAL_CALL rtl_str_indexOfChar_WithLength( const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C();
 311
 312 /** Search for the last occurrence of a character within a string.
 313
 314     The string must be null-terminated.
 315
 316     @param str
 317     a null-terminated string.
 318
 319     @param ch
 320     the character to be searched for.
 321
 322     @return
 323     the index (starting at 0) of the last occurrence of the character in the
 324     string, or -1 if the character does not occur.  The returned value is
 325     always smaller than the string length.
 326  */
 327 sal_Int32 SAL_CALL rtl_str_lastIndexOfChar( const sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C();
 328
 329 /** Search for the last occurrence of a character within a string.
 330
 331     @param str
 332     a string.  Need not be null-terminated, but must be at least as long as
 333     the specified len.
 334
 335     @param len
 336     the length of the string.
 337
 338     @param ch
 339     the character to be searched for.
 340
 341     @return
 342     the index (starting at 0) of the last occurrence of the character in the
 343     string, or -1 if the character does not occur.  The returned value is
 344     always smaller than the string length.
 345  */
 346 sal_Int32 SAL_CALL rtl_str_lastIndexOfChar_WithLength( const sal_Char * str, sal_Int32 len, sal_Char ch ) SAL_THROW_EXTERN_C();
 347
 348 /** Search for the first occurrence of a substring within a string.
 349
 350     If subStr is empty, or both str and subStr are empty, -1 is returned.
 351     Both strings must be null-terminated.
 352
 353     @param str
 354     a null-terminated string.
 355
 356     @param subStr
 357     the null-terminated substring to be searched for.
 358
 359     @return
 360     the index (starting at 0) of the first character of the first occurrence
 361     of the substring within the string, or -1 if the substring does not occur.
 362  */
 363 sal_Int32 SAL_CALL rtl_str_indexOfStr( const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C();
 364
 365 /** Search for the first occurrence of a substring within a string.
 366
 367     If subStr is empty, or both str and subStr are empty, -1 is returned.
 368
 369     @param str
 370     a string.  Need not be null-terminated, but must be at least as long as
 371     the specified len.
 372
 373     @param len
 374     the length of the string.
 375
 376     @param subStr
 377     the substring to be searched for.  Need not be null-terminated, but must
 378     be at least as long as the specified subLen.
 379
 380     @param subLen
 381     the length of the substring.
 382
 383     @return
 384     the index (starting at 0) of the first character of the first occurrence
 385     of the substring within the string, or -1 if the substring does not occur.
 386  */
 387 sal_Int32 SAL_CALL rtl_str_indexOfStr_WithLength( const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
 388
 389 /** Search for the last occurrence of a substring within a string.
 390
 391     If subStr is empty, or both str and subStr are empty, -1 is returned.
 392     Both strings must be null-terminated.
 393
 394     @param str
 395     a null-terminated string.
 396
 397     @param subStr
 398     the null-terminated substring to be searched for.
 399
 400     @return
 401     the index (starting at 0) of the first character of the last occurrence
 402     of the substring within the string, or -1 if the substring does not occur.
 403  */
 404 sal_Int32 SAL_CALL rtl_str_lastIndexOfStr( const sal_Char * str, const sal_Char * subStr ) SAL_THROW_EXTERN_C();
 405
 406 /** Search for the last occurrence of a substring within a string.
 407
 408     If subStr is empty, or both str and subStr are empty, -1 is returned.
 409
 410     @param str
 411     a string.  Need not be null-terminated, but must be at least as long as
 412     the specified len.
 413
 414     @param len
 415     the length of the string.
 416
 417     @param subStr
 418     the substring to be searched for.  Need not be null-terminated, but must
 419     be at least as long as the specified subLen.
 420
 421     @param subLen
 422     the length of the substring.
 423
 424     @return
 425     the index (starting at 0) of the first character of the first occurrence
 426     of the substring within the string, or -1 if the substring does not occur.
 427  */
 428 sal_Int32 SAL_CALL rtl_str_lastIndexOfStr_WithLength( const sal_Char * str, sal_Int32 len, const sal_Char * subStr, sal_Int32 subLen ) SAL_THROW_EXTERN_C();
 429
 430 /** Replace all occurrences of a single character within a string.
 431
 432     If oldChar does not occur within str, then the string is not modified.
 433     The string must be null-terminated.
 434
 435     @param str
 436     a null-terminated string.
 437
 438     @param oldChar
 439     the old character.
 440
 441     @param newChar
 442     the new character.
 443  */
 444 void SAL_CALL rtl_str_replaceChar( sal_Char * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
 445
 446 /** Replace all occurrences of a single character within a string.
 447
 448     If oldChar does not occur within str, then the string is not modified.
 449
 450     @param str
 451     a string.  Need not be null-terminated, but must be at least as long as
 452     the specified len.
 453
 454     @param len
 455     the length of the string.
 456
 457     @param oldChar
 458     the old character.
 459
 460     @param newChar
 461     the new character.
 462  */
 463 void SAL_CALL rtl_str_replaceChar_WithLength( sal_Char * str, sal_Int32 len, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
 464
 465 /** Convert all ASCII uppercase letters to lowercase within a string.
 466
 467     The characters with values between 65 and 90 (ASCII A--Z) are replaced
 468     with values between 97 and 122 (ASCII a--z).  The string must be
 469     null-terminated.
 470
 471     @param str
 472     a null-terminated string.
 473  */
 474 void SAL_CALL rtl_str_toAsciiLowerCase( sal_Char * str ) SAL_THROW_EXTERN_C();
 475
 476 /** Convert all ASCII uppercase letters to lowercase within a string.
 477
 478     The characters with values between 65 and 90 (ASCII A--Z) are replaced
 479     with values between 97 and 122 (ASCII a--z).
 480
 481     @param str
 482     a string.  Need not be null-terminated, but must be at least as long as
 483     the specified len.
 484
 485     @param len
 486     the length of the string.
 487  */
 488 void SAL_CALL rtl_str_toAsciiLowerCase_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 489
 490 /** Convert all ASCII lowercase letters to uppercase within a string.
 491
 492     The characters with values between 97 and 122 (ASCII a--z) are replaced
 493     with values between 65 and 90 (ASCII A--Z).  The string must be
 494     null-terminated.
 495
 496     @param str
 497     a null-terminated string.
 498  */
 499 void SAL_CALL rtl_str_toAsciiUpperCase( sal_Char * str ) SAL_THROW_EXTERN_C();
 500
 501 /** Convert all ASCII lowercase letters to uppercase within a string.
 502
 503     The characters with values between 97 and 122 (ASCII a--z) are replaced
 504     with values between 65 and 90 (ASCII A--Z).
 505
 506     @param str
 507     a string.  Need not be null-terminated, but must be at least as long as
 508     the specified len.
 509
 510     @param len
 511     the length of the string.
 512  */
 513 void SAL_CALL rtl_str_toAsciiUpperCase_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 514
 515 /** Remove white space from both ends of a string.
 516
 517     All characters with values less than or equal to 32 (the space character)
 518     are considered to be white space.  This function cannot be used for
 519     language-specific operations.  The string must be null-terminated.
 520
 521     @param str
 522     a null-terminated string.
 523
 524     @return
 525     the new length of the string.
 526  */
 527 sal_Int32 SAL_CALL rtl_str_trim( sal_Char * str ) SAL_THROW_EXTERN_C();
 528
 529 /** Remove white space from both ends of the string.
 530
 531     All characters with values less than or equal to 32 (the space character)
 532     are considered to be white space.  This function cannot be used for
 533     language-specific operations.  The string must be null-terminated.
 534
 535     @param str
 536     a string.  Need not be null-terminated, but must be at least as long as
 537     the specified len.
 538
 539     @param len
 540     the original length of the string.
 541
 542     @return
 543     the new length of the string.
 544  */
 545 sal_Int32 SAL_CALL rtl_str_trim_WithLength( sal_Char * str, sal_Int32 len ) SAL_THROW_EXTERN_C();
 546
 547 /** Create the string representation of a boolean.
 548
 549     If b is true, the buffer is filled with the string "true" and 5 is
 550     returned.  If b is false, the buffer is filled with the string "false" and
 551     6 is returned.  This function cannot be used for language-specific
 552     operations.
 553
 554     @param str
 555     a buffer that is big enough to hold the result and the terminating NUL
 556     character.  You should use the RTL_STR_MAX_VALUEOFBOOLEAN define to create
 557     a buffer that is big enough.
 558
 559     @param b
 560     a boolean value.
 561
 562     @return
 563     the length of the string.
 564  */
 565 sal_Int32 SAL_CALL rtl_str_valueOfBoolean( sal_Char * str, sal_Bool b ) SAL_THROW_EXTERN_C();
 566 #define RTL_STR_MAX_VALUEOFBOOLEAN 6
 567
 568 /** Create the string representation of a character.
 569
 570     @param str
 571     a buffer that is big enough to hold the result and the terminating NUL
 572     character.  You should use the RTL_STR_MAX_VALUEOFCHAR define to create a
 573     buffer that is big enough.
 574
 575     @param ch
 576     a character value.
 577
 578     @return
 579     the length of the string.
 580  */
 581 sal_Int32 SAL_CALL rtl_str_valueOfChar( sal_Char * str, sal_Char ch ) SAL_THROW_EXTERN_C();
 582 #define RTL_STR_MAX_VALUEOFCHAR 2
 583
 584 /** Create the string representation of an integer.
 585
 586     This function cannot be used for language-specific operations.
 587
 588     @param str
 589     a buffer that is big enough to hold the result and the terminating NUL
 590     character.  You should use the RTL_STR_MAX_VALUEOFINT32 define to create a
 591     buffer that is big enough.
 592
 593     @param i
 594     an integer value.
 595
 596     @param radix
 597     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 598     (36), inclusive.
 599
 600     @return
 601     the length of the string.
 602  */
 603 sal_Int32 SAL_CALL rtl_str_valueOfInt32( sal_Char * str, sal_Int32 i, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 604 #define RTL_STR_MIN_RADIX           2
 605 #define RTL_STR_MAX_RADIX           36
 606 #define RTL_STR_MAX_VALUEOFINT32    33
 607
 608 /** Create the string representation of a long integer.
 609
 610     This function cannot be used for language-specific operations.
 611
 612     @param str
 613     a buffer that is big enough to hold the result and the terminating NUL
 614     character.  You should use the RTL_STR_MAX_VALUEOFINT64 define to create a
 615     buffer that is big enough.
 616
 617     @param l
 618     a long integer value.
 619
 620     @param radix
 621     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 622     (36), inclusive.
 623
 624     @return
 625     the length of the string.
 626  */
 627 sal_Int32 SAL_CALL rtl_str_valueOfInt64( sal_Char * str, sal_Int64 l, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 628 #define RTL_STR_MAX_VALUEOFINT64 65
 629
 630 /** Create the string representation of a float.
 631
 632     This function cannot be used for language-specific conversion.
 633
 634     @param str
 635     a buffer that is big enough to hold the result and the terminating NUL
 636     character.  You should use the RTL_STR_MAX_VALUEOFFLOAT define to create a
 637     buffer that is big enough.
 638
 639     @param f
 640     a float value.
 641
 642     @return
 643     the length of the string.
 644  */
 645 sal_Int32 SAL_CALL rtl_str_valueOfFloat( sal_Char * str, float f ) SAL_THROW_EXTERN_C();
 646 #define RTL_STR_MAX_VALUEOFFLOAT 15
 647
 648 /** Create the string representation of a double.
 649
 650     This function cannot be used for language-specific conversion.
 651
 652     @param str
 653     a buffer that is big enough to hold the result and the terminating NUL
 654     character.  You should use the RTL_STR_MAX_VALUEOFDOUBLE define to create
 655     a buffer that is big enough.
 656
 657     @param d
 658     a double value.
 659
 660     @return
 661     the length of the string.
 662  */
 663 sal_Int32 SAL_CALL rtl_str_valueOfDouble( sal_Char * str, double d ) SAL_THROW_EXTERN_C();
 664 #define RTL_STR_MAX_VALUEOFDOUBLE 25
 665
 666 /** Interpret a string as a boolean.
 667
 668     This function cannot be used for language-specific conversion.  The string
 669     must be null-terminated.
 670
 671     @param str
 672     a null-terminated string.
 673
 674     @return
 675     true if the string is "1" or "true" in any ASCII case, false otherwise.
 676  */
 677 sal_Bool SAL_CALL rtl_str_toBoolean( const sal_Char * str ) SAL_THROW_EXTERN_C();
 678
 679 /** Interpret a string as an integer.
 680
 681     This function cannot be used for language-specific conversion.  The string
 682     must be null-terminated.
 683
 684     @param str
 685     a null-terminated string.
 686
 687     @param radix
 688     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 689     (36), inclusive.
 690
 691     @return
 692     the integer value represented by the string, or 0 if the string does not
 693     represent an integer.
 694  */
 695 sal_Int32 SAL_CALL rtl_str_toInt32( const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 696
 697 /** Interpret a string as a long integer.
 698
 699     This function cannot be used for language-specific conversion.  The string
 700     must be null-terminated.
 701
 702     @param str
 703     a null-terminated string.
 704
 705     @param radix
 706     the radix.  Must be between RTL_STR_MIN_RADIX (2) and RTL_STR_MAX_RADIX
 707     (36), inclusive.
 708
 709     @return
 710     the long integer value represented by the string, or 0 if the string does
 711     not represent a long integer.
 712  */
 713 sal_Int64 SAL_CALL rtl_str_toInt64( const sal_Char * str, sal_Int16 radix ) SAL_THROW_EXTERN_C();
 714
 715 /** Interpret a string as a float.
 716
 717     This function cannot be used for language-specific conversion.  The string
 718     must be null-terminated.
 719
 720     @param str
 721     a null-terminated string.
 722
 723     @return
 724     the float value represented by the string, or 0.0 if the string does not
 725     represent a float.
 726  */
 727 float SAL_CALL rtl_str_toFloat( const sal_Char * str ) SAL_THROW_EXTERN_C();
 728
 729 /** Interpret a string as a double.
 730
 731     This function cannot be used for language-specific conversion.  The string
 732     must be null-terminated.
 733
 734     @param str
 735     a null-terminated string.
 736
 737     @return
 738     the float value represented by the string, or 0.0 if the string does not
 739     represent a double.
 740  */
 741 double SAL_CALL rtl_str_toDouble( const sal_Char * str ) SAL_THROW_EXTERN_C();
 742
 743 /* ======================================================================= */
 744
 745 #ifdef SAL_W32
 746 #       pragma pack(push, 8)
 747 #elif defined(SAL_OS2)
 748 #       pragma pack(push, 4)
 749 #endif
 750
 751 /** The implementation of a byte string.
 752
 753     @internal
 754  */
 755 typedef struct _rtl_String
 756 {
 757     oslInterlockedCount refCount; /* opaque */
 758     sal_Int32           length;
 759     sal_Char            buffer[1];
 760 } rtl_String;
 761
 762 #if defined( SAL_W32) ||  defined(SAL_OS2)
 763 #pragma pack(pop)
 764 #endif
 765
 766 /* ----------------------------------------------------------------------- */
 767
 768 /** Increment the reference count of a string.
 769
 770     @param str
 771     a string.
 772  */
 773 void SAL_CALL rtl_string_acquire( rtl_String * str ) SAL_THROW_EXTERN_C();
 774
 775 /** Decrement the reference count of a string.
 776
 777     If the count goes to zero than the string data is deleted.
 778
 779     @param str
 780     a string.
 781  */
 782 void SAL_CALL rtl_string_release( rtl_String * str ) SAL_THROW_EXTERN_C();
 783
 784 /** Allocate a new string containing no characters.
 785
 786     @param newStr
 787     pointer to the new string.  The pointed-to data must be null or a valid
 788     string.
 789  */
 790 void SAL_CALL rtl_string_new( rtl_String ** newStr ) SAL_THROW_EXTERN_C();
 791
 792 /** Allocate a new string containing space for a given number of characters.
 793
 794     If len is greater than zero, the reference count of the new string will be
 795     1.  The values of all characters are set to 0 and the length of the string
 796     is 0.  This function does not handle out-of-memory conditions.
 797
 798     @param newStr
 799     pointer to the new string.  The pointed-to data must be null or a valid
 800     string.
 801
 802     @param len
 803     the number of characters.
 804  */
 805 void SAL_CALL rtl_string_new_WithLength( rtl_String ** newStr, sal_Int32 len ) SAL_THROW_EXTERN_C();
 806
 807 /** Allocate a new string that contains a copy of another string.
 808
 809     If the length of value is greater than zero, the reference count of the
 810     new string will be 1.  This function does not handle out-of-memory
 811     conditions.
 812
 813     @param newStr
 814     pointer to the new string.  The pointed-to data must be null or a valid
 815     string.
 816
 817     @param value
 818     a valid string.
 819  */
 820 void SAL_CALL rtl_string_newFromString( rtl_String ** newStr, const rtl_String * value ) SAL_THROW_EXTERN_C();
 821
 822 /** Allocate a new string that contains a copy of a character array.
 823
 824     If the length of value is greater than zero, the reference count of the
 825     new string will be 1.  This function does not handle out-of-memory
 826     conditions.
 827
 828     @param newStr
 829     pointer to the new string.  The pointed-to data must be null or a valid
 830     string.
 831
 832     @param value
 833     a null-terminated character array.
 834  */
 835 void SAL_CALL rtl_string_newFromStr( rtl_String ** newStr, const sal_Char * value ) SAL_THROW_EXTERN_C();
 836
 837 /** Allocate a new string that contains a copy of a character array.
 838
 839     If the length of value is greater than zero, the reference count of the
 840     new string will be 1.  This function does not handle out-of-memory
 841     conditions.
 842
 843     @param newStr
 844     pointer to the new string.  The pointed-to data must be null or a valid
 845     string.
 846
 847     @param value
 848     a character array.  Need not be null-terminated, but must be at least as
 849     long as the specified len.
 850
 851     @param len
 852     the length of the character array.
 853  */
 854 void SAL_CALL rtl_string_newFromStr_WithLength( rtl_String ** newStr, const sal_Char * value, sal_Int32 len ) SAL_THROW_EXTERN_C();
 855
 856 /** Assign a new value to a string.
 857
 858     First releases any value str might currently hold, then acquires
 859     rightValue.
 860
 861     @param str
 862     pointer to the string.  The pointed-to data must be null or a valid
 863     string.
 864
 865     @param rightValue
 866     a valid string.
 867  */
 868 void SAL_CALL rtl_string_assign( rtl_String ** str, rtl_String * rightValue ) SAL_THROW_EXTERN_C();
 869
 870 /** Return the length of a string.
 871
 872     The length is equal to the number of characters in the string.
 873
 874     @param str
 875     a valid string.
 876
 877     @return
 878     the length of the string.
 879  */
 880 sal_Int32 SAL_CALL rtl_string_getLength( const rtl_String * str ) SAL_THROW_EXTERN_C();
 881
 882 /** Return a pointer to the underlying character array of a string.
 883
 884     @param str
 885     a valid string.
 886
 887     @return
 888     a pointer to the null-terminated character array.
 889  */
 890 sal_Char * SAL_CALL rtl_string_getStr( rtl_String * str ) SAL_THROW_EXTERN_C();
 891
 892 /** Create a new string that is the concatenation of two other strings.
 893
 894     The new string does not necessarily have a reference count of 1 (in cases
 895     where one of the two other strings is empty), so it must not be modified
 896     without checking the reference count.  This function does not handle
 897     out-of-memory conditions.
 898
 899     @param newStr
 900     pointer to the new string.  The pointed-to data must be null or a valid
 901     string.
 902
 903     @param left
 904     a valid string.
 905
 906     @param right
 907     a valid string.
 908  */
 909 void SAL_CALL rtl_string_newConcat( rtl_String ** newStr, rtl_String * left, rtl_String * right ) SAL_THROW_EXTERN_C();
 910
 911 /** Create a new string by replacing a substring of another string.
 912
 913     The new string results from replacing a number of characters (count),
 914     starting at the specified position (index) in the original string (str),
 915     with some new substring (subStr).  If subStr is null, than only a number
 916     of characters is deleted.
 917
 918     The new string does not necessarily have a reference count of 1, so it
 919     must not be modified without checking the reference count.  This function
 920     does not handle out-of-memory 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 str
 927     a valid string.
 928
 929     @param index
 930     the index into str at which to start replacement.  Must be between 0 and
 931     the length of str, inclusive.
 932
 933     @param count
 934     the number of charcters to remove.  Must not be negative, and the sum of
 935     index and count must not exceed the length of str.
 936
 937     @param subStr
 938     either null or a valid string to be inserted.
 939  */
 940 void SAL_CALL rtl_string_newReplaceStrAt( rtl_String ** newStr, rtl_String * str, sal_Int32 idx, sal_Int32 count, rtl_String * subStr ) SAL_THROW_EXTERN_C();
 941
 942 /** Create a new string by replacing all occurrences of a single character
 943     within another string.
 944
 945     The new string results from replacing all occurrences of oldChar in str
 946     with newChar.
 947
 948     The new string does not necessarily have a reference count of 1 (in cases
 949     where oldChar does not occur in str), so it must not be modified without
 950     checking the reference count.  This function does not handle out-of-memory
 951     conditions.
 952
 953     @param newStr
 954     pointer to the new string.  The pointed-to data must be null or a valid
 955     string.
 956
 957     @param str
 958     a valid string.
 959
 960     @param oldChar
 961     the old character.
 962
 963     @param newChar
 964     the new character.
 965  */
 966 void SAL_CALL rtl_string_newReplace( rtl_String ** newStr, rtl_String * str, sal_Char oldChar, sal_Char newChar ) SAL_THROW_EXTERN_C();
 967
 968 /** Create a new string by converting all ASCII uppercase letters to lowercase
 969     within another string.
 970
 971     The new string results from replacing all characters with values between
 972     65 and 90 (ASCII A--Z) by values between 97 and 122 (ASCII a--z).
 973
 974     This function cannot be used for language-specific conversion.  The new
 975     string does not necessarily have a reference count of 1 (in cases where
 976     no characters need to be converted), so it must not be modified without
 977     checking the reference count.  This function does not handle out-of-memory
 978     conditions.
 979
 980     @param newStr
 981     pointer to the new string.  The pointed-to data must be null or a valid
 982     string.
 983
 984     @param str
 985     a valid string.
 986  */
 987 void SAL_CALL rtl_string_newToAsciiLowerCase( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
 988
 989 /** Create a new string by converting all ASCII lowercase letters to uppercase
 990     within another string.
 991
 992     The new string results from replacing all characters with values between
 993     97 and 122 (ASCII a--z) by values between 65 and 90 (ASCII A--Z).
 994
 995     This function cannot be used for language-specific conversion.  The new
 996     string does not necessarily have a reference count of 1 (in cases where
 997     no characters need to be converted), so it must not be modified without
 998     checking the reference count.  This function does not handle out-of-memory
 999     conditions.
1000
1001     @param newStr
1002     pointer to the new string.  The pointed-to data must be null or a valid
1003     string.
1004
1005     @param str
1006     a valid string.
1007  */
1008 void SAL_CALL rtl_string_newToAsciiUpperCase( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1009
1010 /** Create a new string by removing white space from both ends of another
1011     string.
1012
1013     The new string results from removing all characters with values less than
1014     or equal to 32 (the space character) form both ends of str.
1015
1016     This function cannot be used for language-specific conversion.  The new
1017     string does not necessarily have a reference count of 1 (in cases where
1018     no characters need to be removed), so it must not be modified without
1019     checking the reference count.  This function does not handle out-of-memory
1020     conditions.
1021
1022     @param newStr
1023     pointer to the new string.  The pointed-to data must be null or a valid
1024     string.
1025
1026     @param str
1027     a valid string.
1028  */
1029 void SAL_CALL rtl_string_newTrim( rtl_String ** newStr, rtl_String * str ) SAL_THROW_EXTERN_C();
1030
1031 /** Create a new string by extracting a single token from another string.
1032
1033     Starting at index, the token's next token is searched for.  If there is no
1034     such token, the result is an empty string.  Otherwise, all characters from
1035     the start of that token and up to, but not including the next occurrence
1036     of cTok make up the resulting token.  The return value is the position of
1037     the next token, or -1 if no more tokens follow.
1038
1039     Example code could look like
1040       rtl_String * pToken = NULL;
1041       sal_Int32 nIndex = 0;
1042       do
1043       {
1044           ...
1045           nIndex = rtl_string_getToken(&pToken, pStr, 0, ';', nIndex);
1046           ...
1047       }
1048       while (nIndex >= 0);
1049
1050     The new string does not necessarily have a reference count of 1, so it
1051     must not be modified without checking the reference count.  This function
1052     does not handle out-of-memory conditions.
1053
1054     @param newStr
1055     pointer to the new string.  The pointed-to data must be null or a valid
1056     string.  If either token or index is negative, an empty token is stored in
1057     newStr (and -1 is returned).
1058
1059     @param str
1060     a valid string.
1061
1062     @param token
1063     the number of the token to return, starting at index.
1064
1065     @param cTok
1066     the character that seperates the tokens.
1067
1068     @param index
1069     the position at which searching for the token starts.  Must not be greater
1070     than the length of str.
1071
1072     @return
1073     the index of the next token, or -1 if no more tokens follow.
1074  */
1075 sal_Int32 SAL_CALL rtl_string_getToken( rtl_String ** newStr , rtl_String * str, sal_Int32 token, sal_Char cTok, sal_Int32 idx ) SAL_THROW_EXTERN_C();
1076
1077 /* ======================================================================= */
1078
1079 /** Supply an ASCII string literal together with its length.
1080
1081     This macro can be used to compute (some of) the arguments in function calls
1082     like rtl::OString(RTL_CONSTASCII_STRINGPARAM("foo")) or
1083     rtl::OUString::equalsAsciiL(RTL_CONSTASCII_STRINGPARAM("foo")).
1084
1085     @param constAsciiStr
1086     must be an expression of type "(possibly cv-qualified reference to) array of
1087     (possibly cv-qualified) char."  Each element of the referenced array must
1088     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1089     referenced array is not considered part of the represented ASCII string, and
1090     its value should be 0x00.  Depending on where this macro is used, the nature
1091     of the supplied expression might be further restricted.
1092 */
1093 #define RTL_CONSTASCII_STRINGPARAM( constAsciiStr ) constAsciiStr, ((sal_Int32)sizeof(constAsciiStr)-1)
1094
1095 /** Supply the length of an ASCII string literal.
1096
1097     This macro can be used to compute arguments in function calls like
1098     rtl::OUString::match(other, RTL_CONSTASCII_LENGTH("prefix")).
1099
1100     @param constAsciiStr
1101     must be an expression of type "(possibly cv-qualified reference to) array of
1102     (possibly cv-qualified) char."  Each element of the referenced array must
1103     represent an ASCII value in the range 0x00--0x7F.  The last element of the
1104     referenced array is not considered part of the represented ASCII string, and
1105     its value should be 0x00.  Depending on where this macro is used, the nature
1106     of the supplied expression might be further restricted.
1107 */
1108 #define RTL_CONSTASCII_LENGTH( constAsciiStr ) ((sal_Int32)(sizeof(constAsciiStr)-1))
1109
1110 /* ======================================================================= */
1111
1112 /* predefined constants for String-Conversion */
1113 #define OUSTRING_TO_OSTRING_CVTFLAGS    (RTL_UNICODETOTEXT_FLAGS_UNDEFINED_DEFAULT |\
1114                                          RTL_UNICODETOTEXT_FLAGS_INVALID_DEFAULT |\
1115                                          RTL_UNICODETOTEXT_FLAGS_UNDEFINED_REPLACE |\
1116                                          RTL_UNICODETOTEXT_FLAGS_PRIVATE_MAPTO0 |\
1117                                          RTL_UNICODETOTEXT_FLAGS_NOCOMPOSITE)
1118
1119 /* ----------------------------------------------------------------------- */
1120
1121 /** Create a new byte string by converting a Unicode string, using a specific
1122     text encoding.
1123
1124     The lengths of the byte string and the Unicode string may differ (e.g.,
1125     for double-byte encodings, UTF-7, UTF-8).
1126
1127     If the length of the Unicode string is greater than zero, the reference
1128     count of the new string will be 1.
1129
1130     If an out-of-memory condition occurs, newStr will point to a null pointer
1131     upon return.
1132
1133     @param newStr
1134     pointer to the new string.  The pointed-to data must be null or a valid
1135     string.
1136
1137     @param str
1138     a Unicode character array.  Need not be null-terminated, but must be at
1139     least as long as the specified len.
1140
1141     @param len
1142     the length of the Unicode character array.
1143
1144     @param encoding
1145     the text encoding to use for conversion.
1146
1147     @param convertFlags
1148     flags which control the conversion.  Either use
1149     OUSTRING_TO_OSTRING_CVTFLAGS, or see
1150     <http://udk.openoffice.org/cpp/man/spec/textconversion.html> for more
1151     details.
1152  */
1153 void SAL_CALL rtl_uString2String( rtl_String ** newStr, const sal_Unicode * str, sal_Int32 len, rtl_TextEncoding encoding, sal_uInt32 convertFlags ) SAL_THROW_EXTERN_C();
1154
1155 /**
1156   Converts a Unicode string to a byte string, signalling failure.
1157
1158   @param pTarget
1159   An out parameter receiving the converted string.  Must not be null itself, and
1160   must contain either null or a pointer to a valid rtl_String; the contents are
1161   not modified if conversion fails (rtl_convertUStringToString returns false).
1162
1163   @param pSource
1164   The Unicode string.  May only be null if nLength is zero.
1165
1166   @param nLength
1167   The length of the Unicode string.  Must be non-negative.
1168
1169   @param nEncoding
1170   The text encoding to convert into.  Must be an octet encoding (i.e.,
1171   rtl_isOctetTextEncoding(nEncoding) must return true).
1172
1173   @param nFlags
1174   A combination of RTL_UNICODETOTEXT_FLAGS that detail how to do the conversion
1175   (see rtl_convertUnicodeToText).  RTL_UNICODETOTEXT_FLAGS_FLUSH need not be
1176   included, it is implicitly assumed.  Typical uses are either
1177   RTL_UNICODETOTEXT_FLAGS_UNDEFINED_ERROR |
1178   RTL_UNICODETOTEXT_FLAGS_INVALID_ERROR (fail if a Unicode character cannot be
1179   converted to the target nEncoding) or OUSTRING_TO_OSTRING_CVTFLAGS (make a
1180   best efforts conversion).
1181
1182   @return
1183   True if the conversion succeeded, false otherwise.
1184  */
1185 sal_Bool SAL_CALL rtl_convertUStringToString(rtl_String ** pTarget,
1186                                              sal_Unicode const * pSource,
1187                                              sal_Int32 nLength,
1188                                              rtl_TextEncoding nEncoding,
1189                                              sal_uInt32 nFlags)
1190     SAL_THROW_EXTERN_C();
1191
1192 #ifdef __cplusplus
1193 }
1194 #endif
1195
1196 #endif /* _RTL_STRING_H_ */