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