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