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