@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()
a single character or a wide (UNICODE) string. For all constructors (except the
default which creates an empty string) there is also a corresponding assignment
operator.
-
+
@li wxString()
@li operator=()
@li ~wxString()
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
lower case and leave the original string unchanged.
-
+
@li MakeUpper()
@li Upper()
@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
done in release builds.
This section also contains both implicit and explicit conversions to C style
strings. Although implicit conversion is quite convenient, it is advised to use
- explicit c_str() method for the sake of clarity.
-
+ explicit c_str() method for the sake of clarity.
+
@li GetChar()
@li GetWritableChar()
@li SetChar()
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.
- Matches() is a poor man's regular expression matcher: it only understands
+ Matches() is a poor man's regular expression matcher: it only understands
'*' and '?' metacharacters in the sense of DOS command line interpreter.
StartsWith() is helpful when parsing a line of text which should start
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 then.
-
+
@li Cmp()
@li CmpNoCase()
@li IsSameAs()
floating point numbers. All three functions take a pointer to the variable to
put the numeric value in and return @true if the @b entire string could be
converted to a number.
-
+
@li ToLong()
@li ToLongLong()
@li ToULong()
wxStringBuffer and wxStringBufferLength classes may be very useful
when working with some external API which requires the caller to provide
a writable buffer.
-
+
@li Alloc()
@li Shrink()
@li wxStringBuffer
@li wxStringBufferLength
Misc. other string functions.
-
+
@li Trim()
@li Truncate()
@li Pad()
These functions return the string length and check whether the string
is empty or empty it.
-
+
@li Len()
@li IsEmpty()
@li operator!()
These functions allow to extract substring from this string. All of them don't
modify the original string and return a new string containing the extracted
substring.
-
+
@li Mid()
@li operator()()
@li Left()
These functions replace the standard @e strchr() and @e strstr()
functions.
-
+
@li Find()
@li Replace()
These functions are deprecated, please consider using new wxWidgets 2.0
functions instead of them (or, even better, std::string compatible variants).
-
+
Contains(), First(), Freq(), IsAscii(), IsNull(),
IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(),
SubString(), UpperCase()
*/
static const size_t npos;
- /**
+ /**
@name Standard types
*/
//@{
Default constructor
*/
wxString();
-
+
/**
- Creates a string from another string. Just increases the ref
+ Creates a string from another string. Just increases the ref
count by 1.
*/
wxString(const wxString& stringSrc);
-
+
/**
- 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);
-
+
/**
String destructor. Note that this is not virtual, so wxString must not be
/**
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().
*/
int Cmp(const wxString& s) const;
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().
*/
int CmpNoCase(const wxString& s) const;
/**
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;
- //@}
//@{
/**
Same as Find().
- This is a wxWidgets 1.xx compatibility function;
+ This is a wxWidgets 1.xx compatibility function;
you should not use it in new code.
*/
int First(wxUniChar ch) 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
//@{
/**
Converts the string or character from an ASCII, 7-bit form
- to the native wxString representation.
+ to the native wxString representation.
*/
static wxString FromAscii(const char* s);
static wxString FromAscii(const unsigned char* s);
//@{
/**
Returns a reference to the last character (writable).
- This is a wxWidgets 1.xx compatibility function;
+ This is a wxWidgets 1.xx compatibility function;
you should not use it in new code.
*/
wxUniCharRef Last();
@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;
//@}
/**
/**
Returns a pointer to the string data (@c const char* when using UTF-8
internally, @c const wchar_t* when using UCS-2 internally).
-
+
Note that the returned value is not convertible to @c char* or
@c wchar_t*, use char_str() or wchar_str() if you need to pass
string value to a function expecting non-const pointer.
*/
wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
+ /**
+ Returns buffer of the specified type containing the string data.
+
+ This method is only useful in template code, otherwise you should
+ directly call mb_str() or wc_str() if you need to retrieve a narrow or
+ wide string from this wxString. The template parameter @a t should be
+ either @c char or @c wchar_t.
+
+ Notice that retrieving a char buffer in UTF-8 build will return the
+ internal string representation in UTF-8 while in wchar_t build the char
+ buffer will contain the conversion of the string to the encoding of the
+ current locale (and so can fail).
+
+ @param len If non-@NULL, filled with the length of the returned buffer.
+ @return
+ buffer containing the string contents in the specified type,
+ notice that it may be @NULL if the conversion failed (e.g. Unicode
+ string couldn't be converted to the current encoding when @a T is
+ @c char).
+ */
+ template <typename T>
+ wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const;
+
//@{
/**
Returns string representation suitable for passing to OS' functions
- for file handling.
+ for file handling.
*/
const wchar_t* fn_str() const;
const char* fn_str() 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;
//@}
/**
/**
Empty string is @false, so !string will only return @true if the
string is empty.
-
+
See also IsEmpty().
*/
bool operator!() const;
Converts the strings contents to the wide character represention
and returns it as a temporary wxWCharBuffer object or returns a
pointer to the internal string contents in wide character mode.
-
+
The macro wxWX2WCbuf is defined as the correct return
type (without const).
/**
@name Iterator interface
-
+
These methods return iterators to the beginnnig or
end of the string.
*/
/**
@name STL interface
-
- The supported STL functions are listed here. Please see any
+
+ The supported STL functions are listed here. Please see any
STL reference for their documentation.
*/
//@{
wxString& assign(const_iterator first, const_iterator last);
void clear();
-
+
int compare(const wxString& str) const;
int compare(size_t nStart, size_t nLen, const wxString& str) const;
int compare(size_t nStart, size_t nLen,
size_t rfind(wxUniChar ch, size_t nStart = npos) const;
wxString substr(size_t nStart = 0, size_t nLen = npos) const;
-
+
void swap(wxString& str);
-
+
//@}
};
projects / wxWidgets.git / blobdiff