1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxStringBuffer, wxString
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
13 The wxString class has been completely rewritten for wxWidgets 3.0
14 and this change was actually the main reason for the calling that
15 version wxWidgets 3.0.
17 wxString is a class representing a Unicode character string.
18 wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined)
19 to store its content (unless this is not supported by the compiler or disabled
20 specifically when building wxWidgets) and it therefore inherits
21 many features from @c std::basic_string. (Note that most implementations of
22 @c std::basic_string are thread-safe and don't use reference counting.)
24 These @c std::basic_string standard functions are only listed here, but
25 they are not fully documented in this manual; see the STL documentation
26 (http://www.cppreference.com/wiki/string/start) for more info.
27 The behaviour of all these functions is identical to the behaviour
30 You may notice that wxString sometimes has several functions which do
31 the same thing like Length(), Len() and length() which all return the
32 string length. In all cases of such duplication the @c std::string
33 compatible methods should be used.
35 For informations about the internal encoding used by wxString and
36 for important warnings and advices for using it, please read
37 the @ref overview_string.
39 Since wxWidgets 3.0 wxString always stores Unicode strings, so you should
40 be sure to read also @ref overview_unicode.
43 @section string_index Index of the member groups
45 Links for quick access to the various categories of wxString functions:
46 - @ref_member_group{ctor, Constructors and assignment operators}
47 - @ref_member_group{length, Length functions}
48 - @ref_member_group{ch_access, Character access functions}
49 - @ref_member_group{conv, Conversions functions}
50 - @ref_member_group{concat, Concatenation functions}
51 - @ref_member_group{cmp, Comparison functions}
52 - @ref_member_group{substring, Substring extraction functions}
53 - @ref_member_group{caseconv, Case conversion functions}
54 - @ref_member_group{search, Searching and replacing functions}
55 - @ref_member_group{numconv, Conversion to numbers functions}
56 - @ref_member_group{fmt, Formatting and printing functions}
57 - @ref_member_group{mem, Memory management functions}
58 - @ref_member_group{misc, Miscellaneous functions}
59 - @ref_member_group{iter, Iterator interface functions}
60 - @ref_member_group{stl, STL interface functions}
69 @see @ref overview_string, @ref overview_unicode,
70 @ref group_funcmacro_string "String-related functions", wxUString,
71 wxCharBuffer, wxUniChar, wxStringTokenizer, wxStringBuffer, wxStringBufferLength
79 Types used with wxString.
82 typedef wxUniChar value_type
;
83 typedef wxUniChar char_type
;
84 typedef wxUniCharRef reference
;
85 typedef wxChar
* pointer
;
86 typedef const wxChar
* const_pointer
;
87 typedef size_t size_type
;
88 typedef wxUniChar const_reference
;
93 @member_group_name{ctor, Constructors and assignment operators}
95 A string may be constructed either from a C string, (some number of copies of)
96 a single character or a wide (Unicode) string. For all constructors (except the
97 default which creates an empty string) there is also a corresponding assignment
100 See also the assign() STL-like function.
110 Creates a string from another string.
111 Just increases the ref count by 1.
113 wxString(const wxString
& stringSrc
);
117 Constructs a string from the string literal @a psz using
118 the current locale encoding to convert it to Unicode (wxConvLibc).
120 wxString(const char *psz
);
123 Constructs a string from the string literal @a psz using
124 @a conv to convert it Unicode.
126 wxString(const char *psz
, const wxMBConv
& conv
);
129 Constructs a string from the first @a nLength character of the string literal @a psz using
130 the current locale encoding to convert it to Unicode (wxConvLibc).
132 wxString(const char *psz
, size_t nLength
);
135 Constructs a string from the first @a nLength character of the string literal @a psz using
136 @a conv to convert it Unicode.
138 wxString(const char *psz
, const wxMBConv
& conv
, size_t nLength
);
141 Constructs a string from the string literal @a pwz.
143 wxString(const wchar_t *pwz
);
146 Constructs a string from the first @a nLength characters of the string literal @a pwz.
148 wxString(const wchar_t *pwz
, size_t nLength
);
151 Constructs a string from @a buf using the using the current locale
152 encoding to convert it to Unicode.
154 wxString(const wxCharBuffer
& buf
);
157 Constructs a string from @a buf.
159 wxString(const wxWCharBuffer
& buf
);
162 Constructs a string from @a str using the using the current locale encoding
163 to convert it to Unicode (wxConvLibc).
165 wxString(const std::string
& str
);
168 Constructs a string from @a str.
170 wxString(const std::wstring
& str
);
175 Note that this is not virtual, so wxString must not be inherited from.
180 Assignment: see the relative wxString constructor.
182 wxString
operator =(const wxString
& str
);
185 Assignment: see the relative wxString constructor.
187 wxString
operator =(wxUniChar c
);
194 @member_group_name{length, String length}
196 These functions return the string length and/or check whether the string
199 See also the length(), size() or empty() STL-like functions.
205 Returns the length of the string.
210 Returns the length of the string (same as Len).
211 This is a wxWidgets 1.xx compatibility function; you should not use it in new
214 size_t Length() const;
217 Returns @true if the string is empty.
219 bool IsEmpty() const;
222 Returns @true if the string is empty (same as wxString::IsEmpty).
223 This is a wxWidgets 1.xx compatibility function; you should not use it in new
229 Empty string is @false, so !string will only return @true if the
234 bool operator!() const;
241 @member_group_name{ch_access, Character access}
243 Many functions below take a character index in the string.
244 As with C strings and arrays, the indices start from 0, so the first character
245 of a string is string[0]. An attempt to access a character beyond the end of the
246 string (which may even be 0 if the string is empty) will provoke an assert
247 failure in @ref overview_debugging "debug builds", but no checks are
248 done in release builds.
253 Returns the character at position @a n (read-only).
255 wxUniChar
GetChar(size_t n
) const;
258 wxWidgets compatibility conversion. Same as c_str().
260 const wxCStrData
GetData() const;
263 Returns a reference to the character at position @a n.
265 wxUniCharRef
GetWritableChar(size_t n
);
268 Returns a writable buffer of at least @a len bytes.
270 It returns a pointer to a new memory block, and the existing data will not be copied.
271 Call UngetWriteBuf() as soon as possible to put the string back into a reasonable state.
273 This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead.
275 wxStringCharType
* GetWriteBuf(size_t len
);
278 Puts the string back into a reasonable state (in which it can be used
279 normally), after GetWriteBuf() was called.
281 The version of the function without the @a len parameter will calculate the
282 new string length itself assuming that the string is terminated by the first
283 @c NUL character in it while the second one will use the specified length
284 and thus is the only version which should be used with the strings with
285 embedded @c NULs (it is also slightly more efficient as @c strlen()
286 doesn't have to be called).
288 This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead.
290 void UngetWriteBuf();
295 void UngetWriteBuf(size_t len
);
298 Sets the character at position @e n.
300 void SetChar(size_t n
, wxUniChar ch
);
303 Returns a the last character.
305 This is a wxWidgets 1.xx compatibility function;
306 you should not use it in new code.
308 wxUniChar
Last() const;
311 Returns a reference to the last character (writable).
313 This is a wxWidgets 1.xx compatibility function;
314 you should not use it in new code.
319 Returns the @a i-th character of the string.
321 wxUniChar
operator [](size_t i
) const;
324 Returns a writable reference to the @a i-th character of the string.
326 wxUniCharRef
operator [](size_t i
);
332 @member_group_name{conv, Conversions}
334 This section contains both implicit and explicit conversions to C style
335 strings. Although implicit conversion is quite convenient, you are advised
336 to use wc_str() for the sake of clarity.
341 Returns a lightweight intermediate class which is in turn implicitly
342 convertible to both @c const @c char* and to @c const @c wchar_t*.
343 Given this ambiguity it is mostly better to use wc_str(), mb_str() or
346 Please see the @ref overview_unicode for more information about it.
348 Note that the returned value is not convertible to @c char* or
349 @c wchar_t*, use char_str() or wchar_str() if you need to pass
350 string value to a function expecting non-const pointer.
352 @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
354 wxCStrData
c_str() const;
357 Returns an object with string data that is implicitly convertible to
358 @c char* pointer. Note that any change to the returned buffer is lost and so
359 this function is only usable for passing strings to legacy libraries that
360 don't have const-correct API. Use wxStringBuffer if you want to modify
365 wxWritableCharBuffer
char_str(const wxMBConv
& conv
= wxConvLibc
) const;
368 Returns buffer of the specified type containing the string data.
370 This method is only useful in template code, otherwise you should
371 directly call mb_str() or wc_str() if you need to retrieve a narrow or
372 wide string from this wxString. The template parameter @a t should be
373 either @c char or @c wchar_t.
375 Notice that retrieving a char buffer in UTF-8 build will return the
376 internal string representation in UTF-8 while in wchar_t build the char
377 buffer will contain the conversion of the string to the encoding of the
378 current locale (and so can fail).
381 If non-@NULL, filled with the length of the returned buffer.
384 buffer containing the string contents in the specified type,
385 notice that it may be @NULL if the conversion failed (e.g. Unicode
386 string couldn't be converted to the current encoding when @a T is
389 template <typename T
>
390 wxCharTypeBuffer
<T
> tchar_str(size_t *len
= NULL
) const;
393 Returns a string representation suitable for passing to OS' functions
396 const wchar_t* fn_str() const;
401 const char* fn_str() const;
406 const wxCharBuffer
fn_str() const;
409 Returns the multibyte (C string) representation of the string
410 using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
412 @see wc_str(), utf8_str(), c_str(), wxMBConv
414 const wxCharBuffer
mb_str(const wxMBConv
& conv
= wxConvLibc
) const;
417 Converts the strings contents to UTF-8 and returns it either as a
418 temporary wxCharBuffer object or as a pointer to the internal
419 string contents in UTF-8 build.
421 @see wc_str(), c_str(), mb_str()
423 const char* utf8_str() const;
428 const wxCharBuffer
utf8_str() const;
431 Converts the strings contents to the wide character represention
432 and returns it as a temporary wxWCharBuffer object (Unix and OS X)
433 or returns a pointer to the internal string contents in wide character
436 The macro wxWX2WCbuf is defined as the correct return type (without const).
438 @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
440 const wchar_t* wc_str() const;
445 const wxWCharBuffer
wc_str() const;
448 Returns an object with string data that is implicitly convertible to
449 @c char* pointer. Note that changes to the returned buffer may or may
450 not be lost (depending on the build) and so this function is only usable for
451 passing strings to legacy libraries that don't have const-correct API. Use
452 wxStringBuffer if you want to modify the string.
454 @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
456 wxWritableWCharBuffer
wchar_str() const;
459 Explicit conversion to C string in the internal representation (either
460 wchar_t* or UTF-8-encoded char*, depending on the build).
462 const wxStringCharType
*wx_str() const;
465 Converts the string to an 8-bit string in ISO-8859-1 encoding in the
466 form of a wxCharBuffer (Unicode builds only).
468 This is a convenience method useful when storing binary data in
469 wxString. It should be used @em only for this purpose. It is only valid
470 to call this method on strings created using From8BitData().
474 @see wxString::From8BitData()
476 const char* To8BitData() const;
481 const wxCharBuffer
To8BitData() const;
484 Converts the string to an ASCII, 7-bit string in the form of
485 a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
486 Note that this conversion only works if the string contains only ASCII
487 characters. The @ref mb_str() "mb_str" method provides more
488 powerful means of converting wxString to C string.
490 const char* ToAscii() const;
495 const wxCharBuffer
ToAscii() const;
500 const char* ToUTF8() const;
505 const wxCharBuffer
ToUTF8() const;
511 @member_group_name{concat, Concatenation}
513 Almost anything may be concatenated (appended to) with a string!
515 Note that the various operator<<() overloads work as C++ stream insertion
516 operators. They insert the given value into the string.
517 Precision and format cannot be set using them. Use Printf() instead.
519 See also the insert() and append() STL-like functions.
524 Appends the string literal @a psz.
526 wxString
& Append(const char* psz
);
529 Appends the wide string literal @a pwz.
531 wxString
& Append(const wchar_t* pwz
);
534 Appends the string literal @a psz with max length @a nLen.
536 wxString
& Append(const char* psz
, size_t nLen
);
539 Appends the wide string literal @a psz with max length @a nLen.
541 wxString
& Append(const wchar_t* pwz
, size_t nLen
);
544 Appends the string @a s.
546 wxString
& Append(const wxString
& s
);
549 Appends the character @a ch @a count times.
551 wxString
&Append(wxUniChar ch
, size_t count
= 1u);
554 Prepends @a str to this string, returning a reference to this string.
556 wxString
& Prepend(const wxString
& str
);
559 Concatenation: returns a new string equal to the concatenation of the operands.
561 wxString
operator +(const wxString
& x
, const wxString
& y
);
566 wxString
operator +(const wxString
& x
, wxUniChar y
);
568 wxString
& operator<<(const wxString
& s
);
569 wxString
& operator<<(const char* psz
);
570 wxString
& operator<<(const wchar_t* pwz
);
571 wxString
& operator<<(const wxCStrData
& psz
);
572 wxString
& operator<<(char ch
);
573 wxString
& operator<<(unsigned char ch
);
574 wxString
& operator<<(wchar_t ch
);
575 wxString
& operator<<(const wxCharBuffer
& s
);
576 wxString
& operator<<(const wxWCharBuffer
& s
);
577 wxString
& operator<<(wxUniCharRef ch
);
578 wxString
& operator<<(unsigned int ui
);
579 wxString
& operator<<(long l
);
580 wxString
& operator<<(unsigned long ul
);
581 wxString
& operator<<(wxLongLong_t ll
);
582 wxString
& operator<<(wxULongLong_t ul
);
583 wxString
& operator<<(float f
);
584 wxString
& operator<<(double d
);
587 Concatenation in place: the argument is appended to the string.
589 void operator +=(const wxString
& str
);
594 void operator +=(wxUniChar c
);
600 @member_group_name{cmp, Comparison}
602 The default comparison function Cmp() is case-sensitive and so is the default
603 version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
604 or give a second parameter to IsSameAs(). This last function is maybe more
605 convenient if only equality of the strings matters because it returns a boolean
606 @true value if the strings are the same and not 0 (which is usually @false
609 Matches() is a poor man's regular expression matcher: it only understands
610 '*' and '?' metacharacters in the sense of DOS command line interpreter.
612 StartsWith() is helpful when parsing a line of text which should start
613 with some predefined prefix and is more efficient than doing direct string
614 comparison as you would also have to precalculate the length of the prefix.
616 See also the compare() STL-like function.
621 Case-sensitive comparison.
622 Returns a positive value if the string is greater than the argument,
623 zero if it is equal to it or a negative value if it is less than the
624 argument (same semantics as the standard @c strcmp() function).
626 @see CmpNoCase(), IsSameAs().
628 int Cmp(const wxString
& s
) const;
631 Case-insensitive comparison.
632 Returns a positive value if the string is greater than the argument,
633 zero if it is equal to it or a negative value if it is less than the
634 argument (same semantics as the standard @c strcmp() function).
636 @see Cmp(), IsSameAs().
638 int CmpNoCase(const wxString
& s
) const;
641 Test whether the string is equal to the single character @a c.
643 The test is case-sensitive if @a caseSensitive is @true (default) or not if it is
646 Returns @true if the string is equal to the character, @false otherwise.
648 @see Cmp(), CmpNoCase()
650 bool IsSameAs(const wxString
&s
, bool caseSensitive
= true) const;
655 bool IsSameAs(wxUniChar ch
, bool caseSensitive
= true) const;
658 Returns @true if the string contents matches a mask containing '*' and '?'.
660 bool Matches(const wxString
& mask
) const;
663 This function can be used to test if the string starts with the specified
666 If it does, the function will return @true and put the rest of the string
667 (i.e. after the prefix) into @a rest string if it is not @NULL.
668 Otherwise, the function returns @false and doesn't modify the @a rest.
670 bool StartsWith(const wxString
& prefix
, wxString
*rest
= NULL
) const;
673 This function can be used to test if the string ends with the specified
674 @e suffix. If it does, the function will return @true and put the
675 beginning of the string before the suffix into @e rest string if it is not
676 @NULL. Otherwise, the function returns @false and doesn't
679 bool EndsWith(const wxString
& suffix
, wxString
*rest
= NULL
) const;
685 @member_group_name{substring, Substring extraction}
687 These functions allow you to extract a substring from the string. The
688 original string is not modified and the function returns the extracted
691 See also the at() and the substr() STL-like functions.
695 Returns a substring starting at @e first, with length @e count, or the rest of
696 the string if @a count is the default value.
698 wxString
Mid(size_t first
, size_t nCount
= wxString::npos
) const;
701 Returns the part of the string between the indices @a from and @a to
704 This is a wxWidgets 1.xx compatibility function, use Mid()
705 instead (but note that parameters have different meaning).
707 wxString
SubString(size_t from
, size_t to
) const;
710 Same as Mid() (substring extraction).
712 wxString
operator()(size_t start
, size_t len
) const;
715 Returns the first @a count characters of the string.
717 wxString
Left(size_t count
) const;
720 Returns the last @a count characters.
722 wxString
Right(size_t count
) const;
725 Gets all the characters after the first occurrence of @e ch.
726 Returns the empty string if @e ch is not found.
728 wxString
AfterFirst(wxUniChar ch
) const;
731 Gets all the characters after the last occurrence of @e ch.
732 Returns the whole string if @e ch is not found.
734 wxString
AfterLast(wxUniChar ch
) const;
737 Gets all characters before the first occurrence of @e ch.
738 Returns the whole string if @a ch is not found.
740 wxString
BeforeFirst(wxUniChar ch
) const;
743 Gets all characters before the last occurrence of @e ch.
744 Returns the empty string if @a ch is not found.
746 wxString
BeforeLast(wxUniChar ch
) const;
752 @member_group_name{caseconv, Case conversion}
754 The MakeXXX() variants modify the string in place, while the other functions
755 return a new string which contains the original text converted to the upper or
756 lower case and leave the original string unchanged.
761 Return the copy of the string with the first string character in the
762 upper case and the subsequent ones in the lower case.
766 @see MakeCapitalized()
768 wxString
Capitalize() const;
771 Returns this string converted to the lower case.
775 wxString
Lower() const;
779 This is a wxWidgets 1.xx compatibility function; you should not use it in new
785 Converts the first characters of the string to the upper case and all
786 the subsequent ones to the lower case and returns the result.
792 wxString
& MakeCapitalized();
795 Converts all characters to lower case and returns the reference to the
800 wxString
& MakeLower();
803 Converts all characters to upper case and returns the reference to the
808 wxString
& MakeUpper();
811 Returns this string converted to upper case.
815 wxString
Upper() const;
818 The same as MakeUpper().
820 This is a wxWidgets 1.xx compatibility function; you should not use it in new
829 @member_group_name{search, Searching and replacing}
831 These functions replace the standard @c strchr() and @c strstr()
834 See also the find(), rfind(), replace() STL-like functions.
839 Searches for the given character @a ch.
840 Returns the position or @c wxNOT_FOUND if not found.
842 int Find(wxUniChar ch
, bool fromEnd
= false) const;
845 Searches for the given string @a sub.
846 Returns the starting position or @c wxNOT_FOUND if not found.
848 int Find(const wxString
& sub
) const;
853 This is a wxWidgets 1.xx compatibility function;
854 you should not use it in new code.
856 int First(wxUniChar ch
) const;
861 This is a wxWidgets 1.xx compatibility function;
862 you should not use it in new code.
864 int First(const wxString
& str
) const;
867 Replace first (or all) occurrences of substring with another one.
870 The string to search for replacing.
872 The substitution string.
874 If @true a global replace will be done (default), otherwise only the
875 first occurrence will be replaced.
877 Returns the number of replacements made.
879 size_t Replace(const wxString
& strOld
, const wxString
& strNew
,
880 bool replaceAll
= true);
887 @member_group_name{numconv, Conversion to numbers}
889 The string provides functions for conversion to signed and unsigned integer and
890 floating point numbers. All functions take a pointer to the variable to
891 put the numeric value in and return @true if the @b entire string could be
892 converted to a number.
897 Attempts to convert the string to a floating point number.
899 Returns @true on success (the number is stored in the location pointed to by
900 @a val) or @false if the string does not represent such number (the value of
901 @a val is not modified in this case).
903 Note that unlike ToCDouble() this function uses a localized version of
904 @c wxStrtod() and thus needs as decimal point (and thousands separator) the
905 locale-specific decimal point. Thus you should use this function only when
906 you are sure that this string contains a floating point number formatted with
907 the rules of the locale currently in use (see wxLocale).
909 Refer to the docs of the standard function @c strtod() for more details about
910 the supported syntax.
912 @see ToCDouble(), ToLong(), ToULong()
914 bool ToDouble(double* val
) const;
917 Works like ToDouble() but unlike it this function expects the floating point
918 number to be formatted always with the rules dictated by the "C" locale
919 (in particular, the decimal point must be a dot), independently from the
920 current application-wide locale (see wxLocale).
922 @see ToDouble(), ToLong(), ToULong()
924 bool ToCDouble(double* val
) const;
927 Attempts to convert the string to a signed integer in base @a base.
929 Returns @true on success in which case the number is stored in the location
930 pointed to by @a val or @false if the string does not represent a
931 valid number in the given base (the value of @a val is not modified
934 The value of @a base must be comprised between 2 and 36, inclusive, or
935 be a special value 0 which means that the usual rules of @c C numbers are
936 applied: if the number starts with @c 0x it is considered to be in base
937 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
938 that you may not want to specify the base 0 if you are parsing the numbers
939 which may have leading zeroes as they can yield unexpected (to the user not
940 familiar with C) results.
942 Note that unlike ToCLong() this function uses a localized version of
943 @c wxStrtol(). Thus you should use this function only when you are sure
944 that this string contains an integer number formatted with
945 the rules of the locale currently in use (see wxLocale).
947 Refer to the docs of the standard function @c strtol() for more details about
948 the supported syntax.
950 @see ToCDouble(), ToDouble(), ToULong()
952 bool ToLong(long* val
, int base
= 10) const;
955 Works like ToLong() but unlike it this function expects the integer
956 number to be formatted always with the rules dictated by the "C" locale,
957 independently from the current application-wide locale (see wxLocale).
959 @see ToDouble(), ToLong(), ToULong()
961 bool ToCLong(long* val
, int base
= 10) const;
964 This is exactly the same as ToLong() but works with 64 bit integer numbers.
966 Notice that currently it doesn't work (always returns @false) if parsing of 64
967 bit numbers is not supported by the underlying C run-time library. Compilers
968 with C99 support and Microsoft Visual C++ version 7 and higher do support this.
970 @see ToLong(), ToULongLong()
972 bool ToLongLong(wxLongLong_t
* val
, int base
= 10) const;
975 Attempts to convert the string to an unsigned integer in base @a base.
977 Returns @true on success in which case the number is stored in the
978 location pointed to by @a val or @false if the string does not
979 represent a valid number in the given base (the value of @a val is not
980 modified in this case).
982 Please notice that this function behaves in the same way as the standard
983 @c strtoul() and so it simply converts negative numbers to unsigned
984 representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
986 See ToLong() for the more detailed description of the @a base parameter
987 (and of the locale-specific behaviour of this function).
989 @see ToCULong(), ToDouble(), ToLong()
991 bool ToULong(unsigned long* val
, int base
= 10) const;
994 Works like ToULong() but unlike it this function expects the integer
995 number to be formatted always with the rules dictated by the "C" locale,
996 independently from the current application-wide locale (see wxLocale).
998 @see ToDouble(), ToLong(), ToULong()
1000 bool ToCULong(unsigned long* val
, int base
= 10) const;
1003 This is exactly the same as ToULong() but works with 64
1004 bit integer numbers.
1005 Please see ToLongLong() for additional remarks.
1007 bool ToULongLong(wxULongLong_t
* val
, int base
= 10) const;
1013 @member_group_name{fmt, Formatting and printing}
1015 Both formatted versions (Printf/() and stream-like insertion operators
1016 exist (for basic types only).
1018 See also the static Format() and FormatV() functions.
1023 Similar to the standard function @e sprintf(). Returns the number of
1024 characters written, or an integer less than zero on error.
1025 Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
1026 Unix98-style positional parameters:
1028 @note This function will use a safe version of @e vsprintf() (usually called
1029 @e vsnprintf()) whenever available to always allocate the buffer of correct
1030 size. Unfortunately, this function is not available on all platforms and the
1031 dangerous @e vsprintf() will be used then which may lead to buffer overflows.
1033 int Printf(const wxString
& pszFormat
, ...);
1036 Similar to vprintf. Returns the number of characters written, or an integer
1040 int PrintfV(const wxString
& pszFormat
, va_list argPtr
);
1046 @member_group_name{mem, Memory management}
1048 The following are "advanced" functions and they will be needed rarely.
1049 Alloc() and Shrink() are only interesting for optimization purposes.
1050 wxStringBuffer and wxStringBufferLength classes may be very useful when working
1051 with some external API which requires the caller to provide a writable buffer.
1053 See also the reserve() and resize() STL-like functions.
1058 Preallocate enough space for wxString to store @a nLen characters.
1060 Please note that this method does the same thing as the standard
1061 reserve() one and shouldn't be used in new code.
1063 This function may be used to increase speed when the string is
1064 constructed by repeated concatenation as in
1067 // delete all vowels from the string
1068 wxString DeleteAllVowels(const wxString& original)
1072 size_t len = original.length();
1076 for ( size_t n = 0; n < len; n++ )
1078 if ( strchr("aeuio", tolower(original[n])) == NULL )
1079 result += original[n];
1086 because it will avoid the need to reallocate string memory many times
1087 (in case of long strings). Note that it does not set the maximal length
1088 of a string -- it will still expand if more than @a nLen characters are
1089 stored in it. Also, it does not truncate the existing string (use
1090 Truncate() for this) even if its current length is greater than @a nLen.
1092 @return @true if memory was successfully allocated, @false otherwise.
1094 bool Alloc(size_t nLen
);
1097 Minimizes the string's memory. This can be useful after a call to
1098 Alloc() if too much memory were preallocated.
1103 Returns a deep copy of the string.
1105 That is, the returned string is guaranteed to not share data with this
1106 string when using reference-counted wxString implementation.
1108 This method is primarily useful for passing strings between threads
1109 (because wxString is not thread-safe). Unlike creating a copy using
1110 @c wxString(c_str()), Clone() handles embedded NULs correctly.
1114 wxString
Clone() const;
1117 Empties the string and frees memory occupied by it.
1128 @member_group_name{misc, Miscellaneous}
1130 Miscellaneous other string functions.
1135 Returns @true if target appears anywhere in wxString; else @false.
1137 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
1139 bool Contains(const wxString
& str
) const;
1142 Makes the string empty, but doesn't free memory occupied by the string.
1149 Returns the number of occurrences of @e ch in the string.
1151 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
1153 int Freq(wxUniChar ch
) const;
1156 Returns @true if the string contains only ASCII characters.
1157 See wxUniChar::IsAscii for more details.
1159 This is a wxWidgets 1.xx compatibility function; you should not use it in new
1162 bool IsAscii() const;
1165 Returns @true if the string is an integer (with possible sign).
1167 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
1169 bool IsNumber() const;
1172 Returns @true if the string is a word.
1174 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
1176 bool IsWord() const;
1179 Adds @a count copies of @a chPad to the beginning, or to the end of the
1180 string (the default).
1182 Removes spaces from the left or from the right (default).
1184 wxString
& Pad(size_t count
, wxUniChar chPad
= ' ', bool fromRight
= true);
1187 Removes all characters from the string starting at @a pos.
1188 Use Truncate() as a more readable alternative.
1190 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
1192 wxString
& Remove(size_t pos
);
1195 Removes @a len characters from the string, starting at @a pos.
1197 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
1199 wxString
& Remove(size_t pos
, size_t len
);
1202 Removes the last character.
1204 wxString
& RemoveLast(size_t n
= 1);
1207 Strip characters at the front and/or end.
1209 This is the same as Trim() except that it doesn't change this string.
1211 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
1213 wxString
Strip(stripType s
= trailing
) const;
1216 Removes white-space (space, tabs, form feed, newline and carriage return) from
1217 the left or from the right end of the string (right is default).
1219 wxString
& Trim(bool fromRight
= true);
1222 Truncate the string to the given length.
1224 wxString
& Truncate(size_t len
);
1232 @member_group_name{iter, Iterator interface}
1234 These methods return iterators to the beginnnig or end of the string.
1236 Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start)
1237 for their documentation.
1241 const_iterator
begin() const;
1243 const_iterator
end() const;
1246 const_reverse_iterator
rbegin() const;
1247 reverse_iterator
rbegin();
1248 const_reverse_iterator
rend() const;
1249 reverse_iterator
rend();
1256 @member_group_name{stl, STL interface}
1258 The supported STL functions are listed here.
1260 Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start)
1261 for their documentation.
1265 wxString
& append(const wxString
& str
, size_t pos
, size_t n
);
1266 wxString
& append(const wxString
& str
);
1267 wxString
& append(const char *sz
, size_t n
);
1268 wxString
& append(const wchar_t *sz
, size_t n
);
1269 wxString
& append(size_t n
, wxUniChar ch
);
1270 wxString
& append(const_iterator first
, const_iterator last
);
1272 wxString
& assign(const wxString
& str
, size_t pos
, size_t n
);
1273 wxString
& assign(const wxString
& str
);
1274 wxString
& assign(const char *sz
, size_t n
);
1275 wxString
& assign(const wchar_t *sz
, size_t n
);
1276 wxString
& assign(size_t n
, wxUniChar ch
);
1277 wxString
& assign(const_iterator first
, const_iterator last
);
1279 wxUniChar
at(size_t n
) const;
1280 wxUniCharRef
at(size_t n
);
1284 size_type
capacity() const;
1286 int compare(const wxString
& str
) const;
1287 int compare(size_t nStart
, size_t nLen
, const wxString
& str
) const;
1288 int compare(size_t nStart
, size_t nLen
,
1289 const wxString
& str
, size_t nStart2
, size_t nLen2
) const;
1290 int compare(size_t nStart
, size_t nLen
,
1291 const char* sz
, size_t nCount
= npos
) const;
1292 int compare(size_t nStart
, size_t nLen
,
1293 const wchar_t* sz
, size_t nCount
= npos
) const;
1295 wxCStrData
data() const;
1299 wxString
& erase(size_type pos
= 0, size_type n
= npos
);
1300 iterator
erase(iterator first
, iterator last
);
1301 iterator
erase(iterator first
);
1303 size_t find(const wxString
& str
, size_t nStart
= 0) const;
1304 size_t find(const char* sz
, size_t nStart
= 0, size_t n
= npos
) const;
1305 size_t find(const wchar_t* sz
, size_t nStart
= 0, size_t n
= npos
) const;
1306 size_t find(wxUniChar ch
, size_t nStart
= 0) const;
1307 size_t find_first_of(const char* sz
, size_t nStart
= 0) const;
1308 size_t find_first_of(const wchar_t* sz
, size_t nStart
= 0) const;
1309 size_t find_first_of(const char* sz
, size_t nStart
, size_t n
) const;
1310 size_t find_first_of(const wchar_t* sz
, size_t nStart
, size_t n
) const;
1311 size_t find_first_of(wxUniChar c
, size_t nStart
= 0) const;
1312 size_t find_last_of (const wxString
& str
, size_t nStart
= npos
) const;
1313 size_t find_last_of (const char* sz
, size_t nStart
= npos
) const;
1314 size_t find_last_of (const wchar_t* sz
, size_t nStart
= npos
) const;
1315 size_t find_last_of(const char* sz
, size_t nStart
, size_t n
) const;
1316 size_t find_last_of(const wchar_t* sz
, size_t nStart
, size_t n
) const;
1317 size_t find_last_of(wxUniChar c
, size_t nStart
= npos
) const;
1318 size_t find_first_not_of(const wxString
& str
, size_t nStart
= 0) const;
1319 size_t find_first_not_of(const char* sz
, size_t nStart
= 0) const;
1320 size_t find_first_not_of(const wchar_t* sz
, size_t nStart
= 0) const;
1321 size_t find_first_not_of(const char* sz
, size_t nStart
, size_t n
) const;
1322 size_t find_first_not_of(const wchar_t* sz
, size_t nStart
, size_t n
) const;
1323 size_t find_first_not_of(wxUniChar ch
, size_t nStart
= 0) const;
1324 size_t find_last_not_of(const wxString
& str
, size_t nStart
= npos
) const;
1325 size_t find_last_not_of(const char* sz
, size_t nStart
= npos
) const;
1326 size_t find_last_not_of(const wchar_t* sz
, size_t nStart
= npos
) const;
1327 size_t find_last_not_of(const char* sz
, size_t nStart
, size_t n
) const;
1328 size_t find_last_not_of(const wchar_t* sz
, size_t nStart
, size_t n
) const;
1330 wxString
& insert(size_t nPos
, const wxString
& str
);
1331 wxString
& insert(size_t nPos
, const wxString
& str
, size_t nStart
, size_t n
);
1332 wxString
& insert(size_t nPos
, const char *sz
, size_t n
);
1333 wxString
& insert(size_t nPos
, const wchar_t *sz
, size_t n
);
1334 wxString
& insert(size_t nPos
, size_t n
, wxUniChar ch
);
1335 iterator
insert(iterator it
, wxUniChar ch
);
1336 void insert(iterator it
, const_iterator first
, const_iterator last
);
1337 void insert(iterator it
, size_type n
, wxUniChar ch
);
1339 size_t length() const;
1341 size_type
max_size() const;
1343 void reserve(size_t sz
);
1344 void resize(size_t nSize
, wxUniChar ch
= '\0');
1346 wxString
& replace(size_t nStart
, size_t nLen
, const wxString
& str
);
1347 wxString
& replace(size_t nStart
, size_t nLen
, size_t nCount
, wxUniChar ch
);
1348 wxString
& replace(size_t nStart
, size_t nLen
,
1349 const wxString
& str
, size_t nStart2
, size_t nLen2
);
1350 wxString
& replace(size_t nStart
, size_t nLen
,
1351 const char* sz
, size_t nCount
);
1352 wxString
& replace(size_t nStart
, size_t nLen
,
1353 const wchar_t* sz
, size_t nCount
);
1354 wxString
& replace(size_t nStart
, size_t nLen
,
1355 const wxString
& s
, size_t nCount
);
1356 wxString
& replace(iterator first
, iterator last
, const wxString
& s
);
1357 wxString
& replace(iterator first
, iterator last
, const char* s
, size_type n
);
1358 wxString
& replace(iterator first
, iterator last
, const wchar_t* s
, size_type n
);
1359 wxString
& replace(iterator first
, iterator last
, size_type n
, wxUniChar ch
);
1360 wxString
& replace(iterator first
, iterator last
,
1361 const_iterator first1
, const_iterator last1
);
1362 wxString
& replace(iterator first
, iterator last
,
1363 const char *first1
, const char *last1
);
1364 wxString
& replace(iterator first
, iterator last
,
1365 const wchar_t *first1
, const wchar_t *last1
);
1367 size_t rfind(const wxString
& str
, size_t nStart
= npos
) const;
1368 size_t rfind(const char* sz
, size_t nStart
= npos
, size_t n
= npos
) const;
1369 size_t rfind(const wchar_t* sz
, size_t nStart
= npos
, size_t n
= npos
) const;
1370 size_t rfind(wxUniChar ch
, size_t nStart
= npos
) const;
1372 size_type
size() const;
1373 wxString
substr(size_t nStart
= 0, size_t nLen
= npos
) const;
1374 void swap(wxString
& str
);
1381 // Keep these functions separed from the other groups or Doxygen gets confused
1382 // -----------------------------------------------------------------------------
1385 An 'invalid' value for string index
1387 static const size_t npos
;
1390 This static function returns the string containing the result of calling
1391 Printf() with the passed parameters on it.
1393 @see FormatV(), Printf()
1395 static wxString
Format(const wxString
& format
, ...);
1398 This static function returns the string containing the result of calling
1399 PrintfV() with the passed parameters on it.
1401 @see Format(), PrintfV()
1403 static wxString
FormatV(const wxString
& format
, va_list argptr
);
1407 Converts given buffer of binary data from 8-bit string to wxString. In
1408 Unicode build, the string is interpreted as being in ISO-8859-1
1409 encoding. The version without @e len parameter takes NUL-terminated
1412 This is a convenience method useful when storing binary data in
1413 wxString. It should be used @em only for that purpose and only in
1414 conjunction with To8BitData(). Use mb_str() for conversion of character
1415 data to known encoding.
1419 @see wxString::To8BitData()
1421 static wxString
From8BitData(const char* buf
, size_t len
);
1422 static wxString
From8BitData(const char* buf
);
1427 Converts the string or character from an ASCII, 7-bit form
1428 to the native wxString representation.
1430 static wxString
FromAscii(const char* s
);
1431 static wxString
FromAscii(const unsigned char* s
);
1432 static wxString
FromAscii(const char* s
, size_t len
);
1433 static wxString
FromAscii(const unsigned char* s
, size_t len
);
1434 static wxString
FromAscii(char c
);
1439 Converts C string encoded in UTF-8 to wxString.
1441 If @a s is not a valid UTF-8 string, an empty string is returned.
1443 Notice that when using UTF-8 wxWidgets build there is a more efficient
1444 alternative to this function called FromUTF8Unchecked() which, unlike
1445 this one, doesn't check that the input string is valid.
1449 static wxString
FromUTF8(const char* s
);
1450 static wxString
FromUTF8(const char* s
, size_t len
);
1455 Converts C string encoded in UTF-8 to wxString without checking its
1458 This method assumes that @a s is a valid UTF-8 sequence and doesn't do
1459 any validation (although an assert failure is triggered in debug builds
1460 if the string is invalid). Only use it if you are absolutely sure that
1461 @a s is a correct UTF-8 string (e.g. because it comes from another
1462 library using UTF-8) and if the performance matters, otherwise use
1463 slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8
1464 string to this function will result in creating a corrupted wxString
1465 and all the subsequent operations on it will be undefined.
1469 static wxString
FromUTF8Unchecked(const char* s
);
1470 static wxString
FromUTF8Unchecked(const char* s
, size_t len
);
1478 Comparison operator for string types.
1480 inline bool operator==(const wxString
& s1
, const wxString
& s2
);
1481 inline bool operator!=(const wxString
& s1
, const wxString
& s2
);
1482 inline bool operator< (const wxString
& s1
, const wxString
& s2
);
1483 inline bool operator> (const wxString
& s1
, const wxString
& s2
);
1484 inline bool operator<=(const wxString
& s1
, const wxString
& s2
);
1485 inline bool operator>=(const wxString
& s1
, const wxString
& s2
);
1486 inline bool operator==(const wxString
& s1
, const wxCStrData
& s2
);
1487 inline bool operator==(const wxCStrData
& s1
, const wxString
& s2
);
1488 inline bool operator!=(const wxString
& s1
, const wxCStrData
& s2
);
1489 inline bool operator!=(const wxCStrData
& s1
, const wxString
& s2
);
1490 inline bool operator==(const wxString
& s1
, const wxWCharBuffer
& s2
);
1491 inline bool operator==(const wxWCharBuffer
& s1
, const wxString
& s2
);
1492 inline bool operator!=(const wxString
& s1
, const wxWCharBuffer
& s2
);
1493 inline bool operator!=(const wxWCharBuffer
& s1
, const wxString
& s2
);
1494 inline bool operator==(const wxString
& s1
, const wxCharBuffer
& s2
);
1495 inline bool operator==(const wxCharBuffer
& s1
, const wxString
& s2
);
1496 inline bool operator!=(const wxString
& s1
, const wxCharBuffer
& s2
);
1497 inline bool operator!=(const wxCharBuffer
& s1
, const wxString
& s2
);
1502 Comparison operators char types.
1504 inline bool operator==(const wxUniChar
& c
, const wxString
& s
);
1505 inline bool operator==(const wxUniCharRef
& c
, const wxString
& s
);
1506 inline bool operator==(char c
, const wxString
& s
);
1507 inline bool operator==(wchar_t c
, const wxString
& s
);
1508 inline bool operator==(int c
, const wxString
& s
);
1509 inline bool operator==(const wxString
& s
, const wxUniChar
& c
);
1510 inline bool operator==(const wxString
& s
, const wxUniCharRef
& c
);
1511 inline bool operator==(const wxString
& s
, char c
);
1512 inline bool operator==(const wxString
& s
, wchar_t c
);
1513 inline bool operator!=(const wxUniChar
& c
, const wxString
& s
);
1514 inline bool operator!=(const wxUniCharRef
& c
, const wxString
& s
);
1515 inline bool operator!=(char c
, const wxString
& s
);
1516 inline bool operator!=(wchar_t c
, const wxString
& s
);
1517 inline bool operator!=(int c
, const wxString
& s
);
1518 inline bool operator!=(const wxString
& s
, const wxUniChar
& c
);
1519 inline bool operator!=(const wxString
& s
, const wxUniCharRef
& c
);
1520 inline bool operator!=(const wxString
& s
, char c
);
1521 inline bool operator!=(const wxString
& s
, wchar_t c
);
1525 The global wxString instance of an empty string.
1526 Used extensively in the entire wxWidgets API.
1528 wxString wxEmptyString
;
1533 @class wxStringBufferLength
1535 This tiny class allows you to conveniently access the wxString internal buffer
1536 as a writable pointer without any risk of forgetting to restore the string to
1537 the usable state later, and allows the user to set the internal length of the string.
1539 For example, assuming you have a low-level OS function called
1540 @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided
1541 buffer (which must be writable, of course), and returning the actual length
1542 of the string, you might call it like this:
1546 wxStringBuffer theAnswerBuffer(theAnswer, 1024);
1547 int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
1548 theAnswerBuffer.SetLength(nLength);
1549 if ( theAnswer != "42" )
1550 wxLogError("Something is very wrong!");
1554 the example above does not make use of wxStringBufferLength??
1556 Note that the exact usage of this depends on whether or not wxUSE_STL is
1557 enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
1558 character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
1559 wxString, keeping the same buffer wxString uses intact. In other words,
1560 relying on wxStringBuffer containing the old wxString data is not a good
1561 idea if you want to build your program both with and without wxUSE_STL.
1563 Note that wxStringBuffer::SetLength @b must be called before
1564 wxStringBufferLength destructs.
1569 class wxStringBufferLength
1573 Constructs a writable string buffer object associated with the given string
1574 and containing enough space for at least @a len characters.
1576 Basically, this is equivalent to calling wxString::GetWriteBuf and
1579 wxStringBufferLength(const wxString
& str
, size_t len
);
1582 Restores the string passed to the constructor to the usable state by calling
1583 wxString::UngetWriteBuf on it.
1585 ~wxStringBufferLength();
1588 Sets the internal length of the string referred to by wxStringBufferLength to
1589 @a nLength characters.
1591 Must be called before wxStringBufferLength destructs.
1593 void SetLength(size_t nLength
);
1596 Returns the writable pointer to a buffer of the size at least equal to the
1597 length specified in the constructor.
1599 wxChar
* operator wxChar
*();
1604 @class wxStringBuffer
1606 This tiny class allows you to conveniently access the wxString internal buffer
1607 as a writable pointer without any risk of forgetting to restore the string
1608 to the usable state later.
1610 For example, assuming you have a low-level OS function called
1611 @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided
1612 buffer (which must be writable, of course) you might call it like this:
1616 GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
1617 if ( theAnswer != "42" )
1618 wxLogError("Something is very wrong!");
1621 Note that the exact usage of this depends on whether or not @c wxUSE_STL is
1622 enabled. If @c wxUSE_STL is enabled, wxStringBuffer creates a separate empty
1623 character buffer, and if @c wxUSE_STL is disabled, it uses GetWriteBuf() from
1624 wxString, keeping the same buffer wxString uses intact. In other words,
1625 relying on wxStringBuffer containing the old wxString data is not a good
1626 idea if you want to build your program both with and without @c wxUSE_STL.
1631 class wxStringBuffer
1635 Constructs a writable string buffer object associated with the given string
1636 and containing enough space for at least @a len characters.
1637 Basically, this is equivalent to calling wxString::GetWriteBuf() and
1640 wxStringBuffer(const wxString
& str
, size_t len
);
1643 Restores the string passed to the constructor to the usable state by calling
1644 wxString::UngetWriteBuf() on it.
1649 Returns the writable pointer to a buffer of the size at least equal to the
1650 length specified in the constructor.
1652 wxStringCharType
* operator wxStringCharType
*();
1656 /** @addtogroup group_funcmacro_string */
1660 Allows to extend a function with the signature:
1661 @code bool SomeFunc(const wxUniChar& c) @endcode
1662 which operates on a single character, to an entire wxString.
1664 E.g. if you want to check if an entire string contains only digits,
1667 if (wxStringCheck<wxIsdigit>(myString))
1668 ... // the entire string contains oly digits!
1670 ... // at least one character of myString is not a digit
1673 @return @true if the given function returns a non-zero value for all
1674 characters of the @a val string.
1676 template<bool (T
)(const wxUniChar
& c
)>
1677 inline bool wxStringCheck(const wxString
& val
);