@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()
@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
/**
- 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);
/**
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;
*/
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.
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().
*/
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().
*/
/**
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;
- //@}
//@{
/**
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;
/**
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
@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
@see wxString::From8BitData()
*/
const char* To8BitData() const;
- const const wxCharBuffer To8BitData() const;
+ const wxCharBuffer To8BitData() const;
//@}
//@{
powerful means of converting wxString to C string.
*/
const char* ToAscii() const;
- const const wxCharBuffer ToAscii() const;
+ const wxCharBuffer ToAscii() const;
//@}
/**
Same as utf8_str().
*/
const char* ToUTF8() const;
- const const wxCharBuffer ToUF8() const;
+ const wxCharBuffer ToUF8() const;
//@}
/**
@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;
//@}
/**
projects / wxWidgets.git / blobdiff