interface/wx/string.h

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