interface/string.h

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