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