1/* 2 * Copyright 2007-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Stefano Ceccherini, burton666@freemail.it 7 * Marc Flerackers, mflerackers@androme.be 8 * Niels Sascha Reedijk, niels.reedijk@gmail.com 9 * John Scipione, jscipione@gmail.com 10 * Oliver Tappe, openbeos@hirschaefer.de 11 * 12 * Corresponds to: 13 * headers/os/support/String.h rev 50791 14 * src/kits/support/String.cpp rev 52836 15 */ 16 17 18/*! 19 \file String.h 20 \ingroup support 21 \ingroup libbe 22 \brief Defines the BString class and global operators and functions for 23 handling strings. 24*/ 25 26 27/*! 28 \class BString String.h 29 \ingroup support 30 \ingroup libbe 31 \brief String class supporting common string operations. 32 33 BString is a string allocation and manipulation class. The object 34 takes care to allocate and free memory for you, so it will always be 35 "big enough" to store your strings. 36 37 While BString is in essence a wrapper around a byte-array, which can always 38 be accessed with the BString::String() method, it does have some 39 understanding of UTF-8 and it can be used for the manipulation of UTF-8 40 strings. For all operations that perform on bytes, there is an equivalent 41 that operates on UTF-8 strings. See for example the BString::CopyInto() and 42 BString::CopyCharsInto() methods. The main difference is that if there are 43 any position argumens, the regular method counts the bytes and the 44 Chars methods counts characters. 45 46 \since BeOS R5 47*/ 48 49 50/*! 51 \fn BString::BString() 52 \brief Creates an empty BString. 53 54 \since BeOS R5 55*/ 56 57 58/*! 59 \fn BString::BString(const char* string) 60 \brief Creates and initializes a BString from \a string. 61 62 \param string The \a string to copy from. 63 64 \since BeOS R5 65*/ 66 67 68/*! 69 \fn BString::BString(const BString& string) 70 \brief Creates and initializes a BString as a copy of another \a string. 71 72 \param string The BString object to copy from. 73 74 \since BeOS R5 75*/ 76 77 78/*! 79 \fn BString::BString(const char* string, int32 maxLength) 80 \brief Creates and initializes a BString from a \a string up to 81 \a maxLength characters. 82 83 If \a maxLength is greater than the length of the source \a string then the 84 entire source \a string is copied. If \a maxLength is less than or equal 85 to 0 then the result is an empty BString. 86 87 \warning In BeOS R5 passing in a negative \a maxLength argument will copy 88 the entire \a string. 89 90 \param string The \a string data to initialize the BString to. 91 \param maxLength Maximum number of characters (bytes) to copy. 92 93 \since BeOS R5 94*/ 95 96 97#if __cplusplus >= 201103L 98/*! 99 \fn BString::BString(BString&& string) noexcept 100 \brief Move the data from the \a string to this object. 101 102 Create a new string object with the data of another \a string. The 103 \a string will no longer point to the same contents. 104 105 \note This constructor is only available for modern C++ (C++11 or later). 106 107 \since Haiku R1 108*/ 109#endif 110 111 112/*! 113 \fn BString::~BString() 114 \brief Free all resources associated with the object. 115 116 The destructor also frees the internal buffer associated with the string. 117 118 \since BeOS R5 119*/ 120 121 122/*! 123 \name Access 124*/ 125 126 127//! @{ 128 129 130/*! 131 \fn const char* BString::String() const 132 \brief Return a pointer to the object string, \c NUL terminated. 133 134 The pointer to the object string is guaranteed to be \c NUL 135 terminated. You can't modify or free the pointer. Once the BString 136 object is deleted, the pointer becomes invalid. 137 138 If you want to manipulate the internal string of the object directly, 139 have a look at LockBuffer(). 140 141 \return A pointer to the object string. 142 143 \since BeOS R5 144*/ 145 146 147/*! 148 \fn int32 BString::Length() const 149 \brief Get the length of the string in bytes. 150 151 \return An integer with the length of the string, measured in bytes. 152 153 \sa CountChars() 154 155 \since BeOS R5 156*/ 157 158 159/*! 160 \fn int32 BString::CountChars() const 161 \brief Returns the length of the object measured in characters. 162 163 BString is somewhat aware of UTF-8 characters, so this method will count 164 the actual number of characters in the string. 165 166 \return An integer which is the number of characters in the string. 167 168 \sa Length() 169 170 \since BeOS R5 171*/ 172 173 174/*! 175 \fn int32 BString::CountBytes(int32 fromCharOffset, int32 charCount) const 176 \brief Count the number of bytes starting from a specified character 177 178 BString is somewhat aware of UTF-8 characters, which can take up more than 179 one byte. With this method you can count the number of bytes a subset of 180 the string contains. 181 182 \warning This method does not check whether the input is outside of the 183 boundaries, so make sure that you check your input values. 184 185 \param fromCharOffset The index of the character (not the byte!) from 186 which to start the count 187 \param charCount The number of characters to count 188 189 \return An integer with the number of bytes. 190 191 \since Haiku R1 192*/ 193 194 195/*! 196 \fn bool BString::IsEmpty() const 197 \brief Check whether the string is empty. 198 199 \return Returns \c true if the string is empty. 200 201 \since Haiku R1 202*/ 203 204 205/*! 206 \fn uint32 BString::HashValue() const 207 \brief Return a hash value for the current string 208 209 \sa HashValue(const char*) 210 211 \since Haiku R1 212*/ 213 214 215/*! 216 \fn static uint32 BString::HashValue(const char* string) 217 \brief Return the hash value of a specified \c string 218 219 This allows you to use the BString::HashValue() method on any arbitrary 220 \c string. 221 222 \param string The string that you want to have hashed. 223 224 \sa HashValue() 225 226 \since Haiku R1 227*/ 228 229 230//! @} 231 232 233/*! 234 \name Assignment 235 236 To assign a string to the object, thus overriding the previous string 237 that was stored, there are different methods to use. Use one of the 238 overloaded Adopt() methods to take over data from another object. Use 239 one of the assignment operators to copy data from another object, or 240 use one of the SetTo() methods for more advanced copying. 241*/ 242 243 244//! @{ 245 246 247/*! 248 \fn BString& BString::operator=(const BString& string) 249 \brief Re-initialize the object to a copy of the data of a BString. 250 251 \param string The \a string to copy. 252 253 \return The function always returns \c *this. 254 255 \sa Adopt(BString&) 256 \sa SetTo(const BString&, int32) 257 258 \since BeOS R5 259*/ 260 261 262/*! 263 \fn BString& BString::operator=(const char* str) 264 \brief Re-initialize the BString to a copy of the data of a string. 265 266 \param str The string data to re-initialize the BString to. 267 268 \return This method always returns \c *this. 269 270 \sa SetTo(const char*, int32) 271 272 \since BeOS R5 273*/ 274 275 276/*! 277 \fn BString& BString::operator=(char c) 278 \brief Re-initialize the BString to a character. 279 280 \param c The \c char to re-initialize the BString to. 281 282 \return This method always returns \c *this. 283 284 \since BeOS R5 285*/ 286 287 288#if __cplusplus >= 201103L 289/*! 290 \fn BString& BString::operator=(BString&& string) noexcept 291 \brief Move the contents of \a string to this BString object. 292 293 The \a string will no longer point to the same contents. 294 295 \note This method is only available for modern C++ (C++11 or later). 296 297 \return This method always returns \c *this. 298 299 \since Haiku R1 300*/ 301#endif 302 303 304/*! 305 \fn BString& BString::SetTo(const char* str) 306 \brief Re-initialize the BString to a copy of the data of a string. 307 308 This method calls operator=(const char*). 309 310 \param str The string data to re-initialize the BString to. 311 312 \return This method always returns \c *this. 313 314 \sa SetTo(const char*, int32) 315 316 \since BeOS R5 317*/ 318 319 320/*! 321 \fn BString& BString::SetTo(const char* str, int32 maxLength) 322 \brief Re-initialize the BString to a copy of the data of a string. 323 324 \param str The string data to re-initialize the BString to. 325 \param maxLength Maximum number of characters (bytes) to copy. 326 327 \return This method always returns \c *this. 328 329 \sa operator=(const char*) 330 331 \since BeOS R5 332*/ 333 334 335/*! 336 \fn BString& BString::SetTo(const BString& from) 337 \brief Re-initialize the BString to a copy of the data of a BString. 338 339 \param from The string data to re-initialize the BString to. 340 341 \return The function always returns \c *this. 342 343 \sa SetTo(const BString&, int32) 344 \sa Adopt(BString&) 345 346 \since BeOS R5 347*/ 348 349 350/*! 351 \fn BString& BString::SetTo(const BString& string, int32 maxLength) 352 \brief Re-initialize the string to a copy of the given BString object. 353 354 \param string The string data to re-initialize the BString to. 355 \param maxLength Maximum number of characters (bytes) to copy. 356 357 \return The function always returns \c *this. 358 359 \sa operator=(const BString&) 360 \sa Adopt(BString&, int32) 361 362 \since BeOS R5 363*/ 364 365 366/*! 367 \fn BString& BString::Adopt(BString& from) 368 \brief Adopt the data of the given BString object. 369 370 This method adopts the data from a BString removing the data from \a from 371 and putting it into the BString. 372 373 \warning The object that is adopted from is not deleted, only its private 374 data is initialized to a \c NULL string. If the \a from object 375 was created on the heap you need to clean it up yourself. 376 377 \param from The string data to adopt. 378 379 \return The function always returns \c *this. 380 381 \sa operator=(const BString&) 382 383 \since BeOS R5 384*/ 385 386 387/*! 388 \fn BString& BString::Adopt(BString& from, int32 maxLength) 389 \brief Adopt the data of the given BString object up to \a maxLength 390 characters. 391 392 This method adopts the data from a BString removing the data from \a from 393 and putting it into the BString. 394 395 \param from The string object to adopt. 396 \param maxLength Maximum number of characters (bytes) to adopt. 397 398 \return The function always returns \c *this. 399 400 \sa SetTo(const BString&, int32) 401 402 \since BeOS R5 403*/ 404 405 406/*! 407 \fn BString& BString::SetTo(char c, int32 count) 408 \brief Re-initialize the object to a string composed of a character you 409 specify. 410 411 This method lets you specify the length of a string and what character 412 you want the string to contain repeatedly. 413 414 \param c The character you want to initialize the BString. 415 \param count The length of the string. 416 417 \return The function always returns \c *this. 418 419 \sa operator=(char c) 420 421 \since BeOS R5 422*/ 423 424 425/*! 426 \fn BString& BString::SetToChars(const char* string, int32 charCount) 427 \brief UTF-8 aware version of SetTo(const char*, int32) 428 429 \param string The \a string to copy. 430 \param charCount The number of UTF-8 characters to copy. 431 432 \see SetTo(const char*, int32) 433 434 \since Haiku R1 435*/ 436 437 438/*! 439 \fn BString& BString::SetToChars(const BString& string, int32 charCount) 440 \brief UTF-8 aware version of SetTo(BString&, int32) 441 442 \param string The \a string to copy. 443 \param charCount The number of UTF-8 characters to copy. 444 445 \see SetTo(BString&, int32) 446 447 \return This method always returns \c *this. 448 449 \since Haiku R1 450*/ 451 452 453/*! 454 \fn BString& BString::AdoptChars(BString& from, int32 charCount) 455 \brief UTF-8 aware version of Adopt(BString&, int32) 456 457 \param from The string data to start adopting from. 458 \param charCount Number of UTF-8 characters to adopt. 459 460 \return This method always returns \c *this. 461 462 \since Haiku R1 463*/ 464 465 466/*! 467 \fn BString& BString::SetToFormat(const char* format, ...) 468 \brief Sets the string to a formatted string ala <tt>sprintf()</tt>. 469 470 \param format The \a format string to use. 471 \param ... The rest of the parameters that are filled into \a format. 472 473 \return This method always returns \c *this. 474 475 \since Haiku R1 476*/ 477 478 479/*! 480 \fn BString& BString::SetToFormatVarArgs(const char* format, va_list args) 481 \brief Sets the string to a formatted string ala <tt>sprintf()</tt>. 482 483 \param format The \a format string to use. 484 \param args The rest of the parameters that are filled into \a format. 485 486 \return This method always returns \c *this. 487 488 \since Haiku R1 489*/ 490 491 492/*! 493 \fn int BString::ScanWithFormat(const char* format, ...) 494 \brief Parse a formatted string and save elements to variables ala 495 <tt>scanf()</tt>. 496 497 \param format The \a format string to use. 498 \param ... The parameters that you want to store the parsed data into. 499 500 \return This method returns the number of items that were parsed. 501 502 \since Haiku R1 503*/ 504 505 506/*! 507 \fn int BString::ScanWithFormatVarArgs(const char* format, va_list args) 508 \brief Parse a formatted string and save elements to variables ala 509 <tt>scanf()</tt>. 510 511 \param format The \a format string to use. 512 \param args The parameters that you want to store the parsed data into. 513 514 \return This method returns the number of items that were parsed. 515 516 \since Haiku R1 517*/ 518 519 520//! @} 521 522 523/*! 524 \name Substring Copying 525*/ 526 527 528//! @{ 529 530 531/*! 532 \fn BString& BString::CopyInto(BString& into, int32 fromOffset, 533 int32 length) const 534 \brief Copy the object's data (or part of it) into another BString. 535 536 This methods makes sure you don't copy more bytes than are available 537 in the string. If the length exceeds the length of the string, it only 538 copies the number of characters that are actually available. 539 540 \param into The BString to copy into. 541 \param fromOffset The (zero-based) offset where to begin the copy. 542 \param length The number of bytes to copy. 543 544 \return This method always returns a pointer to the string passed as the 545 \c into parameter. 546 547 \since BeOS R5 548*/ 549 550 551/*! 552 \fn void BString::CopyInto(char* into, int32 fromOffset, int32 length) const 553 \brief Copy the BString data (or part of it) into the supplied buffer. 554 555 This methods makes sure you don't copy more bytes than are available 556 in the string. If the length exceeds the length of the string, it only 557 copies the number of characters that are actually available. 558 559 It's up to you to make sure your buffer is large enough. 560 561 \param into The buffer where to copy the object. 562 \param fromOffset The (zero-based) offset where to begin the copy. 563 \param length The number of bytes to copy. 564 565 \since BeOS R5 566*/ 567 568 569/*! 570 \fn BString& BString::CopyCharsInto(BString& into, int32 fromOffset, 571 int32 charCount) const 572 \brief UTF-8 aware version of CopyInto(BString&, int32, int32) const. 573 574 \param into The BString to copy into. 575 \param fromOffset The (zero-based) offset in bytes where to begin the copy. 576 \param charCount The number of UTF-8 characters to copy. 577 578 \return This method always returns a pointer to the string passed as the 579 \c into parameter. 580 581 \see CopyInto(BString&, int32, int32) const 582 583 \since Haiku R1 584*/ 585 586 587/*! 588 \fn bool BString::CopyCharsInto(char* into, int32* intoLength, 589 int32 fromCharOffset, int32 charCount) const 590 \brief UTF-8 aware version of CopyInto(char*, int32, int32) const. 591 592 \param into The buffer where to copy the object. 593 \param intoLength The length of \a into in bytes. 594 \param fromCharOffset The (zero-based) offset UTF-8 characters where to 595 begin the copy. 596 \param charCount The number of UTF-8 characters to copy. 597 598 \see CopyInto(char*, int32, int32) const 599 600 \return \c false if \a into was \c NULL, \c true otherwise. 601 602 \since Haiku R1 603*/ 604 605 606/*! 607 \fn bool BString::Split(const char* separator, bool noEmptyStrings, 608 BStringList& _list) const 609 \brief Split the string by the \a separator chars into \a _list. 610 611 \param separator The list of \a separator characters to split on. 612 \param noEmptyStrings If \c true, do not add empty strings to \a _list. 613 \param _list The BStringList to add the strings into. 614 615 \since Haiku R1 616*/ 617 618 619//! @} 620 621 622/*! 623 \name Appending 624*/ 625 626 627//! @{ 628 629 630/*! 631 \fn BString& BString::operator+=(const BString& string) 632 \brief Append the given \a string to the end of the BString 633 634 \param string The string to append. 635 636 \return This method always returns \c *this. 637 638 \sa Append(const BString&, int32) 639 640 \since BeOS R5 641*/ 642 643 644/*! 645 \fn BString& BString::operator+=(const char* str) 646 \brief Append the given string to the end of the BString. 647 648 \param str A pointer to the NULL-terminated string to append. 649 650 \return This method always returns \c *this. 651 652 \sa Append(const char*, int32) 653 654 \since BeOS R5 655*/ 656 657 658/*! 659 \fn BString& BString::operator+=(char c) 660 \brief Append the given character to the end of the BString. 661 662 \param c The character to append. 663 664 \return This method always returns \c *this. 665 666 \sa Append(char, int32) 667*/ 668 669 670/*! 671 \fn BString& BString::Append(const BString& string) 672 \brief Append the given \a string to the end of the BString. 673 674 \param string The string to append. 675 676 \return This method always returns \c *this. 677 678 \sa Append(const BString&, int32) 679 680 \since BeOS R5 681*/ 682 683 684/*! 685 \fn BString& BString::Append(const char* str) 686 \brief Append the string data to the end of the BString. 687 688 This method calls operator+=(const char *str). 689 690 \sa Append(const char*, int32) 691 692 \since BeOS R5 693*/ 694 695 696/*! 697 \fn BString& BString::Append(const BString& string, int32 length) 698 \brief Append a part of the given \a string to the end of the BString. 699 700 \param string The BString to append. 701 \param length The maximum number of bytes to append. 702 703 \return This method always returns \c *this. 704 705 \sa operator+=(const BString&) 706 707 \since BeOS R5 708*/ 709 710 711/*! 712 \fn BString& BString::Append(const char* str, int32 length) 713 \brief Append a part of the given string to end of the BString. 714 715 \param str A pointer to the string to append. 716 \param length The maximum number of bytes to append. 717 718 \return This method always returns \c *this. 719 720 \sa operator+=(const char*) 721 722 \since BeOS R5 723*/ 724 725 726/*! 727 \fn BString& BString::Append(char c, int32 count) 728 \brief Append the given character repeatedly to the end of the BString. 729 730 \param c The character to append. 731 \param count The number of times this character should be appended. 732 733 \return This method always returns \c *this. 734 735 \sa operator+=(char c) 736 737 \since BeOS R5 738*/ 739 740 741/*! 742 \fn BString& BString::AppendChars(const BString& string, int32 charCount) 743 \brief UTF-8 aware version of Append(const BString&, int32). 744 745 \param string The \a string to append. 746 \param charCount The maximum number of UTF-8 characters to append. 747 748 \return This method always returns \c *this. 749 750 \see Append(const BString&, int32) 751 752 \since Haiku R1 753*/ 754 755 756/*! 757 \fn BString& BString::AppendChars(const char* string, int32 charCount) 758 \brief UTF-8 aware version of Append(const char*, int32). 759 760 \param string The \a string to append. 761 \param charCount The maximum number of UTF-8 characters to append. 762 763 \return This method always returns \c *this. 764 765 \see Append(const char*, int32) 766 767 \since Haiku R1 768*/ 769 770 771//! @} 772 773 774/*! 775 \name Prepending 776*/ 777 778 779//! @{ 780 781 782/*! 783 \fn BString& BString::Prepend(const char* str) 784 \brief Prepend the given string to the beginning of the BString. 785 786 \param str The \a string to prepend. 787 788 \return This method always returns \c *this. 789 790 \sa Prepend(const char*, int32) 791 792 \since BeOS R5 793*/ 794 795 796/*! 797 \fn BString& BString::Prepend(const BString& string) 798 \brief Prepend the given BString to the beginning of the BString. 799 800 \param string The \a string to prepend. 801 802 \return This method always returns \c *this. 803 804 \sa Prepend(const BString&, int32) 805 806 \since BeOS R5 807*/ 808 809 810/*! 811 \fn BString& BString::Prepend(const char* str, int32 length) 812 \brief Prepend the given string to the beginning of the BString. 813 814 \param str The \a string to prepend. 815 \param length The maximum number of bytes to prepend. 816 817 \return This method always returns \c *this. 818 819 \sa Prepend(const char*) 820 821 \since BeOS R5 822*/ 823 824 825/*! 826 \fn BString& BString::Prepend(const BString& string, int32 length) 827 \brief Prepend the given BString to the beginning of the BString. 828 829 \param string The \a string to prepend. 830 \param length The maximum number of bytes to prepend. 831 832 \return This method always returns \c *this. 833 834 \sa Prepend(const BString&) 835 836 \since BeOS R5 837*/ 838 839 840/*! 841 \fn BString& BString::Prepend(char c, int32 count) 842 \brief Prepend the given character \a count times to the beginning of the 843 BString. 844 845 \param c The character to prepend. 846 \param count The number of times this character should be prepended. 847 848 \return This method always returns \c *this. 849 850 \since BeOS R5 851*/ 852 853 854/*! 855 \fn BString& BString::PrependChars(const char* string, int32 charCount) 856 \brief UTF-8 aware version of Prepend(const char*, int32). 857 858 \param string The \a string to prepend. 859 \param charCount The maximum number of UTF-8 characters to prepend. 860 861 \return This method always returns \c *this. 862 863 \see Prepend(const char*, int32) 864 865 \since Haiku R1 866*/ 867 868 869/*! 870 \fn BString& BString::PrependChars(const BString& string, int32 charCount) 871 \brief UTF-8 aware version of Prepend(const BString&, int32). 872 873 \param string The \a string to prepend. 874 \param charCount The maximum number of UTF-8 characters to prepend. 875 876 \return This method always returns \c *this. 877 878 \see Prepend(const BString&, int32) 879 880 \since Haiku R1 881*/ 882 883 884//! @} 885 886 887/*! 888 \name Inserting 889*/ 890 891 892//! @{ 893 894 895/*! 896 \fn BString& BString::Insert(const char* string, int32 position) 897 \brief Inserts the given string at the given position into the BString 898 data. 899 900 \param string The \a string to insert. 901 \param position The offset in bytes where to insert the \a string into 902 the BString's data. 903 904 \return This method always returns \c *this. 905 906 \sa Insert(const char*, int32, int32) 907 \sa Insert(const char*, int32, int32, int32) 908 909 \since BeOS R5 910*/ 911 912 913/*! 914 \fn BString& BString::Insert(const char* string, int32 length, 915 int32 position) 916 \brief Inserts the given string at the given position into the BString 917 data. 918 919 \param string The \a string to insert. 920 \param length The number of bytes to insert. 921 \param position The offset in bytes into the data of the BString where to 922 insert the string. 923 924 \return This method always returns \c *this. 925 926 \sa Insert(const char*, int32) 927 \sa Insert(const char*, int32, int32, int32) 928 929 \since BeOS R5 930*/ 931 932 933/*! 934 \fn BString& BString::Insert(const char* string, int32 fromOffset, 935 int32 length, int32 position) 936 \brief Inserts the given string at the given position into the BString 937 data. 938 939 \param string The \a string to insert. 940 \param fromOffset The offset in bytes in the \a string to be inserted. 941 \param length The number of bytes to insert. 942 \param position The offset in bytes into the data of the BString where to 943 insert the string. 944 945 \return This method always returns \c *this. 946 947 \sa Insert(const char*, int32) 948 \sa Insert(const char*, int32, int32) 949 950 \since BeOS R5 951*/ 952 953 954/*! 955 \fn BString& BString::Insert(const BString& string, int32 position) 956 \brief Inserts the given BString at the given position into the BString 957 data. 958 959 \param string The \a string to insert. 960 \param position The offset in bytes into the data of the BString where to 961 insert the string. 962 963 \return This method always returns \c *this. 964 965 \sa Insert(const BString&, int32, int32) 966 \sa Insert(const BString&, int32, int32, int32) 967 968 \since BeOS R5 969*/ 970 971 972/*! 973 \fn BString& BString::Insert(const BString& string, int32 length, int32 position) 974 \brief Inserts the given BString at the given position into the BString 975 data. 976 977 \param string The \a string to insert. 978 \param length The number of bytes to insert. 979 \param position The offset in bytes into the data of the BString where to 980 insert the string. 981 982 \return This method always returns \c *this. 983 984 \sa Insert(const BString&, int32) 985 \sa Insert(const BString&, int32, int32, int32) 986 987 \since BeOS R5 988*/ 989 990 991/*! 992 \fn BString& BString::Insert(const BString& string, int32 fromOffset, 993 int32 length, int32 position) 994 \brief Inserts the given string at the given position into the BString 995 data. 996 997 \param string The \a string to insert. 998 \param fromOffset The offset in bytes of the string to be inserted. 999 \param length The amount of bytes to insert. 1000 \param position The offset in bytes into the data of the BString where to 1001 insert the string. 1002 1003 \return This method always returns \c *this. 1004 1005 \sa Insert(const BString&, int32) 1006 \sa Insert(const BString&, int32, int32) 1007 1008 \since BeOS R5 1009*/ 1010 1011 1012/*! 1013 \fn BString& BString::Insert(char c, int32 count, int32 pos) 1014 \brief Inserts the given character repeatedly at the given position 1015 into the BString data. 1016 1017 \param c The character to insert. 1018 \param count The number of times to insert the character. 1019 \param pos The offset in bytes into the data of the BString where to 1020 insert the string. 1021 1022 \return This method always returns \c *this. 1023 1024 \since BeOS R5 1025*/ 1026 1027 1028/*! 1029 \fn BString& BString::InsertChars(const char* string, int32 charPosition) 1030 \brief UTF-8 aware version of Insert(const char*, int32). 1031 1032 \param string The \a string to insert. 1033 \param charPosition The offset in UTF-8 characters where to insert 1034 the string into the data of the BString. 1035 1036 \return This method always returns \c *this. 1037 1038 \see Insert(const char*, int32) 1039 1040 \since Haiku R1 1041*/ 1042 1043 1044/*! 1045 \fn BString& BString::InsertChars(const char* string, int32 charCount, 1046 int32 charPosition) 1047 \brief UTF-8 aware version of Insert(const char*, int32, int32). 1048 1049 \param string The \a string to insert. 1050 \param charCount The number of UTF-8 characters to insert. 1051 \param charPosition The offset in UTF-8 characters where to insert 1052 the string into the data of the BString. 1053 1054 \return This method always returns \c *this. 1055 1056 \see Insert(const char*, int32, int32) 1057 1058 \since Haiku R1 1059*/ 1060 1061 1062/*! 1063 \fn BString& BString::InsertChars(const char* string, int32 fromCharOffset, 1064 int32 charCount, int32 charPosition) 1065 \brief UTF-8 aware version of Insert(const char*, int32, int32, int32). 1066 1067 \param string The \a string to insert. 1068 \param fromCharOffset The offset in UTF-8 characters of the string to be 1069 inserted. 1070 \param charCount The number of UTF-8 characters to insert. 1071 \param charPosition The offset in UTF-8 characters where to insert 1072 the string into the data of the BString. 1073 1074 \return This method always returns \c *this. 1075 1076 \see Insert(const char*, int32, int32, int32) 1077 1078 \since Haiku R1 1079*/ 1080 1081 1082/*! 1083 \fn BString& BString::InsertChars(const BString& string, int32 charPosition) 1084 \brief UTF-8 aware version of Insert(const BString&, int32). 1085 1086 \param string The \a string to insert. 1087 \param charPosition The offset in UTF-8 characters where to insert 1088 the string into the data of the BString. 1089 1090 \return This method always returns \c *this. 1091 1092 \see Insert(const BString&, int32) 1093 1094 \since Haiku R1 1095*/ 1096 1097 1098/*! 1099 \fn BString& BString::InsertChars(const BString& string, int32 charCount, 1100 int32 charPosition) 1101 \brief UTF-8 aware version of Insert(const BString&, int32, int32). 1102 1103 \param string The \a string to insert. 1104 \param charCount The number of UTF-8 characters to insert. 1105 \param charPosition The offset in UTF-8 characters where to insert 1106 the string into the data of the BString. 1107 1108 \return This method always returns \c *this. 1109 1110 \see Insert(const BString&, int32, int32) 1111 1112 \since Haiku R1 1113*/ 1114 1115 1116/*! 1117 \fn BString& BString::InsertChars(const BString& string, int32 fromCharOffset, 1118 int32 charCount, int32 charPosition) 1119 \brief UTF-8 aware version of Insert(const BString&, int32, int32, int32). 1120 1121 \param string The \a string to insert. 1122 \param fromCharOffset The offset in UTF-8 characters of the string to be 1123 inserted. 1124 \param charCount The number of UTF-8 characters to insert. 1125 \param charPosition The offset in UTF-8 characters where to insert 1126 the string into the data of the BString. 1127 1128 \return This method always returns \c *this. 1129 1130 \see Insert(const BString&, int32, int32, int32) 1131 1132 \since Haiku R1 1133*/ 1134 1135 1136//! @} 1137 1138 1139/*! 1140 \name Removing 1141*/ 1142 1143 1144//! @{ 1145 1146 1147/*! 1148 \fn BString& BString::Trim() 1149 \brief Removes spaces from the beginning and end of the string. 1150 1151 The definition of a space is set by the <tt>isspace()</tt> function. 1152 1153 \return This method always returns \c *this. 1154 1155 \since Haiku R1 1156*/ 1157 1158 1159 1160/*! 1161 \fn BString& BString::Truncate(int32 newLength, bool lazy) 1162 \brief Truncate the string to the new length. 1163 1164 \param newLength The new length of the string in bytes. 1165 \param lazy If true, the memory-optimization is postponed until later. 1166 1167 \return This method always returns \c *this. 1168 1169 \since BeOS R5 1170*/ 1171 1172 1173/*! 1174 \fn BString& BString::TruncateChars(int32 newCharCount, bool lazy) 1175 \brief UTF-8 aware version of Truncate(int32, bool). 1176 1177 \param newCharCount The new length of the string in UTF-8 characters. 1178 \param lazy If true, the memory-optimization is postponed until later. 1179 1180 \see Truncate(int32, bool) 1181 1182 \since Haiku R1 1183*/ 1184 1185 1186/*! 1187 \fn BString& BString::Remove(int32 from, int32 length) 1188 \brief Remove some bytes, starting at the given offset 1189 1190 \param from The offset in bytes to start removing. 1191 \param length The number of bytes to remove. 1192 1193 \return This function always returns \c *this. 1194 1195 \since BeOS R5 1196*/ 1197 1198 1199/*! 1200 \fn BString& BString::RemoveChars(int32 fromCharOffset, int32 charCount) 1201 \brief UTF-8 aware version of Remove(int32, int32). 1202 1203 \param fromCharOffset The offset in UTF-8 characters to start removing. 1204 \param charCount The number of UTF-8 characters to remove. 1205 1206 \return This function always returns \c *this. 1207 1208 \see Remove(int32, int32) 1209 1210 \since Haiku R1 1211*/ 1212 1213 1214/*! 1215 \fn BString& BString::RemoveFirst(const BString& string) 1216 \brief Remove the first occurrence of the given BString. 1217 1218 \param string The BString to remove. 1219 1220 \return This function always returns \c *this. 1221 1222 \since BeOS R5 1223*/ 1224 1225 1226/*! 1227 \fn BString& BString::RemoveLast(const BString& string) 1228 \brief Remove the last occurrence of the given BString. 1229 1230 \param string The BString to remove. 1231 1232 \return This function always returns \c *this. 1233 1234 \since BeOS R5 1235*/ 1236 1237 1238/*! 1239 \fn BString& BString::RemoveAll(const BString& string) 1240 \brief Remove all occurrences of the given BString. 1241 1242 \param string The BString to remove. 1243 1244 \return This function always returns \c *this. 1245 1246 \since BeOS R5 1247*/ 1248 1249 1250/*! 1251 \fn BString& BString::RemoveFirst(const char* string) 1252 \brief Remove the first occurrence of the given string. 1253 1254 \param string A pointer to the string to remove. 1255 1256 \return This function always returns \c *this. 1257 1258 \since BeOS R5 1259*/ 1260 1261 1262/*! 1263 \fn BString& BString::RemoveLast(const char* string) 1264 \brief Remove the last occurrence of the given string. 1265 1266 \param string A pointer to the string to remove. 1267 1268 \return This function always returns \c *this. 1269 1270 \since BeOS R5 1271*/ 1272 1273 1274/*! 1275 \fn BString& BString::RemoveAll(const char* str) 1276 \brief Remove all occurrences of the given string. 1277 1278 \param str A pointer to the string to remove. 1279 1280 \return This function always returns \c *this. 1281 1282 \since BeOS R5 1283*/ 1284 1285 1286/*! 1287 \fn BString& BString::RemoveSet(const char* setOfCharsToRemove) 1288 \brief Remove all the characters specified. 1289 1290 \param setOfCharsToRemove The set of characters to remove. 1291 1292 \return This function always returns \c *this. 1293 1294 \since BeOS R5 1295*/ 1296 1297 1298/*! 1299 \fn BString& BString::RemoveCharsSet(const char* setOfCharsToRemove) 1300 \brief UTF-8 aware version of RemoveSet(const char*). 1301 1302 \param setOfCharsToRemove The set of characters to remove. 1303 1304 \return This function always returns \c *this. 1305 1306 \see RemoveSet(const char*) 1307 1308 \since Haiku R1 1309*/ 1310 1311 1312/*! 1313 \fn BString& BString::MoveInto(BString& into, int32 from, int32 length) 1314 \brief Move the BString data (or part of it) into another BString. 1315 1316 \param into The BString to move the string into. 1317 \param from The offset (zero-based) in bytes where to begin the move. 1318 \param length The number of bytes to move. 1319 1320 \return This method always returns \c into. 1321 1322 \since BeOS R5 1323*/ 1324 1325 1326/*! 1327 \fn void BString::MoveInto(char* into, int32 from, int32 length) 1328 \brief Move the BString data (or part of it) into the given buffer. 1329 1330 \param into The buffer to move the string into. 1331 \param from The offset (zero-based) in bytes where to begin the move. 1332 \param length The number of bytes to move. 1333 1334 \since BeOS R5 1335*/ 1336 1337 1338/*! 1339 \fn BString& BString::MoveCharsInto(BString& into, int32 fromCharOffset, 1340 int32 charCount) 1341 \brief UTF-8 aware version of MoveInto(BString&, int32, int32) 1342 1343 \param into The BString where to move the string into. 1344 \param fromCharOffset The offset (zero-based) in UTF-8 characters where to 1345 begin the move. 1346 \param charCount The number of UTF-8 characters to move. 1347 1348 \see MoveInto(BString&, int32, int32) 1349 1350 \since Haiku R1 1351*/ 1352 1353 1354/*! 1355 \fn bool BString::MoveCharsInto(char* into, int32* intoLength, 1356 int32 fromCharOffset, int32 charCount) 1357 \brief UTF-8 aware version of MoveInto(char*, int32*, int32, int32). 1358 1359 \param into The buffer to move the string into. 1360 \param intoLength The offset (zero-based) in bytes where to begin the move. 1361 \param fromCharOffset The offset (zero-based) in UTF-8 characters where to 1362 begin the move. 1363 \param charCount The number of UTF-8 characters to move. 1364 1365 \returns \c false if \a into was \c NULL, \c true otherwise. 1366 1367 \see MoveInto(char*, int32*, int32, int32) 1368 1369 \since Haiku R1 1370*/ 1371 1372 1373//! @} 1374 1375 1376/*! 1377 \name Comparison 1378 1379 There are two different comparison methods. First of all there 1380 is the whole range of operators that return a boolean value, secondly 1381 there are methods that return an integer value, both case sensitive 1382 and case insensitive. 1383 1384 There are also global comparison operators and global compare functions. 1385 You might need these in case you have a sort routine that takes a generic 1386 comparison function, such as BList::SortItems(). 1387 See the String.h documentation file to see the specifics, though basically 1388 there are the same as implemented in this class. 1389*/ 1390 1391 1392//! @{ 1393 1394 1395/*! 1396 \fn bool BString::operator<(const BString& string) const 1397 \brief Lexicographically compare if this BString is less than the given 1398 \a string. 1399 1400 \param string The \a string to compare against. 1401 1402 \since BeOS R5 1403*/ 1404 1405 1406/*! 1407 \fn bool BString::operator<=(const BString& string) const 1408 \brief Lexicographically compare if this BString is less than or equal to 1409 the given \a string. 1410 1411 \param string The \a string to compare against. 1412 1413 \since BeOS R5 1414*/ 1415 1416 1417/*! 1418 \fn bool BString::operator==(const BString& string) const 1419 \brief Lexicographically compare if this BString is equal to the given 1420 \a string. 1421 1422 \param string The \a string to compare against. 1423 1424 \since BeOS R5 1425*/ 1426 1427 1428/*! 1429 \fn bool BString::operator>=(const BString& string) const 1430 \brief Lexicographically compare if this BString is greater than or equal 1431 to the given \a string. 1432 1433 \param string The string to compare against. 1434 1435 \since BeOS R5 1436*/ 1437 1438 1439/*! 1440 \fn bool BString::operator>(const BString& string) const 1441 \brief Lexicographically compare if this BString is greater than the given 1442 \a string. 1443 1444 \param string The string to compare against. 1445 1446 \since BeOS R5 1447*/ 1448 1449 1450/*! 1451 \fn bool BString::operator!=(const BString& string) const 1452 \brief Lexicographically compare if this BString is not equal to the given 1453 \a string. 1454 1455 \param string The string to compare against. 1456 1457 \since BeOS R5 1458*/ 1459 1460 1461/*! 1462 \fn bool BString::operator<(const char* string) const 1463 \brief Lexicographically compare if this BString is less than the given 1464 \a string. 1465 1466 \param string The string to compare against. 1467 1468 \since BeOS R5 1469*/ 1470 1471 1472/*! 1473 \fn bool BString::operator<=(const char* string) const 1474 \brief Lexicographically compare if this BString is less than or equal to 1475 the given \a string. 1476 1477 \param string The \a string to compare against. 1478 1479 \since BeOS R5 1480*/ 1481 1482 1483/*! 1484 \fn bool BString::operator==(const char* string) const 1485 \brief Lexicographically compare if this BString is equal to the given 1486 \a string. 1487 1488 \param string The \a string to compare against. 1489 1490 \since BeOS R5 1491*/ 1492 1493 1494/*! 1495 \fn bool BString::operator>=(const char* string) const 1496 \brief Lexicographically compare if this string is more than or equal 1497 to a given \a string. 1498 1499 \param string The \a string to compare against. 1500 1501 \since BeOS R5 1502*/ 1503 1504 1505/*! 1506 \fn bool BString::operator>(const char* string) const 1507 \brief Lexicographically compare if this string is more than a given string. 1508 1509 \param string The \a string to compare against. 1510 1511 \since BeOS R5 1512*/ 1513 1514 1515/*! 1516 \fn bool BString::operator!=(const char* string) const 1517 \brief Lexicographically compare if this string is not equal to a given 1518 string. 1519 1520 \param string The \a string to compare against. 1521 1522 \since BeOS R5 1523*/ 1524 1525 1526/*! 1527 \fn BString::operator const char*() const 1528 \brief Return an empty string. 1529 1530 \return An empty string. 1531 1532 \since Haiku R1 1533*/ 1534 1535 1536/*! 1537 \fn int BString::Compare(const BString& string) const 1538 \brief Lexicographically compare this BString to another \a string. 1539 1540 \param string The \a string to compare against. 1541 1542 \return An int representing the strings relationship to each other. 1543 \retval >0 The BString sorts lexicographically after \a string. 1544 \retval =0 The BString is equal to \a string. 1545 \retval <0 The BString sorts lexicographically before \a string. 1546 1547 \since BeOS R5 1548*/ 1549 1550 1551/*! 1552 \fn int BString::Compare(const char* string) const 1553 \brief Lexicographically compare this BString to another \a string. 1554 1555 \param string The \a string to compare against. 1556 1557 \return An int representing the strings relationship to each other. 1558 \retval >0 The BString sorts lexicographically after \a string. 1559 \retval =0 The BString is equal to \a string. 1560 \retval <0 The BString sorts lexicographically before \a string. 1561 1562 \sa Compare(const BString&) const 1563 1564 \since BeOS R5 1565*/ 1566 1567 1568/*! 1569 \fn int BString::Compare(const BString& string, int32 length) const 1570 \brief Lexicographically compare \a length characters of this BString to 1571 another \a string. 1572 1573 \param string The \a string to compare against. 1574 \param length The number of bytes to compare. 1575 1576 \return An int representing the strings relationship to each other. 1577 \retval >0 The BString sorts lexicographically after \a string. 1578 \retval =0 The BString is equal to \a string. 1579 \retval <0 The BString sorts lexicographically before \a string. 1580 1581 \since BeOS R5 1582*/ 1583 1584 1585/*! 1586 \fn int BString::Compare(const char* string, int32 length) const 1587 \brief Lexicographically compare \a length characters of this BString to 1588 another \a string. 1589 1590 \param string The \a string to compare against. 1591 \param length The number of bytes to compare. 1592 1593 \return An int representing the strings relationship to each other. 1594 \retval >0 The BString sorts lexicographically after \a string. 1595 \retval =0 The BString is equal to \a string. 1596 \retval <0 The BString sorts lexicographically before \a string. 1597 1598 \sa Compare(const BString&, int32) const 1599 1600 \since BeOS R5 1601*/ 1602 1603 1604/*! 1605 \fn int BString::CompareAt(size_t offset, const BString& string, 1606 int32 length) const 1607 \brief Lexicographically compare \a length of characters of this BString to 1608 another \a string, starting at \a offset. 1609 1610 \param offset The offset (in bytes) to start comparison. 1611 \param string The \a string to compare against. 1612 \param length The number of bytes to compare. 1613 1614 \return An int representing the strings relationship to each other. 1615 \retval >0 The BString sorts lexicographically after \a string. 1616 \retval =0 The BString is equal to \a string. 1617 \retval <0 The BString sorts lexicographically before \a string. 1618 1619 \sa Compare(const BString&, int32) const 1620 1621 \since Haiku R1 1622*/ 1623 1624 1625/*! 1626 \fn int BString::CompareChars(const BString& string, int32 charCount) const 1627 \brief UTF-8 aware version of Compare(const BString&, int32). 1628 1629 \param string The \a string to compare against. 1630 \param charCount The number of UTF-8 characters to compare. 1631 1632 \return An int representing the strings relationship to each other. 1633 \retval >0 The BString sorts lexicographically after \a string. 1634 \retval =0 The BString is equal to \a string. 1635 \retval <0 The BString sorts lexicographically before \a string. 1636 1637 \see Compare(const BString&, int32) 1638 1639 \since Haiku R1 1640*/ 1641 1642 1643/*! 1644 \fn int BString::CompareChars(const char* string, int32 charCount) const 1645 \brief UTF-8 aware version of Compare(const char*, int32). 1646 1647 \param string The \a string to compare against. 1648 \param charCount The number of UTF-8 characters to compare. 1649 1650 \return An int representing the strings relationship to each other. 1651 \retval >0 The BString sorts lexicographically after \a string. 1652 \retval =0 The BString is equal to \a string. 1653 \retval <0 The BString sorts lexicographically before \a string. 1654 1655 \see Compare(const char*, int32) 1656 1657 \since Haiku R1 1658*/ 1659 1660 1661/*! 1662 \fn int BString::ICompare(const BString& string) const 1663 \brief Lexicographically compare this BString to another \a string 1664 case-insensitively. 1665 1666 \param string The \a string to compare against. 1667 1668 \return An int representing the strings relationship to each other. 1669 \retval >0 The BString sorts lexicographically after \a string. 1670 \retval =0 The BString is equal to \a string. 1671 \retval <0 The BString sorts lexicographically before \a string. 1672 1673 \sa Compare(const BString&) const 1674 1675 \since BeOS R5 1676*/ 1677 1678 1679/*! 1680 \fn int BString::ICompare(const char* string) const 1681 \brief Lexicographically compare this BString to another \a string 1682 case-insensitively. 1683 1684 \param string The \a string to compare against. 1685 1686 \return An int representing the strings relationship to each other. 1687 \retval >0 The BString sorts lexicographically after \a string. 1688 \retval =0 The BString is equal to \a string. 1689 \retval <0 The BString sorts lexicographically before \a string. 1690 1691 \sa Compare(const BString&) const 1692 1693 \since BeOS R5 1694*/ 1695 1696 1697/*! 1698 \fn int BString::ICompare(const BString& string, int32 length) const 1699 \brief Lexicographically compare \a length characters of this BString 1700 to another \a string. 1701 1702 \param string The \a string to compare against. 1703 \param length The number of characters to compare. 1704 1705 \return An int representing the strings relationship to each other. 1706 \retval >0 The BString sorts lexicographically after \a string. 1707 \retval =0 The BString is equal to \a string. 1708 \retval <0 The BString sorts lexicographically before \a string. 1709 1710 \sa Compare(const BString&, int32) const 1711 1712 \since BeOS R5 1713*/ 1714 1715 1716/*! 1717 \fn int BString::ICompare(const char* string, int32 length) const 1718 \brief Lexicographically compare \a length characters of this BString 1719 to another \a string. 1720 1721 \param string The \a string to compare against. 1722 \param length The number of characters to compare 1723 1724 \return An int representing the strings relationship to each other. 1725 \retval >0 The BString sorts lexicographically after \a string. 1726 \retval =0 The BString is equal to \a string. 1727 \retval <0 The BString sorts lexicographically before \a string. 1728 1729 \sa Compare(const BString&, int32) const 1730 1731 \since BeOS R5 1732*/ 1733 1734 1735//! @} 1736 1737 1738/*! 1739 \name Searching 1740*/ 1741 1742 1743//! @{ 1744 1745 1746/*! 1747 \fn int32 BString::FindFirst(const BString& string) const 1748 \brief Find the first occurrence of the given \a string. 1749 1750 \param string The \a string to search for. 1751 1752 \return The offset (zero-based) into the data where the given BString 1753 was found or \c B_ERROR if we could not find \c string. 1754 1755 \sa IFindFirst(const BString&) const 1756 1757 \since BeOS R5 1758*/ 1759 1760 1761/*! 1762 \fn int32 BString::FindFirst(const char* string) const 1763 \brief Find the first occurrence of the given \a string. 1764 1765 \param string The \a string to search for. 1766 1767 \return The offset (zero-based) into the data where the given string 1768 was found, \c B_BAD_VALUE if the \c string pointer is invalid, 1769 or \c B_ERROR if we could not find \c string. 1770 1771 \sa IFindFirst(const char*) const 1772 \sa StartsWith(const char*) const 1773 \sa StartsWith(const char*, int32) const 1774 1775 \since BeOS R5 1776*/ 1777 1778 1779/*! 1780 \fn int32 BString::FindFirst(const BString& string, int32 fromOffset) const 1781 \brief Find the first occurrence of the given \a string starting from 1782 the given offset. 1783 1784 \param string The \a string to search for. 1785 \param fromOffset The offset in bytes to start the search. 1786 1787 \return An integer which is the offset (zero-based) into the data 1788 where the given BString was found or \c B_ERROR if we could 1789 not find the \c string. 1790 1791 \sa IFindFirst(const BString&, int32) const 1792 \sa StartsWith(const char*, int32) const 1793 1794 \since BeOS R5 1795*/ 1796 1797 1798/*! 1799 \fn int32 BString::FindFirst(const char* string, int32 fromOffset) const 1800 \brief Find the first occurrence of the given \a string, starting from the 1801 given offset. 1802 1803 \param string The \a string to search for. 1804 \param fromOffset The offset in bytes to start the search. 1805 1806 \return The offset (zero-based) into the data where the given string 1807 was found, \c B_BAD_VALUE if the \c string pointer is invalid, 1808 or \c B_ERROR if we could not find the \c string. 1809 1810 \sa IFindFirst(const char*, int32) const 1811 1812 \since BeOS R5 1813*/ 1814 1815 1816/*! 1817 \fn int32 BString::FindFirst(char c) const 1818 \brief Find the first occurrence of the given character. 1819 1820 \param c The character to search for. 1821 1822 \return The offset (zero-based) into the data where the given character 1823 was found, or \c B_ERROR if we could not find the character. 1824 1825 \since BeOS R5 1826*/ 1827 1828 1829/*! 1830 \fn int32 BString::FindFirst(char c, int32 fromOffset) const 1831 \brief Find the first occurrence of the given character, starting from the 1832 given offset. 1833 1834 \param c The character to search for. 1835 \param fromOffset The offset where to start the search. 1836 1837 \return The offset (zero-based) into the data where the given character 1838 was found, or \c B_ERROR if we could not find the character. 1839 1840 \since BeOS R5 1841*/ 1842 1843 1844/*! 1845 \fn int32 BString::FindFirstChars(const BString& string, 1846 int32 fromCharOffset) const 1847 \brief UTF-8 aware version of FindFirst(const BString&, int32). 1848 1849 \param string The \a string to search for. 1850 \param fromCharOffset The offset in UTF-8 characters to start the search. 1851 1852 \return An integer which is the offset (zero-based) into the data 1853 where the given BString was found or \c B_ERROR if we could 1854 not find the \c string. 1855 1856 \see FindFirst(const BString&, int32) 1857 1858 \since Haiku R1 1859*/ 1860 1861 1862/*! 1863 \fn int32 BString::FindFirstChars(const char* string, 1864 int32 fromCharOffset) const 1865 \brief UTF-8 aware version of FindFirst(const char*, int32). 1866 1867 \param string The \a string to search for. 1868 \param fromCharOffset The offset in UTF-8 characters to start the search. 1869 1870 \see FindChars(const char*, int32) 1871 1872 \since Haiku R1 1873*/ 1874 1875 1876/*! 1877 \fn int32 BString::FindLast(const BString& string) const 1878 \brief Find the last occurrence of the given \a string. 1879 1880 \param string The \a string to search for. 1881 1882 \return The offset (zero-based) into the data where the given BString 1883 was found, or \c B_ERROR if we could not find the \c string. 1884 1885 \sa IFindLast(const BString&) const 1886 \sa EndsWith(const BString&) const 1887 1888 \since BeOS R5 1889*/ 1890 1891 1892/*! 1893 \fn int32 BString::FindLast(const char* string) const 1894 \brief Find the last occurrence of the given string. 1895 1896 \param string The string to search for. 1897 1898 \return The offset in bytes (zero-based) into the data where the given 1899 string was found, \c B_BAD_VALUE if the \c string pointer is invalid, 1900 or \c B_ERROR if we could not find the \c string. 1901 1902 \sa IFindLast(const char*) const 1903 \sa EndsWith(const char*) const 1904 \sa EndsWith(const char*, int32) const 1905 1906 \since BeOS R5 1907*/ 1908 1909 1910/*! 1911 \fn int32 BString::FindLast(const BString& string, int32 beforeOffset) const 1912 \brief Find the last occurrence of the given BString, 1913 starting from the given offset, and going backwards. 1914 1915 \param string The BString to search for. 1916 \param beforeOffset The offset in bytes to start the search. 1917 1918 \return The offset (zero-based) into the data where the given BString 1919 was found, or \c B_ERROR if we could not find the \c string. 1920 1921 \sa IFindLast(const BString&, int32) const 1922 1923 \since BeOS R5 1924*/ 1925 1926 1927/*! 1928 \fn int32 BString::FindLast(const char* string, int32 beforeOffset) const 1929 \brief Find the last occurrence of the given string, 1930 starting from the given offset, and going backwards. 1931 1932 \param string The string to search for. 1933 \param beforeOffset The offset in bytes to start the search. 1934 1935 \return The offset (zero-based) into the data where the given string 1936 was found, \c B_BAD_VALUE if the \c string pointer is invalid, 1937 or \c B_ERROR if we could not find the \c string. 1938 1939 \sa IFindLast(const char*, int32) const 1940 1941 \since BeOS R5 1942*/ 1943 1944 1945/*! 1946 \fn int32 BString::FindLast(char c) const 1947 \brief Find the last occurrence of the given character. 1948 1949 \param c The character to search for. 1950 \return The offset (zero-based) into the data where the given BString 1951 was found, or \c B_ERROR if we could not find the character. 1952 1953 \since BeOS R5 1954*/ 1955 1956 1957/*! 1958 \fn int32 BString::FindLast(char c, int32 beforeOffset) const 1959 \brief Find the last occurrence of the given character, 1960 starting from the given offset going backwards from the end. 1961 1962 \param c The character to search for. 1963 \param beforeOffset The offset in bytes to start the search. 1964 1965 \return The offset (zero-based) into the data where the given character 1966 was found, or \c B_ERROR Could not find the character. 1967 1968 \since BeOS R5 1969*/ 1970 1971 1972/*! 1973 \fn int32 BString::FindLastChars(const BString& string, 1974 int32 beforeCharOffset) const 1975 \brief UTF-8 aware version of FindLast(const BString&, int32). 1976 1977 \param string The BString to search for. 1978 \param beforeCharOffset The offset in UTF-8 characters to start the search. 1979 1980 \return The offset in bytes (zero-based) into the data where the given 1981 BString was found, or \c B_ERROR if we could not find the 1982 \c string. 1983 1984 \see FindLast(const BString&, int32) 1985 1986 \since Haiku R1 1987*/ 1988 1989 1990/*! 1991 \fn int32 BString::FindLastChars(const char* string, 1992 int32 beforeCharOffset) const 1993 \brief UTF-8 aware version of FindLast(const char*, int32). 1994 1995 \param string The string to search for. 1996 \param beforeCharOffset The offset in UTF-8 characters to start the search. 1997 1998 \return The offset in bytes (zero-based) into the data where the given 1999 string was found, \c B_BAD_VALUE if the \c string pointer is 2000 invalid, or \c B_ERROR if we could not find the \c string. 2001 2002 \see FindLast(const char*, int32) 2003 2004 \since Haiku R1 2005*/ 2006 2007 2008/*! 2009 \fn int32 BString::IFindFirst(const BString& string) const 2010 \brief Find the first occurrence of the given \a string case-insensitively. 2011 2012 \copydetails FindFirst(const BString&) const 2013*/ 2014 2015 2016/*! 2017 \fn int32 BString::IFindFirst(const char* string) const 2018 \brief Find the first occurrence of the given \a string case-insensitively. 2019 2020 \copydetails FindFirst(const char*) const 2021*/ 2022 2023 2024/*! 2025 \fn int32 BString::IFindFirst(const BString& string, int32 fromOffset) const 2026 \brief Find the first occurrence of the given BString case-insensitively, 2027 starting from the given offset. 2028 2029 \copydetails FindFirst(const BString&, int32) const 2030*/ 2031 2032 2033/*! 2034 \fn int32 BString::IFindFirst(const char* string, int32 fromOffset) const 2035 \brief Find the first occurrence of the given string case-insensitively, 2036 starting from the given offset. 2037 2038 \copydetails FindFirst(const char*, int32) const 2039*/ 2040 2041 2042/*! 2043 \fn int32 BString::IFindLast(const BString& string) const 2044 \brief Find the last occurrence of the given BString case-insensitively. 2045 2046 \copydetails FindLast(const BString&) const 2047*/ 2048 2049 2050/*! 2051 \fn int32 BString::IFindLast(const char* string) const 2052 \brief Find the last occurrence of the given string case-insensitively. 2053 2054 \copydetails FindLast(const char*) const 2055*/ 2056 2057 2058/*! 2059 \fn int32 BString::IFindLast(const BString& string, int32 beforeOffset) const 2060 \brief Find the last occurrence of the given BString case-insensitively, 2061 starting from the given offset going backwards. 2062 2063 \copydetails FindLast(const BString&, int32) const 2064*/ 2065 2066 2067/*! 2068 \fn int32 BString::IFindLast(const char* string, int32 beforeOffset) const 2069 \brief Find the last occurrence of the given string case-insensitively, 2070 starting from the given offset going backwards. 2071 2072 \copydetails FindLast(const char*, int32) const 2073*/ 2074 2075 2076/*! 2077 \fn bool BString::StartsWith(const BString& string) const 2078 \brief Returns whether or not the BString starts with \a string. 2079 2080 \param string The \a string to search for. 2081 2082 \return \c true if the BString started with \a string, \c false otherwise. 2083 2084 \since Haiku R1 2085*/ 2086 2087 2088/*! 2089 \fn bool BString::StartsWith(const char* string) const 2090 \brief Returns whether or not the BString starts with \a string. 2091 2092 \param string The \a string to search for. 2093 2094 \return \c true if the BString started with \a string, \c false otherwise. 2095 2096 \since Haiku R1 2097*/ 2098 2099 2100/*! 2101 \fn bool BString::StartsWith(const char* string, int32 length) const 2102 \brief Returns whether or not the BString starts with \a length characters 2103 of \a string. 2104 2105 \param string The \a string to search for. 2106 \param length The number of characters (bytes) of \a string to search for. 2107 2108 \return \c true if the BString started with \a length characters of 2109 \a string, \c false otherwise. 2110 2111 \since Haiku R1 2112*/ 2113 2114 2115/*! 2116 \fn bool BString::IStartsWith(const BString& string) const 2117 \brief Returns whether or not the BString starts with \a string 2118 case-insensitively. 2119 2120 \param string The \a string to search for. 2121 2122 \return \c true if the BString started with \a string case-insensitively, 2123 \c false otherwise. 2124 2125 \since Haiku R1 2126*/ 2127 2128 2129/*! 2130 \fn bool BString::IStartsWith(const char* string) const 2131 \brief Returns whether or not the BString starts with \a string 2132 case-insensitively. 2133 2134 \param string The \a string to search for. 2135 2136 \return \c true if the BString started with \a string case-insensitively, 2137 \c false otherwise. 2138 2139 \since Haiku R1 2140*/ 2141 2142 2143/*! 2144 \fn bool BString::IStartsWith(const char* string, int32 length) const 2145 \brief Returns whether or not the BString starts with \a length characters 2146 of \a string case-insensitively. 2147 2148 \param string The \a string to search for. 2149 \param length The number of characters (bytes) of \a string to search for. 2150 2151 \return \c true if the BString started with \a length characters of 2152 \a string case-insensitively, \c false otherwise. 2153 2154 \since Haiku R1 2155*/ 2156 2157 2158/*! 2159 \fn bool BString::EndsWith(const BString& string) const 2160 \brief Returns whether or not the BString ends with \a string. 2161 2162 \param string The \a string to search for. 2163 2164 \return \c true if the BString ended with \a string, \c false otherwise. 2165 2166 \since Haiku R1 2167*/ 2168 2169 2170/*! 2171 \fn bool BString::EndsWith(const char* string) const 2172 \brief Returns whether or not the BString ends with \a string. 2173 2174 \param string The \a string to search for. 2175 2176 \return \c true if the BString ended with \a string, \c false otherwise. 2177 2178 \since Haiku R1 2179*/ 2180 2181 2182/*! 2183 \fn bool BString::EndsWith(const char* string, int32 length) const 2184 \brief Returns whether or not the BString ends with \a length characters 2185 of \a string. 2186 2187 \param string The \a string to search for. 2188 \param length The number of characters (bytes) of \a string to search for. 2189 2190 \return \c true if the BString ended with \a length characters of 2191 \a string, \c false otherwise. 2192 2193 \since Haiku R1 2194*/ 2195 2196 2197/*! 2198 \fn bool BString::IEndsWith(const BString& string) const 2199 \brief Returns whether or not the BString ends with \a string 2200 case-insensitively. 2201 2202 \param string The \a string to search for. 2203 2204 \return \c true if the BString ended with \a string case-insensitively, 2205 \c false otherwise. 2206 2207 \since Haiku R1 2208*/ 2209 2210 2211/*! 2212 \fn bool BString::IEndsWith(const char* string) const 2213 \brief Returns whether or not the BString ends with \a string 2214 case-insensitively. 2215 2216 \param string The \a string to search for. 2217 2218 \return \c true if the BString ended with \a string case-insensitively, 2219 \c false otherwise. 2220 2221 \since Haiku R1 2222*/ 2223 2224 2225/*! 2226 \fn bool BString::IEndsWith(const char* string, int32 length) const 2227 \brief Returns whether or not the BString ends with \a length characters 2228 of \a string case-insensitively. 2229 2230 \param string The \a string to search for. 2231 \param length The number of characters (bytes) of \a string to search for. 2232 2233 \return \c true if the BString ended with \a length characters of 2234 \a string case-insensitively, \c false otherwise. 2235 2236 \since Haiku R1 2237*/ 2238 2239 2240//! @} 2241 2242 2243/*! 2244 \name Replacing 2245*/ 2246 2247 2248//! @{ 2249 2250 2251/*! 2252 \fn BString& BString::ReplaceFirst(char replaceThis, char withThis) 2253 \brief Replace the first occurrence of a character with another character. 2254 2255 \param replaceThis The character to replace. 2256 \param withThis The character to put in its place. 2257 2258 \return This method always returns \c *this. 2259 2260 \sa IReplaceFirst(char, char) 2261 2262 \since BeOS R5 2263*/ 2264 2265 2266/*! 2267 \fn BString& BString::ReplaceLast(char replaceThis, char withThis) 2268 \brief Replace the last occurrence of a character with another character. 2269 2270 \param replaceThis The character to replace. 2271 \param withThis The character to put in its place 2272 2273 \return This method always returns \c *this. 2274 2275 \sa IReplaceLast(char, char) 2276 2277 \since BeOS R5 2278*/ 2279 2280 2281/*! 2282 \fn BString& BString::ReplaceAll(char replaceThis, char withThis, 2283 int32 fromOffset) 2284 \brief Replace all occurrences of a character with another character. 2285 2286 \param replaceThis The character to replace. 2287 \param withThis The character to put in its place 2288 \param fromOffset The offset in bytes to start looking for the character. 2289 2290 \return This method always returns \c *this. 2291 2292 \sa IReplaceAll(char, char, int32) 2293 2294 \since BeOS R5 2295*/ 2296 2297 2298/*! 2299 \fn BString& BString::Replace(char replaceThis, char withThis, 2300 int32 maxReplaceCount, int32 fromOffset) 2301 \brief Replace a number of occurrences of a character with another 2302 character. 2303 2304 \param replaceThis The character to replace. 2305 \param withThis The character to put in its place 2306 \param maxReplaceCount The maximum number of characters that should be 2307 replaced. 2308 \param fromOffset The offset in bytes to start looking for the character 2309 2310 \return This method always returns \c *this. 2311 2312 \sa IReplace(char, char, int32, int32) 2313 2314 \since BeOS R5 2315*/ 2316 2317 2318/*! 2319 \fn BString& BString::ReplaceFirst(const char* replaceThis, 2320 const char* withThis) 2321 \brief Replace the first occurrence of a string with another string. 2322 2323 \param replaceThis The string to replace. 2324 \param withThis The string to put in its place 2325 2326 \return This method always returns \c *this. 2327 2328 \sa IReplaceFirst(const char*, const char*) 2329 2330 \since BeOS R5 2331*/ 2332 2333 2334/*! 2335 \fn BString& BString::ReplaceLast(const char* replaceThis, 2336 const char* withThis) 2337 \brief Replace the last occurrence of a string with another string. 2338 2339 \param replaceThis The string to replace. 2340 \param withThis The string to put in its place 2341 2342 \return This method always returns \c *this. 2343 2344 \sa IReplaceLast(const char*, const char*) 2345 2346 \since BeOS R5 2347*/ 2348 2349 2350/*! 2351 \fn BString& BString::ReplaceAll(const char* replaceThis, 2352 const char* withThis, int32 fromOffset) 2353 \brief Replace all occurrences of a string with another string. 2354 2355 \param replaceThis The string to replace. 2356 \param withThis The string to put in its place 2357 \param fromOffset The offset in bytes to start looking for the string. 2358 2359 \return This method always returns \c *this. 2360 2361 \sa IReplaceAll(const char*, const char*, int32) 2362 2363 \since BeOS R5 2364*/ 2365 2366 2367/*! 2368 \fn BString& BString::Replace(const char* replaceThis, 2369 const char* withThis, int32 maxReplaceCount, int32 fromOffset) 2370 \brief Replace a number of occurrences of a string with another string. 2371 2372 \param replaceThis The string to replace. 2373 \param withThis The string to put in its place 2374 \param maxReplaceCount The maximum number of occurrences that should 2375 be replaced. 2376 \param fromOffset The offset in bytes to start looking for the string. 2377 2378 \return This method always returns \c *this. 2379 2380 \sa IReplace(const char*, const char*, int32, int32) 2381 2382 \since BeOS R5 2383*/ 2384 2385 2386/*! 2387 \fn BString& BString::ReplaceAllChars(const char* replaceThis, 2388 const char* withThis, int32 fromCharOffset) 2389 \brief UTF-8 aware version of ReplaceAll(const char*, const char*, int32). 2390 2391 \param replaceThis The string to replace. 2392 \param withThis The string to put in its place 2393 \param fromCharOffset The offset in UTF-8 characters to start looking for 2394 the string. 2395 2396 \return This method always returns \c *this. 2397 2398 \see ReplaceAll(const char*, const char*, int32) 2399 2400 \since Haiku R1 2401*/ 2402 2403 2404/*! 2405 \fn BString& BString::ReplaceChars(const char* replaceThis, 2406 const char* withThis, int32 maxReplaceCount, int32 fromCharOffset) 2407 \brief UTF-8 aware version of 2408 ReplaceAll(const char*, const char*, int32, int32). 2409 2410 \param replaceThis The string to replace. 2411 \param withThis The string to put in its place 2412 \param maxReplaceCount The maximum number of occurrences that should 2413 be replaced. 2414 \param fromCharOffset The offset in UTF-8 characters to start looking for 2415 the string. 2416 2417 \return This method always returns \c *this. 2418 2419 \see ReplaceAll(const char*, const char*, int32, int32) 2420 2421 \since Haiku R1 2422*/ 2423 2424 2425/*! 2426 \fn BString& BString::IReplaceFirst(char replaceThis, char withThis) 2427 \brief Replace the first occurrence of a character with another 2428 character case-insensitively. 2429 2430 \param replaceThis The string to replace. 2431 \param withThis The string to put in its place 2432 2433 \sa ReplaceFirst(char, char) 2434 2435 \since BeOS R5 2436*/ 2437 2438 2439/*! 2440 \fn BString& BString::IReplaceLast(char replaceThis, char withThis) 2441 \brief Replace the last occurrence of a character with another 2442 character case-insensitively. 2443 2444 \param replaceThis The string to replace. 2445 \param withThis The string to put in its place 2446 2447 \sa ReplaceLast(char, char) 2448 2449 \since BeOS R5 2450*/ 2451 2452 2453/*! 2454 \fn BString& BString::IReplaceAll(char replaceThis, char withThis, 2455 int32 fromOffset) 2456 \brief Replace all occurrences of a character with another character 2457 case-insensitively. 2458 2459 \param replaceThis The string to replace. 2460 \param withThis The string to put in its place 2461 \param fromOffset The offset where to start looking for the string 2462 2463 \sa ReplaceAll(char, char, int32) 2464 2465 \since BeOS R5 2466*/ 2467 2468 2469/*! 2470 \fn BString& BString::IReplace(char replaceThis, char withThis, 2471 int32 maxReplaceCount, int32 fromOffset) 2472 \brief Replace a number of occurrences of a character with another 2473 character case-insensitively. 2474 2475 \param replaceThis The char to replace. 2476 \param withThis The char to put in its place 2477 \param maxReplaceCount The maximum number of occurrences that should 2478 be replaced. 2479 \param fromOffset The offset where to start looking for the string 2480 2481 \sa Replace(char, char, int32, int32) 2482 2483 \since BeOS R5 2484*/ 2485 2486 2487/*! 2488 \fn BString& BString::IReplaceFirst(const char* replaceThis, 2489 const char* withThis) 2490 \brief Replace the first occurrence of a string with another string 2491 case-insensitively. 2492 2493 \param replaceThis The string to replace. 2494 \param withThis The string to put in its place. 2495 2496 \sa ReplaceFirst(const char*, const char*) 2497 2498 \since BeOS R5 2499*/ 2500 2501 2502/*! 2503 \fn BString& BString::IReplaceLast(const char* replaceThis, 2504 const char* withThis) 2505 \brief Replace the last occurrence of a string with another string. Case-insensitive. 2506 2507 \param replaceThis The string to replace. 2508 \param withThis The string to put in its place. 2509 2510 \sa ReplaceLast(const char*, const char*) 2511 2512 \since BeOS R5 2513*/ 2514 2515 2516/*! 2517 \fn BString& BString::IReplaceAll(const char* replaceThis, 2518 const char* withThis, int32 fromOffset) 2519 \brief Replace all occurrences of a string with another string 2520 case-insensitively. 2521 2522 \param replaceThis The string to replace. 2523 \param withThis The string to put in its place. 2524 \param fromOffset The offset where to start looking for the string. 2525 2526 \sa ReplaceAll(const char*, const char*, int32) 2527 2528 \since BeOS R5 2529*/ 2530 2531 2532/*! 2533 \fn BString& BString::IReplace(const char* replaceThis, 2534 const char* withThis, int32 maxReplaceCount, int32 fromOffset) 2535 \brief Replace a number of occurrences of a string with another string 2536 case-insensitively. 2537 2538 \param replaceThis The string to replace. 2539 \param withThis The string to put in its place 2540 \param maxReplaceCount The maximum number of occurrences that should 2541 be replaced. 2542 \param fromOffset The offset where to start looking for the string 2543 2544 \sa Replace(const char*, const char*, int32, int32) 2545 2546 \since BeOS R5 2547*/ 2548 2549 2550/*! 2551 \fn BString& BString::ReplaceSet(const char* setOfBytes, char with) 2552 \brief Replaces characters that are in a certain set with a chosen 2553 character. 2554 2555 \param setOfBytes The set of characters that need to be replaced. 2556 \param with The character to replace the occurrences with. 2557 2558 \return This method always returns \c *this. 2559 2560 \since BeOS R5 2561*/ 2562 2563 2564/*! 2565 \fn BString& BString::ReplaceSet(const char* setOfBytes, const char* with) 2566 \brief Replaces characters that are in a certain set with a chosen string. 2567 2568 \param setOfBytes The set of chars that need to be replaced. 2569 \param with The string to replace the occurrences with. 2570 2571 \return This method always returns \c *this. 2572 2573 \since BeOS R5 2574*/ 2575 2576 2577/*! 2578 \fn BString& BString::ReplaceCharsSet(const char* setOfChars, 2579 const char* with) 2580 \brief UTF-8 aware version of ReplaceSet(const char*, const char*) 2581 2582 \param setOfChars The set of UTF-8 characters that need to be replaced. 2583 \param with The string to replace the occurrences with. 2584 2585 \return This method always returns \c *this. 2586 2587 \since Haiku R1 2588*/ 2589 2590 2591//! @} 2592 2593 2594/*! 2595 \name Indexing 2596*/ 2597 2598 2599//! @{ 2600 2601 2602/*! 2603 \fn char BString::operator[](int32 index) const 2604 \brief Returns the character in the string at the given offset. 2605 2606 This function can be used to read a byte. There is no bound checking 2607 though, use ByteAt() if you don't know if the \c index parameter is 2608 valid. 2609 2610 \param index The index (zero-based) of the byte to get. 2611 2612 \return Returns a reference to the specified byte. 2613 2614 \since BeOS R5 2615*/ 2616 2617 2618/*! 2619 \fn char BString::ByteAt(int32 index) const 2620 \brief Returns the character in the string at the given offset. 2621 2622 This function can be used to read a single byte. 2623 2624 \param index The index (zero-based) of the byte to get. 2625 2626 \return A reference to the specified byte, if out of bounds return 0. 2627 2628 \since BeOS R5 2629*/ 2630 2631 2632/*! 2633 \fn const char* BString::CharAt(int32 charIndex, int32* bytes) const 2634 \brief UTF-8 aware version of ByteAt(int32). 2635 2636 \param charIndex The index (zero-based) of the UTF-8 character to get. 2637 \param bytes An int32 pointer to hold the UTF-8 character. 2638 2639 \return A reference to the specified UTF-8 character, if out of bounds 2640 return 0. 2641 2642 \see ByteAt(int32) 2643 2644 \since Haiku R1 2645*/ 2646 2647 2648/*! 2649 \fn bool BString::CharAt(int32 charIndex, char* buffer, 2650 int32* bytes) const 2651 \brief UTF-8 aware version of ByteAt(int32) with a \a buffer parameter. 2652 2653 \param charIndex The index (zero-based) of the UTF-8 character to get. 2654 \param buffer Set to the position in the string where the character is 2655 found. 2656 \param bytes An int32 pointer to hold the UTF-8 character. 2657 2658 \see ByteAt(int32, char*, int32*) 2659 2660 \since Haiku R1 2661*/ 2662 2663 2664//! @} 2665 2666 2667/*! 2668 \name Low-Level Manipulation 2669*/ 2670 2671 2672//! @{ 2673 2674 2675/*! 2676 \fn char* BString::LockBuffer(int32 maxLength) 2677 \brief Locks the buffer and return the internal string for manipulation. 2678 2679 If you want to do any low-level string manipulation on the internal buffer, 2680 you should call this method. This method includes the possibility to grow 2681 the buffer so that you don't have to worry about that yourself. 2682 2683 Make sure you call UnlockBuffer() when you're done with the manipulation. 2684 2685 \param maxLength The size of the buffer in bytes. If you don't want a 2686 bigger buffer, passing anything under the length of the string will 2687 simply return it as is. 2688 2689 \return A pointer to the buffer to manipulate. 2690 2691 \sa UnlockBuffer() 2692 2693 \since BeOS R5 2694*/ 2695 2696 2697/*! 2698 \fn BString& BString::UnlockBuffer(int32 length) 2699 \brief Unlocks the buffer after you are done with low-level manipulation. 2700 2701 \param length The length in bytes to trim the string to in order to keep 2702 the internal buffer sane. If you don't pass a value in it, 2703 <tt>strlen()</tt> will be used to determine the length. 2704 2705 \return This method always returns \c *this. 2706 2707 \since BeOS R5 2708*/ 2709 2710 2711/*! 2712 \fn BString& BString::SetByteAt(int32 pos, char to) 2713 \brief Set a byte at position \a pos to character \a to. 2714 2715 \param pos The index of the byte to replace. 2716 \param to The new value that should replace the previous byte. 2717 2718 \return This method always returns \c *this. 2719 2720 \since Haiku R1 2721*/ 2722 2723 2724//! @} 2725 2726 2727/*! 2728 \name Case Manipulation 2729*/ 2730 2731 2732//! @{ 2733 2734 2735/*! 2736 \fn BString& BString::ToLower() 2737 \brief Convert each of the characters in the BString to lowercase. 2738 2739 \return This method always returns \c *this. 2740 2741 \since BeOS R5 2742*/ 2743 2744 2745/*! 2746 \fn BString& BString::ToUpper() 2747 \brief Convert each of the characters in the BString to uppercase. 2748 2749 \return This method always returns \c *this. 2750 2751 \since BeOS R5 2752*/ 2753 2754 2755/*! 2756 \fn BString& BString::Capitalize() 2757 \brief Convert the first character to uppercase, and the rest to lowercase. 2758 2759 \return This method always returns \c *this. 2760 2761 \since BeOS R5 2762*/ 2763 2764 2765/*! 2766 \fn BString& BString::CapitalizeEachWord() 2767 \brief Convert the first character of every word to uppercase, and the rest 2768 to lowercase. 2769 2770 Converts the first character of every "word" (series of alphabetical 2771 characters separated by non alphabetical characters) to uppercase, and 2772 the rest to lowercase. 2773 2774 \return This method always returns \c *this. 2775 2776 \since BeOS R5 2777*/ 2778 2779 2780//! @} 2781 2782 2783/*! 2784 \name Escaping and De-escaping 2785 2786 This class contains some methods to help you with escaping and 2787 de-escaping certain characters. Note that this is the C-style of 2788 escaping, where you place a character before the character that is 2789 to be escaped, and not HTML style escaping, where certain characters 2790 are replaced by something else. 2791*/ 2792 2793 2794//! @{ 2795 2796 2797/*! 2798 \fn BString& BString::CharacterEscape(const char* original, 2799 const char* setOfCharsToEscape, char escapeWith) 2800 \brief Escape selected characters on a given string. 2801 2802 This version sets itself to the string supplied in the \c original 2803 parameter, and then escapes the selected characters with a supplied 2804 character. 2805 2806 \param original The string to be escaped. 2807 \param setOfCharsToEscape The set of characters that need to be escaped. 2808 \param escapeWith The character to escape with. 2809 2810 \return This method always returns \c *this. 2811 2812 \sa CharacterDeescape(char) 2813 \sa CharacterDeescape(const char*, char) 2814 2815 \since BeOS R5 2816*/ 2817 2818 2819/*! 2820 \fn BString& BString::CharacterEscape(const char* setOfCharsToEscape, 2821 char escapeWith) 2822 \brief Escape selected characters of this string. 2823 2824 \param setOfCharsToEscape The set of characters that need to be escaped. 2825 \param escapeWith The character to escape with. 2826 2827 \return This method always returns \c *this. 2828 2829 \sa CharacterDeescape(char) 2830 2831 \since BeOS R5 2832*/ 2833 2834 2835/*! 2836 \fn BString& BString::CharacterDeescape(const char* original, 2837 char escapeChar) 2838 \brief Remove the character to escape with from a given string. 2839 2840 This version sets itself to the string supplied in the \c original 2841 parameter, and then removes the escape characters. 2842 2843 \param original The string to be escaped. 2844 \param escapeChar The character that was used to escape with. 2845 2846 \return This method always returns \c *this. 2847 2848 \sa CharacterEscape(const char*, const char*, char) 2849 2850 \since BeOS R5 2851*/ 2852 2853 2854/*! 2855 \fn BString& BString::CharacterDeescape(char escapeChar) 2856 \brief Remove the character to escape with from this string. 2857 2858 \param escapeChar The character that was used to escape with. 2859 2860 \return This method always returns \c *this. 2861 2862 \sa CharacterEscape(const char*, char) 2863*/ 2864 2865 2866//! @} 2867 2868 2869/*! 2870 \name sprintf() Replacement Methods 2871 2872 These methods may be slower than <tt>sprintf()</tt>, but they are overflow safe. 2873*/ 2874 2875 2876//! @{ 2877 2878 2879/*! 2880 \fn BString& BString::operator<<(const char* string) 2881 \brief Append \a string to the BString. 2882 2883 \param string The \a string to append. 2884 2885 \return This method always returns \c *this. 2886 2887 \since BeOS R5 2888*/ 2889 2890 2891/*! 2892 \fn BString& BString::operator<<(const BString& string) 2893 \brief Append \a string to the BString. 2894 2895 \param string The \a string to append. 2896 2897 \return This method always returns \c *this. 2898*/ 2899 2900 2901/*! 2902 \fn BString& BString::operator<<(char c) 2903 \brief Append \a c to the BString. 2904 2905 \param c The character to append. 2906 2907 \return This method always returns \c *this. 2908 2909 \since BeOS R5 2910*/ 2911 2912 2913/*! 2914 \fn BString& BString::operator<<(bool value) 2915 \brief Convert the \c bool \c value to a string and append it. 2916 2917 In case the \a value is true, the string "true" is appended to the string. 2918 Otherwise, the string "false" is appended. 2919 2920 \param value The boolean \c value ("true" of "false") to append. 2921 2922 \return This method always returns \c *this. 2923 2924 \since BeOS R5 2925*/ 2926 2927 2928/*! 2929 \fn BString& BString::operator<<(int value) 2930 \brief Convert the \c int \a value to a string and append it. 2931 2932 \param value The \c int \a value to append. 2933 2934 \return This method always returns \c *this. 2935 2936 \since BeOS R5 2937*/ 2938 2939 2940/*! 2941 \fn BString& BString::operator<<(unsigned int value) 2942 \brief Convert the <tt>unsigned int</tt> \a value to a string and append it. 2943 2944 \param value The <tt>unsigned int</tt> \a value to append. 2945 2946 \return This method always returns \c *this. 2947 2948 \since BeOS R5 2949*/ 2950 2951 2952/*! 2953 \fn BString& BString::operator<<(unsigned long value) 2954 \brief Convert the <tt>unsigned long</tt> \a value to a string and append it. 2955 2956 \param value The <tt>unsigned long</tt> \a value to append. 2957 2958 \return This method always returns \c *this. 2959 2960 \since BeOS R5 2961*/ 2962 2963 2964/*! 2965 \fn BString& BString::operator<<(long value) 2966 \brief Convert the \c long \a value to a string and append it. 2967 2968 \param value The \c long \a value to append. 2969 2970 \return This method always returns \c *this. 2971 2972 \since BeOS R5 2973*/ 2974 2975 2976/*! 2977 \fn BString& BString::operator<<(unsigned long long value) 2978 \brief Convert the <tt>unsigned long long</tt> \a value to a string and 2979 append it. 2980 2981 \param value The <tt>unsigned long long</tt> \a value to append. 2982 2983 \return This method always returns \c *this. 2984 2985 \since BeOS R5 2986*/ 2987 2988 2989/*! 2990 \fn BString& BString::operator<<(long long value) 2991 \brief Convert the <tt>long long</tt> \a value to a string and append it. 2992 2993 \param value The <tt>long long</tt> \a value to append. 2994 2995 \return This method always returns \c *this. 2996 2997 \since BeOS R5 2998*/ 2999 3000 3001/*! 3002 \fn BString& BString::operator<<(float value) 3003 \brief Convert the \c float \a value to a string and append it. 3004 3005 Using this operator will append using <tt>%.2f</tt> formatting. 3006 3007 \param value The \c float \a value to append. 3008 3009 \return This method always returns \c *this. 3010 3011 \since BeOS R5 3012*/ 3013 3014 3015/*! 3016 \fn BString& BString::operator<<(double value) 3017 \brief Convert the \c double \a value to a string and append it. 3018 3019 Using this operator will append using <tt>%.2f</tt> formatting. 3020 3021 \param value The \c double \a value to append. 3022 3023 \return This method always returns \c *this. 3024 3025 \since BeOS R5 3026*/ 3027 3028 3029//! @} 3030 3031 3032/************* end of BString class, start of general operators ************/ 3033/*! 3034 \addtogroup support_globals 3035*/ 3036 3037 3038//! @{ 3039 3040 3041/*! 3042 \fn bool operator<(const char* a, const BString& b) 3043 \brief Lexicographically compare if \c a is less than the given BString \a b. 3044 3045 From String.h and in libbe.so. 3046 3047 \param a The first string to compare. 3048 \param b The second string to compare. 3049 3050 \return \c true if \a a is less than \a b, \c false otherwise. 3051 3052 \sa BString::operator<(const char*) const 3053 3054 \since BeOS R5 3055*/ 3056 3057 3058/*! 3059 \fn bool operator<=(const char* a, const BString& b) 3060 \brief Lexicographically compare if \c a is less than or equal to a 3061 given BString \a b. 3062 3063 From String.h and in libbe.so. 3064 3065 \param a The first string to compare. 3066 \param b The second string to compare. 3067 3068 \return \c true if \a a is less than or equal to \a b, 3069 \c false otherwise. 3070 3071 \sa BString::operator<=(const char*) const 3072 3073 \since BeOS R5 3074*/ 3075 3076 3077/*! 3078 \fn bool operator==(const char* a, const BString& b) 3079 \brief Lexicographically compare if \c a is equal to a given BString \a b. 3080 3081 From String.h and in libbe.so. 3082 3083 \param a The first string to compare. 3084 \param b The second string to compare. 3085 3086 \sa BString::operator==(const char*) const 3087 3088 \return \c true if \a a is equal to \a b, \c false otherwise. 3089 3090 \since BeOS R5 3091*/ 3092 3093 3094/*! 3095 \fn bool operator>(const char* a, const BString& b) 3096 \brief Lexicographically compare if \c a is greater than a given BString \a b. 3097 3098 From String.h and in libbe.so. 3099 3100 \param a The first string to compare. 3101 \param b The second string to compare. 3102 3103 \sa BString::operator>(const char*) const 3104 3105 \return \c true if \a a is greater than \a b, \c false otherwise. 3106 3107 \since BeOS R5 3108*/ 3109 3110 3111/*! 3112 \fn bool operator>=(const char* a, const BString& b) 3113 \brief Lexicographically compare if \c a is greater than or equal to a 3114 given BString \a b. 3115 3116 From String.h and in libbe.so. 3117 3118 \param a The first string to compare. 3119 \param b The second string to compare. 3120 3121 \return \c true if \a a is greater than or equal to \a b, 3122 \c false otherwise. 3123 3124 \sa BString::operator>=(const char*) const 3125 3126 \since BeOS R5 3127*/ 3128 3129 3130/*! 3131 \fn bool operator!=(const char* a, const BString& b) 3132 \brief Lexicographically compare if \c a is not equal to given BString \a b. 3133 3134 From String.h and in libbe.so. 3135 3136 \param a The first string to compare. 3137 \param b The second string to compare. 3138 3139 \return \c true if \a a is NOT equal to \a b, \c false otherwise. 3140 3141 \sa BString::operator!=(const char*) const 3142 3143 \since BeOS R5 3144*/ 3145 3146 3147/*! 3148 \fn int Compare(const BString& a, const BString& b) 3149 \brief Lexicographically compare two strings. 3150 3151 This function is useful if you need a global compare function to feed to 3152 BList::SortItems(). 3153 3154 \param a The first string to compare. 3155 \param b The second string to compare. 3156 3157 From String.h and in libbe.so. 3158 3159 \return An int representing the strings relationship to each other. 3160 \retval >0 \a a sorts lexicographically after \a b. 3161 \retval =0 \a a is equal to \a b. 3162 \retval <0 \a a sorts lexicographically before \a b. 3163 3164 \sa BString::Compare(const BString&) const 3165 3166 \since BeOS R5 3167*/ 3168 3169 3170/*! 3171 \fn int ICompare(const BString& a, const BString& b) 3172 \brief Lexicographically compare two strings case-insensitively. 3173 3174 This function is useful if you need a global compare function to feed to 3175 BList::SortItems(). 3176 3177 From String.h and in libbe.so. 3178 3179 \param a The first string to compare. 3180 \param b The second string to compare. 3181 3182 \return An int representing the strings relationship to each other. 3183 \retval >0 \a a sorts lexicographically after \a b. 3184 \retval =0 \a a is equal to \a b. 3185 \retval <0 \a a sorts lexicographically before \a b. 3186 3187 \sa BString::Compare(const BString&) const 3188 3189 \since BeOS R5 3190*/ 3191 3192 3193/*! 3194 \fn int Compare(const BString* a, const BString* b) 3195 \brief Lexicographically compare two strings. 3196 3197 This function is useful if you need a global compare function to feed to 3198 BList::SortItems(). 3199 3200 From String.h and in libbe.so. 3201 3202 \param a The first string to compare. 3203 \param b The second string to compare. 3204 3205 \return An int representing the strings relationship to each other. 3206 \retval >0 \a a sorts lexicographically after \a b. 3207 \retval =0 \a a is equal to \a b. 3208 \retval <0 \a a sorts lexicographically before \a b. 3209 3210 \sa BString::Compare(const BString&) const 3211 3212 \since BeOS R5 3213*/ 3214 3215 3216/*! 3217 \fn int ICompare(const BString* a, const BString* b) 3218 \brief Lexicographically compare two strings case-insensitively. 3219 3220 This function is useful if you need a global compare function to feed to 3221 BList::SortItems(). 3222 3223 From String.h and in libbe.so. 3224 3225 \param a The first string to compare. 3226 \param b The second string to compare. 3227 3228 \return An int representing the strings relationship to each other. 3229 \retval >0 \a a sorts lexicographically after \a b. 3230 \retval =0 \a a is equal to \a b. 3231 \retval <0 \a a sorts lexicographically before \a b. 3232 3233 \sa BString::Compare(const BString&) const 3234 3235 \since BeOS R5 3236*/ 3237 3238 3239//! @} 3240