interface/wx/string.h

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