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