X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/0c7db140c582e66be907160ae2d3a781c6d1353c..6b03a638a437316e47f02a896d3ad664d59c6ddb:/interface/wx/string.h diff --git a/interface/wx/string.h b/interface/wx/string.h index 99b3c9aac1..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"; @@ -123,6 +136,8 @@ public: append something to a C string (including literal constants), so to do this it should be converted to a wxString first. + @li insert() + @li append() @li operator<<() @li operator+=() @li operator+() @@ -137,6 +152,7 @@ public: @li wxString() @li operator=() @li ~wxString() + @li assign() The MakeXXX() variants modify the string in place, while the other functions return a new string which contains the original text converted to the upper or @@ -146,6 +162,8 @@ public: @li Upper() @li MakeLower() @li Lower() + @li MakeCapitalized() + @li Capitalize() Many functions below take a character index in the string. As with C strings and arrays, the indices start from 0, so the first character of a @@ -169,10 +187,9 @@ public: @li mb_str() @li fn_str() - The default comparison function Cmp() is case-sensitive and - so is the default version of IsSameAs(). For case - insensitive comparisons you should use CmpNoCase() or - give a second parameter to IsSameAs. This last function is may be more + The default comparison function Cmp() is case-sensitive and so is the default + version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase() + or give a second parameter to IsSameAs(). This last function is maybe more convenient if only equality of the strings matters because it returns a boolean @true value if the strings are the same and not 0 (which is usually @false in C) as Cmp() does. @@ -182,6 +199,7 @@ public: with some predefined prefix and is more efficient than doing direct string comparison as you would also have to precalculate the length of the prefix. + @li compare() @li Cmp() @li CmpNoCase() @li IsSameAs() @@ -206,6 +224,8 @@ public: when working with some external API which requires the caller to provide a writable buffer. + @li reserve() + @li resize() @li Alloc() @li Shrink() @li wxStringBuffer @@ -220,6 +240,8 @@ public: These functions return the string length and check whether the string is empty or they empty it. + @li length() + @li size() @li Len() @li IsEmpty() @li operator!() @@ -230,6 +252,7 @@ public: original string is not modified and the function returns the extracted substring. + @li substr() @li Mid() @li operator()() @li Left() @@ -244,6 +267,9 @@ public: These functions replace the standard @e strchr() and @e strstr() functions. + @li find() + @li rfind() + @li replace() @li Find() @li Replace() @@ -433,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. @@ -443,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. @@ -792,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() */ @@ -1139,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);