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