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