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