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
 627         If @a s is not a valid UTF-8 string, an empty string is returned.
 628
 629         Notice that when using UTF-8 wxWidgets build there is a more efficient
 630         alternative to this function called FromUTF8Unchecked() which, unlike
 631         this one, doesn't check that the input string is valid.
 632
 633         @since 2.8.4
 634     */
 635     static wxString FromUTF8(const char* s);
 636     static wxString FromUTF8(const char* s, size_t len);
 637     //@}
 638
 639     //@{
 640     /**
 641         Converts C string encoded in UTF-8 to wxString without checking its
 642         validity.
 643
 644         This method assumes that @a s is a valid UTF-8 sequence and doesn't do
 645         any validation (although an assert failure is triggered in debug builds
 646         if the string is invalid). Only use it if you are absolutely sure that
 647         @a s is a correct UTF-8 string (e.g. because it comes from another
 648         library using UTF-8) and if the performance matters, otherwise use
 649         slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8
 650         string to this function will result in creating a corrupted wxString
 651         and all the subsequent operations on it will be undefined.
 652
 653         @since 2.8.9
 654     */
 655     static wxString FromUTF8Unchecked(const char* s);
 656     static wxString FromUTF8Unchecked(const char* s, size_t len);
 657     //@}
 658
 659     /**
 660         Returns the character at position @a n (read-only).
 661     */
 662     wxUniChar GetChar(size_t n) const;
 663
 664     /**
 665         wxWidgets compatibility conversion. Same as c_str().
 666     */
 667     const wxCStrData* GetData() const;
 668
 669     /**
 670         Returns a reference to the character at position @e n.
 671     */
 672     wxUniCharRef GetWritableChar(size_t n);
 673
 674     /**
 675         Returns a writable buffer of at least @a len bytes.
 676         It returns a pointer to a new memory block, and the
 677         existing data will not be copied.
 678         Call UngetWriteBuf() as soon as possible to put the
 679         string back into a reasonable state.
 680         This method is deprecated, please use wxStringBuffer or
 681         wxStringBufferLength instead.
 682     */
 683     wxStringCharType* GetWriteBuf(size_t len);
 684
 685     /**
 686         Returns @true if the string contains only ASCII characters.
 687         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 688         code.
 689     */
 690     bool IsAscii() const;
 691
 692     /**
 693         Returns @true if the string is empty.
 694     */
 695     bool IsEmpty() const;
 696
 697     /**
 698         Returns @true if the string is empty (same as wxString::IsEmpty).
 699         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 700         code.
 701     */
 702     bool IsNull() const;
 703
 704     /**
 705         Returns @true if the string is an integer (with possible sign).
 706         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 707         code.
 708     */
 709     bool IsNumber() const;
 710
 711     //@{
 712     /**
 713         Test whether the string is equal to the single character @e c. The test is
 714         case-sensitive if @a caseSensitive is @true (default) or not if it is @c
 715         @false.
 716         Returns @true if the string is equal to the character, @false otherwise.
 717         See also Cmp(), CmpNoCase()
 718     */
 719     bool IsSameAs(const wxString &s, bool caseSensitive = true) const;
 720     bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const;
 721     //@}
 722
 723     /**
 724         Returns @true if the string is a word.
 725         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 726         code.
 727     */
 728     bool IsWord() const;
 729
 730     //@{
 731     /**
 732         Returns a reference to the last character (writable).
 733         This is a wxWidgets 1.xx compatibility function;
 734         you should not use it in new code.
 735     */
 736     wxUniCharRef Last();
 737     const wxUniChar Last();
 738     //@}
 739
 740     /**
 741         Returns the first @a count characters of the string.
 742     */
 743     wxString Left(size_t count) const;
 744
 745     /**
 746         Returns the length of the string.
 747     */
 748     size_t Len() const;
 749
 750     /**
 751         Returns the length of the string (same as Len).
 752         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 753         code.
 754     */
 755     size_t Length() const;
 756
 757     /**
 758         Returns this string converted to the lower case.
 759     */
 760     wxString Lower() const;
 761
 762     /**
 763         Same as MakeLower.
 764         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 765         code.
 766     */
 767     void LowerCase();
 768
 769     /**
 770         Converts all characters to lower case and returns the result.
 771     */
 772     wxString& MakeLower();
 773
 774     /**
 775         Converts all characters to upper case and returns the result.
 776     */
 777     wxString& MakeUpper();
 778
 779     /**
 780         Returns @true if the string contents matches a mask containing '*' and '?'.
 781     */
 782     bool Matches(const wxString& mask) const;
 783
 784     /**
 785         Returns a substring starting at @e first, with length @e count, or the rest of
 786         the string if @a count is the default value.
 787     */
 788     wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const;
 789
 790
 791     /**
 792         Adds @a count copies of @a pad to the beginning, or to the end of the
 793         string (the default).  Removes spaces from the left or from the right (default).
 794     */
 795     wxString& Pad(size_t count, wxUniChar pad = ' ',
 796                  bool fromRight = true);
 797
 798     /**
 799         Prepends @a str to this string, returning a reference to this string.
 800     */
 801     wxString& Prepend(const wxString& str);
 802
 803     /**
 804         Similar to the standard function @e sprintf(). Returns the number of
 805         characters written, or an integer less than zero on error.
 806         Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
 807         Unix98-style positional parameters:
 808
 809         @note This function will use a safe version of @e vsprintf() (usually called
 810         @e vsnprintf()) whenever available to always allocate the buffer of correct
 811         size. Unfortunately, this function is not available on all platforms and the
 812         dangerous @e vsprintf() will be used then which may lead to buffer overflows.
 813     */
 814     int Printf(const wxChar* pszFormat, ...);
 815
 816     /**
 817         Similar to vprintf. Returns the number of characters written, or an integer
 818         less than zero
 819         on error.
 820     */
 821     int PrintfV(const wxChar* pszFormat, va_list argPtr);
 822
 823     //@{
 824     /**
 825         Removes @a len characters from the string, starting at @e pos.
 826         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 827         code.
 828     */
 829     wxString Remove(size_t pos);
 830     wxString Remove(size_t pos, size_t len);
 831     //@}
 832
 833     /**
 834         Removes the last character.
 835     */
 836     wxString RemoveLast();
 837
 838     /**
 839         Replace first (or all) occurrences of substring with another one.
 840         @e replaceAll: global replace (default), or only the first occurrence.
 841         Returns the number of replacements made.
 842     */
 843     size_t Replace(const wxString& strOld, const wxString& strNew,
 844                    bool replaceAll = true);
 845
 846     /**
 847         Returns the last @a count characters.
 848     */
 849     wxString Right(size_t count) const;
 850
 851     /**
 852         Sets the character at position @e n.
 853     */
 854     void SetChar(size_t n, wxUniChar ch);
 855
 856     /**
 857         Minimizes the string's memory. This can be useful after a call to
 858         Alloc() if too much memory were preallocated.
 859     */
 860     void Shrink();
 861
 862     /**
 863         This function can be used to test if the string starts with the specified
 864         @e prefix. If it does, the function will return @true and put the rest
 865         of the string (i.e. after the prefix) into @a rest string if it is not
 866         @NULL. Otherwise, the function returns @false and doesn't modify the
 867         @e rest.
 868     */
 869     bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;
 870
 871     /**
 872         Strip characters at the front and/or end. The same as Trim except that it
 873         doesn't change this string.
 874         This is a wxWidgets 1.xx compatibility function; you should not use it in new
 875         code.
 876     */
 877     wxString Strip(stripType s = trailing) const;
 878
 879     /**
 880         Returns the part of the string between the indices @a from and @e to
 881         inclusive.
 882         This is a wxWidgets 1.xx compatibility function, use Mid()
 883         instead (but note that parameters have different meaning).
 884     */
 885     wxString SubString(size_t from, size_t to) const;
 886
 887     //@{
 888     /**
 889         Converts the string to an 8-bit string in ISO-8859-1 encoding in the
 890         form of a wxCharBuffer (Unicode builds only).
 891
 892         This is a convenience method useful when storing binary data in
 893         wxString. It should be used @em only for this purpose. It is only valid
 894         to call this method on strings created using From8BitData().
 895
 896         @since 2.8.4
 897
 898         @see wxString::From8BitData()
 899     */
 900     const char* To8BitData() const;
 901     const wxCharBuffer To8BitData() const;
 902     //@}
 903
 904     //@{
 905     /**
 906         Converts the string to an ASCII, 7-bit string in the form of
 907         a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
 908         Note that this conversion only works if the string contains only ASCII
 909         characters. The @ref mb_str() "mb_str" method provides more
 910         powerful means of converting wxString to C string.
 911     */
 912     const char* ToAscii() const;
 913     const wxCharBuffer ToAscii() const;
 914     //@}
 915
 916     /**
 917         Attempts to convert the string to a floating point number. Returns @true on
 918         success (the number is stored in the location pointed to by @e val) or @false
 919         if the string does not represent such number (the value of @a val is not
 920         modified in this case).
 921
 922         @see ToLong(), ToULong()
 923     */
 924     bool ToDouble(double val) const;
 925
 926     /**
 927         Attempts to convert the string to a signed integer in base @e base. Returns
 928         @true on success in which case the number is stored in the location
 929         pointed to by @a val or @false if the string does not represent a
 930         valid number in the given base (the value of @a val is not modified
 931         in this case).
 932         The value of @a base must be comprised between 2 and 36, inclusive, or
 933         be a special value 0 which means that the usual rules of @c C numbers are
 934         applied: if the number starts with @c 0x it is considered to be in base
 935         16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
 936         that you may not want to specify the base 0 if you are parsing the numbers
 937         which may have leading zeroes as they can yield unexpected (to the user not
 938         familiar with C) results.
 939
 940         @see ToDouble(), ToULong()
 941     */
 942     bool ToLong(long val, int base = 10) const;
 943
 944     /**
 945         This is exactly the same as ToLong() but works with 64
 946         bit integer numbers.
 947         Notice that currently it doesn't work (always returns @false) if parsing of 64
 948         bit numbers is not supported by the underlying C run-time library. Compilers
 949         with C99 support and Microsoft Visual C++ version 7 and higher do support this.
 950
 951         @see ToLong(), ToULongLong()
 952     */
 953     bool ToLongLong(wxLongLong_t val, int base = 10) const;
 954
 955     /**
 956         Attempts to convert the string to an unsigned integer in base @e base.
 957         Returns @true on success in which case the number is stored in the
 958         location pointed to by @a val or @false if the string does not
 959         represent a valid number in the given base (the value of @a val is not
 960         modified in this case). Please notice that this function
 961         behaves in the same way as the standard @c strtoul() and so it simply
 962         converts negative numbers to unsigned representation instead of rejecting them
 963         (e.g. -1 is returned as @c ULONG_MAX).
 964         See ToLong() for the more detailed
 965         description of the @a base parameter.
 966
 967         @see ToDouble(), ToLong()
 968     */
 969     bool ToULong(unsigned long val, int base = 10) const;
 970
 971     /**
 972         This is exactly the same as ToULong() but works with 64
 973         bit integer numbers.
 974         Please see ToLongLong() for additional remarks.
 975     */
 976     bool ToULongLong(wxULongLong_t val, int base = 10) const;
 977
 978     //@{
 979     /**
 980         Same as utf8_str().
 981     */
 982     const char* ToUTF8() const;
 983     const wxCharBuffer ToUTF8() const;
 984     //@}
 985
 986     /**
 987         Removes white-space (space, tabs, form feed, newline and carriage return) from
 988         the left or from the right end of the string (right is default).
 989     */
 990     wxString& Trim(bool fromRight = true);
 991
 992     /**
 993         Truncate the string to the given length.
 994     */
 995     wxString& Truncate(size_t len);
 996
 997     //@{
 998     /**
 999         Puts the string back into a reasonable state (in which it can be used
1000         normally), after
1001         GetWriteBuf() was called.
1002         The version of the function without the @a len parameter will calculate the
1003         new string length itself assuming that the string is terminated by the first
1004         @c NUL character in it while the second one will use the specified length
1005         and thus is the only version which should be used with the strings with
1006         embedded @c NULs (it is also slightly more efficient as @c strlen()
1007         doesn't have to be called).
1008         This method is deprecated, please use
1009         wxStringBuffer or
1010         wxStringBufferLength instead.
1011     */
1012     void UngetWriteBuf();
1013     void UngetWriteBuf(size_t len);
1014     //@}
1015
1016     /**
1017         Returns this string converted to upper case.
1018     */
1019     wxString Upper() const;
1020
1021     /**
1022         The same as MakeUpper.
1023         This is a wxWidgets 1.xx compatibility function; you should not use it in new
1024         code.
1025     */
1026     void UpperCase();
1027
1028     /**
1029         Returns a lightweight intermediate class which is in turn implicitly
1030         convertible to both @c const @c char* and to @c const @c wchar_t*.
1031         Given this ambiguity it is mostly better to use wc_str(), mb_str() or
1032         utf8_str() instead.
1033
1034         Please see the @ref overview_unicode "Unicode overview" for more
1035         information about it.
1036
1037         Note that the returned value is not convertible to @c char* or
1038         @c wchar_t*, use char_str() or wchar_str() if you need to pass
1039         string value to a function expecting non-const pointer.
1040
1041         @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
1042     */
1043     const wxCStrData c_str() const;
1044
1045     /**
1046         Returns an object with string data that is implicitly convertible to
1047         @c char* pointer. Note that any change to the returned buffer is lost and so
1048         this function is only usable for passing strings to legacy libraries that
1049         don't have const-correct API. Use wxStringBuffer if you want to modify
1050         the string.
1051
1052         @see c_str()
1053     */
1054     wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
1055
1056     /**
1057         Returns buffer of the specified type containing the string data.
1058
1059         This method is only useful in template code, otherwise you should
1060         directly call mb_str() or wc_str() if you need to retrieve a narrow or
1061         wide string from this wxString. The template parameter @a t should be
1062         either @c char or @c wchar_t.
1063
1064         Notice that retrieving a char buffer in UTF-8 build will return the
1065         internal string representation in UTF-8 while in wchar_t build the char
1066         buffer will contain the conversion of the string to the encoding of the
1067         current locale (and so can fail).
1068
1069         @param len If non-@NULL, filled with the length of the returned buffer.
1070         @return
1071             buffer containing the string contents in the specified type,
1072             notice that it may be @NULL if the conversion failed (e.g. Unicode
1073             string couldn't be converted to the current encoding when @a T is
1074             @c char).
1075      */
1076     template <typename T>
1077     wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const;
1078
1079     //@{
1080     /**
1081         Returns string representation suitable for passing to OS' functions
1082         for file handling.
1083     */
1084     const wchar_t* fn_str() const;
1085     const char* fn_str() const;
1086     const wxCharBuffer fn_str() const;
1087     //@}
1088
1089     /**
1090         Returns the multibyte (C string) representation of the string
1091         using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
1092
1093         @see wc_str(), utf8_str(), c_str(), wxMBConv
1094     */
1095     const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
1096
1097     /**
1098         Extraction from a stream.
1099     */
1100     friend istream operator>>(istream& is, wxString& str);
1101
1102     /**
1103         These functions work as C++ stream insertion operators. They insert the
1104         given value into the string. Precision and format cannot be set using them.
1105         Use Printf() instead.
1106     */
1107     wxString& operator<<(const wxString& s);
1108     wxString& operator<<(const char* psz)
1109     wxString& operator<<(const wchar_t* pwz)
1110     wxString& operator<<(const wxCStrData& psz)
1111     wxString& operator<<(wxUniChar ch);
1112     wxString& operator<<(wxUniCharRef ch)
1113     wxString& operator<<(char ch)
1114     wxString& operator<<(unsigned char ch)
1115     wxString& operator<<(wchar_t ch)
1116     wxString& operator<<(const wxCharBuffer& s)
1117     wxString& operator<<(const wxWCharBuffer& s)
1118     wxString& operator<<(int i);
1119     wxString& operator<<(unsigned int ui);
1120     wxString& operator<<(long l);
1121     wxString& operator<<(unsigned long ul);
1122     wxString& operator<<(wxLongLong_t ll);
1123     wxString& operator<<(wxULongLong_t ul);
1124     wxString& operator<<(float f);
1125     wxString& operator<<(double d);
1126
1127     /**
1128         Same as Mid (substring extraction).
1129     */
1130     wxString operator ()(size_t start, size_t len);
1131
1132     //@{
1133     /**
1134         Concatenation: these operators return a new string equal to the
1135         concatenation of the operands.
1136     */
1137     wxString operator +(const wxString& x, const wxString& y);
1138     wxString operator +(const wxString& x, wxUniChar y);
1139     //@}
1140
1141     //@{
1142     /**
1143         Concatenation in place: the argument is appended to the string.
1144     */
1145     void operator +=(const wxString& str);
1146     void operator +=(wxUniChar c);
1147     //@}
1148
1149     //@{
1150     /**
1151         Assignment: the effect of each operation is the same as for the corresponding
1152         constructor (see @ref wxString() "wxString constructors").
1153     */
1154     wxString operator =(const wxString& str);
1155     wxString operator =(wxUniChar c);
1156     //@}
1157
1158     //@{
1159     /**
1160         Element extraction.
1161     */
1162     wxUniChar operator [](size_t i) const;
1163     wxUniCharRef operator [](size_t i);
1164     //@}
1165
1166     /**
1167         Empty string is @false, so !string will only return @true if the
1168         string is empty.
1169
1170         See also IsEmpty().
1171     */
1172     bool operator!() const;
1173
1174
1175     //@{
1176     /**
1177         Converts the strings contents to UTF-8 and returns it either as a
1178         temporary wxCharBuffer object or as a pointer to the internal
1179         string contents in UTF-8 build.
1180
1181         @see wc_str(), c_str(), mb_str()
1182     */
1183     const char* utf8_str() const;
1184     const wxCharBuffer utf8_str() const;
1185     //@}
1186
1187     //@{
1188     /**
1189         Converts the strings contents to the wide character represention
1190         and returns it as a temporary wxWCharBuffer object (Unix and OS X)
1191         or returns a pointer to the internal string contents in wide character
1192         mode (Windows).
1193
1194         The macro wxWX2WCbuf is defined as the correct return
1195         type (without const).
1196
1197         @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
1198     */
1199     const wchar_t* wc_str() const;
1200     const wxWCharBuffer wc_str() const;
1201     //@}
1202
1203     /**
1204         Returns an object with string data that is implicitly convertible to
1205         @c char* pointer. Note that changes to the returned buffer may or may
1206         not be lost (depending on the build) and so this function is only usable for
1207         passing strings to legacy libraries that don't have const-correct API. Use
1208         wxStringBuffer if you want to modify the string.
1209
1210         @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
1211     */
1212     wxWritableWCharBuffer wchar_str() const;
1213
1214     /**
1215        Explicit conversion to C string in the internal representation (either
1216        wchar_t* or UTF-8-encoded char*, depending on the build).
1217     */
1218     const wxStringCharType *wx_str() const;
1219
1220
1221     /**
1222         @name Iterator interface
1223
1224         These methods return iterators to the beginnnig or
1225         end of the string.
1226     */
1227     //@{
1228         const_iterator begin() const;
1229         iterator begin();
1230         const_iterator end() const;
1231         iterator end();
1232
1233         const_reverse_iterator rbegin() const;
1234         reverse_iterator rbegin();
1235         const_reverse_iterator rend() const;
1236         reverse_iterator rend();
1237     //@}
1238
1239     /**
1240         @name STL interface
1241
1242         The supported STL functions are listed here. Please see any
1243         STL reference for their documentation.
1244     */
1245     //@{
1246         size_t length() const;
1247         size_type size() const;
1248         size_type max_size() const;
1249         size_type capacity() const;
1250         void reserve(size_t sz);
1251
1252         void resize(size_t nSize, wxUniChar ch = '\0');
1253
1254         wxString& append(const wxString& str, size_t pos, size_t n);
1255         wxString& append(const wxString& str);
1256         wxString& append(const char *sz, size_t n);
1257         wxString& append(const wchar_t *sz, size_t n);
1258         wxString& append(size_t n, wxUniChar ch);
1259         wxString& append(const_iterator first, const_iterator last);
1260
1261         wxString& assign(const wxString& str, size_t pos, size_t n);
1262         wxString& assign(const wxString& str);
1263         wxString& assign(const char *sz, size_t n);
1264         wxString& assign(const wchar_t *sz, size_t n);
1265         wxString& assign(size_t n, wxUniChar ch);
1266         wxString& assign(const_iterator first, const_iterator last);
1267
1268         void clear();
1269
1270         int compare(const wxString& str) const;
1271         int compare(size_t nStart, size_t nLen, const wxString& str) const;
1272         int compare(size_t nStart, size_t nLen,
1273               const wxString& str, size_t nStart2, size_t nLen2) const;
1274         int compare(size_t nStart, size_t nLen,
1275               const char* sz, size_t nCount = npos) const;
1276         int compare(size_t nStart, size_t nLen,
1277               const wchar_t* sz, size_t nCount = npos) const;
1278
1279         bool empty() const;
1280
1281         wxString& erase(size_type pos = 0, size_type n = npos);
1282         iterator erase(iterator first, iterator last);
1283         iterator erase(iterator first);
1284
1285         size_t find(const wxString& str, size_t nStart = 0) const;
1286         size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
1287         size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const;
1288         size_t find(wxUniChar ch, size_t nStart = 0) const;
1289
1290         wxString& insert(size_t nPos, const wxString& str);
1291         wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);
1292         wxString& insert(size_t nPos, const char *sz, size_t n);
1293         wxString& insert(size_t nPos, const wchar_t *sz, size_t n);
1294         wxString& insert(size_t nPos, size_t n, wxUniChar ch);
1295         iterator insert(iterator it, wxUniChar ch);
1296         void insert(iterator it, const_iterator first, const_iterator last);
1297         void insert(iterator it, size_type n, wxUniChar ch);
1298
1299         wxString& replace(size_t nStart, size_t nLen, const wxString& str);
1300         wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch);
1301         wxString& replace(size_t nStart, size_t nLen,
1302                     const wxString& str, size_t nStart2, size_t nLen2);
1303         wxString& replace(size_t nStart, size_t nLen,
1304                     const char* sz, size_t nCount);
1305         wxString& replace(size_t nStart, size_t nLen,
1306                     const wchar_t* sz, size_t nCount);
1307         wxString& replace(size_t nStart, size_t nLen,
1308                     const wxString& s, size_t nCount);
1309         wxString& replace(iterator first, iterator last, const wxString& s);
1310         wxString& replace(iterator first, iterator last, const char* s, size_type n);
1311         wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n);
1312         wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch);
1313         wxString& replace(iterator first, iterator last,
1314                     const_iterator first1, const_iterator last1);
1315         wxString& replace(iterator first, iterator last,
1316                     const char *first1, const char *last1);
1317         wxString& replace(iterator first, iterator last,
1318                     const wchar_t *first1, const wchar_t *last1);
1319
1320         size_t rfind(const wxString& str, size_t nStart = npos) const;
1321         size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const;
1322         size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const;
1323         size_t rfind(wxUniChar ch, size_t nStart = npos) const;
1324
1325         wxString substr(size_t nStart = 0, size_t nLen = npos) const;
1326
1327         void swap(wxString& str);
1328
1329     //@}
1330
1331 };
1332
1333
1334 /**
1335     FIXME
1336 */
1337 wxString Objects:
1338 ;
1339
1340 /**
1341     FIXME
1342 */
1343 wxString wxEmptyString;
1344
1345
1346
1347
1348 /**
1349     @class wxStringBufferLength
1350
1351     This tiny class allows you to conveniently access the wxString
1352     internal buffer as a writable pointer without any risk of forgetting to restore
1353     the string to the usable state later, and allows the user to set the internal
1354     length of the string.
1355
1356     For example, assuming you have a low-level OS function called
1357     @c int GetMeaningOfLifeAsString(char *) copying the value in the provided
1358     buffer (which must be writable, of course), and returning the actual length
1359     of the string, you might call it like this:
1360
1361     @code
1362     wxString theAnswer;
1363         wxStringBuffer theAnswerBuffer(theAnswer, 1024);
1364         int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
1365         theAnswerBuffer.SetLength(nLength);
1366         if ( theAnswer != "42" )
1367         {
1368             wxLogError("Something is very wrong!");
1369         }
1370     @endcode
1371
1372     Note that the exact usage of this depends on whether or not wxUSE_STL is
1373     enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
1374     character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
1375     wxString, keeping the same buffer wxString uses intact. In other words,
1376     relying on wxStringBuffer containing the old wxString data is not a good
1377     idea if you want to build your program both with and without wxUSE_STL.
1378
1379     Note that SetLength @c must be called before wxStringBufferLength destructs.
1380
1381     @library{wxbase}
1382     @category{data}
1383 */
1384 class wxStringBufferLength
1385 {
1386 public:
1387     /**
1388         Constructs a writable string buffer object associated with the given string
1389         and containing enough space for at least @a len characters. Basically, this
1390         is equivalent to calling wxString::GetWriteBuf and
1391         saving the result.
1392     */
1393     wxStringBufferLength(const wxString& str, size_t len);
1394
1395     /**
1396         Restores the string passed to the constructor to the usable state by calling
1397         wxString::UngetWriteBuf on it.
1398     */
1399     ~wxStringBufferLength();
1400
1401     /**
1402         Sets the internal length of the string referred to by wxStringBufferLength to
1403         @a nLength characters.
1404         Must be called before wxStringBufferLength destructs.
1405     */
1406     void SetLength(size_t nLength);
1407
1408     /**
1409         Returns the writable pointer to a buffer of the size at least equal to the
1410         length specified in the constructor.
1411     */
1412     wxChar* operator wxChar *();
1413 };
1414