X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e846cf877627cb724a348cb44132523ebfcf2390..500b128d0e42dfaa70f46e58d3cc5300c6b25489:/interface/string.h diff --git a/interface/string.h b/interface/string.h index 21e0e70d49..97dfe25336 100644 --- a/interface/string.h +++ b/interface/string.h @@ -72,35 +72,61 @@ public: @class wxString @wxheader{string.h} - wxString is a class representing a character string. It uses - reference counting and copy-on-write internally and is not - thread-safe. Please see the - @ref overview_string "wxString overview" and the - @ref overview_unicode "Unicode overview" for more information - about it. + 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's. Most + implementations of @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) under Windows and UTF-8 under Unix, Linux and - OS X to store its content. Much work has been done to make - existing code using ANSI string literals work as before. + OS X to store its content. 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. + + As a consequence of this change, iterating over a wxString by index + can become inefficient in UTF8 mode and iterators should be used instead: + + @code + wxString s = "hello"; + wxString::const_iterator i; + for (i = s.begin(); i != s.end(); ++i) + { + wxUniChar uni_ch = *i; + // do something with it + } + @endcode + + Please see the + @ref overview_string "wxString overview" and the + @ref overview_unicode "Unicode overview" for more information + about it. - wxString implements most of the methods of the - std::string class. These standard functions are not documented in - this manual, please see the STL documentation. The behaviour of - all these functions is identical to the behaviour described there. + wxString uses the current locale encoding to convert any C string + literal to Unicode. The same is done for converting to and from + @c std::string and for the return value of c_str(). For this + conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv. - You may notice that wxString sometimes has many functions which do - the same thing like, for example, wxString::Length, wxString::Len and @c length() - which all return the string length. In all cases of such duplication the @c std::string - compatible method (@c length() in this case, always the lowercase version) should be - used as it will ensure smoother transition to @c std::string when wxWidgets - starts using it instead of wxString. + wxString implements most of the methods of the @c std::string class. + These standard functions are only listed here, but they are not + fully documented in this manual. Please see the STL documentation. + The behaviour of all these functions is identical to the behaviour + described there. + + You may notice that wxString sometimes has several functions which do + the same thing like, for example, Length(), Len() and length() which + all return the string length. In all cases of such duplication the + @c std::string compatible method should be used. Anything may be concatenated (appended to) with a string. However, you can't append something to a C string (including literal constants), so to do this it should be converted to a wxString first. - @li @ref operatorout() "operator " + @li operator<<() @li operator+=() @li operator+() @li Append() @@ -124,7 +150,6 @@ public: @li MakeLower() @li Lower() - Many functions in this section take a character index in the string. As with C strings and/or arrays, the indices start from 0, so the first character of a string is string[0]. Attempt to access a character beyond the end of the @@ -284,58 +309,58 @@ public: /** - Constructs a string from the string literal @c psz using - the current locale encoding to convert it to Unicode. + Constructs a string from the string literal @e psz using + the current locale encoding to convert it to Unicode (wxConvLibc). */ wxString(const char *psz); /** - Constructs a string from the string literal @c psz using - @c conv to convert it Unicode. + Constructs a string from the string literal @e psz using + @e conv to convert it Unicode. */ wxString(const char *psz, const wxMBConv& conv); /** - Constructs a string from the first @ nLength character of the string literal @c psz using - the current locale encoding to convert it to Unicode. + Constructs a string from the first @e nLength character of the string literal @e psz using + the current locale encoding to convert it to Unicode (wxConvLibc). */ wxString(const char *psz, size_t nLength); /** - Constructs a string from the first @ nLength character of the string literal @c psz using - @c conv to convert it Unicode. + Constructs a string from the first @e nLength character of the string literal @e psz using + @e conv to convert it Unicode. */ wxString(const char *psz, const wxMBConv& conv, size_t nLength); /** - Constructs a string from the string literal @c pwz. + Constructs a string from the string literal @e pwz. */ wxString(const wchar_t *pwz); /** - Constructs a string from the first @ nLength characters of the string literal @c pwz. + Constructs a string from the first @e nLength characters of the string literal @e pwz. */ wxString(const wchar_t *pwz, size_t nLength); /** - Constructs a string from @c buf using the using + Constructs a string from @e buf using the using the current locale encoding to convert it to Unicode. */ wxString(const wxCharBuffer& buf); /** - Constructs a string from @c buf. + Constructs a string from @e buf. */ wxString(const wxWCharBuffer& buf); /** - Constructs a string from @str using the using - the current locale encoding to convert it to Unicode. + Constructs a string from @e str using the using the current locale encoding + to convert it to Unicode (wxConvLibc). */ wxString(const std::string& str); /** - Constructs a string from @str. + Constructs a string from @e str. */ wxString(const std::wstring& str); @@ -348,13 +373,13 @@ public: /** Gets all the characters after the first occurrence of @e ch. - Returns the empty string if @a ch is not found. + Returns the empty string if @e ch is not found. */ wxString AfterFirst(wxUniChar ch) const; /** Gets all the characters after the last occurrence of @e ch. - Returns the whole string if @a ch is not found. + Returns the whole string if @e ch is not found. */ wxString AfterLast(wxUniChar ch) const; @@ -397,15 +422,35 @@ public: */ bool Alloc(size_t nLen); - //@{ /** - Appends the string or string literal or character. + Appends the string literal @e psz. + */ + wxString& Append(const char* psz); + + /** + Appends the wide string literal @e pwz. + */ + wxString& Append(const wchar_t* pwz) + + /** + Appends the string literal @e psz with max length @e nLen. */ wxString& Append(const char* psz, size_t nLen); + + /** + Appends the wide string literal @e psz with max length @e nLen. + */ wxString& Append(const wchar_t* pwz, size_t nLen) + + /** + Appends the string @e s. + */ wxString &Append(const wxString &s); + + /** + Appends the character @e ch @e count times. + */ wxString &Append(wxUniChar ch, size_t count = 1u); - //@} /** Gets all characters before the first occurrence of @e ch. @@ -444,7 +489,7 @@ public: Case-sensitive comparison. Returns a positive value if the string is greater than the argument, zero if it is equal to it or a negative value if it is less than the - argument (same semantics as the standard @e strcmp() function). + argument (same semantics as the standard @c strcmp() function). See also CmpNoCase(), IsSameAs(). */ @@ -454,7 +499,7 @@ public: Case-insensitive comparison. Returns a positive value if the string is greater than the argument, zero if it is equal to it or a negative value if it is less than the - argument (same semantics as the standard @e strcmp() function). + argument (same semantics as the standard @c strcmp() function). See also Cmp(), IsSameAs(). */ @@ -497,20 +542,23 @@ public: /** This function can be used to test if the string ends with the specified @e suffix. If it does, the function will return @true and put the - beginning of the string before the suffix into @a rest string if it is not + beginning of the string before the suffix into @e rest string if it is not @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool EndsWith(const wxString& suffix, wxString rest = NULL) const; + bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; - //@{ /** - Searches for the given string. Returns the starting index, or + Searches for the given character @e ch. Returns the position or @c wxNOT_FOUND if not found. */ int Find(wxUniChar ch, bool fromEnd = false) const; + + /** + Searches for the given string @e sub. Returns the starting position or + @c wxNOT_FOUND if not found. + */ int Find(const wxString& sub) const; - //@} //@{ /** @@ -539,9 +587,9 @@ public: static wxString FormatV(const wxChar format, va_list argptr); /** - Returns the number of occurrences of @a ch in the string. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + Returns the number of occurrences of @e ch in the string. + This is a wxWidgets 1.xx compatibility function; you should not + use it in new code. */ int Freq(wxUniChar ch) const; @@ -549,7 +597,7 @@ public: /** Converts given buffer of binary data from 8-bit string to wxString. In Unicode build, the string is interpreted as being in ISO-8859-1 - encoding. The version without @a len parameter takes NUL-terminated + encoding. The version without @e len parameter takes NUL-terminated data. This is a convenience method useful when storing binary data in @@ -798,7 +846,7 @@ public: @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool StartsWith(const wxString& prefix, wxString rest = NULL) const; + bool StartsWith(const wxString& prefix, wxString *rest = NULL) const; /** Strip characters at the front and/or end. The same as Trim except that it @@ -830,7 +878,7 @@ public: @see wxString::From8BitData() */ const char* To8BitData() const; - const const wxCharBuffer To8BitData() const; + const wxCharBuffer To8BitData() const; //@} //@{ @@ -842,7 +890,7 @@ public: powerful means of converting wxString to C string. */ const char* ToAscii() const; - const const wxCharBuffer ToAscii() const; + const wxCharBuffer ToAscii() const; //@} /** @@ -912,7 +960,7 @@ public: Same as utf8_str(). */ const char* ToUTF8() const; - const const wxCharBuffer ToUF8() const; + const wxCharBuffer ToUF8() const; //@} /** @@ -999,7 +1047,7 @@ public: @see wxMBConv, c_str(), wc_str(), fn_str(), char_str() */ const char* mb_str(const wxMBConv& conv = wxConvLibc) const; - const const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; + const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; //@} /**