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