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