interface/string.h

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