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