1/* 2 * Copyright 2007-2011 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 * Oliver Tappe, openbeos@hirschaefer.de 10 * 11 * Corresponds to: 12 * headers/os/support/String.h rev 43319 13 * src/kits/support/String.cpp rev 42682 14 */ 15 16/*! 17 \file String.h 18 \ingroup support 19 \ingroup libbe 20 \brief Defines the BString class and global operators and functions for 21 handling strings. 22*/ 23 24/*! 25 \class BString String.h 26 \ingroup support 27 \ingroup libbe 28 \brief String class supporting common string operations. 29 30 BString is a string allocation and manipulation class. The object 31 takes care to allocate and free memory for you, so it will always be 32 "big enough" to store your strings. 33 34 While BString is in essence a wrapper around a byte-array, which can always 35 be accessed with the BString::String() method, it does have some 36 understanding of UTF-8 and it can be used for the manipulation of UTF-8 37 strings. For all operations that perform on bytes, there is an equivalent 38 that operates on UTF-8 strings. See for example the BString::CopyInto() and 39 BString::CopyCharsInto() methods. The main difference is that if there are 40 any position argumens, the regular method counts the bytes and the 41 Chars methods counts characters. 42*/ 43 44 45/*! 46 \fn BString::BString() 47 \brief Creates an empty BString. 48*/ 49 50 51/*! 52 \fn BString::BString(const char* string) 53 \brief Creates and initializes a BString from a \a string. 54*/ 55 56 57/*! 58 \fn BString::BString(const BString &string) 59 \brief Creates and initializes a BString from another BString. 60*/ 61 62 63/*! 64 \fn BString::BString(const char *string, int32 maxLength) 65 \brief Creates and initializes a BString from a \a string up to 66 \a maxLength characters. 67 68 If \a maxLength is greater than the length of the source \a string then the 69 entire source \a string is copied. If \a maxLength is less than or equal 70 to 0 then the result is an empty BString. 71 72 \warning In BeOS R5 passing in a negative \a maxLength argument will copy 73 the entire \a string. 74*/ 75 76 77/*! 78 \fn BString::~BString() 79 \brief Free all resources associated with the object. 80 81 The destructor also frees the internal buffer associated with the string. 82*/ 83 84 85/*! 86 \name Access Methods 87*/ 88 89 90//! @{ 91 92 93/*! 94 \fn const char* BString::String() const 95 \brief Return a pointer to the object string, \c NUL terminated. 96 97 The pointer to the object string is guaranteed to be \c NUL 98 terminated. You can't modify or free the pointer. Once the BString 99 object is deleted, the pointer becomes invalid. 100 101 If you want to manipulate the internal string of the object directly, 102 have a look at LockBuffer(). 103 104 \return A pointer to the object string. 105*/ 106 107 108/*! 109 \fn int32 BString::Length() const 110 \brief Get the length of the string in bytes. 111 112 \return An integer with the length of the string, measured in bytes. 113 \sa CountChars() 114*/ 115 116 117/*! 118 \fn int32 BString::CountChars() const 119 \brief Returns the length of the object measured in characters. 120 121 BString is aware of UTF8 characters, so this method will count 122 the actual number of characters in the string. 123 124 \return An integer which is the number of characters in the string. 125 \sa Length() 126*/ 127 128 129/*! 130 \fn int32 BString::CountBytes(int32 fromCharOffset, int32 charCount) const 131 \brief Count the number of bytes starting from a specified character 132 133 BString is somewhat aware of UTF8 characters, which can take up more than 134 one byte. With this method you can count the number of bytes a subset of 135 the string contains. 136 137 \warning This method does not check whether the input is outside of the 138 boundaries, so make sure that you check your input values. 139 140 \param fromCharOffset The index of the character (not the byte!) from 141 which to start the count 142 \param charCount The number of characters to count 143 144 \return An integer with the number of bytes. 145*/ 146 147 148/*! 149 \fn bool BString::IsEmpty() const 150 \brief Check whether the string is empty. 151 152 \return Returns \c true if the string is empty. 153*/ 154 155 156/*! 157 \fn uint32 BString::HashValue() const 158 \brief Return a hash value for the current string 159 160 \sa HashValue(const char *string) 161*/ 162 163 164/*! 165 \fn static uint32 BString::HashValue(const char* string) 166 \brief Return the hash value of a specified \c string 167 168 This allows you to use the BString::HashValue() method on any arbitrary 169 \c string. 170 171 \param string The string that you want to have hashed. 172 173 \sa HashValue() 174*/ 175 176 177//! @} 178 179 180/*! 181 \name Assignment Methods 182 183 To assign a string to the object, thus overriding the previous string 184 that was stored, there are different methods to use. Use one of the 185 overloaded Adopt() methods to take over data from another object. Use 186 one of the assignment operators to copy data from another object, or 187 use one of the SetTo() methods for more advanced copying. 188*/ 189 190 191//! @{ 192 193 194/*! 195 \fn BString& BString::operator=(const BString &string) 196 \brief Re-initialize the object to a copy of the data of a BString. 197 198 \param string The string object to copy. 199 200 \return The function always returns \c *this. 201 202 \sa Adopt(BString &from) 203 \sa SetTo(const BString &string, int32 length) 204*/ 205 206 207/*! 208 \fn BString& BString::operator=(const char *str) 209 \brief Re-initialize the object to a copy of the data of a string. 210 211 \sa SetTo(const char *str, int32 maxLength) 212*/ 213 214 215/*! 216 \fn BString& BString::operator=(char c) 217 \brief Re-initialize the object to a character. 218 219 \param c The character which you want to initialize the string to. 220*/ 221 222 223/*! 224 \fn BString& BString::SetTo(const char *str) 225 \brief Re-initialize the object to a copy of the data of a string. 226 227 This method calls operator=(const char *str). 228 229 \sa SetTo(const char *str, int32 maxLength) 230*/ 231 232 233/*! 234 \fn BString& BString::SetTo(const char *str, int32 maxLength) 235 \brief Re-initialize the object to a copy of the data of a string. 236 237 \param str The string to copy. 238 \param maxLength Amount of characters to copy from the string. 239 240 \sa operator=(const char *str) 241*/ 242 243 244/*! 245 \fn BString& BString::SetTo(const BString &from) 246 \brief Re-initialize the object to a copy of the data of a BString. 247 248 \param from The string object to copy. 249 250 \return The function always returns \c *this. 251 252 \sa SetTo(const BString &string, int32 length) 253 \sa Adopt(BString &from) 254*/ 255 256 257/*! 258 \fn BString& BString::Adopt(BString &from) 259 \brief Adopt the data of the given BString object. 260 261 This method adopts the data from a BString. 262 263 \note The object that is adopted from is not deleted, only its private 264 data is initialized to a \c NULL string. So if the from object was 265 created on the heap, you need to clean it up yourself. 266 267 \param from The string object to adopt. 268 269 \return The function always returns \c *this. 270 271 \sa operator=(const BString &string) 272*/ 273 274 275/*! 276 \fn BString& BString::SetTo(const BString &string, int32 maxLength) 277 \brief Re-initialize the string to a copy of the given BString object. 278 279 \param string The BString object to copy. 280 \param maxLength Amount of characters to copy from the original BString. 281 282 \return The function always returns \c *this. 283 284 \sa operator=(const BString &string) 285 \sa Adopt(BString &from, int32 maxLength) 286*/ 287 288 289/*! 290 \fn BString& BString::Adopt(BString &from, int32 maxLength) 291 \brief Adopt the data of the given BString object up to \a maxLength 292 characters. 293 294 \param from The string object to adopt. 295 \param maxLength Number of characters to adopt from the original BString. 296 297 \return The function always returns \c *this. 298 299 \sa SetTo(const BString &string, int32 maxLength) 300*/ 301 302 303/*! 304 \fn BString& BString::SetTo(char c, int32 count) 305 \brief Re-initialize the object to a string composed of a character you 306 specify. 307 308 This method lets you specify the length of a string and what character 309 you want the string to contain repeatedly. 310 311 \param c The character you want to initialize the BString. 312 \param count The length of the string. 313 314 \return The function always returns \c *this. 315 316 \sa operator=(char c) 317*/ 318 319 320/*! 321 \fn BString& BString::SetToChars(const char *string, int32 charCount) 322 \brief Undocumented 323*/ 324 325 326/*! 327 \fn BString& BString::SetToChars(const BString& string, int32 charCount) 328 \brief Undocumented 329*/ 330 331 332/*! 333 \fn BString& BString::AdoptChars(BString& from, int32 charCount) 334 \brief Undocumented 335*/ 336 337 338/*! 339 \fn BString& BString::SetToFormat(const char *format, ...) 340 \brief Undocumented 341*/ 342 343 344//! @} 345 346 347/*! 348 \name Substring Copying 349*/ 350 351 352//! @{ 353 354 355/*! 356 \fn BString &BString::CopyInto(BString &into, int32 fromOffset, 357 int32 length) const 358 \brief Copy the object's data (or part of it) into another BString. 359 360 This methods makes sure you don't copy more bytes than are available 361 in the string. If the length exceeds the length of the string, it only 362 copies the number of characters that are actually available. 363 364 \param into The BString to where to copy the object. 365 \param fromOffset The (zero-based) offset where to begin the copy. 366 \param length The amount of bytes to copy. 367 368 \return This method always returns a pointer to the string passed as the 369 \c into parameter. 370*/ 371 372 373/*! 374 \fn void BString::CopyInto(char *into, int32 fromOffset, int32 length) const 375 \brief Copy the BString data (or part of it) into the supplied buffer. 376 377 This methods makes sure you don't copy more bytes than are available 378 in the string. If the length exceeds the length of the string, it only 379 copies the number of characters that are actually available. 380 381 It's up to you to make sure your buffer is large enough. 382 383 \param into The buffer where to copy the object. 384 \param fromOffset The (zero-based) offset where to begin the copy. 385 \param length The amount of bytes to copy. 386*/ 387 388 389/*! 390 \fn BString& BString::CopyCharsInto(BString& into, int32 fromOffset, 391 int32 charCount) const 392 \brief Undocumented 393*/ 394 395 396/*! 397 \fn bool BString::CopyCharsInto(char* into, int32* intoLength, 398 int32 fromCharOffset, int32 charCount) const 399 \brief Undocumented 400*/ 401 402 403//! @} 404 405 406/*! 407 \name Appending Methods 408*/ 409 410 411//! @{ 412 413 414/*! 415 \fn BString & BString::operator+=(const BString &string) 416 \brief Append the given string to the object 417 418 \param string The string to append 419 420 \return This method always returns \c *this. 421 422 \sa Append(const BString &string, int32 length) 423*/ 424 425 426/*! 427 \fn BString& BString::operator+=(const char *str) 428 \brief Append the given string to the object. 429 430 \param str A pointer to the NULL-terminated string to append. 431 432 \return This method always returns \c *this. 433 434 \sa Append(const char *str, int32 length) 435*/ 436 437 438/*! 439 \fn BString& BString::operator+=(char c) 440 \brief Append the given character to the object. 441 442 \param c The character to append. 443 444 \return This method always returns \c *this. 445 446 \sa Append(char c, int32 count) 447*/ 448 449 450/*! 451 \fn BString & BString::operator+=(const BString &string) 452 \brief Append the given string to the object 453 454 \param string The string to append 455 456 \return This method always returns \c *this. 457 458 \sa Append(const BString &string, int32 length) 459*/ 460 461 462/*! 463 \fn BString &BString::Append(const BString &string) 464 \brief Append the given string to the object 465 466 \param string The string to append 467 468 \return This method always returns \c *this. 469 470 \sa Append(const BString &string, int32 length) 471*/ 472 473 474/*! 475 \fn BString &BString::Append(const char *str) 476 \brief Append the given string to the object. 477 478 This method calls operator+=(const char *str). 479 480 \sa Append(const char *str, int32 length) 481*/ 482 483 484/*! 485 \fn BString& BString::Append(const BString &string, int32 length) 486 \brief Append a part of the given BString to the object. 487 488 \param string The BString to append. 489 \param length The maximum number ofbytes to get from the original object. 490 491 \return This method always returns \c *this. 492 493 \sa operator+=(const BString &string) 494*/ 495 496 497/*! 498 \fn BString& BString::Append(const char *str, int32 length) 499 \brief Append a part of the given string to the object. 500 501 \param str A pointer to the string to append. 502 \param length The maximum bytes to get from the original string. 503 504 \return This method always returns \c *this. 505 506 \sa operator+=(const char *str) 507*/ 508 509 510/*! 511 \fn BString& BString::Append(char c, int32 count) 512 \brief Append the given character repeatedly to the object. 513 514 \param c The character to append. 515 \param count The number of times this character should be appended. 516 517 \return This method always returns \c *this. 518 519 \sa operator+=(char c) 520*/ 521 522 523/*! 524 \fn BString& BString::AppendChars(const BString& string, int32 charCount) 525 \brief undocumented 526*/ 527 528 529/*! 530 \fn BString& BString::AppendChars(const char *string, int32 charCount) 531 \brief undocumented 532*/ 533 534 535//! @} 536 537 538/*! 539 \name Prepending Methods 540*/ 541 542 543//! @{ 544 545 546/*! 547 \fn BString& BString::Prepend(const char *str) 548 \brief Prepend the given string to the object. 549 550 \param str A pointer to the string to prepend. 551 552 \return This method always returns \c *this. 553 554 \sa Prepend(const char *str, int32 length) 555*/ 556 557 558/*! 559 \fn BString& BString::Prepend(const BString &string) 560 \brief Prepend the given BString to the object. 561 562 \param string The BString object to prepend. 563 564 \return This method always returns \c *this. 565 566 \sa Prepend(const BString &string, int32 len) 567*/ 568 569 570/*! 571 \fn BString& BString::Prepend(const char *str, int32 length) 572 \brief Prepend the given string to the object. 573 574 \param str A pointer to the string to prepend. 575 \param length The maximum amount of bytes to get from the string. 576 577 \return This method always returns \c *this. 578 579 \sa Prepend(const char *str) 580*/ 581 582 583/*! 584 \fn BString& BString::Prepend(const BString &string, int32 length) 585 \brief Prepend the given BString to the object. 586 587 \param string The BString object to prepend. 588 \param length The maximum amount of bytes to get from the BString. 589 590 \return This method always returns \c *this. 591 592 \sa Prepend(const BString &string) 593*/ 594 595 596/*! 597 \fn BString& BString::Prepend(char c, int32 count) 598 \brief Prepend the given character repeatedly to the object. 599 600 \param c The character to prepend. 601 \param count The number of times this character should be prepended. 602 603 \return This method always returns \c *this. 604*/ 605 606 607/*! 608 \fn BString& BString::PrependChars(const char *string, int32 charCount) 609 \brief undocumented 610*/ 611 612 613/*! 614 \fn BString& BString::PrependChars(const BString& string, int32 charCount) 615 \brief undocumented 616*/ 617 618 619//! @} 620 621 622/*! 623 \name Inserting Methods 624*/ 625 626 627//! @{ 628 629 630/*! 631 \fn BString& BString::Insert(const char *string, int32 position) 632 \brief Insert the given string at the given position into the object's 633 data. 634 635 \param string A pointer to the string to insert. 636 \param position The offset in bytes into the BString's data where to insert 637 the string. 638 639 \return This method always returns \c *this. 640 641 \sa Insert(const char *string, int32 length, int32 position) 642 \sa Insert(const char *string, int32 fromOffset, int32 length, int32 position) 643*/ 644 645 646/*! 647 \fn BString& BString::Insert(const char *string, int32 length, int32 position) 648 \brief Inserts the given string at the given position into the object's 649 data. 650 651 \param string A pointer to the string to insert. 652 \param length The amount of bytes to insert. 653 \param position The offset in bytes into the BString's data where to insert 654 the string. 655 656 \return This method always returns \c *this. 657 658 \sa Insert(const char *string, int32 position) 659 \sa Insert(const char *string, int32 fromOffset, int32 length, int32 position) 660*/ 661 662 663/*! 664 \fn BString& BString::Insert(const char *string, int32 fromOffset, 665 int32 length, int32 position) 666 \brief Insert the given string at the given position into the object's 667 data. 668 669 \param string A pointer to the string to insert. 670 \param fromOffset The offset in the string that is to be inserted 671 \param length The amount of bytes to insert. 672 \param position The offset in bytes into the BString's data where to insert 673 the string. 674 675 \return This method always returns \c *this. 676 677 \sa Insert(const char *string, int32 position) 678 \sa Insert(const char *string, int32 length, int32 position) 679*/ 680 681 682/*! 683 \fn BString& BString::Insert(const BString &string, int32 position) 684 \brief Insert the given BString at the given position into the object's 685 data. 686 \param string The BString object to insert. 687 \param position The offset in bytes into the BString's data where to insert 688 the string. 689 690 \return This method always returns \c *this. 691 692 \sa Insert(const BString &string, int32 length, int32 position) 693 \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 position) 694*/ 695 696 697/*! 698 \fn BString& BString::Insert(const BString &string, int32 length, int32 position) 699 \brief Insert the given BString at the given position into the object's 700 data. 701 \param string The BString object to insert. 702 \param length The amount of bytes to insert. 703 \param position The offset in bytes into the BString's data where to insert 704 the string. 705 706 \return This method always returns \c *this. 707 708 \sa Insert(const BString &string, int32 position) 709 \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 position) 710*/ 711 712 713/*! 714 \fn BString& BString::Insert(const BString &string, int32 fromOffset, 715 int32 length, int32 position) 716 \brief Insert the given string at the given position into the object's 717 data. 718 719 \param string The BString object to insert. 720 \param fromOffset The offset in the string that is to be inserted 721 \param length The amount of bytes to insert. 722 \param position The offset in bytes into the BString's data where to insert 723 the string. 724 725 \return This method always returns \c *this. 726 727 \sa Insert(const BString &string, int32 position) 728 \sa Insert(const BString &string, int32 length, int32 position) 729*/ 730 731 732/*! 733 \fn BString& BString::Insert(char c, int32 count, int32 pos) 734 \brief Insert the given character repeatedly at the given position 735 into the object's data. 736 737 \param c The character to insert. 738 \param count The number of times to insert the character. 739 \param pos The offset in bytes into the BString's data where to insert 740 the string. 741 742 \return This method always returns \c *this. 743*/ 744 745 746/*! 747 \fn BString& BString::InsertChars(const char *string, int32 charPosition) 748 \brief Undocumented 749*/ 750 751 752/*! 753 \fn BString& BString::InsertChars(const char* string, int32 charCount, 754 int32 charPosition) 755 \brief Undocumented 756*/ 757 758 759/*! 760 \fn BString& BString::InsertChars(const char* string, int32 fromCharOffset, 761 int32 charCount, int32 charPosition) 762 \brief Undocumented 763*/ 764 765 766/*! 767 \fn BString& BString::InsertChars(const BString& string, int32 charPosition) 768 \brief Undocumented 769*/ 770 771 772/*! 773 \fn BString& BString::InsertChars(const BString& string, int32 charCount, 774 int32 charPosition) 775 \brief Undocumented 776*/ 777 778 779/*! 780 \fn BString& BString::InsertChars(const BString& string, int32 fromCharOffset, 781 int32 charCount, int32 charPosition) 782 \brief Undocumented 783*/ 784 785 786//! @} 787 788 789/*! 790 \name Removing Methods 791*/ 792 793 794//! @{ 795 796 797/*! 798 \fn BString& BString::Truncate(int32 newLength, bool lazy) 799 \brief Truncate the string to the new length. 800 801 \param newLength The new length of the string. 802 \param lazy If true, the memory-optimization is postponed to later 803 804 \return This method always returns \c *this. 805*/ 806 807 808/*! 809 \fn BString& BString::TruncateChars(int32 newCharCount, bool lazy) 810 \brief Undocumented 811*/ 812 813 814/*! 815 \fn BString& BString::Remove(int32 from, int32 length) 816 \brief Remove some bytes, starting at the given offset 817 818 \param from The offset from which you want to start removing 819 \param length The number of bytes to remove 820 821 \return This function always returns \c *this. 822*/ 823 824 825/*! 826 \fn BString& BString::RemoveChars(int32 fromCharOffset, int32 charCount) 827 \brief Undocumented 828*/ 829 830 831/*! 832 \fn BString& BString::RemoveFirst(const BString &string) 833 \brief Remove the first occurrence of the given BString. 834 835 \param string The BString to remove. 836 837 \return This function always returns \c *this. 838*/ 839 840 841/*! 842 \fn BString& BString::RemoveLast(const BString &string) 843 \brief Remove the last occurrence of the given BString. 844 845 \param string The BString to remove. 846 847 \return This function always returns \c *this. 848*/ 849 850 851/*! 852 \fn BString& BString::RemoveAll(const BString &string) 853 \brief Remove all occurrences of the given BString. 854 855 \param string The BString to remove. 856 857 \return This function always returns \c *this. 858*/ 859 860 861/*! 862 \fn BString& BString::RemoveFirst(const char *string) 863 \brief Remove the first occurrence of the given string. 864 865 \param string A pointer to the string to remove. 866 867 \return This function always returns \c *this. 868*/ 869 870 871/*! 872 \fn BString& BString::RemoveLast(const char *string) 873 \brief Remove the last occurrence of the given string. 874 875 \param string A pointer to the string to remove. 876 877 \return This function always returns \c *this. 878*/ 879 880 881/*! 882 \fn BString& BString::RemoveAll(const char *str) 883 \brief Remove all occurrences of the given string. 884 885 \param str A pointer to the string to remove. 886 887 \return This function always returns \c *this. 888*/ 889 890 891/*! 892 \fn BString& BString::RemoveSet(const char *setOfCharsToRemove) 893 \brief Remove all the characters specified. 894 895 \param setOfCharsToRemove The set of characters to remove. 896 897 \return This function always returns \c *this. 898*/ 899 900 901/*! 902 \fn BString& BString::RemoveCharsSet(const char*setOfCharsToRemove) 903 \brief Undocumented 904*/ 905 906 907/*! 908 \fn BString& BString::MoveInto(BString &into, int32 from, int32 length) 909 \brief Move the BString data (or part of it) into another BString. 910 911 \param into The BString where to move the object. 912 \param from The offset (zero-based) where to begin the move. 913 \param length The amount of bytes to move. 914 915 \return This method always returns \c into . 916*/ 917 918 919/*! 920 \fn void BString::MoveInto(char *into, int32 from, int32 length) 921 \brief Move the BString data (or part of it) into the given buffer. 922 923 \param into The buffer where to move the object. 924 \param from The offset (zero-based) where to begin the move. 925 \param length The amount of bytes to move. 926*/ 927 928 929/*! 930 \fn BString& BString::MoveCharsInto(BString &into, int32 fromCharOffset, 931 int32 charCount) 932 \brief Undocumented 933*/ 934 935 936/*! 937 \fn bool BString::MoveCharsInto(char* into, int32* intoLength, 938 int32 fromCharOffset, int32 charCount) 939 \brief Undocumented 940*/ 941 942 943//! @} 944 945 946/*! 947 \name Comparison Methods 948 949 There are two different comparison methods. First of all there 950 is the whole range of operators that return a boolean value, secondly 951 there are methods that return an integer value, both case sensitive 952 and case insensitive. 953 954 There are also global comparison operators and global compare functions. 955 You might need these in case you have a sort routine that takes a generic 956 comparison function, such as BList::SortItems(). 957 See the String.h documentation file to see the specifics, though basically 958 there are the same as implemented in this class. 959*/ 960 961 962//! @{ 963 964 965/*! 966 \fn bool BString::operator<(const BString &string) const 967 \brief Lexicographically compare if this string is less than a given string. 968 969 \param string The string to compare with. 970*/ 971 972 973/*! 974 \fn bool BString::operator<=(const BString &string) const 975 \brief Lexicographically compare if this string is less than or equal to 976 a given string. 977 978 \param string The string to compare with. 979*/ 980 981 982/*! 983 \fn bool BString::operator==(const BString &string) const 984 \brief Lexicographically compare if this string is equal to a given string. 985 986 \param string The string to compare with. 987*/ 988 989 990/*! 991 \fn bool BString::operator>=(const BString &string) const 992 \brief Lexicographically compare if this string is more than or equal 993 to a given string. 994 995 \param string The string to compare with. 996*/ 997 998 999/*! 1000 \fn bool BString::operator>(const BString &string) const 1001 \brief Lexicographically compare if this string is more than a given string. 1002 1003 \param string The string to compare with. 1004*/ 1005 1006 1007/*! 1008 \fn bool BString::operator!=(const BString &string) const 1009 \brief Lexicographically compare if this string is not equal to a given 1010 string. 1011 1012 \param string The string to compare with. 1013*/ 1014 1015 1016/*! 1017 \fn bool BString::operator<(const char *string) const 1018 \brief Lexicographically compare if this string is less than a given string. 1019 1020 \param string The string to compare with. 1021*/ 1022 1023 1024/*! 1025 \fn bool BString::operator<=(const char *string) const 1026 \brief Lexicographically compare if this string is less than or equal to 1027 a given string. 1028 1029 \param string The string to compare with. 1030*/ 1031 1032 1033/*! 1034 \fn bool BString::operator==(const char *string) const 1035 \brief Lexicographically compare if this string is equal to a given string. 1036 1037 \param string The string to compare with. 1038*/ 1039 1040 1041/*! 1042 \fn bool BString::operator>=(const char *string) const 1043 \brief Lexicographically compare if this string is more than or equal 1044 to a given string. 1045 1046 \param string The string to compare with. 1047*/ 1048 1049 1050/*! 1051 \fn bool BString::operator>(const char *string) const 1052 \brief Lexicographically compare if this string is more than a given string. 1053 1054 \param string The string to compare with. 1055*/ 1056 1057 1058/*! 1059 \fn bool BString::operator!=(const char *string) const 1060 \brief Lexicographically compare if this string is not equal to a given 1061 string. 1062 1063 \param string The string to compare with. 1064*/ 1065 1066 1067/*! 1068 \fn BString::operator const char*() const 1069 \brief Undocumented 1070*/ 1071 1072 1073/*! 1074 \fn int BString::Compare(const BString &string) const 1075 \brief Lexicographically compare this string to another. 1076 1077 \param string The string to compare to. 1078 1079 \retval >0 The object sorts lexicographically after \c string. 1080 \retval =0 The object is equal to \c string. 1081 \retval <0 The object sorts lexicographically before \c string. 1082*/ 1083 1084 1085/*! 1086 \fn int BString::Compare(const char *string) const 1087 \brief Lexicographically compare this string to another. 1088 1089 \param string The string to compare to. 1090 1091 \retval >0 The object sorts lexicographically after \c string. 1092 \retval =0 The object is equal to \c string. 1093 \retval <0 The object sorts lexicographically before \c string. 1094 1095 \sa Compare(const BString &string) const 1096*/ 1097 1098 1099/*! 1100 \fn int BString::Compare(const BString &string, int32 length) const 1101 \brief Lexicographically compare a number of characters of a string to 1102 another. 1103 1104 \param string The string to compare to. 1105 \param length The number of characters to compare 1106 1107 \retval >0 The object sorts lexicographically after \c string. 1108 \retval =0 The object is equal to \c string. 1109 \retval <0 The object sorts lexicographically before \c string. 1110*/ 1111 1112 1113/*! 1114 \fn int BString::Compare(const char *string, int32 length) const 1115 \brief Lexicographically compare a number of characters of a string to 1116 another. 1117 1118 \param string The string to compare to. 1119 \param length The number of characters to compare. 1120 1121 \retval >0 The object sorts lexicographically after \c string. 1122 \retval =0 The object is equal to \c string. 1123 \retval <0 The object sorts lexicographically before \c string. 1124 1125 \sa Compare(const BString &string, int32 n) const 1126*/ 1127 1128 1129/*! 1130 \fn int BString::CompareChars(const BString& string, 1131 int32 charCount) const 1132 \brief Undocumented 1133*/ 1134 1135 1136/*! 1137 \fn int BString::CompareChars(const char *string, 1138 int32 charCount) const 1139 \brief Undocumented 1140*/ 1141 1142 1143/*! 1144 \fn int BString::ICompare(const BString &string) const 1145 \brief Lexicographically compare a string to another in a 1146 case-insensitive way. 1147 1148 \param string The string to compare to. 1149 1150 \retval >0 The object sorts lexicographically after \c string. 1151 \retval =0 The object is equal to \c string. 1152 \retval <0 The object sorts lexicographically before \c string. 1153 1154 \sa Compare(const BString &string) const 1155*/ 1156 1157 1158/*! 1159 \fn int BString::ICompare(const char* string) const 1160 \brief Lexicographically compare this string to another in a 1161 case-insensitive way. 1162 1163 \param string The string to compare to. 1164 1165 \retval >0 The object sorts lexicographically after \c string. 1166 \retval =0 The object is equal to \c string. 1167 \retval <0 The object sorts lexicographically before \c string. 1168 1169 \sa Compare(const BString &string) const 1170*/ 1171 1172 1173/*! 1174 \fn int BString::ICompare(const BString& string, int32 length) const 1175 \brief Lexicographically compare a number of characters of this string 1176 to another. 1177 1178 \param string The string to compare to. 1179 \param length The number of characters to compare 1180 1181 \retval >0 The object sorts lexicographically after \c string. 1182 \retval =0 The object is equal to \c string. 1183 \retval <0 The object sorts lexicographically before \c string. 1184 1185 \sa Compare(const BString &string, int32 length) const 1186*/ 1187 1188 1189/*! 1190 \fn int BString::ICompare(const char* string, int32 length) const 1191 \brief Lexicographically compare a number of characters of this string 1192 to another. 1193 1194 \param string The string to compare to. 1195 \param length The number of characters to compare 1196 1197 \retval >0 The object sorts lexicographically after \c string. 1198 \retval =0 The object is equal to \c string. 1199 \retval <0 The object sorts lexicographically before \c string. 1200 1201 \sa Compare(const BString &string, int32 length) const 1202*/ 1203 1204 1205//! @} 1206 1207 1208/*! 1209 \name Searching Methods 1210*/ 1211 1212 1213//! @{ 1214 1215 1216/*! 1217 \fn int32 BString::FindFirst(const BString &string) const 1218 \brief Find the first occurrence of the given BString. 1219 1220 \param string The BString to search for. 1221 1222 \return The offset (zero-based) into the data where the given BString 1223 has been found. 1224 1225 \retval B_ERROR Could not find \c string. 1226 1227 \sa IFindFirst(const BString &string) const 1228*/ 1229 1230 1231/*! 1232 \fn int32 BString::FindFirst(const char *string) const 1233 \brief Find the first occurrence of the given string. 1234 1235 \param string The string to search for. 1236 1237 \return The offset (zero-based) into the data where the given string 1238 has been found. 1239 1240 \retval B_BAD_VALUE The \c string pointer is invalid. 1241 \retval B_ERROR Could not find \c string. 1242 1243 \sa IFindFirst(const char *string) const 1244*/ 1245 1246 1247/*! 1248 \fn int32 BString::FindFirst(const BString &string, int32 fromOffset) const 1249 \brief Find the first occurrence of the given BString, starting from 1250 the given offset. 1251 1252 \param string The BString to search for. 1253 \param fromOffset The offset where to start the search. 1254 1255 \return An integer which is the offset (zero-based) into the data 1256 where the given BString has been found. 1257 1258 \retval B_ERROR Could not find \c string. 1259 1260 \sa IFindFirst(const BString &string, int32 fromOffset) const 1261*/ 1262 1263 1264/*! 1265 \fn int32 BString::FindFirst(const char *string, int32 fromOffset) const 1266 \brief Find the first occurrence of the given string, 1267 starting from the given offset. 1268 1269 \param string The string to search for. 1270 \param fromOffset The offset where to start the search. 1271 1272 \return The offset (zero-based) into the data where the given string 1273 has been found. 1274 1275 \retval B_BAD_VALUE The \c string pointer is invalid. 1276 \retval B_ERROR Could not find \c string. 1277 1278 \sa IFindFirst(const char *string, int32 fromOffset) const 1279*/ 1280 1281 1282/*! 1283 \fn int32 BString::FindFirst(char c) const 1284 \brief Find the first occurrence of the given character. 1285 1286 \param c The character to search for. 1287 1288 \return The offset (zero-based) into the data 1289 where the given character has been found. 1290 1291 \retval B_ERROR Could not find \c c. 1292*/ 1293 1294 1295/*! 1296 \fn int32 BString::FindFirst(char c, int32 fromOffset) const 1297 \brief Find the first occurrence of the given character, 1298 starting from the given offset. 1299 1300 \param c The character to search for. 1301 \param fromOffset The offset where to start the search. 1302 1303 \return The offset (zero-based) into the data 1304 where the given character has been found. 1305 1306 \retval B_ERROR Could not find \c c. 1307*/ 1308 1309 1310/*! 1311 \fn int32 BString::FindFirstChars(const BString& string, 1312 int32 fromCharOffset) const 1313 \brief Undocumented 1314*/ 1315 1316 1317/*! 1318 \fn int32 BString::FindFirstChars(const char *string, 1319 int32 fromCharOffset) const 1320 \brief Undocumented 1321*/ 1322 1323 1324/*! 1325 \fn int32 BString::FindLast(const BString &string) const 1326 \brief Find the last occurrence of the given BString. 1327 1328 \param string The BString to search for. 1329 1330 \return The offset (zero-based) into the data where the given BString 1331 has been found. 1332 1333 \retval B_ERROR Could not find \c string. 1334 \sa IFindLast(const BString &string) const 1335*/ 1336 1337 1338/*! 1339 \fn int32 BString::FindLast(const char *string) const 1340 \brief Find the last occurrence of the given string. 1341 1342 \param string The string to search for. 1343 1344 \return The offset (zero-based) into the data where the given string 1345 has been found. 1346 1347 \retval B_BAD_VALUE The \c string pointer is invalid. 1348 \retval B_ERROR Could not find \c string. 1349 1350 \sa IFindLast(const char *string) const 1351/*! 1352 1353 1354/*! 1355 \fn int32 BString::FindLast(const BString &string, int32 beforeOffset) const 1356 \brief Find the last occurrence of the given BString, 1357 starting from the given offset, and going backwards. 1358 1359 \param string The BString to search for. 1360 \param beforeOffset The offset where to start the search. 1361 1362 \return An integer which is the offset (zero-based) into the data 1363 where the given BString has been found. 1364 1365 \retval B_ERROR Could not find \c string. 1366 1367 \sa IFindLast(const BString &string, int32 beforeOffset) const 1368*/ 1369 1370 1371/*! 1372 \fn int32 BString::FindLast(const char *string, int32 beforeOffset) const 1373 \brief Find the last occurrence of the given string, 1374 starting from the given offset, and going backwards. 1375 1376 \param string The string to search for. 1377 \param beforeOffset The offset where to start the search. 1378 1379 \return The offset (zero-based) into the data 1380 where the given string has been found. 1381 1382 \retval B_BAD_VALUE The \c string pointer is invalid. 1383 \retval B_ERROR Could not find \c string. 1384 1385 \sa IFindLast(const char *string, int32 beforeOffset) const 1386*/ 1387 1388 1389/*! 1390 \fn int32 BString::FindLast(char c) const 1391 \brief Find the last occurrence of the given character. 1392 1393 \param c The character to search for. 1394 \return The offset (zero-based) into the data where the given character 1395 has been found. 1396 1397 \retval B_ERROR Could not find \c c. 1398*/ 1399 1400 1401/*! 1402 \fn int32 BString::FindLast(char c, int32 beforeOffset) const 1403 \brief Find the last occurrence of the given character, 1404 starting from the given offset and going backwards. 1405 1406 \param c The character to search for. 1407 \param beforeOffset The offset where to start the search. 1408 1409 \return The offset (zero-based) into the data where the given character 1410 has been found. 1411 1412 \retval B_ERROR Could not find \c c. 1413*/ 1414 1415 1416/*! 1417 \fn int32 BString::FindLastChars(const BString& string, 1418 int32 beforeCharOffset) const 1419 \brief Undocumented 1420*/ 1421 1422 1423/*! 1424 \fn int32 BString::FindLastChars(const char *string, 1425 int32 beforeCharOffset) const 1426 \brief Undocumented 1427*/ 1428 1429 1430/*! 1431 \fn int32 BString::IFindFirst(const BString &string) const 1432 \brief Find the first occurrence of the given BString case-insensitively. 1433 1434 \sa FindFirst(const BString &string) const 1435*/ 1436 1437 1438/*! 1439 \fn int32 BString::IFindFirst(const char *string) const 1440 \brief Find the first occurrence of the given BString case-insensitively. 1441 1442 \sa FindFirst(const char *string) const 1443*/ 1444 1445 1446/*! 1447 \fn int32 BString::IFindFirst(const BString &string, int32 fromOffset) const 1448 \brief Find the first occurrence of the given BString case-insensitively, 1449 starting from the given offset. 1450 1451 \sa FindFirst(const BString &string, int32 fromOffset) const 1452*/ 1453 1454 1455/*! 1456 \fn int32 BString::IFindFirst(const char *string, int32 fromOffset) const 1457 \brief Find the first occurrence of the given string case-insensitively, 1458 starting from the given offset. 1459 1460 \sa FindFirst(const char *string, int32 fromOffset) const 1461*/ 1462 1463 1464/*! 1465 \fn int32 BString::IFindLast(const BString &string) const 1466 \brief Find the last occurrence of the given BString case-insensitively. 1467 1468 \sa FindLast(const BString &string) const 1469*/ 1470 1471 1472/*! 1473 \fn int32 BString::IFindLast(const char *string) const 1474 \brief Find the last occurrence of the given string case-insensitively. 1475 1476 \sa FindLast(const char *string) const 1477*/ 1478 1479 1480/*! 1481 \fn int32 BString::IFindLast(const BString &string, int32 beforeOffset) const 1482 \brief Find the last occurrence of the given BString case-insensitively, 1483 starting from the given offset, and going backwards. 1484 1485 \sa FindLast(const BString &string, int32 beforeOffset) const 1486*/ 1487 1488 1489/*! 1490 \fn int32 BString::IFindLast(const char *string, int32 beforeOffset) const 1491 \brief Find the last occurrence of the given string case-insensitively, 1492 starting from the given offset, and going backwards. 1493 1494 \sa FindLast(const char *string, int32 beforeOffset) const 1495*/ 1496 1497 1498//! @} 1499 1500 1501/*! 1502 \name Replacing Methods 1503*/ 1504 1505 1506//! @{ 1507 1508 1509/*! 1510 \fn BString& BString::ReplaceFirst(char replaceThis, char withThis) 1511 \brief Replace the first occurrence of a character with another character. 1512 1513 \param replaceThis The character to replace. 1514 \param withThis The character to put in that place 1515 1516 \return This method always returns \c *this. 1517 1518 \sa IReplaceFirst(char replaceThis, char withThis) 1519*/ 1520 1521 1522/*! 1523 \fn BString& BString::ReplaceLast(char replaceThis, char withThis) 1524 \brief Replace the last occurrence of a character with another character. 1525 1526 \param replaceThis The character to replace. 1527 \param withThis The character to put in that place 1528 1529 \return This method always returns \c *this. 1530 1531 \sa ReplaceLast(char replaceThis, char withThis) 1532*/ 1533 1534 1535/*! 1536 \fn BString& BString::ReplaceAll(char replaceThis, char withThis, 1537 int32 fromOffset) 1538 \brief Replace all occurrences of a character with another character. 1539 1540 \param replaceThis The character to replace. 1541 \param withThis The character to put in that place 1542 \param fromOffset The offset where to start looking for the character. 1543 1544 \return This method always returns \c *this. 1545 1546 \sa IReplaceAll(char replaceThis, char withThis, int32 fromOffset) 1547*/ 1548 1549 1550/*! 1551 \fn BString& BString::Replace(char replaceThis, char withThis, 1552 int32 maxReplaceCount, int32 fromOffset) 1553 \brief Replace a number of occurrences of a character with another 1554 character. 1555 1556 \param replaceThis The character to replace. 1557 \param withThis The character to put in that place 1558 \param maxReplaceCount The maximum number of characters that should be 1559 replaced. 1560 \param fromOffset The offset where to start looking for the character 1561 1562 \return This method always returns \c *this. 1563 1564 \sa IReplace(char replaceThis, char withThis, int32 maxReplaceCount, 1565 int32 fromOffset) 1566*/ 1567 1568 1569/*! 1570 \fn BString& BString::ReplaceFirst(const char *replaceThis, 1571 const char *withThis) 1572 \brief Replace the first occurrence of a string with another string. 1573 1574 \param replaceThis The string to replace. 1575 \param withThis The string to put in that place 1576 1577 \return This method always returns \c *this. 1578 1579 \sa IReplaceFirst(const char *replaceThis, const char *withThis) 1580*/ 1581 1582 1583/*! 1584 \fn BString& BString::ReplaceLast(const char *replaceThis, 1585 const char *withThis) 1586 \brief Replace the last occurrence of a string with another string. 1587 1588 \param replaceThis The string to replace. 1589 \param withThis The string to put in that place 1590 1591 \return This method always returns \c *this. 1592 1593 \sa IReplaceLast(const char *replaceThis, const char *withThis) 1594*/ 1595 1596 1597/*! 1598 \fn BString& BString::ReplaceAll(const char *replaceThis, 1599 const char *withThis, int32 fromOffset) 1600 \brief Replace all occurrences of a string with another string. 1601 1602 \param replaceThis The string to replace. 1603 \param withThis The string to put in that place 1604 \param fromOffset The offset where to start looking for the string. 1605 1606 \return This method always returns \c *this. 1607 1608 \sa IReplaceAll(const char *replaceThis, const char *withThis, 1609 int32 fromOffset) 1610*/ 1611 1612 1613/*! 1614 \fn BString& BString::Replace(const char *replaceThis, 1615 const char *withThis, int32 maxReplaceCount, int32 fromOffset) 1616 \brief Replace a number of occurrences of a string with another string. 1617 1618 \param replaceThis The string to replace. 1619 \param withThis The string to put in that place 1620 \param maxReplaceCount The maximum number of occurences that should 1621 be replaced. 1622 \param fromOffset The offset where to start looking for the string 1623 1624 \return This method always returns \c *this. 1625 1626 \sa IReplace(const char *replaceThis, const char *withThis, 1627 int32 maxReplaceCount, int32 fromOffset) 1628*/ 1629 1630 1631/*! 1632 \fn BString& BString::ReplaceAllChars(const char* replaceThis, 1633 const char* withThis, int32 fromCharOffset) 1634 \brief Undocumented 1635*/ 1636 1637 1638/*! 1639 \fn BString& BString::ReplaceChars(const char* replaceThis, const char* withThis, 1640 int32 maxReplceCount, int32 fromCharOffset) 1641 \brief Undocumented 1642*/ 1643 1644 1645/*! 1646 \fn BString& BString::IReplaceFirst(char replaceThis, char withThis) 1647 \brief Replace the first occurrence of a character with another 1648 character. Case insensitive. 1649 1650 \param replaceThis The string to replace. 1651 \param withThis The string to put in that place 1652 1653 \sa ReplaceFirst(char replaceThis, char withThis) 1654*/ 1655 1656 1657/*! 1658 \fn BString& BString::IReplaceLast(char replaceThis, char withThis) 1659 \brief Replace the last occurrence of a character with another 1660 character. Case-insensitive. 1661 1662 \param replaceThis The string to replace. 1663 \param withThis The string to put in that place 1664 1665 \sa ReplaceLast(char replaceThis, char withThis) 1666*/ 1667 1668 1669/*! 1670 \fn BString& BString::IReplaceAll(char replaceThis, char withThis, 1671 int32 fromOffset) 1672 \brief Replace all occurrences of a character with another character. 1673 Case-insensitive. 1674 1675 \param replaceThis The string to replace. 1676 \param withThis The string to put in that place 1677 \param fromOffset The offset where to start looking for the string 1678 1679 \sa ReplaceAll(char replaceThis, char withThis, int32 fromOffset) 1680*/ 1681 1682 1683/*! 1684 \fn BString& BString::IReplace(char replaceThis, char withThis, 1685 int32 maxReplaceCount, int32 fromOffset) 1686 \brief Replace a number of occurrences of a character with another 1687 character. Case-insensive. 1688 1689 \param replaceThis The char to replace. 1690 \param withThis The char to put in that place 1691 \param maxReplaceCount The maximum number of occurences that should 1692 be replaced. 1693 \param fromOffset The offset where to start looking for the string 1694 1695 \sa Replace(char replaceThis, char withThis, int32 maxReplaceCount, 1696 int32 fromOffset) 1697*/ 1698 1699 1700/*! 1701 \fn BString& BString::IReplaceFirst(const char *replaceThis, 1702 const char *withThis) 1703 \brief Replace the first occurrence of a string with another string. 1704 Case-insensitive. 1705 1706 \param replaceThis The string to replace. 1707 \param withThis The string to put in that place 1708 1709 \sa ReplaceFirst(const char *replaceThis, const char *withThis) 1710*/ 1711 1712 1713/*! 1714 \fn BString& BString::IReplaceLast(const char *replaceThis, 1715 const char *withThis) 1716 \brief Replace the last occurrence of a string with another string. Case-insensitive. 1717 1718 \param replaceThis The string to replace. 1719 \param withThis The string to put in that place 1720 1721 \sa ReplaceLast(const char *replaceThis, const char *withThis) 1722*/ 1723 1724 1725/*! 1726 \fn BString& BString::IReplaceAll(const char *replaceThis, 1727 const char *withThis, int32 fromOffset) 1728 \brief Replace all occurrences of a string with another string. 1729 Case-insensitive. 1730 1731 \param replaceThis The string to replace. 1732 \param withThis The string to put in that place 1733 \param fromOffset The offset where to start looking for the string 1734 1735 \sa ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) 1736*/ 1737 1738 1739/*! 1740 \fn BString& BString::IReplace(const char *replaceThis, 1741 const char *withThis, int32 maxReplaceCount, int32 fromOffset) 1742 \brief Replace a number of occurrences of a string with another string. 1743 Case-insensitive. 1744 1745 \param replaceThis The string to replace. 1746 \param withThis The string to put in that place 1747 \param maxReplaceCount The maximum number of occurences that should 1748 be replaced. 1749 \param fromOffset The offset where to start looking for the string 1750 1751 \sa Replace(const char *replaceThis, const char *withThis, 1752 int32 maxReplaceCount, int32 fromOffset) 1753*/ 1754 1755 1756/*! 1757 \fn BString& BString::ReplaceSet(const char* setOfBytes, char with) 1758 \brief Replaces characters that are in a certain set with a chosen 1759 character. 1760 1761 \param setOfBytes The set of characters that need to be replaced. 1762 \param with The character to replace the occurences with. 1763 1764 \return This method always returns \c *this. 1765*/ 1766 1767 1768/*! 1769 \fn BString& BString::ReplaceSet(const char* setOfBytes, const char* with) 1770 \brief Replaces characters that are in a certain set with a chosen string. 1771 1772 \param setOfBytes The set of characters that need to be replaced. 1773 \param with The string to replace the occurences with. 1774 1775 \return This method always returns \c *this. 1776*/ 1777 1778 1779/*! 1780 \fn BString& BString::ReplaceCharsSet(const char* setOfChars, 1781 const char* with) 1782 \brief Undocumented 1783*/ 1784 1785 1786// @} 1787 1788 1789/*! 1790 \name Character Access 1791*/ 1792 1793 1794//! @{ 1795 1796 1797/*! 1798 \fn char& BString::operator[](int32 index) 1799 \brief Return a reference to the data at the given offset. 1800 1801 This function can be used to read a byte. 1802 There is no bounds checking though, so make sure the \c index 1803 you supply is valid. 1804 1805 \param index The index (zero-based) of the byte to get. 1806 1807 \return Returns a reference to the specified byte. 1808 1809 \sa ByteAt(int32 index) for a safer version. 1810*/ 1811 1812 1813/*! 1814 \fn char BString::operator[](int32 index) const 1815 \brief Returns the character in the string at the given offset. 1816 1817 This function can be used to read a byte. There is no bound checking 1818 though, use ByteAt() if you don't know if the \c index parameter is 1819 valid. 1820 1821 \param index The index (zero-based) of the byte to get. 1822 1823 \return Returns a reference to the specified byte. 1824*/ 1825 1826 1827/*! 1828 \fn char BString::ByteAt(int32 index) const 1829 \brief Returns the character in the string at the given offset. 1830 1831 This function can be used to read a single byte. 1832 1833 \param index The index (zero-based) of the byte to get. 1834 1835 \return Returns a reference to the specified byte. If you are out of 1836 bounds, it will return 0. 1837*/ 1838 1839 1840/*! 1841 \fn const char* BString::CharAt(int32 charIndex, int32* bytes) const 1842 \brief Undocumented 1843*/ 1844 1845 1846/*! 1847 \fn bool BString::CharAt(int32 charIndex, char* buffer, 1848 int32* bytes) const 1849 \brief Undocumented 1850*/ 1851 1852 1853//! @} 1854 1855 1856/*! 1857 \name Low-Level Manipulation 1858*/ 1859 1860 1861//! @{ 1862 1863 1864/*! 1865 \fn char* BString::LockBuffer(int32 maxLength) 1866 \brief Locks the buffer and return the internal string for manipulation. 1867 1868 If you want to do any lowlevel string manipulation on the internal buffer, 1869 you should call this method. This method includes the possibility to grow 1870 the buffer so that you don't have to worry about that yourself. 1871 1872 Make sure you call UnlockBuffer() when you're done with the manipulation. 1873 1874 \param maxLength The size of the buffer. If you don't want a biggerx 1875 buffer, passing anything under the length of the string will simply 1876 return it as is. 1877 1878 \return A pointer to the buffer you may manipulate. 1879 1880 \sa UnlockBuffer() 1881*/ 1882 1883 1884/*! 1885 \fn BString& BString::UnlockBuffer(int32 length) 1886 \brief Unlocks the buffer after you are done with lowlevel manipulation. 1887 1888 \param length The length to trim the string to in order to keep the 1889 internal buffer sane. If you don't pass a value in it, a \c strlen 1890 call will be used to determine the length. 1891 1892 \return This method always returns \c *this. 1893*/ 1894 1895 1896//! @} 1897 1898 1899/*! 1900 \name Case Manipulation 1901*/ 1902 1903 1904//! @{ 1905 1906 1907/*! 1908 \fn BString& BString::ToLower() 1909 \brief Convert the BString to lowercase. 1910 \return This method always returns \c *this. 1911*/ 1912 1913 1914/*! 1915 \fn BString& BString::ToUpper() 1916 \brief Convert the BString to uppercase. 1917 \return This method always returns \c *this. 1918*/ 1919 1920 1921/*! 1922 \fn BString& BString::Capitalize() 1923 \brief Convert the first character to uppercase, rest to lowercase 1924 \return This method always returns \c *this. 1925*/ 1926 1927 1928/*! 1929 \fn BString& BString::CapitalizeEachWord() 1930 \brief Convert the first character of every word to uppercase, rest 1931 to lowercase. 1932 1933 Converts the first character of every "word" (series of alphabetical 1934 characters separated by non alphabetical characters) to uppercase, and 1935 the rest to lowercase. 1936 1937 \return This method always returns \c *this. 1938*/ 1939 1940 1941//! @} 1942 1943 1944/*! 1945 \name Escaping and De-escaping Methods 1946 1947 This class contains some methods to help you with escaping and 1948 de-escaping certain characters. Note that this is the C-style of 1949 escaping, where you place a character before the character that is 1950 to be escaped, and not HTML style escaping, where certain characters 1951 are replaced by something else. 1952*/ 1953 1954 1955//! @{ 1956 1957 1958/*! 1959 \fn BString& BString::CharacterEscape(const char* original, 1960 const char* setOfCharsToEscape, char escapeWith) 1961 \brief Escape selected characters on a given string. 1962 1963 This version sets itself to the string supplied in the \c original 1964 paramater, and then escapes the selected characters with a supplied 1965 character. 1966 1967 \param original The string to be escaped. 1968 \param setOfCharsToEscape The set of characters that need to be escaped. 1969 \param escapeWith The character to escape with. 1970 1971 \return This method always returns \c *this. 1972 1973 \sa CharacterDeescape(char escapeChar) 1974 \sa CharacterDeescape(const char *original, char escapeChar) 1975*/ 1976 1977 1978/*! 1979 \fn BString& BString::CharacterEscape(const char* setOfCharsToEscape, 1980 char escapeWith) 1981 \brief Escape selected characters of this string. 1982 1983 \param setOfCharsToEscape The set of characters that need to be escaped. 1984 \param escapeWith The character to escape with. 1985 1986 \return This method always returns \c *this. 1987 1988 \sa CharacterDeescape(char escapeChar) 1989*/ 1990 1991 1992/*! 1993 \fn BString& BString::CharacterDeescape(const char* original, 1994 char escapeChar) 1995 \brief Remove the character to escape with from a given string. 1996 1997 This version sets itself to the string supplied in the \c original 1998 parameter, and then removes the escape characters. 1999 2000 \param original The string to be escaped. 2001 \param escapeChar The character that was used to escape with. 2002 2003 \return This method always returns \c *this. 2004 2005 \sa CharacterEscape(const char *original, const char *setOfCharsToEscape, 2006 char escapeWith) 2007*/ 2008 2009 2010/*! 2011 \fn BString& BString::CharacterDeescape(char escapeChar) 2012 \brief Remove the character to escape with from this string. 2013 2014 \param escapeChar The character that was used to escape with. 2015 2016 \return This method always returns \c *this. 2017 2018 \sa CharacterEscape(const char *setOfCharsToEscape, char escapeWith) 2019*/ 2020 2021 2022//! @} 2023 2024 2025/*! 2026 \name Trimming methods 2027*/ 2028 2029 2030//! @{ 2031 2032 2033/*! 2034 \fn BString& BString::Trim() 2035 \brief Undocumented 2036*/ 2037 2038 2039//! @} 2040 2041 2042/*! 2043 \name Simple sprintf Replacement Methods 2044 2045 These methods may be slower than sprintf(), but they are overflow safe. 2046*/ 2047 2048 2049//! @{ 2050 2051 2052/*! 2053 \fn BString& BString::operator<<(const char *string) 2054 \brief Append the string \a string. 2055*/ 2056 2057 2058/*! 2059 \fn BString& BString::operator<<(const BString &string) 2060 \brief Append the BString \a string. 2061*/ 2062 2063 2064/*! 2065 \fn BString& BString::operator<<(char c) 2066 \brief Append the \c char \a c. 2067*/ 2068 2069 2070/*! 2071 \fn BString& BString::operator<<(bool value) 2072 \brief Append the boolean \c value to the string. 2073 2074 In case the \a value is true, the string \c true is appended to the string. 2075 Otherwise, the string \c false is appended. 2076*/ 2077 2078 2079/*! 2080 \fn BString& BString::operator<<(int value) 2081 \brief Convert the \c int \a value to a string and append it. 2082*/ 2083 2084 2085/*! 2086 \fn BString& BString::operator<<(unsigned int value) 2087 \brief Convert the \c unsigned \c int \a value to a string and append it. 2088*/ 2089 2090 2091/*! 2092 \fn BString& BString::operator<<(unsigned long value) 2093 \brief Convert the \c unsigned \c long \a value to a string and append it. 2094*/ 2095 2096 2097/*! 2098 \fn BString& BString::operator<<(long value) 2099 \brief Convert the \c long \a value to a string and append it. 2100*/ 2101 2102 2103/*! 2104 \fn BString& BString::operator<<(unsigned long long value) 2105 \brief Convert the \c unsigned \c long \c long \a value to a string and 2106 append it. 2107*/ 2108 2109 2110/*! 2111 \fn BString& BString::operator<<(long long value) 2112 \brief Convert the \c long \c long \a value to a string and append it. 2113*/ 2114 2115 2116/*! 2117 \fn BString& BString::operator<<(float value) 2118 \brief Convert the \c float \a value to a string and append it. 2119 2120 Using this operator will append in the \c %.2f style formatting. 2121*/ 2122 2123 2124/*! 2125 \fn BString& BString::operator<<(double value) 2126 \brief Convert the \c double \a value to a string and append it. 2127 2128 Using this operator will append in the \c %.2f style formatting. 2129*/ 2130 2131 2132//! @} 2133 2134 2135/************* end of BString class, start of general operators ************/ 2136/*! 2137 \addtogroup support_globals 2138*/ 2139 2140 2141//! @{ 2142 2143 2144/*! 2145 \fn bool operator<(const char *a, const BString &b) 2146 \brief Lexicographically compare if \c a is less than a given BString. 2147 2148 From String.h and in libbe.so. 2149 2150 \param a The first string to compare. 2151 \param b The second string to compare. 2152 2153 \sa BString::operator<(const char *string) const 2154*/ 2155 2156 2157/*! 2158 \fn bool operator<=(const char *a, const BString &b) 2159 \brief Lexicographically compare if \c a is less than or equal to a 2160 given BString. 2161 2162 From String.h and in libbe.so. 2163 2164 \param a The first string to compare. 2165 \param b The second string to compare. 2166 2167 \sa BString::operator<=(const char *string) const 2168*/ 2169 2170 2171/*! 2172 \fn bool operator==(const char *a, const BString &b) 2173 \brief Lexicographically compare if \c a is equal to a given BString. 2174 2175 From String.h and in libbe.so. 2176 2177 \param a The first string to compare. 2178 \param b The second string to compare. 2179 2180 \sa BString::operator==(const char *string) const 2181*/ 2182 2183 2184/*! 2185 \fn bool operator>(const char *a, const BString &b) 2186 \brief Lexicographically compare if \c a is more than a given BString. 2187 2188 From String.h and in libbe.so. 2189 2190 \param a The first string to compare. 2191 \param b The second string to compare. 2192 2193 \sa BString::operator>(const char *string) const 2194*/ 2195 2196 2197/*! 2198 \fn bool operator>=(const char *a, const BString &b) 2199 \brief Lexicographically compare if \c a is more than or equal to a 2200 given BString. 2201 2202 From String.h and in libbe.so. 2203 2204 \param a The first string to compare. 2205 \param b The second string to compare. 2206 2207 \sa BString::operator>=(const char *string) const 2208*/ 2209 2210 2211/*! 2212 \fn bool operator!=(const char *a, const BString &b) 2213 \brief Lexicographically compare if \c a is not equal to given BString. 2214 2215 From String.h and in libbe.so. 2216 2217 \param a The first string to compare. 2218 \param b The second string to compare. 2219 2220 \sa BString::operator!=(const char *string) const 2221*/ 2222 2223 2224/*! 2225 \fn int Compare(const BString &a, const BString &b) 2226 \brief Lexicographically compare two strings. 2227 2228 This function is useful if you need a global compare function to feed to 2229 BList::SortItems() for example. 2230 2231 \param a The first string to compare. 2232 \param b The second string to compare. 2233 2234 From String.h and in libbe.so. 2235 2236 \sa BString::Compare(const BString &string) const 2237*/ 2238 2239 2240/*! 2241 \fn int ICompare(const BString &a, const BString &b) 2242 \brief Lexicographically compare two strings case-insensitively. 2243 2244 This function is useful if you need a global compare function to feed to 2245 BList::SortItems() for example. 2246 2247 From String.h and in libbe.so. 2248 2249 \param a The first string to compare. 2250 \param b The second string to compare. 2251 2252 \sa BString::Compare(const BString &string) const 2253*/ 2254 2255 2256/*! 2257 \fn int Compare(const BString *a, const BString *b) 2258 \brief Lexicographically compare two strings. 2259 2260 This function is useful if you need a global compare function to feed to 2261 BList::SortItems() for example. 2262 2263 From String.h and in libbe.so. 2264 2265 \param a The first string to compare. 2266 \param b The second string to compare. 2267 2268 \sa BString::Compare(const BString &string) const 2269*/ 2270 2271 2272/*! 2273 \fn int ICompare(const BString *a, const BString *b) 2274 \brief Lexicographically compare two strings case-insensitively. 2275 2276 This function is useful if you need a global compare function to feed to 2277 BList::SortItems() for example. 2278 2279 From String.h and in libbe.so. 2280 2281 \param a The first string to compare. 2282 \param b The second string to compare. 2283 2284 \sa BString::Compare(const BString &string) const 2285*/ 2286 2287 2288//! @} 2289