1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxStringBuffer, wxString
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 This tiny class allows you to conveniently access the wxString internal buffer
13 as a writable pointer without any risk of forgetting to restore the string
14 to the usable state later.
16 For example, assuming you have a low-level OS function called
17 @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided
18 buffer (which must be writable, of course) you might call it like this:
22 GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
23 if ( theAnswer != "42" )
24 wxLogError("Something is very wrong!");
27 Note that the exact usage of this depends on whether or not wxUSE_STL is
28 enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
29 character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
30 wxString, keeping the same buffer wxString uses intact. In other words,
31 relying on wxStringBuffer containing the old wxString data is not a good
32 idea if you want to build your program both with and without wxUSE_STL.
41 Constructs a writable string buffer object associated with the given string
42 and containing enough space for at least @a len characters.
43 Basically, this is equivalent to calling wxString::GetWriteBuf() and
46 wxStringBuffer(const wxString
& str
, size_t len
);
49 Restores the string passed to the constructor to the usable state by calling
50 wxString::UngetWriteBuf() on it.
55 Returns the writable pointer to a buffer of the size at least equal to the
56 length specified in the constructor.
58 wxStringCharType
* operator wxStringCharType
*();
66 The wxString class has been completely rewritten for wxWidgets 3.0
67 and this change was actually the main reason for the calling that
68 version wxWidgets 3.0.
70 wxString is a class representing a Unicode character string.
71 wxString uses @c std::string internally to store its content
72 unless this is not supported by the compiler or disabled
73 specifically when building wxWidgets and it therefore inherits
74 many features from @c std::string. Most implementations of
75 @c std::string are thread-safe and don't use reference counting.
76 By default, wxString uses @c std::string internally even if
77 wxUSE_STL is not defined.
79 wxString now internally uses UTF-16 under Windows and UTF-8 under
80 Unix, Linux and OS X to store its content. Note that when iterating
81 over a UTF-16 string under Windows, the user code has to take care
82 of surrogate pair handling whereas Windows itself has built-in
83 support pairs in UTF-16, such as for drawing strings on screen.
85 Much work has been done to make existing code using ANSI string literals
86 work as before. If you nonetheless need to have a wxString that uses wchar_t
87 on Unix and Linux, too, you can specify this on the command line with the
88 @c configure @c --disable-utf8 switch or you can consider using wxUString
89 or std::wstring instead.
91 Accessing a UTF-8 string by index can be very inefficient because
92 a single character is represented by a variable number of bytes so that
93 the entire string has to be parsed in order to find the character.
94 Since iterating over a string by index is a common programming technique and
95 was also possible and encouraged by wxString using the access operator[]()
96 wxString implements caching of the last used index so that iterating over
97 a string is a linear operation even in UTF-8 mode.
99 It is nonetheless recommended to use iterators (instead of index based
103 wxString s = "hello";
104 wxString::const_iterator i;
105 for (i = s.begin(); i != s.end(); ++i)
107 wxUniChar uni_ch = *i;
108 // do something with it
112 Please see the @ref overview_string and the @ref overview_unicode for more
113 information about it.
115 wxString uses the current locale encoding to convert any C string
116 literal to Unicode. The same is done for converting to and from
117 @c std::string and for the return value of c_str().
118 For this conversion, the @a wxConvLibc class instance is used.
119 See wxCSConv and wxMBConv.
121 wxString implements most of the methods of the @c std::string class.
122 These standard functions are only listed here, but they are not
123 fully documented in this manual. Please see the STL documentation.
124 The behaviour of all these functions is identical to the behaviour
127 You may notice that wxString sometimes has several functions which do
128 the same thing like Length(), Len() and length() which
129 all return the string length. In all cases of such duplication the
130 @c std::string compatible method should be used.
133 @section string_construct Constructors and assignment operators
135 A string may be constructed either from a C string, (some number of copies of)
136 a single character or a wide (Unicode) string. For all constructors (except the
137 default which creates an empty string) there is also a corresponding assignment
146 @section string_len String length
148 These functions return the string length and check whether the string
149 is empty or they empty it.
160 @section string_access Character access
162 Many functions below take a character index in the string. As with C
163 strings and arrays, the indices start from 0, so the first character of a
164 string is string[0]. An attempt to access a character beyond the end of the
165 string (which may even be 0 if the string is empty) will provoke an assert
166 failure in @ref overview_debugging "debug builds", but no checks are
167 done in release builds.
169 This section also contains both implicit and explicit conversions to C style
170 strings. Although implicit conversion is quite convenient, you are advised
171 to use wc_str() for the sake of clarity.
174 @li GetWritableChar()
186 @section string_concat Concatenation
188 Anything may be concatenated (appended to) with a string. However, you can't
189 append something to a C string (including literal constants), so to do this it
190 should be converted to a wxString first.
201 @section string_comp Comparison
203 The default comparison function Cmp() is case-sensitive and so is the default
204 version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
205 or give a second parameter to IsSameAs(). This last function is maybe more
206 convenient if only equality of the strings matters because it returns a boolean
207 @true value if the strings are the same and not 0 (which is usually @false
210 Matches() is a poor man's regular expression matcher: it only understands
211 '*' and '?' metacharacters in the sense of DOS command line interpreter.
213 StartsWith() is helpful when parsing a line of text which should start
214 with some predefined prefix and is more efficient than doing direct string
215 comparison as you would also have to precalculate the length of the prefix.
226 @section string_substring Substring extraction
228 These functions allow you to extract a substring from the string. The
229 original string is not modified and the function returns the extracted
245 @section string_case Case conversion
247 The MakeXXX() variants modify the string in place, while the other functions
248 return a new string which contains the original text converted to the upper or
249 lower case and leave the original string unchanged.
255 @li MakeCapitalized()
259 @section string_search Searching and replacing
261 These functions replace the standard @e strchr() and @e strstr()
271 @section string_conv Conversion to numbers
273 The string provides functions for conversion to signed and unsigned integer and
274 floating point numbers. All functions take a pointer to the variable to
275 put the numeric value in and return @true if the @b entire string could be
276 converted to a number.
285 @section string_fmt Writing values into the string
287 Both formatted versions (Printf/() and stream-like insertion operators
288 exist (for basic types only). Additionally, the Format() function allows
289 you to simply append a formatted value to a string:
298 @section string_mem Memory management
300 The following are "advanced" functions and they will be needed rarely.
301 Alloc() and Shrink() are only interesting for optimization purposes.
302 wxStringBuffer and wxStringBufferLength classes may be very useful
303 when working with some external API which requires the caller to provide
311 @li wxStringBufferLength
314 @section string_misc Miscellaneous
316 Miscellaneous other string functions.
323 @section string_compat wxWidgets 1.xx compatibility functions
325 The following functions are deprecated.
326 Please consider using @c std::string compatible variants.
328 Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(),
329 Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase()
338 @see @ref overview_string, @ref overview_unicode, wxUString
344 An 'invalid' value for string index
346 static const size_t npos
;
352 typedef wxUniChar value_type
;
353 typedef wxUniChar char_type
;
354 typedef wxUniCharRef reference
;
355 typedef wxChar
* pointer
;
356 typedef const wxChar
* const_pointer
;
357 typedef size_t size_type
;
358 typedef wxUniChar const_reference
;
367 Creates a string from another string.
368 Just increases the ref count by 1.
370 wxString(const wxString
& stringSrc
);
374 Constructs a string from the string literal @e psz using
375 the current locale encoding to convert it to Unicode (wxConvLibc).
377 wxString(const char *psz
);
380 Constructs a string from the string literal @e psz using
381 @e conv to convert it Unicode.
383 wxString(const char *psz
, const wxMBConv
& conv
);
386 Constructs a string from the first @e nLength character of the string literal @e psz using
387 the current locale encoding to convert it to Unicode (wxConvLibc).
389 wxString(const char *psz
, size_t nLength
);
392 Constructs a string from the first @e nLength character of the string literal @e psz using
393 @e conv to convert it Unicode.
395 wxString(const char *psz
, const wxMBConv
& conv
, size_t nLength
);
398 Constructs a string from the string literal @e pwz.
400 wxString(const wchar_t *pwz
);
403 Constructs a string from the first @e nLength characters of the string literal @e pwz.
405 wxString(const wchar_t *pwz
, size_t nLength
);
408 Constructs a string from @e buf using the using the current locale
409 encoding to convert it to Unicode.
411 wxString(const wxCharBuffer
& buf
);
414 Constructs a string from @e buf.
416 wxString(const wxWCharBuffer
& buf
);
419 Constructs a string from @e str using the using the current locale encoding
420 to convert it to Unicode (wxConvLibc).
422 wxString(const std::string
& str
);
425 Constructs a string from @e str.
427 wxString(const std::wstring
& str
);
433 Note that this is not virtual, so wxString must not be inherited from.
438 Gets all the characters after the first occurrence of @e ch.
439 Returns the empty string if @e ch is not found.
441 wxString
AfterFirst(wxUniChar ch
) const;
444 Gets all the characters after the last occurrence of @e ch.
445 Returns the whole string if @e ch is not found.
447 wxString
AfterLast(wxUniChar ch
) const;
450 Preallocate enough space for wxString to store @a nLen characters.
452 Please note that this method does the same thing as the standard
453 reserve() one and shouldn't be used in new code.
455 This function may be used to increase speed when the string is
456 constructed by repeated concatenation as in
459 // delete all vowels from the string
460 wxString DeleteAllVowels(const wxString& original)
464 size_t len = original.length();
468 for ( size_t n = 0; n < len; n++ )
470 if ( strchr("aeuio", tolower(original[n])) == NULL )
471 result += original[n];
478 because it will avoid the need to reallocate string memory many times
479 (in case of long strings). Note that it does not set the maximal length
480 of a string -- it will still expand if more than @a nLen characters are
481 stored in it. Also, it does not truncate the existing string (use
482 Truncate() for this) even if its current length is greater than @a nLen.
484 @return @true if memory was successfully allocated, @false otherwise.
486 bool Alloc(size_t nLen
);
489 Appends the string literal @e psz.
491 wxString
& Append(const char* psz
);
494 Appends the wide string literal @e pwz.
496 wxString
& Append(const wchar_t* pwz
)
499 Appends the string literal @e psz with max length @e nLen.
501 wxString
& Append(const wchar_t* pwz
);
504 Appends the wide string literal @e psz with max length @e nLen.
506 wxString
& Append(const wchar_t* pwz
, size_t nLen
)
509 Appends the string @e s.
511 wxString
& Append(const wchar_t* pwz
, size_t nLen
);
514 Appends the character @e ch @e count times.
516 wxString
&Append(wxUniChar ch
, size_t count
= 1u);
519 Gets all characters before the first occurrence of @e ch.
520 Returns the whole string if @a ch is not found.
522 wxString
BeforeFirst(wxUniChar ch
) const;
525 Gets all characters before the last occurrence of @e ch.
526 Returns the empty string if @a ch is not found.
528 wxString
BeforeLast(wxUniChar ch
) const;
531 Return the copy of the string with the first string character in the
532 upper case and the subsequent ones in the lower case.
536 @see MakeCapitalized()
538 wxString
Capitalize() const;
541 Empties the string and frees memory occupied by it.
547 Returns a deep copy of the string.
549 That is, the returned string is guaranteed to not share data with this
550 string when using reference-counted wxString implementation.
552 This method is primarily useful for passing strings between threads
553 (because wxString is not thread-safe). Unlike creating a copy using
554 @c wxString(c_str()), Clone() handles embedded NULs correctly.
558 wxString
Clone() const;
561 Case-sensitive comparison.
562 Returns a positive value if the string is greater than the argument,
563 zero if it is equal to it or a negative value if it is less than the
564 argument (same semantics as the standard @c strcmp() function).
566 See also CmpNoCase(), IsSameAs().
568 int Cmp(const wxString
& s
) const;
571 Case-insensitive comparison.
572 Returns a positive value if the string is greater than the argument,
573 zero if it is equal to it or a negative value if it is less than the
574 argument (same semantics as the standard @c strcmp() function).
576 See also Cmp(), IsSameAs().
578 int CmpNoCase(const wxString
& s
) const;
585 bool operator ==(const wxString
& x
, const wxString
& y
);
586 bool operator ==(const wxString
& x
, wxUniChar ch
);
587 bool operator !=(const wxString
& x
, const wxString
& y
);
588 bool operator !=(const wxString
& x
, wxUniChar ch
);
589 bool operator(const wxString
& x
, const wxString
& y
);
590 bool operator(const wxString
& x
, wxUniChar ch
);
591 bool operator =(const wxString
& x
, const wxString
& y
);
592 bool operator =(const wxString
& x
, wxUniChar ch
);
593 bool operator(const wxString
& x
, const wxString
& y
);
594 bool operator(const wxString
& x
, wxUniChar ch
);
595 bool operator =(const wxString
& x
, const wxString
& y
);
596 bool operator =(const wxString
& x
, wxUniChar ch
);
601 Returns @true if target appears anywhere in wxString; else @false.
602 This is a wxWidgets 1.xx compatibility function; you should not use it in new
605 bool Contains(const wxString
& str
) const;
609 Makes the string empty, but doesn't free memory occupied by the string.
615 This function can be used to test if the string ends with the specified
616 @e suffix. If it does, the function will return @true and put the
617 beginning of the string before the suffix into @e rest string if it is not
618 @NULL. Otherwise, the function returns @false and doesn't
621 bool EndsWith(const wxString
& suffix
, wxString
*rest
= NULL
) const;
624 Searches for the given character @e ch. Returns the position or
625 @c wxNOT_FOUND if not found.
627 int Find(wxUniChar ch
, bool fromEnd
= false) const;
630 Searches for the given string @e sub. Returns the starting position or
631 @c wxNOT_FOUND if not found.
633 int Find(const wxString
& sub
) const;
638 This is a wxWidgets 1.xx compatibility function;
639 you should not use it in new code.
641 int First(wxUniChar ch
) const;
642 int First(const wxString
& str
) const;
646 This static function returns the string containing the result of calling
647 Printf() with the passed parameters on it.
649 @see FormatV(), Printf()
651 static wxString
Format(const wxChar format
, ...);
654 This static function returns the string containing the result of calling
655 PrintfV() with the passed parameters on it.
657 @see Format(), PrintfV()
659 static wxString
FormatV(const wxChar format
, va_list argptr
);
662 Returns the number of occurrences of @e ch in the string.
663 This is a wxWidgets 1.xx compatibility function; you should not
666 int Freq(wxUniChar ch
) const;
670 Converts given buffer of binary data from 8-bit string to wxString. In
671 Unicode build, the string is interpreted as being in ISO-8859-1
672 encoding. The version without @e len parameter takes NUL-terminated
675 This is a convenience method useful when storing binary data in
676 wxString. It should be used @em only for that purpose and only in
677 conjunction with To8BitData(). Use mb_str() for conversion of character
678 data to known encoding.
682 @see wxString::To8BitData()
684 static wxString
From8BitData(const char* buf
, size_t len
);
685 static wxString
From8BitData(const char* buf
);
690 Converts the string or character from an ASCII, 7-bit form
691 to the native wxString representation.
693 static wxString
FromAscii(const char* s
);
694 static wxString
FromAscii(const unsigned char* s
);
695 static wxString
FromAscii(const char* s
, size_t len
);
696 static wxString
FromAscii(const unsigned char* s
, size_t len
);
697 static wxString
FromAscii(char c
);
702 Converts C string encoded in UTF-8 to wxString.
704 If @a s is not a valid UTF-8 string, an empty string is returned.
706 Notice that when using UTF-8 wxWidgets build there is a more efficient
707 alternative to this function called FromUTF8Unchecked() which, unlike
708 this one, doesn't check that the input string is valid.
712 static wxString
FromUTF8(const char* s
);
713 static wxString
FromUTF8(const char* s
, size_t len
);
718 Converts C string encoded in UTF-8 to wxString without checking its
721 This method assumes that @a s is a valid UTF-8 sequence and doesn't do
722 any validation (although an assert failure is triggered in debug builds
723 if the string is invalid). Only use it if you are absolutely sure that
724 @a s is a correct UTF-8 string (e.g. because it comes from another
725 library using UTF-8) and if the performance matters, otherwise use
726 slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8
727 string to this function will result in creating a corrupted wxString
728 and all the subsequent operations on it will be undefined.
732 static wxString
FromUTF8Unchecked(const char* s
);
733 static wxString
FromUTF8Unchecked(const char* s
, size_t len
);
737 Returns the character at position @a n (read-only).
739 wxUniChar
GetChar(size_t n
) const;
742 wxWidgets compatibility conversion. Same as c_str().
744 const wxCStrData
GetData() const;
747 Returns a reference to the character at position @e n.
749 wxUniCharRef
GetWritableChar(size_t n
);
752 Returns a writable buffer of at least @a len bytes.
753 It returns a pointer to a new memory block, and the
754 existing data will not be copied.
755 Call UngetWriteBuf() as soon as possible to put the
756 string back into a reasonable state.
757 This method is deprecated, please use wxStringBuffer or
758 wxStringBufferLength instead.
760 wxStringCharType
* GetWriteBuf(size_t len
);
763 Returns @true if the string contains only ASCII characters.
764 This is a wxWidgets 1.xx compatibility function; you should not use it in new
767 bool IsAscii() const;
770 Returns @true if the string is empty.
772 bool IsEmpty() const;
775 Returns @true if the string is empty (same as wxString::IsEmpty).
776 This is a wxWidgets 1.xx compatibility function; you should not use it in new
782 Returns @true if the string is an integer (with possible sign).
783 This is a wxWidgets 1.xx compatibility function; you should not use it in new
786 bool IsNumber() const;
790 Test whether the string is equal to the single character @e c. The test is
791 case-sensitive if @a caseSensitive is @true (default) or not if it is @c
793 Returns @true if the string is equal to the character, @false otherwise.
794 See also Cmp(), CmpNoCase()
796 bool IsSameAs(const wxString
&s
, bool caseSensitive
= true) const;
797 bool IsSameAs(wxUniChar ch
, bool caseSensitive
= true) const;
801 Returns @true if the string is a word.
802 This is a wxWidgets 1.xx compatibility function; you should not use it in new
809 Returns a reference to the last character (writable).
810 This is a wxWidgets 1.xx compatibility function;
811 you should not use it in new code.
814 const wxUniChar
Last();
818 Returns the first @a count characters of the string.
820 wxString
Left(size_t count
) const;
823 Returns the length of the string.
828 Returns the length of the string (same as Len).
829 This is a wxWidgets 1.xx compatibility function; you should not use it in new
832 size_t Length() const;
835 Returns this string converted to the lower case.
839 wxString
Lower() const;
843 This is a wxWidgets 1.xx compatibility function; you should not use it in new
849 Converts the first characters of the string to the upper case and all
850 the subsequent ones to the lower case and returns the result.
856 wxString
& MakeCapitalized();
859 Converts all characters to lower case and returns the reference to the
864 wxString
& MakeLower();
867 Converts all characters to upper case and returns the reference to the
872 wxString
& MakeUpper();
875 Returns @true if the string contents matches a mask containing '*' and '?'.
877 bool Matches(const wxString
& mask
) const;
880 Returns a substring starting at @e first, with length @e count, or the rest of
881 the string if @a count is the default value.
883 wxString
Mid(size_t first
, size_t nCount
= wxString::npos
) const;
887 Adds @a count copies of @a pad to the beginning, or to the end of the
888 string (the default). Removes spaces from the left or from the right (default).
890 wxString
& Pad(size_t count
, wxUniChar chPad
= ' ', bool fromRight
= true);
893 Prepends @a str to this string, returning a reference to this string.
895 wxString
& Prepend(const wxString
& str
);
898 Similar to the standard function @e sprintf(). Returns the number of
899 characters written, or an integer less than zero on error.
900 Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
901 Unix98-style positional parameters:
903 @note This function will use a safe version of @e vsprintf() (usually called
904 @e vsnprintf()) whenever available to always allocate the buffer of correct
905 size. Unfortunately, this function is not available on all platforms and the
906 dangerous @e vsprintf() will be used then which may lead to buffer overflows.
908 int Printf(const wxString
& pszFormat
, ...);
911 Similar to vprintf. Returns the number of characters written, or an integer
915 int PrintfV(const wxString
& pszFormat
, va_list argPtr
);
919 Removes @a len characters from the string, starting at @e pos.
920 This is a wxWidgets 1.xx compatibility function; you should not use it in new
923 wxString
Remove(size_t pos
);
924 wxString
Remove(size_t pos
, size_t len
);
928 Removes the last character.
930 wxString
& RemoveLast(size_t n
= 1);
933 Replace first (or all) occurrences of substring with another one.
934 @e replaceAll: global replace (default), or only the first occurrence.
935 Returns the number of replacements made.
937 size_t Replace(const wxString
& strOld
, const wxString
& strNew
,
938 bool replaceAll
= true);
941 Returns the last @a count characters.
943 wxString
Right(size_t count
) const;
946 Sets the character at position @e n.
948 void SetChar(size_t n
, wxUniChar ch
);
951 Minimizes the string's memory. This can be useful after a call to
952 Alloc() if too much memory were preallocated.
957 This function can be used to test if the string starts with the specified
958 @e prefix. If it does, the function will return @true and put the rest
959 of the string (i.e. after the prefix) into @a rest string if it is not
960 @NULL. Otherwise, the function returns @false and doesn't modify the
963 bool StartsWith(const wxString
& prefix
, wxString
*rest
= NULL
) const;
966 Strip characters at the front and/or end. The same as Trim except that it
967 doesn't change this string.
968 This is a wxWidgets 1.xx compatibility function; you should not use it in new
971 wxString
Strip(stripType s
= trailing
) const;
974 Returns the part of the string between the indices @a from and @e to
976 This is a wxWidgets 1.xx compatibility function, use Mid()
977 instead (but note that parameters have different meaning).
979 wxString
SubString(size_t from
, size_t to
) const;
983 Converts the string to an 8-bit string in ISO-8859-1 encoding in the
984 form of a wxCharBuffer (Unicode builds only).
986 This is a convenience method useful when storing binary data in
987 wxString. It should be used @em only for this purpose. It is only valid
988 to call this method on strings created using From8BitData().
992 @see wxString::From8BitData()
994 const char* To8BitData() const;
995 const wxCharBuffer
To8BitData() const;
1000 Converts the string to an ASCII, 7-bit string in the form of
1001 a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
1002 Note that this conversion only works if the string contains only ASCII
1003 characters. The @ref mb_str() "mb_str" method provides more
1004 powerful means of converting wxString to C string.
1006 const char* ToAscii() const;
1007 const wxCharBuffer
ToAscii() const;
1011 Attempts to convert the string to a floating point number. Returns @true on
1012 success (the number is stored in the location pointed to by @e val) or @false
1013 if the string does not represent such number (the value of @a val is not
1014 modified in this case).
1016 @see ToLong(), ToULong()
1018 bool ToDouble(double* val
) const;
1021 Attempts to convert the string to a signed integer in base @e base. Returns
1022 @true on success in which case the number is stored in the location
1023 pointed to by @a val or @false if the string does not represent a
1024 valid number in the given base (the value of @a val is not modified
1026 The value of @a base must be comprised between 2 and 36, inclusive, or
1027 be a special value 0 which means that the usual rules of @c C numbers are
1028 applied: if the number starts with @c 0x it is considered to be in base
1029 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
1030 that you may not want to specify the base 0 if you are parsing the numbers
1031 which may have leading zeroes as they can yield unexpected (to the user not
1032 familiar with C) results.
1034 @see ToDouble(), ToULong()
1036 bool ToLong(long* val
, int base
= 10) const;
1039 This is exactly the same as ToLong() but works with 64
1040 bit integer numbers.
1041 Notice that currently it doesn't work (always returns @false) if parsing of 64
1042 bit numbers is not supported by the underlying C run-time library. Compilers
1043 with C99 support and Microsoft Visual C++ version 7 and higher do support this.
1045 @see ToLong(), ToULongLong()
1047 bool ToLongLong(wxLongLong_t
* val
, int base
= 10) const;
1050 Attempts to convert the string to an unsigned integer in base @e base.
1051 Returns @true on success in which case the number is stored in the
1052 location pointed to by @a val or @false if the string does not
1053 represent a valid number in the given base (the value of @a val is not
1054 modified in this case).
1056 Please notice that this function behaves in the same way as the standard
1057 @c strtoul() and so it simply converts negative numbers to unsigned
1058 representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
1060 See ToLong() for the more detailed description of the @a base parameter.
1062 @see ToDouble(), ToLong()
1064 bool ToULong(unsigned long* val
, int base
= 10) const;
1067 This is exactly the same as ToULong() but works with 64
1068 bit integer numbers.
1069 Please see ToLongLong() for additional remarks.
1071 bool ToULongLong(wxULongLong_t
* val
, int base
= 10) const;
1077 const char* ToUTF8() const;
1078 const wxCharBuffer
ToUTF8() const;
1082 Removes white-space (space, tabs, form feed, newline and carriage return) from
1083 the left or from the right end of the string (right is default).
1085 wxString
& Trim(bool fromRight
= true);
1088 Truncate the string to the given length.
1090 wxString
& Truncate(size_t len
);
1094 Puts the string back into a reasonable state (in which it can be used
1095 normally), after GetWriteBuf() was called.
1097 The version of the function without the @a len parameter will calculate the
1098 new string length itself assuming that the string is terminated by the first
1099 @c NUL character in it while the second one will use the specified length
1100 and thus is the only version which should be used with the strings with
1101 embedded @c NULs (it is also slightly more efficient as @c strlen()
1102 doesn't have to be called).
1104 This method is deprecated, please use wxStringBuffer or
1105 wxStringBufferLength instead.
1107 void UngetWriteBuf();
1108 void UngetWriteBuf(size_t len
);
1112 Returns this string converted to upper case.
1116 wxString
Upper() const;
1119 The same as MakeUpper().
1121 This is a wxWidgets 1.xx compatibility function; you should not use it in new
1127 Returns a lightweight intermediate class which is in turn implicitly
1128 convertible to both @c const @c char* and to @c const @c wchar_t*.
1129 Given this ambiguity it is mostly better to use wc_str(), mb_str() or
1132 Please see the @ref overview_unicode for more information about it.
1134 Note that the returned value is not convertible to @c char* or
1135 @c wchar_t*, use char_str() or wchar_str() if you need to pass
1136 string value to a function expecting non-const pointer.
1138 @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
1140 wxCStrData
c_str() const;
1143 Returns an object with string data that is implicitly convertible to
1144 @c char* pointer. Note that any change to the returned buffer is lost and so
1145 this function is only usable for passing strings to legacy libraries that
1146 don't have const-correct API. Use wxStringBuffer if you want to modify
1151 wxWritableCharBuffer
char_str(const wxMBConv
& conv
= wxConvLibc
) const;
1154 Returns buffer of the specified type containing the string data.
1156 This method is only useful in template code, otherwise you should
1157 directly call mb_str() or wc_str() if you need to retrieve a narrow or
1158 wide string from this wxString. The template parameter @a t should be
1159 either @c char or @c wchar_t.
1161 Notice that retrieving a char buffer in UTF-8 build will return the
1162 internal string representation in UTF-8 while in wchar_t build the char
1163 buffer will contain the conversion of the string to the encoding of the
1164 current locale (and so can fail).
1167 If non-@NULL, filled with the length of the returned buffer.
1170 buffer containing the string contents in the specified type,
1171 notice that it may be @NULL if the conversion failed (e.g. Unicode
1172 string couldn't be converted to the current encoding when @a T is
1175 template <typename T
>
1176 wxCharTypeBuffer
<T
> tchar_str(size_t *len
= NULL
) const;
1180 Returns string representation suitable for passing to OS' functions
1183 const wchar_t* fn_str() const;
1184 const char* fn_str() const;
1185 const wxCharBuffer
fn_str() const;
1189 Returns the multibyte (C string) representation of the string
1190 using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
1192 @see wc_str(), utf8_str(), c_str(), wxMBConv
1194 const wxCharBuffer
mb_str(const wxMBConv
& conv
= wxConvLibc
) const;
1197 Extraction from a stream.
1199 friend istream
operator>>(istream
& is
, wxString
& str
);
1202 These functions work as C++ stream insertion operators. They insert the
1203 given value into the string. Precision and format cannot be set using them.
1204 Use Printf() instead.
1206 wxString
& operator<<(const wxString
& s
);
1207 wxString
& operator<<(const char* psz
)
1208 wxString
& operator<<(const wchar_t* pwz
)
1209 wxString
& operator<<(const wxCStrData
& psz
)
1210 wxString
& operator<<(const char* psz
);
1211 wxString
& operator<<(wxUniCharRef ch
)
1212 wxString
& operator<<(char ch
)
1213 wxString
& operator<<(unsigned char ch
)
1214 wxString
& operator<<(wchar_t ch
)
1215 wxString
& operator<<(const wxCharBuffer
& s
)
1216 wxString
& operator<<(const wxWCharBuffer
& s
)
1217 wxString
& operator<<(wxUniCharRef ch
);
1218 wxString
& operator<<(unsigned int ui
);
1219 wxString
& operator<<(long l
);
1220 wxString
& operator<<(unsigned long ul
);
1221 wxString
& operator<<(wxLongLong_t ll
);
1222 wxString
& operator<<(wxULongLong_t ul
);
1223 wxString
& operator<<(float f
);
1224 wxString
& operator<<(double d
);
1227 Same as Mid() (substring extraction).
1229 wxString
operator()(size_t start
, size_t len
) const;
1233 Concatenation: these operators return a new string equal to the
1234 concatenation of the operands.
1236 wxString
operator +(const wxString
& x
, const wxString
& y
);
1237 wxString
operator +(const wxString
& x
, wxUniChar y
);
1242 Concatenation in place: the argument is appended to the string.
1244 void operator +=(const wxString
& str
);
1245 void operator +=(wxUniChar c
);
1250 Assignment: the effect of each operation is the same as for the corresponding
1251 constructor (see @ref wxString() "wxString constructors").
1253 wxString
operator =(const wxString
& str
);
1254 wxString
operator =(wxUniChar c
);
1261 wxUniChar
operator [](size_t i
) const;
1262 wxUniCharRef
operator [](size_t i
);
1266 Empty string is @false, so !string will only return @true if the
1271 bool operator!() const;
1276 Converts the strings contents to UTF-8 and returns it either as a
1277 temporary wxCharBuffer object or as a pointer to the internal
1278 string contents in UTF-8 build.
1280 @see wc_str(), c_str(), mb_str()
1282 const char* utf8_str() const;
1283 const wxCharBuffer
utf8_str() const;
1288 Converts the strings contents to the wide character represention
1289 and returns it as a temporary wxWCharBuffer object (Unix and OS X)
1290 or returns a pointer to the internal string contents in wide character
1293 The macro wxWX2WCbuf is defined as the correct return
1294 type (without const).
1296 @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
1298 const wchar_t* wc_str() const;
1299 const wxWCharBuffer
wc_str() const;
1303 Returns an object with string data that is implicitly convertible to
1304 @c char* pointer. Note that changes to the returned buffer may or may
1305 not be lost (depending on the build) and so this function is only usable for
1306 passing strings to legacy libraries that don't have const-correct API. Use
1307 wxStringBuffer if you want to modify the string.
1309 @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
1311 wxWritableWCharBuffer
wchar_str() const;
1314 Explicit conversion to C string in the internal representation (either
1315 wchar_t* or UTF-8-encoded char*, depending on the build).
1317 const wxStringCharType
*wx_str() const;
1321 @name Iterator interface
1323 These methods return iterators to the beginnnig or
1327 const_iterator
begin() const;
1329 const_iterator
end() const;
1332 const_reverse_iterator
rbegin() const;
1333 reverse_iterator
rbegin();
1334 const_reverse_iterator
rend() const;
1335 reverse_iterator
rend();
1341 The supported STL functions are listed here. Please see any
1342 STL reference for their documentation.
1345 size_t length() const;
1346 size_type
size() const;
1347 size_type
max_size() const;
1348 size_type
capacity() const;
1349 void reserve(size_t sz
);
1351 void resize(size_t nSize
, wxUniChar ch
= '\0');
1353 wxString
& append(const wxString
& str
, size_t pos
, size_t n
);
1354 wxString
& append(const wxString
& str
);
1355 wxString
& append(const char *sz
, size_t n
);
1356 wxString
& append(const wchar_t *sz
, size_t n
);
1357 wxString
& append(size_t n
, wxUniChar ch
);
1358 wxString
& append(const_iterator first
, const_iterator last
);
1360 wxString
& assign(const wxString
& str
, size_t pos
, size_t n
);
1361 wxString
& assign(const wxString
& str
);
1362 wxString
& assign(const char *sz
, size_t n
);
1363 wxString
& assign(const wchar_t *sz
, size_t n
);
1364 wxString
& assign(size_t n
, wxUniChar ch
);
1365 wxString
& assign(const_iterator first
, const_iterator last
);
1369 int compare(const wxString
& str
) const;
1370 int compare(size_t nStart
, size_t nLen
, const wxString
& str
) const;
1371 int compare(size_t nStart
, size_t nLen
,
1372 const wxString
& str
, size_t nStart2
, size_t nLen2
) const;
1373 int compare(size_t nStart
, size_t nLen
,
1374 const char* sz
, size_t nCount
= npos
) const;
1375 int compare(size_t nStart
, size_t nLen
,
1376 const wchar_t* sz
, size_t nCount
= npos
) const;
1380 wxString
& erase(size_type pos
= 0, size_type n
= npos
);
1381 iterator
erase(iterator first
, iterator last
);
1382 iterator
erase(iterator first
);
1384 size_t find(const wxString
& str
, size_t nStart
= 0) const;
1385 size_t find(const char* sz
, size_t nStart
= 0, size_t n
= npos
) const;
1386 size_t find(const wchar_t* sz
, size_t nStart
= 0, size_t n
= npos
) const;
1387 size_t find(wxUniChar ch
, size_t nStart
= 0) const;
1389 wxString
& insert(size_t nPos
, const wxString
& str
);
1390 wxString
& insert(size_t nPos
, const wxString
& str
, size_t nStart
, size_t n
);
1391 wxString
& insert(size_t nPos
, const char *sz
, size_t n
);
1392 wxString
& insert(size_t nPos
, const wchar_t *sz
, size_t n
);
1393 wxString
& insert(size_t nPos
, size_t n
, wxUniChar ch
);
1394 iterator
insert(iterator it
, wxUniChar ch
);
1395 void insert(iterator it
, const_iterator first
, const_iterator last
);
1396 void insert(iterator it
, size_type n
, wxUniChar ch
);
1398 wxString
& replace(size_t nStart
, size_t nLen
, const wxString
& str
);
1399 wxString
& replace(size_t nStart
, size_t nLen
, size_t nCount
, wxUniChar ch
);
1400 wxString
& replace(size_t nStart
, size_t nLen
,
1401 const wxString
& str
, size_t nStart2
, size_t nLen2
);
1402 wxString
& replace(size_t nStart
, size_t nLen
,
1403 const char* sz
, size_t nCount
);
1404 wxString
& replace(size_t nStart
, size_t nLen
,
1405 const wchar_t* sz
, size_t nCount
);
1406 wxString
& replace(size_t nStart
, size_t nLen
,
1407 const wxString
& s
, size_t nCount
);
1408 wxString
& replace(iterator first
, iterator last
, const wxString
& s
);
1409 wxString
& replace(iterator first
, iterator last
, const char* s
, size_type n
);
1410 wxString
& replace(iterator first
, iterator last
, const wchar_t* s
, size_type n
);
1411 wxString
& replace(iterator first
, iterator last
, size_type n
, wxUniChar ch
);
1412 wxString
& replace(iterator first
, iterator last
,
1413 const_iterator first1
, const_iterator last1
);
1414 wxString
& replace(iterator first
, iterator last
,
1415 const char *first1
, const char *last1
);
1416 wxString
& replace(iterator first
, iterator last
,
1417 const wchar_t *first1
, const wchar_t *last1
);
1419 size_t rfind(const wxString
& str
, size_t nStart
= npos
) const;
1420 size_t rfind(const char* sz
, size_t nStart
= npos
, size_t n
= npos
) const;
1421 size_t rfind(const wchar_t* sz
, size_t nStart
= npos
, size_t n
= npos
) const;
1422 size_t rfind(wxUniChar ch
, size_t nStart
= npos
) const;
1424 wxString
substr(size_t nStart
= 0, size_t nLen
= npos
) const;
1426 void swap(wxString
& str
);
1433 The global wxString instance of an empty string.
1434 Used extensively in the entire wxWidgets API.
1436 wxString wxEmptyString
;
1442 @class wxStringBufferLength
1444 This tiny class allows you to conveniently access the wxString internal buffer
1445 as a writable pointer without any risk of forgetting to restore the string to
1446 the usable state later, and allows the user to set the internal length of the string.
1448 For example, assuming you have a low-level OS function called
1449 @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided
1450 buffer (which must be writable, of course), and returning the actual length
1451 of the string, you might call it like this:
1455 wxStringBuffer theAnswerBuffer(theAnswer, 1024);
1456 int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
1457 theAnswerBuffer.SetLength(nLength);
1458 if ( theAnswer != "42" )
1459 wxLogError("Something is very wrong!");
1463 the example above does not make use of wxStringBufferLength??
1465 Note that the exact usage of this depends on whether or not wxUSE_STL is
1466 enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
1467 character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
1468 wxString, keeping the same buffer wxString uses intact. In other words,
1469 relying on wxStringBuffer containing the old wxString data is not a good
1470 idea if you want to build your program both with and without wxUSE_STL.
1472 Note that wxStringBuffer::SetLength @b must be called before
1473 wxStringBufferLength destructs.
1478 class wxStringBufferLength
1482 Constructs a writable string buffer object associated with the given string
1483 and containing enough space for at least @a len characters.
1485 Basically, this is equivalent to calling wxString::GetWriteBuf and
1488 wxStringBufferLength(const wxString
& str
, size_t len
);
1491 Restores the string passed to the constructor to the usable state by calling
1492 wxString::UngetWriteBuf on it.
1494 ~wxStringBufferLength();
1497 Sets the internal length of the string referred to by wxStringBufferLength to
1498 @a nLength characters.
1500 Must be called before wxStringBufferLength destructs.
1502 void SetLength(size_t nLength
);
1505 Returns the writable pointer to a buffer of the size at least equal to the
1506 length specified in the constructor.
1508 wxChar
* operator wxChar
*();