X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0c339e7c64caf6e72acea0a83344abbfa8a1b791..b54129836cbc680fbeb338bb6087c1a4f80bdf18:/interface/wx/string.h?ds=sidebyside diff --git a/interface/wx/string.h b/interface/wx/string.h index 204cd4ec95..dd0c7d7d2e 100644 --- a/interface/wx/string.h +++ b/interface/wx/string.h @@ -65,28 +65,41 @@ public: /** @class wxString + The wxString class has been completely rewritten for wxWidgets 3.0 + and this change was actually the main reason for the calling that + version wxWidgets 3.0. + wxString is a class representing a Unicode character string. wxString uses @c std::string internally to store its content unless this is not supported by the compiler or disabled - specifically when building wxWidgets. Therefore wxString - inherits many features from @c std::string. Most - implementations of @c std::string are thread-safe and don't - use reference counting. By default, wxString uses @c std::string - internally even if wxUSE_STL is not defined. - - Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per - character wchar_t and nearly the same as UTF-16) under Windows and - UTF-8 under Unix, Linux and OS X to store its content. + specifically when building wxWidgets and it therefore inherits + many features from @c std::string. Most implementations of + @c std::string are thread-safe and don't use reference counting. + By default, wxString uses @c std::string internally even if + wxUSE_STL is not defined. + + wxString now internally uses UTF-16 under Windows and UTF-8 under + Unix, Linux and OS X to store its content. Note that when iterating + over a UTF-16 string under Windows, the user code has to take care + of surrogate pair handling whereas Windows itself has built-in + support pairs in UTF-16, such as for drawing strings on screen. + Much work has been done to make existing code using ANSI string literals - work as before. If you need to have a wxString that uses wchar_t on Unix - and Linux, too, you can specify this on the command line with the - @c configure @c --disable-utf8 switch. - - If you need a Unicode string class with O(1) access on all platforms - you should consider using wxUString. - - Since iterating over a wxString by index can become inefficient in UTF-8 - mode iterators should be used instead of index based access: + work as before. If you nonetheless need to have a wxString that uses wchar_t + on Unix and Linux, too, you can specify this on the command line with the + @c configure @c --disable-utf8 switch or you can consider using wxUString + or std::wstring instead. + + Accessing a UTF-8 string by index can be very inefficient because + a single character is represented by a variable number of bytes so that + the entire string has to be parsed in order to find the character. + Since iterating over a string by index is a common programming technique and + was also possible and encouraged by wxString using the access operator[]() + wxString implements caching of the last used index so that iterating over + a string is a linear operation even in UTF-8 mode. + + It is nonetheless recommended to use iterators (instead of index based + access) like this: @code wxString s = "hello"; @@ -446,7 +459,7 @@ public: /** Appends the string literal @e psz with max length @e nLen. */ - wxString& Append(const char* psz, size_t nLen); + wxString& Append(const wchar_t* pwz); /** Appends the wide string literal @e psz with max length @e nLen. @@ -456,7 +469,7 @@ public: /** Appends the string @e s. */ - wxString &Append(const wxString &s); + wxString& Append(const wchar_t* pwz, size_t nLen); /** Appends the character @e ch @e count times. @@ -805,14 +818,16 @@ public: wxString& MakeCapitalized(); /** - Converts all characters to lower case and returns the result. + Converts all characters to lower case and returns the reference to the + modified string. @see Lower() */ wxString& MakeLower(); /** - Converts all characters to upper case and returns the result. + Converts all characters to upper case and returns the reference to the + modified string. @see Upper() */ @@ -1152,14 +1167,14 @@ public: wxString& operator<<(const char* psz) wxString& operator<<(const wchar_t* pwz) wxString& operator<<(const wxCStrData& psz) - wxString& operator<<(wxUniChar ch); + wxString& operator<<(const char* psz); wxString& operator<<(wxUniCharRef ch) wxString& operator<<(char ch) wxString& operator<<(unsigned char ch) wxString& operator<<(wchar_t ch) wxString& operator<<(const wxCharBuffer& s) wxString& operator<<(const wxWCharBuffer& s) - wxString& operator<<(int i); + wxString& operator<<(wxUniCharRef ch); wxString& operator<<(unsigned int ui); wxString& operator<<(long l); wxString& operator<<(unsigned long ul);