+ String class for passing textual data to or receiving it from wxWidgets.
+
+ @note
+ While the use of wxString is unavoidable in wxWidgets program, you are
+ encouraged to use the standard string classes @c std::string or @c
+ 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 @c wchar_t wide characters and @c wchar_t*
+ wide strings and traditional @c char characters and @c 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 Unicode build of wxWidgets 3.0. It is also mostly
+ transparent when using wxString with the few exceptions described below.
+
+
+ @section string_api API overview
+
+ wxString tries to be similar to both @c std::string and @c 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 any standard library
+ documentation, for example http://en.cppreference.com/w/cpp/string for more
+ details).
+
+ 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.
+
+
+ @section string_conv Converting to and from wxString
+
+ wxString can be created from:
+ - ASCII string guaranteed to contain only 7 bit characters using
+ wxString::FromAscii().
+ - Narrow @c char* string in the current locale encoding using implicit
+ wxString::wxString(const char*) constructor.
+ - Narrow @c char* string in UTF-8 encoding using wxString::FromUTF8().
+ - Narrow @c 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 @c 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()
+ or the constructor taking wxMBConv if this is not the case.
+ - Wide @c wchar_t* string using implicit wxString::wxString(const
+ wchar_t*) constructor.
+ - Standard @c std::wstring using implicit wxString::wxString(const
+ std::wstring&) 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.
+
+ 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 @e
+ 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 @c std::string using wxString::ToStdString(). The contents
+ of the returned string use the current locale encoding, so this
+ conversion is potentially destructive as well.
+ - Wide C string using wxString::wc_str().
+ - Standard @c std::wstring using wxString::ToStdWstring().
+
+ @note If you built wxWidgets with @c wxUSE_STL set to 1, the implicit
+ conversions to both narrow and wide C strings are disabled and replaced
+ with implicit conversions to @c std::string and @c std::wstring.
+
+ Please notice that the conversions marked as "potentially destructive"
+ above can result in loss of data if their result is not checked, so you
+ need to verify that converting the contents of a non-empty Unicode string
+ to a non-UTF-8 multibyte encoding results in non-empty string. The simplest
+ and best way to ensure that the conversion never fails is to always use
+ UTF-8.
+
+
+ @section string_gotchas 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.
+
+ @subsection string_gotchas_element 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 @c char or a @c
+ wchar_t to the given index. Because of this, the return type of this
+ operator is neither @c char nor @c 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 @c switch statement. So the following code does @e not compile
+ @code
+ wxString s(...);
+ switch ( s[n] ) {
+ case 'A':
+ ...
+ break;
+ }
+ @endcode
+ and you need to use
+ @code
+ switch ( s[n].GetValue() ) {
+ ...
+ }
+ @endcode
+ instead. Alternatively, you can use an explicit cast:
+ @code
+ switch ( static_cast<char>(s[n]) ) {
+ ...
+ }
+ @endcode
+ but notice that this will result in an assert failure if the character at
+ the given position is not representable as a single @c char in the current
+ encoding, so you may want to cast to @c 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 @c 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:
+ @code
+ wxString s("abc");
+ auto c = s[0];
+ c = 'x'; // Modifies the string!
+ wxASSERT( s == "xbc" );
+ @endcode
+ Due to this, either explicitly specify the variable type:
+ @code
+ int c = s[0];
+ c = 'x'; // Doesn't modify the string any more.
+ wxASSERT( s == "abc" );
+ @endcode
+ or explicitly convert the return value:
+ @code
+ auto c = s[0].GetValue();
+ c = 'x'; // Doesn't modify the string neither.
+ wxASSERT( s == "abc" );
+ @endcode
projects / wxWidgets.git / blobdiff