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