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