interface/wx/string.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        string.h
   3 // Purpose:     interface of wxStringBuffer, wxString
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxString
  12
  13     The wxString class has been completely rewritten for wxWidgets 3.0
  14     and this change was actually the main reason for the calling that
  15     version wxWidgets 3.0.
  16
  17     wxString is a class representing a Unicode character string.
  18     wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined)
  19     to store its content (unless this is not supported by the compiler or disabled
  20     specifically when building wxWidgets) and it therefore inherits
  21     many features from @c std::basic_string. (Note that most implementations of
  22     @c std::basic_string are thread-safe and don't use reference counting.)
  23
  24     These @c std::basic_string standard functions are only listed here, but
  25     they are not fully documented in this manual; see the STL documentation
  26     (http://www.cppreference.com/wiki/string/start) for more info.
  27     The behaviour of all these functions is identical to the behaviour
  28     described there.
  29
  30     You may notice that wxString sometimes has several functions which do
  31     the same thing like Length(), Len() and length() which all return the
  32     string length. In all cases of such duplication the @c std::string
  33     compatible methods should be used.
  34
  35     For informations about the internal encoding used by wxString and
  36     for important warnings and advices for using it, please read
  37     the @ref overview_string.
  38
  39     Since wxWidgets 3.0 wxString always stores Unicode strings, so you should
  40     be sure to read also @ref overview_unicode.
  41
  42
  43     @section string_construct Constructors and assignment operators
  44
  45     A string may be constructed either from a C string, (some number of copies of)
  46     a single character or a wide (Unicode) string. For all constructors (except the
  47     default which creates an empty string) there is also a corresponding assignment
  48     operator.
  49
  50     @li wxString()
  51     @li operator=()
  52     @li ~wxString()
  53     @li assign()
  54
  55
  56     @section string_len String length
  57
  58     These functions return the string length and check whether the string
  59     is empty or they empty it.
  60
  61     @li length()
  62     @li size()
  63     @li Len()
  64     @li IsEmpty()
  65     @li operator!()
  66     @li Empty()
  67     @li Clear()
  68
  69
  70     @section string_access Character access
  71
  72     Many functions below take a character index in the string. As with C
  73     strings and arrays, the indices start from 0, so the first character of a
  74     string is string[0]. An attempt to access a character beyond the end of the
  75     string (which may even be 0 if the string is empty) will provoke an assert
  76     failure in @ref overview_debugging "debug builds", but no checks are
  77     done in release builds.
  78
  79     This section also contains both implicit and explicit conversions to C style
  80     strings. Although implicit conversion is quite convenient, you are advised
  81     to use wc_str() for the sake of clarity.
  82
  83     @li GetChar()
  84     @li GetWritableChar()
  85     @li SetChar()
  86     @li Last()
  87     @li operator[]()
  88     @li wc_str()
  89     @li utf8_str()
  90     @li c_str()
  91     @li wx_str()
  92     @li mb_str()
  93     @li fn_str()
  94
  95
  96     @section string_concat Concatenation
  97
  98     Anything may be concatenated (appended to) with a string. However, you can't
  99     append something to a C string (including literal constants), so to do this it
 100     should be converted to a wxString first.
 101
 102     @li insert()
 103     @li append()
 104     @li operator<<()
 105     @li operator+=()
 106     @li operator+()
 107     @li Append()
 108     @li Prepend()
 109
 110
 111     @section string_comp Comparison
 112
 113     The default comparison function Cmp() is case-sensitive and so is the default
 114     version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
 115     or give a second parameter to IsSameAs(). This last function is maybe more
 116     convenient if only equality of the strings matters because it returns a boolean
 117     @true value if the strings are the same and not 0 (which is usually @false
 118     in C) as Cmp() does.
 119
 120     Matches() is a poor man's regular expression matcher: it only understands
 121     '*' and '?' metacharacters in the sense of DOS command line interpreter.
 122
 123     StartsWith() is helpful when parsing a line of text which should start
 124     with some predefined prefix and is more efficient than doing direct string
 125     comparison as you would also have to precalculate the length of the prefix.
 126
 127     @li compare()
 128     @li Cmp()
 129     @li CmpNoCase()
 130     @li IsSameAs()
 131     @li Matches()
 132     @li StartsWith()
 133     @li EndsWith()
 134
 135
 136     @section string_substring Substring extraction
 137
 138     These functions allow you to extract a substring from the string. The
 139     original string is not modified and the function returns the extracted
 140     substring.
 141
 142     @li at()
 143     @li substr()
 144     @li Mid()
 145     @li operator()()
 146     @li Left()
 147     @li Right()
 148     @li BeforeFirst()
 149     @li BeforeLast()
 150     @li AfterFirst()
 151     @li AfterLast()
 152     @li StartsWith()
 153     @li EndsWith()
 154
 155
 156     @section string_case Case conversion
 157
 158     The MakeXXX() variants modify the string in place, while the other functions
 159     return a new string which contains the original text converted to the upper or
 160     lower case and leave the original string unchanged.
 161
 162     @li MakeUpper()
 163     @li Upper()
 164     @li MakeLower()
 165     @li Lower()
 166     @li MakeCapitalized()
 167     @li Capitalize()
 168
 169
 170     @section string_search Searching and replacing
 171
 172     These functions replace the standard @e strchr() and @e strstr()
 173     functions.
 174
 175     @li find()
 176     @li rfind()
 177     @li replace()
 178     @li Find()
 179     @li Replace()
 180
 181
 182     @section string_conv Conversion to numbers
 183
 184     The string provides functions for conversion to signed and unsigned integer and
 185     floating point numbers. All functions take a pointer to the variable to
 186     put the numeric value in and return @true if the @b entire string could be
 187     converted to a number.
 188
 189     @li ToLong()
 190     @li ToLongLong()
 191     @li ToULong()
 192     @li ToULongLong()
 193     @li ToDouble()
 194
 195
 196     @section string_fmt Writing values into the string
 197
 198     Both formatted versions (Printf/() and stream-like insertion operators
 199     exist (for basic types only). Additionally, the Format() function allows
 200     you to simply append a formatted value to a string:
 201
 202     @li Format()
 203     @li FormatV()
 204     @li Printf()
 205     @li PrintfV()
 206     @li operator>>()
 207
 208
 209     @section string_mem Memory management
 210
 211     The following are "advanced" functions and they will be needed rarely.
 212     Alloc() and Shrink() are only interesting for optimization purposes.
 213     wxStringBuffer and wxStringBufferLength classes may be very useful
 214     when working with some external API which requires the caller to provide
 215     a writable buffer.
 216
 217     @li reserve()
 218     @li resize()
 219     @li Alloc()
 220     @li Shrink()
 221     @li wxStringBuffer
 222     @li wxStringBufferLength
 223
 224
 225     @section string_misc Miscellaneous
 226
 227     Miscellaneous other string functions.
 228
 229     @li Trim()
 230     @li Truncate()
 231     @li Pad()
 232
 233
 234     @section string_compat wxWidgets 1.xx compatibility functions
 235
 236     The following functions are deprecated.
 237     Please consider using @c std::string compatible variants.
 238
 239     Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(),
 240     Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase()
 241
 242
 243     @library{wxbase}
 244     @category{data}
 245
 246     @stdobjects
 247     ::wxEmptyString
 248
 249     @see @ref overview_string, @ref overview_unicode, wxUString,
 250          wxCharBuffer, wxUniChar, wxStringTokenizer, @ref group_funcmacro_string
 251 */
 252 class wxString
 253 {
 254 public:
 255     /**
 256         An 'invalid' value for string index
 257     */
 258     static const size_t npos;
 259
 260     /**
 261         @name Standard types
 262     */
 263     //@{
 264     typedef wxUniChar value_type;
 265     typedef wxUniChar char_type;
 266     typedef wxUniCharRef reference;
 267     typedef wxChar* pointer;
 268     typedef const wxChar* const_pointer;
 269     typedef size_t size_type;
 270     typedef wxUniChar const_reference;
 271     //@}
 272
 273     /**
 274        Default constructor
 275     */
 276     wxString();
 277
 278     /**
 279        Creates a string from another string.
 280         Just increases the ref count by 1.
 281     */
 282     wxString(const wxString& stringSrc);
 283
 284
 285     /**
 286        Constructs a string from the string literal @e psz using
 287        the current locale encoding to convert it to Unicode (wxConvLibc).
 288     */
 289     wxString(const char *psz);
 290
 291     /**
 292        Constructs a string from the string literal @e psz using
 293        @e conv to convert it Unicode.
 294     */
 295     wxString(const char *psz, const wxMBConv& conv);
 296
 297     /**
 298        Constructs a string from the first @e nLength character of the string literal @e psz using
 299        the current locale encoding to convert it to Unicode (wxConvLibc).
 300     */
 301     wxString(const char *psz, size_t nLength);
 302
 303     /**
 304        Constructs a string from the first @e nLength character of the string literal @e psz using
 305        @e conv to convert it Unicode.
 306     */
 307     wxString(const char *psz, const wxMBConv& conv, size_t nLength);
 308
 309     /**
 310        Constructs a string from the string literal @e pwz.
 311     */
 312     wxString(const wchar_t *pwz);
 313
 314     /**
 315        Constructs a string from the first @e nLength characters of the string literal @e pwz.
 316     */
 317     wxString(const wchar_t *pwz, size_t nLength);
 318
 319     /**
 320        Constructs a string from @e buf using the using the current locale
 321         encoding to convert it to Unicode.
 322     */
 323     wxString(const wxCharBuffer& buf);
 324
 325     /**
 326        Constructs a string from @e buf.
 327     */
 328     wxString(const wxWCharBuffer& buf);
 329
 330     /**
 331        Constructs a string from @e str using the using the current locale encoding
 332        to convert it to Unicode (wxConvLibc).
 333     */
 334     wxString(const std::string& str);
 335
 336     /**
 337        Constructs a string from @e str.
 338     */
 339     wxString(const std::wstring& str);
 340
 341
 342     /**
 343         String destructor.
 344
 345         Note that this is not virtual, so wxString must not be inherited from.
 346     */
 347     ~wxString();
 348
 349     /**
 350         Gets all the characters after the first occurrence of @e ch.
 351         Returns the empty string if @e ch is not found.
 352     */
 353     wxString AfterFirst(wxUniChar ch) const;
 354
 355     /**
 356         Gets all the characters after the last occurrence of @e ch.
 357         Returns the whole string if @e ch is not found.
 358     */
 359     wxString AfterLast(wxUniChar ch) const;
 360
 361     /**
 362         Preallocate enough space for wxString to store @a nLen characters.
 363
 364         Please note that this method does the same thing as the standard
 365         reserve() one and shouldn't be used in new code.
 366
 367         This function may be used to increase speed when the string is
 368         constructed by repeated concatenation as in
 369
 370         @code
 371             // delete all vowels from the string
 372             wxString DeleteAllVowels(const wxString& original)
 373             {
 374                 wxString result;
 375
 376                 size_t len = original.length();
 377
 378                 result.Alloc(len);
 379
 380                 for ( size_t n = 0; n < len; n++ )
 381                 {
 382                     if ( strchr("aeuio", tolower(original[n])) == NULL )
 383                         result += original[n];
 384                 }
 385
 386                 return result;
 387             }
 388         @endcode
 389
 390         because it will avoid the need to reallocate string memory many times
 391         (in case of long strings). Note that it does not set the maximal length
 392         of a string -- it will still expand if more than @a nLen characters are
 393         stored in it. Also, it does not truncate the existing string (use
 394         Truncate() for this) even if its current length is greater than @a nLen.
 395
 396         @return @true if memory was successfully allocated, @false otherwise.
 397     */
 398     bool Alloc(size_t nLen);
 399
 400     /**
 401        Appends the string literal @e psz.
 402     */
 403     wxString& Append(const char* psz);
 404
 405     /**
 406        Appends the wide string literal @e pwz.
 407     */
 408     wxString& Append(const wchar_t* pwz);
 409
 410     /**
 411        Appends the string literal @e psz with max length @e nLen.
 412     */
 413     wxString& Append(const char* psz, size_t nLen);
 414
 415     /**
 416        Appends the wide string literal @e psz with max length @e nLen.
 417     */
 418     wxString& Append(const wchar_t* pwz, size_t nLen);
 419
 420     /**
 421        Appends the string @e s.
 422     */
 423     wxString& Append(const wxString& s);
 424
 425     /**
 426        Appends the character @e ch @e count times.
 427     */
 428     wxString &Append(wxUniChar ch, size_t count = 1u);
 429
 430     /**
 431         Gets all characters before the first occurrence of @e ch.
 432         Returns the whole string if @a ch is not found.
 433     */
 434     wxString BeforeFirst(wxUniChar ch) const;
 435
 436     /**
 437         Gets all characters before the last occurrence of @e ch.
 438         Returns the empty string if @a ch is not found.
 439     */
 440     wxString BeforeLast(wxUniChar ch) const;
 441
 442     /**
 443         Return the copy of the string with the first string character in the
 444         upper case and the subsequent ones in the lower case.
 445
 446         @since 2.9.0
 447
 448         @see MakeCapitalized()
 449      */
 450     wxString Capitalize() const;
 451
 452     /**
 453         Empties the string and frees memory occupied by it.
 454         See also: Empty()
 455     */
 456     void Clear();
 457
 458     /**
 459         Returns a deep copy of the string.
 460
 461         That is, the returned string is guaranteed to not share data with this
 462         string when using reference-counted wxString implementation.
 463
 464         This method is primarily useful for passing strings between threads
 465         (because wxString is not thread-safe). Unlike creating a copy using
 466         @c wxString(c_str()), Clone() handles embedded NULs correctly.
 467
 468         @since 2.9.0
 469      */
 470     wxString Clone() const;
 471
 472     /**
 473         Case-sensitive comparison.
 474         Returns a positive value if the string is greater than the argument,
 475         zero if it is equal to it or a negative value if it is less than the
 476         argument (same semantics as the standard @c strcmp() function).
 477
 478         See also CmpNoCase(), IsSameAs().
 479     */
 480     int Cmp(const wxString& s) const;
 481
 482     /**
 483         Case-insensitive comparison.
 484         Returns a positive value if the string is greater than the argument,
 485         zero if it is equal to it or a negative value if it is less than the
 486         argument (same semantics as the standard @c strcmp() function).
 487
 488         See also Cmp(), IsSameAs().
 489     */
 490     int CmpNoCase(const wxString& s) const;
 491
 492     /**
 493         Returns @true if target appears anywhere in wxString; else @false.
 494         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 495         code.
 496     */
 497     bool Contains(const wxString& str) const;
 498
 499
 500     /**
 501         Makes the string empty, but doesn't free memory occupied by the string.
 502         See also: Clear().
 503     */
 504     void Empty();
 505
 506     /**
 507         This function can be used to test if the string ends with the specified
 508         @e suffix. If it does, the function will return @true and put the
 509         beginning of the string before the suffix into @e rest string if it is not
 510         @NULL. Otherwise, the function returns @false and doesn't
 511         modify the @e rest.
 512     */
 513     bool EndsWith(const wxString& suffix, wxString *rest = NULL) const;
 514
 515     /**
 516         Searches for the given character @e ch. Returns the position or
 517         @c wxNOT_FOUND if not found.
 518     */
 519     int Find(wxUniChar ch, bool fromEnd = false) const;
 520
 521     /**
 522         Searches for the given string @e sub. Returns the starting position or
 523         @c wxNOT_FOUND if not found.
 524     */
 525     int Find(const wxString& sub) const;
 526
 527     //@{
 528     /**
 529         Same as Find().
 530         This is a wxWidgets 1.xx compatibility function;
 531         you should not use it in new code.
 532     */
 533     int First(wxUniChar ch) const;
 534     int First(const wxString& str) const;
 535     //@}
 536
 537     /**
 538         This static function returns the string containing the result of calling
 539         Printf() with the passed parameters on it.
 540
 541         @see FormatV(), Printf()
 542     */
 543     static wxString Format(const wxString& format, ...);
 544
 545     /**
 546         This static function returns the string containing the result of calling
 547         PrintfV() with the passed parameters on it.
 548
 549         @see Format(), PrintfV()
 550     */
 551     static wxString FormatV(const wxString& format, va_list argptr);
 552
 553     /**
 554         Returns the number of occurrences of @e ch in the string.
 555         This is a wxWidgets 1.xx compatibility function; you should not
 556         use it in new code.
 557     */
 558     int Freq(wxUniChar ch) const;
 559
 560     //@{
 561     /**
 562         Converts given buffer of binary data from 8-bit string to wxString. In
 563         Unicode build, the string is interpreted as being in ISO-8859-1
 564         encoding. The version without @e len parameter takes NUL-terminated
 565         data.
 566
 567         This is a convenience method useful when storing binary data in
 568         wxString. It should be used @em only for that purpose and only in
 569         conjunction with To8BitData(). Use mb_str() for conversion of character
 570         data to known encoding.
 571
 572         @since 2.8.4
 573
 574         @see wxString::To8BitData()
 575     */
 576     static wxString From8BitData(const char* buf, size_t len);
 577     static wxString From8BitData(const char* buf);
 578     //@}
 579
 580     //@{
 581     /**
 582         Converts the string or character from an ASCII, 7-bit form
 583         to the native wxString representation.
 584     */
 585     static wxString FromAscii(const char* s);
 586     static wxString FromAscii(const unsigned char* s);
 587     static wxString FromAscii(const char* s, size_t len);
 588     static wxString FromAscii(const unsigned char* s, size_t len);
 589     static wxString FromAscii(char c);
 590     //@}
 591
 592     //@{
 593     /**
 594         Converts C string encoded in UTF-8 to wxString.
 595
 596         If @a s is not a valid UTF-8 string, an empty string is returned.
 597
 598         Notice that when using UTF-8 wxWidgets build there is a more efficient
 599         alternative to this function called FromUTF8Unchecked() which, unlike
 600         this one, doesn't check that the input string is valid.
 601
 602         @since 2.8.4
 603     */
 604     static wxString FromUTF8(const char* s);
 605     static wxString FromUTF8(const char* s, size_t len);
 606     //@}
 607
 608     //@{
 609     /**
 610         Converts C string encoded in UTF-8 to wxString without checking its
 611         validity.
 612
 613         This method assumes that @a s is a valid UTF-8 sequence and doesn't do
 614         any validation (although an assert failure is triggered in debug builds
 615         if the string is invalid). Only use it if you are absolutely sure that
 616         @a s is a correct UTF-8 string (e.g. because it comes from another
 617         library using UTF-8) and if the performance matters, otherwise use
 618         slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8
 619         string to this function will result in creating a corrupted wxString
 620         and all the subsequent operations on it will be undefined.
 621
 622         @since 2.8.9
 623     */
 624     static wxString FromUTF8Unchecked(const char* s);
 625     static wxString FromUTF8Unchecked(const char* s, size_t len);
 626     //@}
 627
 628     /**
 629         Returns the character at position @a n (read-only).
 630     */
 631     wxUniChar GetChar(size_t n) const;
 632
 633     /**
 634         wxWidgets compatibility conversion. Same as c_str().
 635     */
 636     const wxCStrData GetData() const;
 637
 638     /**
 639         Returns a reference to the character at position @e n.
 640     */
 641     wxUniCharRef GetWritableChar(size_t n);
 642
 643     /**
 644         Returns a writable buffer of at least @a len bytes.
 645         It returns a pointer to a new memory block, and the
 646         existing data will not be copied.
 647         Call UngetWriteBuf() as soon as possible to put the
 648         string back into a reasonable state.
 649         This method is deprecated, please use wxStringBuffer or
 650         wxStringBufferLength instead.
 651     */
 652     wxStringCharType* GetWriteBuf(size_t len);
 653
 654     /**
 655         Returns @true if the string contains only ASCII characters.
 656         See wxUniChar::IsAscii for more details.
 657
 658         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 659         code.
 660     */
 661     bool IsAscii() const;
 662
 663     /**
 664         Returns @true if the string is empty.
 665     */
 666     bool IsEmpty() const;
 667
 668     /**
 669         Returns @true if the string is empty (same as wxString::IsEmpty).
 670         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 671         code.
 672     */
 673     bool IsNull() const;
 674
 675     /**
 676         Returns @true if the string is an integer (with possible sign).
 677         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 678         code.
 679     */
 680     bool IsNumber() const;
 681
 682     //@{
 683     /**
 684         Test whether the string is equal to the single character @e c. The test is
 685         case-sensitive if @a caseSensitive is @true (default) or not if it is @c
 686         @false.
 687         Returns @true if the string is equal to the character, @false otherwise.
 688         See also Cmp(), CmpNoCase()
 689     */
 690     bool IsSameAs(const wxString &s, bool caseSensitive = true) const;
 691     bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const;
 692     //@}
 693
 694     /**
 695         Returns @true if the string is a word.
 696         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 697         code.
 698     */
 699     bool IsWord() const;
 700
 701     //@{
 702     /**
 703         Returns a reference to the last character (writable).
 704         This is a wxWidgets 1.xx compatibility function;
 705         you should not use it in new code.
 706     */
 707     wxUniCharRef Last();
 708     const wxUniChar Last();
 709     //@}
 710
 711     /**
 712         Returns the first @a count characters of the string.
 713     */
 714     wxString Left(size_t count) const;
 715
 716     /**
 717         Returns the length of the string.
 718     */
 719     size_t Len() const;
 720
 721     /**
 722         Returns the length of the string (same as Len).
 723         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 724         code.
 725     */
 726     size_t Length() const;
 727
 728     /**
 729         Returns this string converted to the lower case.
 730
 731         @see MakeLower()
 732     */
 733     wxString Lower() const;
 734
 735     /**
 736         Same as MakeLower.
 737         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 738         code.
 739     */
 740     void LowerCase();
 741
 742     /**
 743         Converts the first characters of the string to the upper case and all
 744         the subsequent ones to the lower case and returns the result.
 745
 746         @since 2.9.0
 747
 748         @see Capitalize()
 749     */
 750     wxString& MakeCapitalized();
 751
 752     /**
 753         Converts all characters to lower case and returns the reference to the
 754         modified string.
 755
 756         @see Lower()
 757     */
 758     wxString& MakeLower();
 759
 760     /**
 761         Converts all characters to upper case and returns the reference to the
 762         modified string.
 763
 764         @see Upper()
 765     */
 766     wxString& MakeUpper();
 767
 768     /**
 769         Returns @true if the string contents matches a mask containing '*' and '?'.
 770     */
 771     bool Matches(const wxString& mask) const;
 772
 773     /**
 774         Returns a substring starting at @e first, with length @e count, or the rest of
 775         the string if @a count is the default value.
 776     */
 777     wxString Mid(size_t first, size_t nCount = wxString::npos) const;
 778
 779
 780     /**
 781         Adds @a count copies of @a pad to the beginning, or to the end of the
 782         string (the default).  Removes spaces from the left or from the right (default).
 783     */
 784     wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true);
 785
 786     /**
 787         Prepends @a str to this string, returning a reference to this string.
 788     */
 789     wxString& Prepend(const wxString& str);
 790
 791     /**
 792         Similar to the standard function @e sprintf(). Returns the number of
 793         characters written, or an integer less than zero on error.
 794         Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
 795         Unix98-style positional parameters:
 796
 797         @note This function will use a safe version of @e vsprintf() (usually called
 798         @e vsnprintf()) whenever available to always allocate the buffer of correct
 799         size. Unfortunately, this function is not available on all platforms and the
 800         dangerous @e vsprintf() will be used then which may lead to buffer overflows.
 801     */
 802     int Printf(const wxString& pszFormat, ...);
 803
 804     /**
 805         Similar to vprintf. Returns the number of characters written, or an integer
 806         less than zero
 807         on error.
 808     */
 809     int PrintfV(const wxString& pszFormat, va_list argPtr);
 810
 811     //@{
 812     /**
 813         Removes @a len characters from the string, starting at @e pos.
 814         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 815         code.
 816     */
 817     wxString Remove(size_t pos);
 818     wxString Remove(size_t pos, size_t len);
 819     //@}
 820
 821     /**
 822         Removes the last character.
 823     */
 824     wxString& RemoveLast(size_t n = 1);
 825
 826     /**
 827         Replace first (or all) occurrences of substring with another one.
 828         @e replaceAll: global replace (default), or only the first occurrence.
 829         Returns the number of replacements made.
 830     */
 831     size_t Replace(const wxString& strOld, const wxString& strNew,
 832                    bool replaceAll = true);
 833
 834     /**
 835         Returns the last @a count characters.
 836     */
 837     wxString Right(size_t count) const;
 838
 839     /**
 840         Sets the character at position @e n.
 841     */
 842     void SetChar(size_t n, wxUniChar ch);
 843
 844     /**
 845         Minimizes the string's memory. This can be useful after a call to
 846         Alloc() if too much memory were preallocated.
 847     */
 848     bool Shrink();
 849
 850     /**
 851         This function can be used to test if the string starts with the specified
 852         @e prefix. If it does, the function will return @true and put the rest
 853         of the string (i.e. after the prefix) into @a rest string if it is not
 854         @NULL. Otherwise, the function returns @false and doesn't modify the
 855         @e rest.
 856     */
 857     bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;
 858
 859     /**
 860         Strip characters at the front and/or end. The same as Trim except that it
 861         doesn't change this string.
 862         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 863         code.
 864     */
 865     wxString Strip(stripType s = trailing) const;
 866
 867     /**
 868         Returns the part of the string between the indices @a from and @e to
 869         inclusive.
 870         This is a wxWidgets 1.xx compatibility function, use Mid()
 871         instead (but note that parameters have different meaning).
 872     */
 873     wxString SubString(size_t from, size_t to) const;
 874
 875     //@{
 876     /**
 877         Converts the string to an 8-bit string in ISO-8859-1 encoding in the
 878         form of a wxCharBuffer (Unicode builds only).
 879
 880         This is a convenience method useful when storing binary data in
 881         wxString. It should be used @em only for this purpose. It is only valid
 882         to call this method on strings created using From8BitData().
 883
 884         @since 2.8.4
 885
 886         @see wxString::From8BitData()
 887     */
 888     const char* To8BitData() const;
 889     const wxCharBuffer To8BitData() const;
 890     //@}
 891
 892     //@{
 893     /**
 894         Converts the string to an ASCII, 7-bit string in the form of
 895         a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
 896         Note that this conversion only works if the string contains only ASCII
 897         characters. The @ref mb_str() "mb_str" method provides more
 898         powerful means of converting wxString to C string.
 899     */
 900     const char* ToAscii() const;
 901     const wxCharBuffer ToAscii() const;
 902     //@}
 903
 904     /**
 905         Attempts to convert the string to a floating point number. Returns @true on
 906         success (the number is stored in the location pointed to by @e val) or @false
 907         if the string does not represent such number (the value of @a val is not
 908         modified in this case).
 909
 910         @see ToLong(), ToULong()
 911     */
 912     bool ToDouble(double* val) const;
 913
 914     /**
 915         Attempts to convert the string to a signed integer in base @e base. Returns
 916         @true on success in which case the number is stored in the location
 917         pointed to by @a val or @false if the string does not represent a
 918         valid number in the given base (the value of @a val is not modified
 919         in this case).
 920         The value of @a base must be comprised between 2 and 36, inclusive, or
 921         be a special value 0 which means that the usual rules of @c C numbers are
 922         applied: if the number starts with @c 0x it is considered to be in base
 923         16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
 924         that you may not want to specify the base 0 if you are parsing the numbers
 925         which may have leading zeroes as they can yield unexpected (to the user not
 926         familiar with C) results.
 927
 928         @see ToDouble(), ToULong()
 929     */
 930     bool ToLong(long* val, int base = 10) const;
 931
 932     /**
 933         This is exactly the same as ToLong() but works with 64
 934         bit integer numbers.
 935         Notice that currently it doesn't work (always returns @false) if parsing of 64
 936         bit numbers is not supported by the underlying C run-time library. Compilers
 937         with C99 support and Microsoft Visual C++ version 7 and higher do support this.
 938
 939         @see ToLong(), ToULongLong()
 940     */
 941     bool ToLongLong(wxLongLong_t* val, int base = 10) const;
 942
 943     /**
 944         Attempts to convert the string to an unsigned integer in base @e base.
 945         Returns @true on success in which case the number is stored in the
 946         location pointed to by @a val or @false if the string does not
 947         represent a valid number in the given base (the value of @a val is not
 948         modified in this case).
 949
 950         Please notice that this function  behaves in the same way as the standard
 951         @c strtoul() and so it simply converts negative numbers to unsigned
 952         representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
 953
 954         See ToLong() for the more detailed description of the @a base parameter.
 955
 956         @see ToDouble(), ToLong()
 957     */
 958     bool ToULong(unsigned long* val, int base = 10) const;
 959
 960     /**
 961         This is exactly the same as ToULong() but works with 64
 962         bit integer numbers.
 963         Please see ToLongLong() for additional remarks.
 964     */
 965     bool ToULongLong(wxULongLong_t* val, int base = 10) const;
 966
 967     //@{
 968     /**
 969         Same as utf8_str().
 970     */
 971     const char* ToUTF8() const;
 972     const wxCharBuffer ToUTF8() const;
 973     //@}
 974
 975     /**
 976         Removes white-space (space, tabs, form feed, newline and carriage return) from
 977         the left or from the right end of the string (right is default).
 978     */
 979     wxString& Trim(bool fromRight = true);
 980
 981     /**
 982         Truncate the string to the given length.
 983     */
 984     wxString& Truncate(size_t len);
 985
 986     //@{
 987     /**
 988         Puts the string back into a reasonable state (in which it can be used
 989         normally), after GetWriteBuf() was called.
 990
 991         The version of the function without the @a len parameter will calculate the
 992         new string length itself assuming that the string is terminated by the first
 993         @c NUL character in it while the second one will use the specified length
 994         and thus is the only version which should be used with the strings with
 995         embedded @c NULs (it is also slightly more efficient as @c strlen()
 996         doesn't have to be called).
 997
 998         This method is deprecated, please use wxStringBuffer or
 999         wxStringBufferLength instead.
1000     */
1001     void UngetWriteBuf();
1002     void UngetWriteBuf(size_t len);
1003     //@}
1004
1005     /**
1006         Returns this string converted to upper case.
1007
1008         @see MakeUpper()
1009     */
1010     wxString Upper() const;
1011
1012     /**
1013         The same as MakeUpper().
1014
1015         This is a wxWidgets 1.xx compatibility function; you should not use it in new
1016         code.
1017     */
1018     void UpperCase();
1019
1020     /**
1021         Returns a lightweight intermediate class which is in turn implicitly
1022         convertible to both @c const @c char* and to @c const @c wchar_t*.
1023         Given this ambiguity it is mostly better to use wc_str(), mb_str() or
1024         utf8_str() instead.
1025
1026         Please see the @ref overview_unicode for more information about it.
1027
1028         Note that the returned value is not convertible to @c char* or
1029         @c wchar_t*, use char_str() or wchar_str() if you need to pass
1030         string value to a function expecting non-const pointer.
1031
1032         @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
1033     */
1034     wxCStrData c_str() const;
1035
1036     /**
1037         Returns an object with string data that is implicitly convertible to
1038         @c char* pointer. Note that any change to the returned buffer is lost and so
1039         this function is only usable for passing strings to legacy libraries that
1040         don't have const-correct API. Use wxStringBuffer if you want to modify
1041         the string.
1042
1043         @see c_str()
1044     */
1045     wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
1046
1047     /**
1048         Returns buffer of the specified type containing the string data.
1049
1050         This method is only useful in template code, otherwise you should
1051         directly call mb_str() or wc_str() if you need to retrieve a narrow or
1052         wide string from this wxString. The template parameter @a t should be
1053         either @c char or @c wchar_t.
1054
1055         Notice that retrieving a char buffer in UTF-8 build will return the
1056         internal string representation in UTF-8 while in wchar_t build the char
1057         buffer will contain the conversion of the string to the encoding of the
1058         current locale (and so can fail).
1059
1060         @param len
1061             If non-@NULL, filled with the length of the returned buffer.
1062
1063         @return
1064             buffer containing the string contents in the specified type,
1065             notice that it may be @NULL if the conversion failed (e.g. Unicode
1066             string couldn't be converted to the current encoding when @a T is
1067             @c char).
1068      */
1069     template <typename T>
1070     wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const;
1071
1072     //@{
1073     /**
1074         Returns string representation suitable for passing to OS' functions
1075         for file handling.
1076     */
1077     const wchar_t* fn_str() const;
1078     const char* fn_str() const;
1079     const wxCharBuffer fn_str() const;
1080     //@}
1081
1082     /**
1083         Returns the multibyte (C string) representation of the string
1084         using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
1085
1086         @see wc_str(), utf8_str(), c_str(), wxMBConv
1087     */
1088     const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
1089
1090     /**
1091         Extraction from a stream.
1092     */
1093     friend istream operator>>(istream& is, wxString& str);
1094
1095     //@{
1096     /**
1097         These functions work as C++ stream insertion operators. They insert the
1098         given value into the string. Precision and format cannot be set using them.
1099         Use Printf() instead.
1100     */
1101     wxString& operator<<(const wxString& s);
1102     wxString& operator<<(const char* psz);
1103     wxString& operator<<(const wchar_t* pwz);
1104     wxString& operator<<(const wxCStrData& psz);
1105     wxString& operator<<(char ch);
1106     wxString& operator<<(unsigned char ch);
1107     wxString& operator<<(wchar_t ch);
1108     wxString& operator<<(const wxCharBuffer& s);
1109     wxString& operator<<(const wxWCharBuffer& s);
1110     wxString& operator<<(wxUniCharRef ch);
1111     wxString& operator<<(unsigned int ui);
1112     wxString& operator<<(long l);
1113     wxString& operator<<(unsigned long ul);
1114     wxString& operator<<(wxLongLong_t ll);
1115     wxString& operator<<(wxULongLong_t ul);
1116     wxString& operator<<(float f);
1117     wxString& operator<<(double d);
1118     //@}
1119
1120     /**
1121         Same as Mid() (substring extraction).
1122     */
1123     wxString operator()(size_t start, size_t len) const;
1124
1125     //@{
1126     /**
1127         Concatenation: these operators return a new string equal to the
1128         concatenation of the operands.
1129     */
1130     wxString operator +(const wxString& x, const wxString& y);
1131     wxString operator +(const wxString& x, wxUniChar y);
1132     //@}
1133
1134     //@{
1135     /**
1136         Concatenation in place: the argument is appended to the string.
1137     */
1138     void operator +=(const wxString& str);
1139     void operator +=(wxUniChar c);
1140     //@}
1141
1142     //@{
1143     /**
1144         Assignment: the effect of each operation is the same as for the corresponding
1145         constructor (see wxString constructors).
1146     */
1147     wxString operator =(const wxString& str);
1148     wxString operator =(wxUniChar c);
1149     //@}
1150
1151     //@{
1152     /**
1153         Element extraction.
1154     */
1155     wxUniChar operator [](size_t i) const;
1156     wxUniCharRef operator [](size_t i);
1157     //@}
1158
1159     /**
1160         Empty string is @false, so !string will only return @true if the
1161         string is empty.
1162
1163         See also IsEmpty().
1164     */
1165     bool operator!() const;
1166
1167
1168     //@{
1169     /**
1170         Converts the strings contents to UTF-8 and returns it either as a
1171         temporary wxCharBuffer object or as a pointer to the internal
1172         string contents in UTF-8 build.
1173
1174         @see wc_str(), c_str(), mb_str()
1175     */
1176     const char* utf8_str() const;
1177     const wxCharBuffer utf8_str() const;
1178     //@}
1179
1180     //@{
1181     /**
1182         Converts the strings contents to the wide character represention
1183         and returns it as a temporary wxWCharBuffer object (Unix and OS X)
1184         or returns a pointer to the internal string contents in wide character
1185         mode (Windows).
1186
1187         The macro wxWX2WCbuf is defined as the correct return
1188         type (without const).
1189
1190         @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
1191     */
1192     const wchar_t* wc_str() const;
1193     const wxWCharBuffer wc_str() const;
1194     //@}
1195
1196     /**
1197         Returns an object with string data that is implicitly convertible to
1198         @c char* pointer. Note that changes to the returned buffer may or may
1199         not be lost (depending on the build) and so this function is only usable for
1200         passing strings to legacy libraries that don't have const-correct API. Use
1201         wxStringBuffer if you want to modify the string.
1202
1203         @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
1204     */
1205     wxWritableWCharBuffer wchar_str() const;
1206
1207     /**
1208        Explicit conversion to C string in the internal representation (either
1209        wchar_t* or UTF-8-encoded char*, depending on the build).
1210     */
1211     const wxStringCharType *wx_str() const;
1212
1213
1214     /**
1215         @name Iterator interface
1216
1217         These methods return iterators to the beginnnig or
1218         end of the string.
1219     */
1220     //@{
1221         const_iterator begin() const;
1222         iterator begin();
1223         const_iterator end() const;
1224         iterator end();
1225
1226         const_reverse_iterator rbegin() const;
1227         reverse_iterator rbegin();
1228         const_reverse_iterator rend() const;
1229         reverse_iterator rend();
1230     //@}
1231
1232     /**
1233         @name STL interface
1234
1235         The supported STL functions are listed here. Please see any
1236         STL reference for their documentation.
1237     */
1238     //@{
1239         wxString& append(const wxString& str, size_t pos, size_t n);
1240         wxString& append(const wxString& str);
1241         wxString& append(const char *sz, size_t n);
1242         wxString& append(const wchar_t *sz, size_t n);
1243         wxString& append(size_t n, wxUniChar ch);
1244         wxString& append(const_iterator first, const_iterator last);
1245
1246         wxString& assign(const wxString& str, size_t pos, size_t n);
1247         wxString& assign(const wxString& str);
1248         wxString& assign(const char *sz, size_t n);
1249         wxString& assign(const wchar_t *sz, size_t n);
1250         wxString& assign(size_t n, wxUniChar ch);
1251         wxString& assign(const_iterator first, const_iterator last);
1252
1253         wxUniChar at(size_t n) const;
1254         wxUniCharRef at(size_t n);
1255
1256         void clear();
1257
1258         size_type capacity() const;
1259
1260         int compare(const wxString& str) const;
1261         int compare(size_t nStart, size_t nLen, const wxString& str) const;
1262         int compare(size_t nStart, size_t nLen,
1263               const wxString& str, size_t nStart2, size_t nLen2) const;
1264         int compare(size_t nStart, size_t nLen,
1265               const char* sz, size_t nCount = npos) const;
1266         int compare(size_t nStart, size_t nLen,
1267               const wchar_t* sz, size_t nCount = npos) const;
1268
1269         wxCStrData data() const;
1270
1271         bool empty() const;
1272
1273         wxString& erase(size_type pos = 0, size_type n = npos);
1274         iterator erase(iterator first, iterator last);
1275         iterator erase(iterator first);
1276
1277         size_t find(const wxString& str, size_t nStart = 0) const;
1278         size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
1279         size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const;
1280         size_t find(wxUniChar ch, size_t nStart = 0) const;
1281         size_t find_first_of(const char* sz, size_t nStart = 0) const;
1282         size_t find_first_of(const wchar_t* sz, size_t nStart = 0) const;
1283         size_t find_first_of(const char* sz, size_t nStart, size_t n) const;
1284         size_t find_first_of(const wchar_t* sz, size_t nStart, size_t n) const;
1285         size_t find_first_of(wxUniChar c, size_t nStart = 0) const;
1286         size_t find_last_of (const wxString& str, size_t nStart = npos) const;
1287         size_t find_last_of (const char* sz, size_t nStart = npos) const;
1288         size_t find_last_of (const wchar_t* sz, size_t nStart = npos) const;
1289         size_t find_last_of(const char* sz, size_t nStart, size_t n) const;
1290         size_t find_last_of(const wchar_t* sz, size_t nStart, size_t n) const;
1291         size_t find_last_of(wxUniChar c, size_t nStart = npos) const;
1292         size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
1293         size_t find_first_not_of(const char* sz, size_t nStart = 0) const;
1294         size_t find_first_not_of(const wchar_t* sz, size_t nStart = 0) const;
1295         size_t find_first_not_of(const char* sz, size_t nStart, size_t n) const;
1296         size_t find_first_not_of(const wchar_t* sz, size_t nStart, size_t n) const;
1297         size_t find_first_not_of(wxUniChar ch, size_t nStart = 0) const;
1298         size_t find_last_not_of(const wxString& str, size_t nStart = npos) const;
1299         size_t find_last_not_of(const char* sz, size_t nStart = npos) const;
1300         size_t find_last_not_of(const wchar_t* sz, size_t nStart = npos) const;
1301         size_t find_last_not_of(const char* sz, size_t nStart, size_t n) const;
1302         size_t find_last_not_of(const wchar_t* sz, size_t nStart, size_t n) const;
1303
1304         wxString& insert(size_t nPos, const wxString& str);
1305         wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);
1306         wxString& insert(size_t nPos, const char *sz, size_t n);
1307         wxString& insert(size_t nPos, const wchar_t *sz, size_t n);
1308         wxString& insert(size_t nPos, size_t n, wxUniChar ch);
1309         iterator insert(iterator it, wxUniChar ch);
1310         void insert(iterator it, const_iterator first, const_iterator last);
1311         void insert(iterator it, size_type n, wxUniChar ch);
1312
1313         size_t length() const;
1314
1315         size_type max_size() const;
1316
1317         void reserve(size_t sz);
1318         void resize(size_t nSize, wxUniChar ch = '\0');
1319
1320         wxString& replace(size_t nStart, size_t nLen, const wxString& str);
1321         wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch);
1322         wxString& replace(size_t nStart, size_t nLen,
1323                           const wxString& str, size_t nStart2, size_t nLen2);
1324         wxString& replace(size_t nStart, size_t nLen,
1325                           const char* sz, size_t nCount);
1326         wxString& replace(size_t nStart, size_t nLen,
1327                           const wchar_t* sz, size_t nCount);
1328         wxString& replace(size_t nStart, size_t nLen,
1329                           const wxString& s, size_t nCount);
1330         wxString& replace(iterator first, iterator last, const wxString& s);
1331         wxString& replace(iterator first, iterator last, const char* s, size_type n);
1332         wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n);
1333         wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch);
1334         wxString& replace(iterator first, iterator last,
1335                           const_iterator first1, const_iterator last1);
1336         wxString& replace(iterator first, iterator last,
1337                           const char *first1, const char *last1);
1338         wxString& replace(iterator first, iterator last,
1339                           const wchar_t *first1, const wchar_t *last1);
1340
1341         size_t rfind(const wxString& str, size_t nStart = npos) const;
1342         size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const;
1343         size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const;
1344         size_t rfind(wxUniChar ch, size_t nStart = npos) const;
1345
1346         size_type size() const;
1347         wxString substr(size_t nStart = 0, size_t nLen = npos) const;
1348         void swap(wxString& str);
1349     //@}
1350 };
1351
1352 /** @addtogroup group_string_operators */
1353 //@{
1354 /**
1355     Comparison operators for wxString.
1356 */
1357 inline bool operator==(const wxString& s1, const wxString& s2);
1358 inline bool operator!=(const wxString& s1, const wxString& s2);
1359 inline bool operator< (const wxString& s1, const wxString& s2);
1360 inline bool operator> (const wxString& s1, const wxString& s2);
1361 inline bool operator<=(const wxString& s1, const wxString& s2);
1362 inline bool operator>=(const wxString& s1, const wxString& s2);
1363 inline bool operator==(const wxString& s1, const wxCStrData& s2);
1364 inline bool operator==(const wxCStrData& s1, const wxString& s2);
1365 inline bool operator!=(const wxString& s1, const wxCStrData& s2);
1366 inline bool operator!=(const wxCStrData& s1, const wxString& s2);
1367 inline bool operator==(const wxString& s1, const wxWCharBuffer& s2);
1368 inline bool operator==(const wxWCharBuffer& s1, const wxString& s2);
1369 inline bool operator!=(const wxString& s1, const wxWCharBuffer& s2);
1370 inline bool operator!=(const wxWCharBuffer& s1, const wxString& s2);
1371 inline bool operator==(const wxString& s1, const wxCharBuffer& s2);
1372 inline bool operator==(const wxCharBuffer& s1, const wxString& s2);
1373 inline bool operator!=(const wxString& s1, const wxCharBuffer& s2);
1374 inline bool operator!=(const wxCharBuffer& s1, const wxString& s2);
1375
1376 /**
1377     Comparison operators with wxUniChar or wxUniCharRef.
1378 */
1379 inline bool operator==(const wxUniChar& c, const wxString& s);
1380 inline bool operator==(const wxUniCharRef& c, const wxString& s);
1381 inline bool operator==(char c, const wxString& s);
1382 inline bool operator==(wchar_t c, const wxString& s);
1383 inline bool operator==(int c, const wxString& s);
1384 inline bool operator==(const wxString& s, const wxUniChar& c);
1385 inline bool operator==(const wxString& s, const wxUniCharRef& c);
1386 inline bool operator==(const wxString& s, char c);
1387 inline bool operator==(const wxString& s, wchar_t c);
1388 inline bool operator!=(const wxUniChar& c, const wxString& s);
1389 inline bool operator!=(const wxUniCharRef& c, const wxString& s);
1390 inline bool operator!=(char c, const wxString& s);
1391 inline bool operator!=(wchar_t c, const wxString& s);
1392 inline bool operator!=(int c, const wxString& s);
1393 inline bool operator!=(const wxString& s, const wxUniChar& c);
1394 inline bool operator!=(const wxString& s, const wxUniCharRef& c);
1395 inline bool operator!=(const wxString& s, char c);
1396 inline bool operator!=(const wxString& s, wchar_t c);
1397 //@}
1398
1399 /**
1400     The global wxString instance of an empty string.
1401     Used extensively in the entire wxWidgets API.
1402 */
1403 wxString wxEmptyString;
1404
1405
1406
1407
1408 /**
1409     @class wxStringBufferLength
1410
1411     This tiny class allows you to conveniently access the wxString internal buffer
1412     as a writable pointer without any risk of forgetting to restore the string to
1413     the usable state later, and allows the user to set the internal length of the string.
1414
1415     For example, assuming you have a low-level OS function called
1416     @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided
1417     buffer (which must be writable, of course), and returning the actual length
1418     of the string, you might call it like this:
1419
1420     @code
1421         wxString theAnswer;
1422         wxStringBuffer theAnswerBuffer(theAnswer, 1024);
1423         int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
1424         theAnswerBuffer.SetLength(nLength);
1425         if ( theAnswer != "42" )
1426             wxLogError("Something is very wrong!");
1427     @endcode
1428
1429     @todo
1430         the example above does not make use of wxStringBufferLength??
1431
1432     Note that the exact usage of this depends on whether or not wxUSE_STL is
1433     enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
1434     character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
1435     wxString, keeping the same buffer wxString uses intact. In other words,
1436     relying on wxStringBuffer containing the old wxString data is not a good
1437     idea if you want to build your program both with and without wxUSE_STL.
1438
1439     Note that wxStringBuffer::SetLength @b must be called before
1440     wxStringBufferLength destructs.
1441
1442     @library{wxbase}
1443     @category{data}
1444 */
1445 class wxStringBufferLength
1446 {
1447 public:
1448     /**
1449         Constructs a writable string buffer object associated with the given string
1450         and containing enough space for at least @a len characters.
1451
1452         Basically, this is equivalent to calling wxString::GetWriteBuf and
1453         saving the result.
1454     */
1455     wxStringBufferLength(const wxString& str, size_t len);
1456
1457     /**
1458         Restores the string passed to the constructor to the usable state by calling
1459         wxString::UngetWriteBuf on it.
1460     */
1461     ~wxStringBufferLength();
1462
1463     /**
1464         Sets the internal length of the string referred to by wxStringBufferLength to
1465         @a nLength characters.
1466
1467         Must be called before wxStringBufferLength destructs.
1468     */
1469     void SetLength(size_t nLength);
1470
1471     /**
1472         Returns the writable pointer to a buffer of the size at least equal to the
1473         length specified in the constructor.
1474     */
1475     wxChar* operator wxChar *();
1476 };
1477
1478
1479 /**
1480     @class wxStringBuffer
1481
1482     This tiny class allows you to conveniently access the wxString internal buffer
1483     as a writable pointer without any risk of forgetting to restore the string
1484     to the usable state later.
1485
1486     For example, assuming you have a low-level OS function called
1487     @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided
1488     buffer (which must be writable, of course) you might call it like this:
1489
1490     @code
1491         wxString theAnswer;
1492         GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
1493         if ( theAnswer != "42" )
1494             wxLogError("Something is very wrong!");
1495     @endcode
1496
1497     Note that the exact usage of this depends on whether or not @c wxUSE_STL is
1498     enabled. If @c wxUSE_STL is enabled, wxStringBuffer creates a separate empty
1499     character buffer, and if @c wxUSE_STL is disabled, it uses GetWriteBuf() from
1500     wxString, keeping the same buffer wxString uses intact. In other words,
1501     relying on wxStringBuffer containing the old wxString data is not a good
1502     idea if you want to build your program both with and without @c wxUSE_STL.
1503
1504     @library{wxbase}
1505     @category{data}
1506 */
1507 class wxStringBuffer
1508 {
1509 public:
1510     /**
1511         Constructs a writable string buffer object associated with the given string
1512         and containing enough space for at least @a len characters.
1513         Basically, this is equivalent to calling wxString::GetWriteBuf() and
1514         saving the result.
1515     */
1516     wxStringBuffer(const wxString& str, size_t len);
1517
1518     /**
1519         Restores the string passed to the constructor to the usable state by calling
1520         wxString::UngetWriteBuf() on it.
1521     */
1522     ~wxStringBuffer();
1523
1524     /**
1525         Returns the writable pointer to a buffer of the size at least equal to the
1526         length specified in the constructor.
1527     */
1528     wxStringCharType* operator wxStringCharType *();
1529 };
1530
1531
1532 /** @addtogroup group_funcmacro_string */
1533 //@{
1534
1535 /**
1536     Allows to extend a function with the signature:
1537     @code bool SomeFunc(const wxUniChar& c) @endcode
1538     which operates on a single character, to an entire wxString.
1539
1540     E.g. if you want to check if an entire string contains only digits,
1541     you can do:
1542     @code
1543         if (wxStringCheck<wxIsdigit>(myString))
1544             ... // the entire string contains oly digits!
1545         else
1546             ... // at least one character of myString is not a digit
1547     @endcode
1548
1549     @return @true if the given function returns a non-zero value for all
1550             characters of the @a val string.
1551 */
1552 template<bool (T)(const wxUniChar& c)>
1553     inline bool wxStringCheck(const wxString& val);
1554
1555 //@}