1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxStringBuffer
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
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.
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:
23 GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
24 if ( theAnswer != "42" )
26 wxLogError("Something is very wrong!");
30 Note that the exact usage of this depends on whether on not wxUSE_STL is
32 wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer,
34 if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same
36 wxString uses intact. In other words, relying on wxStringBuffer containing the
38 wxString data is probably not a good idea if you want to build your program in
40 with and without wxUSE_STL.
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
54 wxStringBuffer(const wxString
& str
, size_t len
);
57 Restores the string passed to the constructor to the usable state by calling
58 wxString::UngetWriteBuf on it.
63 Returns the writable pointer to a buffer of the size at least equal to the
64 length specified in the constructor.
66 wxChar
* operator wxChar
*();
75 wxString is a class representing a character string. It uses
76 reference counting and copy-on-write internally and is not
77 thread-safe. Please see the
78 @ref overview_string "wxString overview" and the
79 @ref overview_unicode "Unicode overview" for more information
82 Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per
83 character wchar_t) under Windows and UTF-8 under Unix, Linux and
84 OS X to store its content. Much work has been done to make
85 existing code using ANSI string literals work as before.
87 wxString implements most of the methods of the
88 std::string class. These standard functions are not documented in
89 this manual, please see the STL documentation. The behaviour of
90 all these functions is identical to the behaviour described there.
92 You may notice that wxString sometimes has many functions which do
93 the same thing like, for example, wxString::Length, wxString::Len and @c length()
94 which all return the string length. In all cases of such duplication the @c std::string
95 compatible method (@c length() in this case, always the lowercase version) should be
96 used as it will ensure smoother transition to @c std::string when wxWidgets
97 starts using it instead of wxString.
99 Anything may be concatenated (appended to) with a string. However, you can't
100 append something to a C string (including literal constants), so to do this it
101 should be converted to a wxString first.
103 @li @ref operatorout() "operator "
109 A string may be constructed either from a C string, (some number of copies of)
110 a single character or a wide (UNICODE) string. For all constructors (except the
111 default which creates an empty string) there is also a corresponding assignment
118 The MakeXXX() variants modify the string in place, while the other functions
119 return a new string which contains the original text converted to the upper or
120 lower case and leave the original string unchanged.
128 Many functions in this section take a character index in the string. As with C
129 strings and/or arrays, the indices start from 0, so the first character of a
130 string is string[0]. Attempt to access a character beyond the end of the
131 string (which may be even 0 if the string is empty) will provoke an assert
132 failure in @ref overview_debugging "debug build", but no checks are
133 done in release builds.
134 This section also contains both implicit and explicit conversions to C style
135 strings. Although implicit conversion is quite convenient, it is advised to use
136 explicit c_str() method for the sake of clarity.
139 @li GetWritableChar()
147 @li operator const char*()
149 The default comparison function Cmp() is case-sensitive and
150 so is the default version of IsSameAs(). For case
151 insensitive comparisons you should use CmpNoCase() or
152 give a second parameter to IsSameAs. This last function is may be more
153 convenient if only equality of the strings matters because it returns a boolean
154 @true value if the strings are the same and not 0 (which is usually @false
156 Matches() is a poor man's regular expression matcher: it only understands
157 '*' and '?' metacharacters in the sense of DOS command line interpreter.
158 StartsWith() is helpful when parsing a line of text which should start
159 with some predefined prefix and is more efficient than doing direct string
160 comparison as you would also have to precalculate the length of the prefix then.
169 The string provides functions for conversion to signed and unsigned integer and
170 floating point numbers. All three functions take a pointer to the variable to
171 put the numeric value in and return @true if the @b entire string could be
172 converted to a number.
180 These are "advanced" functions and they will be needed quite rarely.
181 Alloc() and Shrink() are only interesting for optimization purposes.
182 wxStringBuffer and wxStringBufferLength classes may be very useful
183 when working with some external API which requires the caller to provide
189 @li wxStringBufferLength
191 Misc. other string functions.
197 These functions return the string length and check whether the string
198 is empty or empty it.
207 These functions allow to extract substring from this string. All of them don't
208 modify the original string and return a new string containing the extracted
222 These functions replace the standard @e strchr() and @e strstr()
228 Both formatted versions (Printf/() and stream-like insertion operators
229 exist (for basic types only). Additionally, the Format() function allows
230 to use simply append formatted value to a string:
238 These functions are deprecated, please consider using new wxWidgets 2.0
239 functions instead of them (or, even better, std::string compatible variants).
241 CompareTo(), Contains(), First(), Freq(), Index(), IsAscii(), IsNull(),
242 IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(),
243 SubString(), UpperCase()
249 ::Objects:, ::wxEmptyString,
251 @see @ref overview_string "wxString overview", @ref overview_unicode
263 Creates a string from another string. Just increases the ref
266 wxString(const wxString
& stringSrc
);
270 Constructs a string from the string literal @c psz using
271 the current locale encoding to convert it to Unicode.
273 wxString(const char *psz
);
276 Constructs a string from the string literal @c psz using
277 @c conv to convert it Unicode.
279 wxString(const char *psz
, const wxMBConv
& conv
);
282 Constructs a string from the first @ nLength character of the string literal @c psz using
283 the current locale encoding to convert it to Unicode.
285 wxString(const char *psz
, size_t nLength
);
288 Constructs a string from the first @ nLength character of the string literal @c psz using
289 @c conv to convert it Unicode.
291 wxString(const char *psz
, const wxMBConv
& conv
, size_t nLength
);
294 Constructs a string from the string literal @c pwz.
296 wxString(const wchar_t *pwz
);
299 Constructs a string from the first @ nLength characters of the string literal @c pwz.
301 wxString(const wchar_t *pwz
, size_t nLength
);
304 Constructs a string from @c buf using the using
305 the current locale encoding to convert it to Unicode.
307 wxString(const wxCharBuffer
& buf
);
310 Constructs a string from @c buf.
312 wxString(const wxWCharBuffer
& buf
);
315 Constructs a string from @str using the using
316 the current locale encoding to convert it to Unicode.
318 wxString(const std::string
& str
);
321 Constructs a string from @str.
323 wxString(const std::wstring
& str
);
327 String destructor. Note that this is not virtual, so wxString must not be
333 Gets all the characters after the first occurrence of @e ch.
334 Returns the empty string if @a ch is not found.
336 wxString
AfterFirst(wxChar ch
) const;
339 Gets all the characters after the last occurrence of @e ch.
340 Returns the whole string if @a ch is not found.
342 wxString
AfterLast(wxChar ch
) const;
345 Preallocate enough space for wxString to store @a nLen characters.
347 Please note that this method does the same thing as the standard
348 reserve() one and shouldn't be used in new code.
350 This function may be used to increase speed when the string is
351 constructed by repeated concatenation as in
354 // delete all vowels from the string
355 wxString DeleteAllVowels(const wxString& original)
359 size_t len = original.length();
363 for ( size_t n = 0; n < len; n++ )
365 if ( strchr("aeuio", tolower(original[n])) == NULL )
366 result += original[n];
373 because it will avoid the need to reallocate string memory many times
374 (in case of long strings). Note that it does not set the maximal length
375 of a string -- it will still expand if more than @a nLen characters are
376 stored in it. Also, it does not truncate the existing string (use
377 Truncate() for this) even if its current length is greater than @a nLen.
379 @return @true if memory was successfully allocated, @false otherwise.
381 bool Alloc(size_t nLen
);
385 Concatenates character @a ch to this string, @a count times, returning a
389 wxString
Append(const wxChar
* psz
);
390 wxString
Append(wxChar ch
, int count
= 1);
394 Gets all characters before the first occurrence of @e ch.
395 Returns the whole string if @a ch is not found.
397 wxString
BeforeFirst(wxChar ch
) const;
400 Gets all characters before the last occurrence of @e ch.
401 Returns the empty string if @a ch is not found.
403 wxString
BeforeLast(wxChar ch
) const;
407 Empties the string and frees memory occupied by it.
413 Returns a deep copy of the string.
415 That is, the returned string is guaranteed to not share data with this
416 string when using reference-counted wxString implementation.
418 This method is primarily useful for passing strings between threads
419 (because wxString is not thread-safe). Unlike creating a copy using
420 @c wxString(c_str()), Clone() handles embedded NULs correctly.
424 wxString
Clone() const;
428 Case-sensitive comparison.
429 Returns a positive value if the string is greater than the argument, zero if
430 it is equal to it or a negative value if it is less than the argument (same
432 as the standard @e strcmp() function).
433 See also CmpNoCase(), IsSameAs().
435 int Cmp(const wxString
& s
) const;
436 const int Cmp(const wxChar
* psz
) const;
441 Case-insensitive comparison.
442 Returns a positive value if the string is greater than the argument, zero if
443 it is equal to it or a negative value if it is less than the argument (same
445 as the standard @e strcmp() function).
446 See also Cmp(), IsSameAs().
448 int CmpNoCase(const wxString
& s
) const;
449 const int CmpNoCase(const wxChar
* psz
) const;
453 Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.
454 This is a wxWidgets 1.xx compatibility function; use Cmp() instead.
456 int CompareTo(const wxChar
* psz
, caseCompare cmp
= exact
) const;
464 bool operator ==(const wxString
& x
, const wxString
& y
);
465 bool operator ==(const wxString
& x
, const wxChar
* t
);
466 bool operator !=(const wxString
& x
, const wxString
& y
);
467 bool operator !=(const wxString
& x
, const wxChar
* t
);
468 bool operator(const wxString
& x
, const wxString
& y
);
469 bool operator(const wxString
& x
, const wxChar
* t
);
470 bool operator =(const wxString
& x
, const wxString
& y
);
471 bool operator =(const wxString
& x
, const wxChar
* t
);
472 bool operator(const wxString
& x
, const wxString
& y
);
473 bool operator(const wxString
& x
, const wxChar
* t
);
474 bool operator =(const wxString
& x
, const wxString
& y
);
475 bool operator =(const wxString
& x
, const wxChar
* t
);
480 Returns @true if target appears anywhere in wxString; else @false.
481 This is a wxWidgets 1.xx compatibility function; you should not use it in new
484 bool Contains(const wxString
& str
) const;
488 Makes the string empty, but doesn't free memory occupied by the string.
494 This function can be used to test if the string ends with the specified
495 @e suffix. If it does, the function will return @true and put the
496 beginning of the string before the suffix into @a rest string if it is not
497 @NULL. Otherwise, the function returns @false and doesn't
500 bool EndsWith(const wxString
& suffix
, wxString rest
= NULL
) const;
504 Searches for the given string. Returns the starting index, or @c wxNOT_FOUND if
507 int Find(wxUniChar ch
, bool fromEnd
= false) const;
508 const int Find(const wxString
& sub
) const;
514 This is a wxWidgets 1.xx compatibility function; you should not use it in new
517 int First(wxChar c
) const;
518 int First(const wxChar
* psz
) const;
519 const int First(const wxString
& str
) const;
523 This static function returns the string containing the result of calling
524 Printf() with the passed parameters on it.
526 @see FormatV(), Printf()
528 static wxString
Format(const wxChar format
, ...);
531 This static function returns the string containing the result of calling
532 PrintfV() with the passed parameters on it.
534 @see Format(), PrintfV()
536 static wxString
FormatV(const wxChar format
, va_list argptr
);
539 Returns the number of occurrences of @a ch in the string.
540 This is a wxWidgets 1.xx compatibility function; you should not use it in new
543 int Freq(wxChar ch
) const;
547 Converts given buffer of binary data from 8-bit string to wxString. In Unicode
548 build, the string is interpreted as being in ISO-8859-1 encoding. The version
549 without @a len parameter takes NUL-terminated data.
550 This is a convenience method useful when storing binary data in wxString.
554 @see wxString::To8BitData
556 static wxString
From8BitData(const char* buf
, size_t len
);
557 static wxString
From8BitData(const char* buf
);
562 Converts the string or character from an ASCII, 7-bit form
563 to the native wxString representation. Most useful when using
564 a Unicode build of wxWidgets (note the use of @c char instead of @c wxChar).
565 Use @ref construct() "wxString constructors" if you
566 need to convert from another charset.
568 static wxString
FromAscii(const char* s
);
569 static wxString
FromAscii(const unsigned char* s
);
570 static wxString
FromAscii(const char* s
, size_t len
);
571 static wxString
FromAscii(const unsigned char* s
, size_t len
);
572 static wxString
FromAscii(char c
);
577 Converts C string encoded in UTF-8 to wxString.
578 Note that this method assumes that @a s is a valid UTF-8 sequence and
579 doesn't do any validation in release builds, it's validity is only checked in
582 static wxString
FromUTF8(const char* s
);
583 static wxString
FromUTF8(const char* s
, size_t len
);
587 Returns the character at position @a n (read-only).
589 wxChar
GetChar(size_t n
) const;
592 wxWidgets compatibility conversion. Returns a constant pointer to the data in
595 const wxChar
* GetData() const;
598 Returns a reference to the character at position @e n.
600 wxChar
GetWritableChar(size_t n
);
603 Returns a writable buffer of at least @a len bytes.
604 It returns a pointer to a new memory block, and the
605 existing data will not be copied.
606 Call UngetWriteBuf() as soon as
607 possible to put the string back into a reasonable state.
608 This method is deprecated, please use
610 wxStringBufferLength instead.
612 wxChar
* GetWriteBuf(size_t len
);
617 This is a wxWidgets 1.xx compatibility function; you should not use it in new
620 size_t Index(wxChar ch
) const;
621 const size_t Index(const wxChar
* sz
) const;
625 Returns @true if the string contains only ASCII characters.
626 This is a wxWidgets 1.xx compatibility function; you should not use it in new
629 bool IsAscii() const;
632 Returns @true if the string is empty.
634 bool IsEmpty() const;
637 Returns @true if the string is empty (same as wxString::IsEmpty).
638 This is a wxWidgets 1.xx compatibility function; you should not use it in new
644 Returns @true if the string is an integer (with possible sign).
645 This is a wxWidgets 1.xx compatibility function; you should not use it in new
648 bool IsNumber() const;
652 Test whether the string is equal to the single character @e c. The test is
653 case-sensitive if @a caseSensitive is @true (default) or not if it is @c
655 Returns @true if the string is equal to the character, @false otherwise.
656 See also Cmp(), CmpNoCase()
658 bool IsSameAs(const wxChar
* psz
, bool caseSensitive
= true) const;
659 const bool IsSameAs(wxChar c
, bool caseSensitive
= true) const;
663 Returns @true if the string is a word.
664 This is a wxWidgets 1.xx compatibility function; you should not use it in new
671 Returns a reference to the last character (writable).
672 This is a wxWidgets 1.xx compatibility function; you should not use it in new
680 Returns the first @a count characters of the string.
682 wxString
Left(size_t count
) const;
685 Returns the length of the string.
690 Returns the length of the string (same as Len).
691 This is a wxWidgets 1.xx compatibility function; you should not use it in new
694 size_t Length() const;
697 Returns this string converted to the lower case.
699 wxString
Lower() const;
703 This is a wxWidgets 1.xx compatibility function; you should not use it in new
709 Converts all characters to lower case and returns the result.
711 wxString
MakeLower();
714 Converts all characters to upper case and returns the result.
716 wxString
MakeUpper();
719 Returns @true if the string contents matches a mask containing '*' and '?'.
721 bool Matches(const wxString
& mask
) const;
724 Returns a substring starting at @e first, with length @e count, or the rest of
725 the string if @a count is the default value.
727 wxString
Mid(size_t first
, size_t count
= wxSTRING_MAXLEN
) const;
731 Adds @a count copies of @a pad to the beginning, or to the end of the
732 string (the default). Removes spaces from the left or from the right (default).
734 wxString
Pad(size_t count
, wxChar pad
= ' ',
735 bool fromRight
= true);
738 Prepends @a str to this string, returning a reference to this string.
740 wxString
Prepend(const wxString
& str
);
743 Similar to the standard function @e sprintf(). Returns the number of
744 characters written, or an integer less than zero on error.
745 Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
746 Unix98-style positional parameters:
748 @note This function will use a safe version of @e vsprintf() (usually called
749 @e vsnprintf()) whenever available to always allocate the buffer of correct
750 size. Unfortunately, this function is not available on all platforms and the
751 dangerous @e vsprintf() will be used then which may lead to buffer overflows.
753 int Printf(const wxChar
* pszFormat
, ...);
756 Similar to vprintf. Returns the number of characters written, or an integer
760 int PrintfV(const wxChar
* pszFormat
, va_list argPtr
);
764 Removes @a len characters from the string, starting at @e pos.
765 This is a wxWidgets 1.xx compatibility function; you should not use it in new
768 wxString
Remove(size_t pos
);
769 wxString
Remove(size_t pos
, size_t len
);
773 Removes the last character.
775 wxString
RemoveLast();
778 Replace first (or all) occurrences of substring with another one.
779 @e replaceAll: global replace (default), or only the first occurrence.
780 Returns the number of replacements made.
782 size_t Replace(const wxString
& strOld
, const wxString
& strNew
,
783 bool replaceAll
= true);
786 Returns the last @a count characters.
788 wxString
Right(size_t count
) const;
791 Sets the character at position @e n.
793 void SetChar(size_t n
, wxChar ch
);
796 Minimizes the string's memory. This can be useful after a call to
797 Alloc() if too much memory were preallocated.
802 This function can be used to test if the string starts with the specified
803 @e prefix. If it does, the function will return @true and put the rest
804 of the string (i.e. after the prefix) into @a rest string if it is not
805 @NULL. Otherwise, the function returns @false and doesn't modify the
808 bool StartsWith(const wxString
& prefix
, wxString rest
= NULL
) const;
811 Strip characters at the front and/or end. The same as Trim except that it
812 doesn't change this string.
813 This is a wxWidgets 1.xx compatibility function; you should not use it in new
816 wxString
Strip(stripType s
= trailing
) const;
819 Returns the part of the string between the indices @a from and @e to
821 This is a wxWidgets 1.xx compatibility function, use Mid()
822 instead (but note that parameters have different meaning).
824 wxString
SubString(size_t from
, size_t to
) const;
828 Converts the string to an 8-bit string in ISO-8859-1 encoding in the form of
829 a wxCharBuffer (Unicode builds only).
830 This is a convenience method useful when storing binary data in wxString.
834 @see wxString::From8BitData
836 const char* To8BitData() const;
837 const const wxCharBuffer
To8BitData() const;
842 Converts the string to an ASCII, 7-bit string in the form of
843 a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
844 Note that this conversion only works if the string contains only ASCII
845 characters. The @ref mbstr() mb_str method provides more
846 powerful means of converting wxString to C string.
848 const char* ToAscii() const;
849 const const wxCharBuffer
ToAscii() const;
853 Attempts to convert the string to a floating point number. Returns @true on
854 success (the number is stored in the location pointed to by @e val) or @false
855 if the string does not represent such number (the value of @a val is not
856 modified in this case).
858 @see ToLong(), ToULong()
860 bool ToDouble(double val
) const;
863 Attempts to convert the string to a signed integer in base @e base. Returns
864 @true on success in which case the number is stored in the location
865 pointed to by @a val or @false if the string does not represent a
866 valid number in the given base (the value of @a val is not modified
868 The value of @a base must be comprised between 2 and 36, inclusive, or
869 be a special value 0 which means that the usual rules of @c C numbers are
870 applied: if the number starts with @c 0x it is considered to be in base
871 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
872 that you may not want to specify the base 0 if you are parsing the numbers
873 which may have leading zeroes as they can yield unexpected (to the user not
874 familiar with C) results.
876 @see ToDouble(), ToULong()
878 bool ToLong(long val
, int base
= 10) const;
881 This is exactly the same as ToLong() but works with 64
883 Notice that currently it doesn't work (always returns @false) if parsing of 64
884 bit numbers is not supported by the underlying C run-time library. Compilers
885 with C99 support and Microsoft Visual C++ version 7 and higher do support this.
887 @see ToLong(), ToULongLong()
889 bool ToLongLong(wxLongLong_t val
, int base
= 10) const;
892 Attempts to convert the string to an unsigned integer in base @e base.
893 Returns @true on success in which case the number is stored in the
894 location pointed to by @a val or @false if the string does not
895 represent a valid number in the given base (the value of @a val is not
896 modified in this case). Please notice that this function
897 behaves in the same way as the standard @c strtoul() and so it simply
898 converts negative numbers to unsigned representation instead of rejecting them
899 (e.g. -1 is returned as @c ULONG_MAX).
900 See ToLong() for the more detailed
901 description of the @a base parameter.
903 @see ToDouble(), ToLong()
905 bool ToULong(unsigned long val
, int base
= 10) const;
908 This is exactly the same as ToULong() but works with 64
910 Please see ToLongLong() for additional remarks.
912 bool ToULongLong(wxULongLong_t val
, int base
= 10) const;
916 Same as @ref wxString::utf8str utf8_str.
918 const char* ToUTF8() const;
919 const const wxCharBuffer
ToUF8() const;
923 Removes white-space (space, tabs, form feed, newline and carriage return) from
924 the left or from the right end of the string (right is default).
926 wxString
Trim(bool fromRight
= true);
929 Truncate the string to the given length.
931 wxString
Truncate(size_t len
);
935 Puts the string back into a reasonable state (in which it can be used
937 GetWriteBuf() was called.
938 The version of the function without the @a len parameter will calculate the
939 new string length itself assuming that the string is terminated by the first
940 @c NUL character in it while the second one will use the specified length
941 and thus is the only version which should be used with the strings with
942 embedded @c NULs (it is also slightly more efficient as @c strlen()
943 doesn't have to be called).
944 This method is deprecated, please use
946 wxStringBufferLength instead.
948 void UngetWriteBuf();
949 void UngetWriteBuf(size_t len
);
953 Returns this string converted to upper case.
955 wxString
Upper() const;
958 The same as MakeUpper.
959 This is a wxWidgets 1.xx compatibility function; you should not use it in new
965 Returns a pointer to the string data (@c const char* when using UTF-8
966 internally, @c const wchar_t* when using UCS-2 internally).
967 Note that the returned value is not convertible to @c char* or
968 @c wchar_t*, use char_str() or wchar_str() if you need to pass
969 string value to a function expecting non-const pointer.
971 const wxChar
* c_str() const;
974 Returns an object with string data that is implicitly convertible to
975 @c char* pointer. Note that any change to the returned buffer is lost and so
976 this function is only usable for passing strings to legacy libraries that
977 don't have const-correct API. Use wxStringBuffer if you want to modify
982 wxWritableCharBuffer
char_str(const wxMBConv
& conv
= wxConvLibc
) const;
986 Returns string representation suitable for passing to OS' functions for
989 const wchar_t* fn_str() const;
990 const const char* fn_str() const;
991 const const wxCharBuffer
fn_str() const;
996 Returns multibyte (C string) representation of the string.
997 In Unicode build, converts using @e conv's wxMBConv::cWC2MB
998 method and returns wxCharBuffer. In ANSI build, this function is same
999 as @ref cstr() c_str.
1000 The macro wxWX2MBbuf is defined as the correct return type (without const).
1002 @see wxMBConv, c_str(), wc_str(), fn_str(), char_str()
1004 const char* mb_str(const wxMBConv
& conv
= wxConvLibc
) const;
1005 const const wxCharBuffer
mb_str(const wxMBConv
& conv
= wxConvLibc
) const;
1009 Extraction from a stream.
1011 friend istream
operator(istream
& is
, wxString
& str
);
1015 These functions work as C++ stream insertion operators: they insert the given
1016 value into the string. Precision or format cannot be set using them, you can
1017 use Printf() for this.
1019 wxString
operator(const wxString
& str
);
1020 wxString
operator(const wxChar
* psz
);
1021 wxString
operator(wxChar ch
);
1022 wxString
operator(int i
);
1023 wxString
operator(float f
);
1024 wxString
operator(double d
);
1028 Same as Mid (substring extraction).
1030 wxString
operator ()(size_t start
, size_t len
);
1034 Concatenation: all these operators return a new string equal to the
1035 concatenation of the operands.
1037 wxString
operator +(const wxString
& x
, const wxString
& y
);
1038 wxString
operator +(const wxString
& x
, const wxChar
* y
);
1039 wxString
operator +(const wxString
& x
, wxChar y
);
1040 wxString
operator +(const wxChar
* x
, const wxString
& y
);
1045 Concatenation in place: the argument is appended to the string.
1047 void operator +=(const wxString
& str
);
1048 void operator +=(const wxChar
* psz
);
1049 void operator +=(wxChar c
);
1054 Assignment: the effect of each operation is the same as for the corresponding
1055 constructor (see @ref construct() "wxString constructors").
1057 wxString
operator =(const wxString
& str
);
1058 wxString
operator =(const wxChar
* psz
);
1059 wxString
operator =(wxChar c
);
1066 wxChar
operator [](size_t i
) const;
1067 wxChar
operator [](size_t i
) const;
1068 const wxChar
operator [](int i
) const;
1069 wxChar
operator [](int i
) const;
1073 Implicit conversion to a C string.
1075 operator const wxChar
*() const;
1078 Empty string is @false, so !string will only return @true if the string is
1080 This allows the tests for @NULLness of a @e const wxChar * pointer and emptiness
1081 of the string to look the same in the code and makes it easier to port old code
1085 bool operator!() const;
1088 The supported functions are only listed here, please see any STL reference for
1089 their documentation.
1095 Converts the strings contents to UTF-8 and returns it either as a temporary
1096 wxCharBuffer object or as a pointer to the internal string contents in
1099 const char* utf8_str() const;
1100 const const wxCharBuffer
utf8_str() const;
1105 Returns wide character representation of the string.
1106 In Unicode build, this function is same as c_str().
1107 The macro wxWX2WCbuf is defined as the correct return
1108 type (without const).
1110 @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str()
1112 const wchar_t* wc_str(const wxMBConv
& conv
) const;
1113 const const wxWCharBuffer
wc_str(const wxMBConv
& conv
) const;
1117 Returns an object with string data that is implicitly convertible to
1118 @c char* pointer. Note that changes to the returned buffer may or may
1119 not be lost (depending on the build) and so this function is only usable for
1120 passing strings to legacy libraries that don't have const-correct API. Use
1121 wxStringBuffer if you want to modify the string.
1123 @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
1125 wxWritableWCharBuffer
wchar_str() const;
1139 wxString wxEmptyString
;
1145 @class wxStringBufferLength
1148 This tiny class allows to conveniently access the wxString
1149 internal buffer as a writable pointer without any risk of forgetting to restore
1150 the string to the usable state later, and allows the user to set the internal
1151 length of the string.
1153 For example, assuming you have a low-level OS function called
1154 @c int GetMeaningOfLifeAsString(char *) copying the value in the provided
1155 buffer (which must be writable, of course), and returning the actual length
1156 of the string, you might call it like this:
1160 wxStringBuffer theAnswerBuffer(theAnswer, 1024);
1161 int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
1162 theAnswerBuffer.SetLength(nLength);
1163 if ( theAnswer != "42" )
1165 wxLogError("Something is very wrong!");
1169 Note that the exact usage of this depends on whether on not wxUSE_STL is
1171 wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer,
1173 if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same
1175 wxString uses intact. In other words, relying on wxStringBuffer containing the
1177 wxString data is probably not a good idea if you want to build your program in
1179 with and without wxUSE_STL.
1181 Note that SetLength @c must be called before wxStringBufferLength destructs.
1186 class wxStringBufferLength
1190 Constructs a writable string buffer object associated with the given string
1191 and containing enough space for at least @a len characters. Basically, this
1192 is equivalent to calling wxString::GetWriteBuf and
1195 wxStringBufferLength(const wxString
& str
, size_t len
);
1198 Restores the string passed to the constructor to the usable state by calling
1199 wxString::UngetWriteBuf on it.
1201 ~wxStringBufferLength();
1204 Sets the internal length of the string referred to by wxStringBufferLength to
1205 @a nLength characters.
1206 Must be called before wxStringBufferLength destructs.
1208 void SetLength(size_t nLength
);
1211 Returns the writable pointer to a buffer of the size at least equal to the
1212 length specified in the constructor.
1214 wxChar
* operator wxChar
*();