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