wxString Class Reference

#include <wx/string.h>

Inheritance diagram for wxString:

Detailed Description

String class for passing textual data to or receiving it from wxWidgets.

Note

While the use of wxString is unavoidable in wxWidgets programs, you are encouraged to use the standard string classes std::string or std::wstring in your applications and convert them to and from wxString only when interacting with wxWidgets.

wxString is a class representing a Unicode character string but with methods taking or returning both wchar_t wide characters and wchar_t* wide strings and traditional char characters and char* strings. The dual nature of wxString API makes it simple to use in all cases and, importantly, allows the code written for either ANSI or Unicode builds of the previous wxWidgets versions to compile and work correctly with the single unified build of wxWidgets 3.0 and later. It is also mostly transparent when using wxString with the few exceptions described below.

API overview

wxString tries to be similar to both std::string and std::wstring and can mostly be used as either class. It provides practically all of the methods of these classes, which behave exactly the same as in the standard C++, and so are not documented here (please see documentation at https://en.cppreference.com/w/cpp/string/basic_string for this).

In addition to these standard methods, wxString adds functions dealing with the conversions between different string encodings, described below, as well as many extra helpers such as functions for formatted output (Printf(), Format(), ...), case conversion (MakeUpper(), Capitalize(), ...) and various others (Trim(), StartsWith(), Matches(), ...). All of the non-standard methods follow wxWidgets "CamelCase" naming convention and are documented here.

Notice that some wxString methods exist in several versions for compatibility reasons. For example all of length(), Length() and Len() are provided. In such cases it is recommended to use the standard string-like method, i.e. length() in this case.

Converting to and from wxString

wxString can be created from:

• ASCII string guaranteed to contain only 7 bit characters using wxString::FromAscii().
• Narrow char* string in the current locale encoding using implicit wxString::wxString(const char*) constructor or using more explicit wxString::wxString(const char*, const wxMBConv&) constructor passing it wxConvLibc as the second argument.
• Narrow char* string in UTF-8 encoding using wxString::FromUTF8().
• Narrow char* string in the given encoding using wxString::wxString(const char*, const wxMBConv&) constructor passing a wxCSConv corresponding to the encoding as the second argument.
• Standard std::string using implicit wxString::wxString(const std::string&) constructor. Notice that this constructor supposes that the string contains data in the current locale encoding, use FromUTF8() if the string contains UTF-8-encoded data instead.
• Standard std::string_view using implicit wxString::wxString(std::string_view) constructor. Notice that this constructor supposes that the string contains data in the current locale encoding, use FromUTF8() if the string contains UTF-8-encoded data instead.
• Wide wchar_t* string using implicit wxString::wxString(const wchar_t*) constructor.
• Standard std::wstring using implicit wxString::wxString(const std::wstring&) constructor.
• Standard std::wstring_view using implicit wxString::wxString(std::wstring_view) constructor.

Notice that many of the constructors are implicit, meaning that you don't even need to write them at all to pass the existing string to some wxWidgets function taking a wxString. This is convenient, but can also be dangerous when constructing wxString from char* or std::string if it doesn't have the expected encoding, as the resulting string will be empty if the conversion from the current locale encoding fails. If you want to disable all such conversions at compile-time, you may predefine wxNO_IMPLICIT_WXSTRING_ENCODING when compiling the application code and the corresponding conversions become inaccessible, i.e.

wxString s;
// s = "world"; does not compile with wxNO_IMPLICIT_WXSTRING_ENCODING
s = wxString::FromAscii("world"); // Always compiles
s = wxASCII_STR("world"); // shorthand for the above
s = wxString::FromUTF8("world"); // Always compiles
s = wxString("world", wxConvLibc); // Always compiles, explicit encoding
s = wxASCII_STR("Grüße"); // Always compiles but s may be empty!

The only case in which such conversions are fully safe is when the library is compiled with wxUSE_UTF8_LOCALE_ONLY option set to 1, as all the strings are assumed to be in UTF-8 encoding then.

Similarly, wxString can be converted to:

• ASCII string using wxString::ToAscii(). This is a potentially destructive operation as all non-ASCII string characters are replaced with a placeholder character.
• String in the current locale encoding implicitly or using c_str() or mb_str() methods. This is a potentially destructive operation as an empty string is returned if the conversion fails.
• String in UTF-8 encoding using wxString::utf8_str().
• String in any given encoding using mb_str() with the appropriate wxMBConv object. This is also a potentially destructive operation.
• Standard std::string using wxString::ToStdString(). The encoding of the returned string is specified with a wxMBConv object, so this conversion is potentially destructive as well. To ensure that there is no data loss, use wxConvUTF8 conversion or wxString::utf8_string().
• Wide C string using implicit conversion or wxString::wc_str() explicitly.
• Standard std::wstring using wxString::ToStdWstring() or its synonym wxString::wc_string().

As above, defining wxNO_IMPLICIT_WXSTRING_ENCODING when compiling application code prevents the implicit use of the current locale encoding and disables implicit conversions to char* and std::string as well as using mb_str() and ToStdString() without explicitly specifying the encoding:

const char *c;
// c = s.c_str();  does not compile with wxNO_IMPLICIT_WXSTRING_ENCODING
// c = s.mb_str(); does not compile with wxNO_IMPLICIT_WXSTRING_ENCODING
c = s.ToAscii(); // Always compiles, encoding may fail
c = s.ToUTF8(); // Always compiles, encoding never fails
c = s.utf8_str(); // Alias for the above
c = s.mb_str(wxConvLibc); // Always compiles, explicit encoding, but
                          // conversion may fail!

However, if completely disabling conversions to narrow strings by defining wxNO_IMPLICIT_WXSTRING_ENCODING is undesirable, it is also possible to disable implicit conversions by predefining wxNO_UNSAFE_WXSTRING_CONV instead, i.e. with this symbol defined implicit conversion to const char* becomes unavailable – but explicit conversions using c_str() and mb_str() still work.

Finally, please note that implicit conversion to both const char* (which is unsafe for the reasons explained above) and to const wchar_t* (which is safe from this point of view, but may still be considered dangerous, as any implicit conversion) may be entirely disabled by defining wxNO_IMPLICIT_WXSTRING_CONV_TO_PTR when building the application.

To summarize, the safest way to use wxString is to always define wxNO_IMPLICIT_WXSTRING_ENCODING in the application compilation options to disable all implicit uses of encoding and specify it explicitly, typically by using utf8_str() or utf8_string() and FromUTF8() for conversions, for every operation. If this is impossible, for example because it would require too many changes to the existing code, consider defining wxNO_UNSAFE_WXSTRING_CONV to at least disable implicit unsafe conversions.

Traps for the unwary

As mentioned above, wxString tries to be compatible with both narrow and wide standard string classes and mostly does it transparently, but there are some exceptions.

String element access

Some problems are caused by wxString::operator[]() which returns an object of a special proxy class allowing to assign either a simple char or a wchar_t to the given index. Because of this, the return type of this operator is neither char nor wchar_t nor a reference to one of these types but wxUniCharRef which is not a primitive type and hence can't be used in the switch statement. So the following code does not compile

wxString s(...);
switch ( s[n] ) {
    case 'A':
        ...
        break;
}

and you need to use

switch ( s[n].GetValue() ) {
    ...
}

instead. Alternatively, you can use an explicit cast:

switch ( static_cast<char>(s[n]) ) {
    ...
}

but notice that this will result in an assert failure if the character at the given position is not representable as a single char in the current encoding, so you may want to cast to int instead if non-ASCII values can be used.

Another consequence of this unusual return type arises when it is used with template deduction or C++11 auto keyword. Unlike with the normal references which are deduced to be of the referenced type, the deduced type for wxUniCharRef is wxUniCharRef itself. This results in potentially unexpected behaviour, for example:

wxString s("abc");
auto c = s[0];
c = 'x';            // Modifies the string!
wxASSERT( s == "xbc" );

Due to this, either explicitly specify the variable type:

int c = s[0];
c = 'x';            // Doesn't modify the string any more.
wxASSERT( s == "abc" );

or explicitly convert the return value:

auto c = s[0].GetValue();
c = 'x';            // Doesn't modify the string either.
wxASSERT( s == "abc" );

Conversion to C string

A different class of problems happens due to the dual nature of the return value of wxString::c_str() method, which is also used for implicit conversions. The result of calls to this method is convertible to either narrow char* string or wide wchar_t* string and so, again, has neither the former nor the latter type. Usually, the correct type will be chosen depending on how you use the result but sometimes the compiler can't choose it because of an ambiguity, e.g.:

// Some non-wxWidgets functions existing for both narrow and wide
// strings:
void dump_text(const char* text);       // Version (1)
void dump_text(const wchar_t* text);    // Version (2)
 
wxString s(...);
dump_text(s);           // ERROR: ambiguity.
dump_text(s.c_str());   // ERROR: still ambiguous.

In this case you need to explicitly convert to the type that you need to use or use a different, non-ambiguous, conversion function (which is usually the best choice):

dump_text(static_cast<const char*>(s));            // OK, calls (1)
dump_text(static_cast<const wchar_t*>(s.c_str())); // OK, calls (2)
dump_text(s.mb_str());                             // OK, calls (1)
dump_text(s.wc_str());                             // OK, calls (2)
dump_text(s.wx_str());                             // OK, calls ???

Using wxString with vararg functions

A special subclass of the problems arising due to the polymorphic nature of wxString::c_str() result type happens when using functions taking an arbitrary number of arguments, such as the standard printf(). Due to the rules of the C++ language, the types for the "variable" arguments of such functions are not specified and hence the compiler cannot convert wxString objects, or the objects returned by wxString::c_str(), to these unknown types automatically. Hence neither wxString objects nor the results of most of the conversion functions can be passed as vararg arguments:

// ALL EXAMPLES HERE DO NOT WORK, DO NOT USE THEM!
printf("Don't do this: %s", s);
printf("Don't do that: %s", s.c_str());
printf("Nor even this: %s", s.mb_str());
wprintf("And even not always this: %s", s.wc_str());

Instead you need to either explicitly cast to the needed type:

// These examples work but are not the best solution, see below.
printf("You can do this: %s", static_cast<const char*>(s));
printf("Or this: %s", static_cast<const char*>(s.c_str()));
printf("And this: %s", static_cast<const char*>(s.mb_str()));
wprintf("Or this: %s", static_cast<const wchar_t*>(s.wc_str()));

But a better solution is to use wxWidgets-provided functions, if possible, as is the case for printf family of functions:

// This is the recommended way.
wxPrintf("You can do just this: %s", s);
wxPrintf("And this (but it is redundant): %s", s.c_str());
wxPrintf("And this (not using Unicode): %s", s.mb_str());
wxPrintf("And this (always Unicode): %s", s.wc_str());

Notice that wxPrintf() replaces both printf() and wprintf() and accepts wxString objects, results of c_str() calls but also char* and wchar_t* strings directly.

wxWidgets provides wx-prefixed equivalents to all the standard vararg functions and a few more, notably wxString::Format(), wxLogMessage(), wxLogError() and other log functions. But if you can't use one of those functions and need to pass wxString objects to non-wx vararg functions, you need to use the explicit casts as explained above.

Performance characteristics

wxString uses std::basic_string internally to store its content and it therefore inherits many features from the standard class. In particular, most implementations of std::basic_string use small string optimization, meaning that they avoid allocating heap memory for short strings, and this is also true for wxString.

By default, wxString uses std::basic_string specialized for the platform-dependent wchar_t type, meaning that it is not memory-efficient for ASCII strings, especially under Unix platforms where every ASCII character, normally fitting in a byte, is represented by a 4 byte wchar_t.

It is possible to build wxWidgets with wxUSE_UNICODE_UTF8 set to 1 in which case an UTF-8-encoded string representation is stored in std::basic_string specialized for char, i.e. the usual std::string. In this case the memory efficiency problem mentioned above doesn't arise but run-time performance of many wxString methods changes dramatically, in particular accessing the N-th character of the string becomes an operation taking O(N) time instead of O(1), i.e. constant, time by default. Thus, if you do use this so called UTF-8 build, you should avoid using indices to access the strings whenever possible and use the iterators instead. As an example, traversing the string using iterators is an O(N), where N is the string length, operation in both the normal ("wchar_t") and UTF-8 builds but doing it using indices becomes O(N^2) in UTF-8 case meaning that simply checking every character of a reasonably long (e.g. a couple of millions elements) string can take an unreasonably long time.

However, if you do use iterators, UTF-8 build can be a better choice than the default build, especially for the memory-constrained embedded systems. Notice also that GTK+ and DirectFB use UTF-8 internally, so using this build not only saves memory for ASCII strings but also avoids conversions between wxWidgets and the underlying toolkit.

Index of the member groups

Links for quick access to the various categories of wxString functions:

• Constructors and assignment operators
• Length functions
• Character access functions
• Conversions functions
• Concatenation functions
• Comparison functions
• Substring extraction functions
• Case conversion functions
• Searching and replacing functions
• Conversion to numbers functions
• Formatting and printing functions
• Memory management functions
• Miscellaneous functions
• Iterator interface functions
• STL interface functions

Library:  wxBase

Category:  Data Structures

Predefined objects/pointers: wxEmptyString

See also

wxString Overview, Unicode Support in wxWidgets, String-related functions, wxUString, wxCharBuffer, wxUniChar, wxStringTokenizer, wxStringBuffer, wxStringBufferLength

Public Types
Standard types
Types used with wxString.
typedef wxUniChar	value_type
typedef wxUniChar	char_type
typedef wxUniCharRef	reference
typedef wxChar *	pointer
typedef const wxChar *	const_pointer
typedef size_t	size_type
typedef wxUniChar	const_reference

Public Member Functions
Constructors and assignment operators
A string may be constructed either from a C string, (some number of copies of) a single character or a wide (Unicode) string. For all constructors (except the default which creates an empty string) there is also a corresponding assignment operator. See also the assign() STL-like function.
	wxString ()
	Default constructor.
	wxString (const wxString &stringSrc)
	Creates a string from another string.
	wxString (wxUniChar ch, size_t nRepeat=1)
	Construct a string consisting of nRepeat copies of ch.
	wxString (wxUniCharRef ch, size_t nRepeat=1)
	Construct a string consisting of nRepeat copies of ch.
	wxString (char ch, size_t nRepeat=1)
	Construct a string consisting of nRepeat copies of ch converted to Unicode using the current locale encoding.
	wxString (wchar_t ch, size_t nRepeat=1)
	Construct a string consisting of nRepeat copies of ch.
	wxString (const char *psz)
	Constructs a string from the string literal psz using the current locale encoding to convert it to Unicode (wxConvLibc).
	wxString (const char *psz, const wxMBConv &conv)
	Constructs a string from the string literal psz using conv to convert it Unicode.
	wxString (const char *psz, size_t nLength)
	Constructs a string from the first nLength bytes of the string literal psz using the current locale encoding to convert it to Unicode (wxConvLibc).
	wxString (const char *psz, const wxMBConv &conv, size_t nLength)
	Constructs a string from the first nLength bytes of the string literal psz using conv to convert it Unicode.
	wxString (const wchar_t *pwz)
	Constructs a string from the string literal pwz.
	wxString (const wchar_t *pwz, size_t nLength)
	Constructs a string from the first nLength characters of the string literal pwz.
	wxString (const wxCharBuffer &buf)
	Constructs a string from buf using the using the current locale encoding to convert it to Unicode.
	wxString (const wxWCharBuffer &buf)
	Constructs a string from buf.
	wxString (const std::string &str)
	Constructs a string from str using the using the current locale encoding to convert it to Unicode (wxConvLibc).
	wxString (std::string_view str)
	Constructs a string from str using the using the current locale encoding to convert it to Unicode (wxConvLibc).
	wxString (const std::wstring &str)
	Constructs a string from str.
	wxString (std::wstring_view str)
	Constructs a string from str.
	~wxString ()
	String destructor.
wxString	operator= (const wxString &str)
	Assignment: see the relative wxString constructor.
wxString	operator= (wxUniChar c)
	Assignment: see the relative wxString constructor.
void	AssignFromUTF8Unchecked (const char *utf8, size_t len=npos)
	Assignment from UTF-8 string.

Member Typedef Documentation

char_type

typedef wxUniChar wxString::char_type

const_pointer

typedef const wxChar* wxString::const_pointer

const_reference

typedef wxUniChar wxString::const_reference

pointer

typedef wxChar* wxString::pointer

reference

typedef wxUniCharRef wxString::reference

size_type

typedef size_t wxString::size_type

value_type

typedef wxUniChar wxString::value_type

Constructor & Destructor Documentation

wxString() [1/18]

wxString::wxString

(

)

Default constructor.

wxString() [2/18]

wxString::wxString

(

const wxString &

stringSrc

)

Creates a string from another string.

Just increases the ref count by 1.

wxString() [3/18]

wxString::wxString	(	wxUniChar	ch,
		size_t	nRepeat = 1 )

Construct a string consisting of nRepeat copies of ch.

wxString() [4/18]

wxString::wxString	(	wxUniCharRef	ch,
		size_t	nRepeat = 1 )

Construct a string consisting of nRepeat copies of ch.

wxString() [5/18]

wxString::wxString	(	char	ch,
		size_t	nRepeat = 1 )

Construct a string consisting of nRepeat copies of ch converted to Unicode using the current locale encoding.

wxString() [6/18]

wxString::wxString	(	wchar_t	ch,
		size_t	nRepeat = 1 )

Construct a string consisting of nRepeat copies of ch.

wxString() [7/18]

wxString::wxString

(

const char *

psz

)

Constructs a string from the string literal psz using the current locale encoding to convert it to Unicode (wxConvLibc).

wxString() [8/18]

wxString::wxString	(	const char *	psz,
		const wxMBConv &	conv )

Constructs a string from the string literal psz using conv to convert it Unicode.

wxString() [9/18]

wxString::wxString	(	const char *	psz,
		size_t	nLength )

Constructs a string from the first nLength bytes of the string literal psz using the current locale encoding to convert it to Unicode (wxConvLibc).

wxString() [10/18]

wxString::wxString	(	const char *	psz,
		const wxMBConv &	conv,
		size_t	nLength )

Constructs a string from the first nLength bytes of the string literal psz using conv to convert it Unicode.

wxString() [11/18]

wxString::wxString

(

const wchar_t *

pwz

)

Constructs a string from the string literal pwz.

wxString() [12/18]

wxString::wxString	(	const wchar_t *	pwz,
		size_t	nLength )

Constructs a string from the first nLength characters of the string literal pwz.

wxString() [13/18]

wxString::wxString

(

const wxCharBuffer &

buf

)

Constructs a string from buf using the using the current locale encoding to convert it to Unicode.

wxString() [14/18]

wxString::wxString

(

const wxWCharBuffer &

buf

)

Constructs a string from buf.

wxString() [15/18]

wxString::wxString

(

const std::string &

str

)

Constructs a string from str using the using the current locale encoding to convert it to Unicode (wxConvLibc).

See also

ToStdString()

wxString() [16/18]

wxString::wxString

(

std::string_view

str

)

Constructs a string from str using the using the current locale encoding to convert it to Unicode (wxConvLibc).

Note

Requires the application to be compiled with C++17

Since

3.3.0

wxString() [17/18]

wxString::wxString

(

const std::wstring &

str

)

Constructs a string from str.

See also

ToStdWstring(), wc_string()

wxString() [18/18]

wxString::wxString

(

std::wstring_view

str

)

Constructs a string from str.

Note

Requires the application to be compiled with C++17

Since

3.3.0

~wxString()

wxString::~wxString

(

)

String destructor.

Note that this is not virtual, so wxString must not be inherited from.

Member Function Documentation

AssignFromUTF8Unchecked()

void wxString::AssignFromUTF8Unchecked	(	const char *	utf8,
		size_t	len = npos )

Assignment from UTF-8 string.

Calling s.AssignFromUTF8(utf8, len) is equivalent to doing s = wxString::FromUTF8(utf8, len)` but may be more efficient as it can reuse the existing string buffer instead of always having to allocate a new one.

This function can be useful in performance-sensitive loops or with static variables (retaining their buffer between calls) in often called functions.

Since

3.3.2 */ void AssignFromUTF8(const char *utf8, size_t len = npos);

/** Assignment from UTF-8 string.

This function is the same as AssignFromUTF8() but doesn't check that utf8 is a valid pointer to a valid UTF-8 string. It must not be called if utf8 is @NULL or its contents is not already known to be correct UTF-8.

Since

3.3.2

operator=() [1/2]

wxString wxString::operator=

(

const wxString &

str

)

Assignment: see the relative wxString constructor.

operator=() [2/2]

wxString wxString::operator=

(

wxUniChar

c

)

Assignment: see the relative wxString constructor.