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