wxString Class Reference
[Data Structures]

#include <wx/string.h>

List of all members.

Detailed Description

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 std::string internally to store its content unless this is not supported by the compiler or disabled specifically when building wxWidgets and it therefore inherits many features from std::string. Most implementations of std::string are thread-safe and don't use reference counting. By default, wxString uses 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 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 configure --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:

    wxString s = "hello";
    wxString::const_iterator i;
    for (i = s.begin(); i != s.end(); ++i)
    {
        wxUniChar uni_ch = *i;
        // do something with it
    }

Please see the wxString Overview and the Unicode Support in wxWidgets for more information about it.

wxString uses the current locale encoding to convert any C string literal to Unicode. The same is done for converting to and from std::string and for the return value of c_str(). For this conversion, the wxConvLibc class instance is used. See wxCSConv and wxMBConv.

wxString implements most of the methods of the 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 Length(), Len() and length() which all return the string length. In all cases of such duplication the std::string compatible method should be used.

Constructors and assignment operators

A string may be constructed either from a C string, (some number of copies of) 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.

String length

These functions return the string length and check whether the string is empty or they empty it.

Character access

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 string is string[0]. An attempt to access a character beyond the end of the string (which may even be 0 if the string is empty) will provoke an assert failure in debug builds, but no checks are done in release builds.

This section also contains both implicit and explicit conversions to C style strings. Although implicit conversion is quite convenient, you are advised to use wc_str() for the sake of clarity.

Concatenation

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.

Comparison

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.

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.

Substring extraction

These functions allow you to extract a substring from the string. The original string is not modified and the function returns the extracted substring.

Case conversion

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.

Searching and replacing

These functions replace the standard strchr() and strstr() functions.

Conversion to numbers

The string provides functions for conversion to signed and unsigned integer and floating point numbers. All functions take a pointer to the variable to put the numeric value in and return true if the entire string could be converted to a number.

Writing values into the string

Both formatted versions (Printf/() and stream-like insertion operators exist (for basic types only). Additionally, the Format() function allows you to simply append a formatted value to a string:

Memory management

The following are "advanced" functions and they will be needed rarely. Alloc() and Shrink() are only interesting for optimization purposes. wxStringBuffer and wxStringBufferLength classes may be very useful when working with some external API which requires the caller to provide a writable buffer.

Miscellaneous

Miscellaneous other string functions.

wxWidgets 1.xx compatibility functions

The following functions are deprecated. Please consider using std::string compatible variants.

Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase()

Library:  wxBase

Category:  Data Structures

Predefined objects/pointers: wxEmptyString

See also:
wxString Overview, Unicode Support in wxWidgets, wxUString

Public Types

Standard types
typedef wxUniChar value_type
typedef wxUniChar char_type
typedef wxUniCharRef reference
typedef wxChar * pointer
typedef const wxChar * const_pointer
typedef size_t size_type
typedef wxUniChar const_reference

Public Member Functions

 wxString ()
 wxString (const wxString &stringSrc)
 wxString (const char *psz)
 wxString (const char *psz, const wxMBConv &conv)
 wxString (const char *psz, size_t nLength)
 wxString (const char *psz, const wxMBConv &conv, size_t nLength)
 wxString (const wchar_t *pwz)
 wxString (const wchar_t *pwz, size_t nLength)
 wxString (const wxCharBuffer &buf)
 wxString (const wxWCharBuffer &buf)
 wxString (const std::string &str)
 wxString (const std::wstring &str)
 ~wxString ()
wxString AfterFirst (wxUniChar ch) const
wxString AfterLast (wxUniChar ch) const
bool Alloc (size_t nLen)
wxString & Append (const char *psz)
wxString & Append (const wchar_t *pwz)
wxString & Append (const char *psz, size_t nLen)
wxString & Append (const wchar_t *pwz, size_t nLen)
wxString & Append (const wxString &s)
wxString & Append (wxUniChar ch, size_t count=1u)
wxString BeforeFirst (wxUniChar ch) const
wxString BeforeLast (wxUniChar ch) const
wxString Capitalize () const
void Clear ()
wxString Clone () const
int Cmp (const wxString &s) const
int CmpNoCase (const wxString &s) const
bool Contains (const wxString &str) const
void Empty ()
bool EndsWith (const wxString &suffix, wxString *rest=NULL) const
int Find (wxUniChar ch, bool fromEnd=false) const
int Find (const wxString &sub) const
int Freq (wxUniChar ch) const
wxUniChar GetChar (size_t n) const
const wxCStrData GetData () const
wxUniCharRef GetWritableChar (size_t n)
wxStringCharType * GetWriteBuf (size_t len)
bool IsAscii () const
bool IsEmpty () const
bool IsNull () const
bool IsNumber () const
bool IsWord () const
wxString Left (size_t count) const
size_t Len () const
size_t Length () const
wxString Lower () const
void LowerCase ()
wxString & MakeCapitalized ()
wxString & MakeLower ()
wxString & MakeUpper ()
bool Matches (const wxString &mask) const
wxString Mid (size_t first, size_t nCount=wxString::npos) const
wxString & Pad (size_t count, wxUniChar chPad= ' ', bool fromRight=true)
wxString & Prepend (const wxString &str)
int Printf (const wxString &pszFormat,...)
int PrintfV (const wxString &pszFormat, va_list argPtr)
wxString & RemoveLast (size_t n=1)
size_t Replace (const wxString &strOld, const wxString &strNew, bool replaceAll=true)
wxString Right (size_t count) const
void SetChar (size_t n, wxUniChar ch)
bool Shrink ()
bool StartsWith (const wxString &prefix, wxString *rest=NULL) const
wxString Strip (stripType s=trailing) const
wxString SubString (size_t from, size_t to) const
bool ToDouble (double *val) const
bool ToLong (long *val, int base=10) const
bool ToLongLong (wxLongLong_t *val, int base=10) const
bool ToULong (unsigned long *val, int base=10) const
bool ToULongLong (wxULongLong_t *val, int base=10) const
wxString & Trim (bool fromRight=true)
wxString & Truncate (size_t len)
wxString Upper () const
void UpperCase ()
wxCStrData c_str () const
wxWritableCharBuffer char_str (const wxMBConv &conv=wxConvLibc) const
template<typename T>
wxCharTypeBuffer< T > tchar_str (size_t *len=NULL) const
const wxCharBuffer mb_str (const wxMBConv &conv=wxConvLibc) const
wxString operator() (size_t start, size_t len) const
bool operator! () const
wxWritableWCharBuffer wchar_str () const
const wxStringCharType * wx_str () const
bool operator== (const wxString &x, const wxString &y)
bool operator== (const wxString &x, wxUniChar ch)
bool operator!= (const wxString &x, const wxString &y)
bool operator!= (const wxString &x, wxUniChar ch)
bool operator (const wxString &x, const wxString &y)
bool operator (const wxString &x, wxUniChar ch)
bool operator= (const wxString &x, const wxString &y)
bool operator= (const wxString &x, wxUniChar ch)
bool operator (const wxString &x, const wxString &y)
bool operator (const wxString &x, wxUniChar ch)
bool operator= (const wxString &x, const wxString &y)
bool operator= (const wxString &x, wxUniChar ch)
int First (wxUniChar ch) const
int First (const wxString &str) const
bool IsSameAs (const wxString &s, bool caseSensitive=true) const
bool IsSameAs (wxUniChar ch, bool caseSensitive=true) const
wxUniCharRef Last ()
const wxUniChar Last ()
wxString Remove (size_t pos)
wxString Remove (size_t pos, size_t len)
const char * To8BitData () const
const wxCharBuffer To8BitData () const
const char * ToAscii () const
const wxCharBuffer ToAscii () const
const char * ToUTF8 () const
const wxCharBuffer ToUTF8 () const
void UngetWriteBuf ()
void UngetWriteBuf (size_t len)
const wchar_t * fn_str () const
const char * fn_str () const
const wxCharBuffer fn_str () const
wxString & operator<< (const wxString &s)
wxString & operator<< (const char *psz)
wxString & operator<< (const wchar_t *pwz)
wxString & operator<< (const wxCStrData &psz)
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<< (wxUniCharRef ch)
wxString & operator<< (unsigned int ui)
wxString & operator<< (long l)
wxString & operator<< (unsigned long ul)
wxString & operator<< (wxLongLong_t ll)
wxString & operator<< (wxULongLong_t ul)
wxString & operator<< (float f)
wxString & operator<< (double d)
wxString operator+ (const wxString &x, const wxString &y)
wxString operator+ (const wxString &x, wxUniChar y)
void operator+= (const wxString &str)
void operator+= (wxUniChar c)
wxString operator= (const wxString &str)
wxString operator= (wxUniChar c)
wxUniChar operator[] (size_t i) const
wxUniCharRef operator[] (size_t i)
const char * utf8_str () const
const wxCharBuffer utf8_str () const
const wchar_t * wc_str () const
const wxWCharBuffer wc_str () const
Iterator interface
These methods return iterators to the beginnnig or end of the string.

const_iterator begin () const
iterator begin ()
const_iterator end () const
iterator end ()
const_reverse_iterator rbegin () const
reverse_iterator rbegin ()
const_reverse_iterator rend () const
reverse_iterator rend ()
STL interface
The supported STL functions are listed here. Please see any STL reference for their documentation.

size_t length () const
size_type size () const
size_type max_size () const
size_type capacity () const
void reserve (size_t sz)
void resize (size_t nSize, wxUniChar ch= '\0')
wxString & append (const wxString &str, size_t pos, size_t n)
wxString & append (const wxString &str)
wxString & append (const char *sz, size_t n)
wxString & append (const wchar_t *sz, size_t n)
wxString & append (size_t n, wxUniChar ch)
wxString & append (const_iterator first, const_iterator last)
wxString & assign (const wxString &str, size_t pos, size_t n)
wxString & assign (const wxString &str)
wxString & assign (const char *sz, size_t n)
wxString & assign (const wchar_t *sz, size_t n)
wxString & assign (size_t n, wxUniChar ch)
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, const wxString &str, size_t nStart2, size_t nLen2) const
int compare (size_t nStart, size_t nLen, const char *sz, size_t nCount=npos) const
int compare (size_t nStart, size_t nLen, const wchar_t *sz, size_t nCount=npos) const
bool empty () const
wxString & erase (size_type pos=0, size_type n=npos)
iterator erase (iterator first, iterator last)
iterator erase (iterator first)
size_t find (const wxString &str, size_t nStart=0) const
size_t find (const char *sz, size_t nStart=0, size_t n=npos) const
size_t find (const wchar_t *sz, size_t nStart=0, size_t n=npos) const
size_t find (wxUniChar ch, size_t nStart=0) const
wxString & insert (size_t nPos, const wxString &str)
wxString & insert (size_t nPos, const wxString &str, size_t nStart, size_t n)
wxString & insert (size_t nPos, const char *sz, size_t n)
wxString & insert (size_t nPos, const wchar_t *sz, size_t n)
wxString & insert (size_t nPos, size_t n, wxUniChar ch)
iterator insert (iterator it, wxUniChar ch)
void insert (iterator it, const_iterator first, const_iterator last)
void insert (iterator it, size_type n, wxUniChar ch)
wxString & replace (size_t nStart, size_t nLen, const wxString &str)
wxString & replace (size_t nStart, size_t nLen, size_t nCount, wxUniChar ch)
wxString & replace (size_t nStart, size_t nLen, const wxString &str, size_t nStart2, size_t nLen2)
wxString & replace (size_t nStart, size_t nLen, const char *sz, size_t nCount)
wxString & replace (size_t nStart, size_t nLen, const wchar_t *sz, size_t nCount)
wxString & replace (size_t nStart, size_t nLen, const wxString &s, size_t nCount)
wxString & replace (iterator first, iterator last, const wxString &s)
wxString & replace (iterator first, iterator last, const char *s, size_type n)
wxString & replace (iterator first, iterator last, const wchar_t *s, size_type n)
wxString & replace (iterator first, iterator last, size_type n, wxUniChar ch)
wxString & replace (iterator first, iterator last, const_iterator first1, const_iterator last1)
wxString & replace (iterator first, iterator last, const char *first1, const char *last1)
wxString & replace (iterator first, iterator last, const wchar_t *first1, const wchar_t *last1)
size_t rfind (const wxString &str, size_t nStart=npos) const
size_t rfind (const char *sz, size_t nStart=npos, size_t n=npos) const
size_t rfind (const wchar_t *sz, size_t nStart=npos, size_t n=npos) const
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)

Static Public Member Functions

static wxString Format (const wxChar format,...)
static wxString FormatV (const wxChar format, va_list argptr)
static wxString From8BitData (const char *buf, size_t len)
static wxString From8BitData (const char *buf)
static wxString FromAscii (const char *s)
static wxString FromAscii (const unsigned char *s)
static wxString FromAscii (const char *s, size_t len)
static wxString FromAscii (const unsigned char *s, size_t len)
static wxString FromAscii (char c)
static wxString FromUTF8 (const char *s)
static wxString FromUTF8 (const char *s, size_t len)
static wxString FromUTF8Unchecked (const char *s)
static wxString FromUTF8Unchecked (const char *s, size_t len)

Static Public Attributes

static const size_t npos

Friends

istream operator>> (istream &is, wxString &str)

Member Typedef Documentation

typedef wxUniChar wxString::value_type

typedef wxUniChar wxString::char_type

typedef wxUniCharRef wxString::reference

typedef wxChar* wxString::pointer

typedef const wxChar* wxString::const_pointer

typedef size_t wxString::size_type

typedef wxUniChar wxString::const_reference

Constructor & Destructor Documentation

wxString::wxString (  ) 

Default constructor

wxString::wxString ( const wxString &  stringSrc  ) 

Creates a string from another string. Just increases the ref count by 1.

wxString::wxString ( const char *  psz  ) 

Constructs a string from the string literal psz using the current locale encoding to convert it to Unicode (wxConvLibc).

wxString::wxString ( const char *  psz,
const wxMBConv &  conv 
)

Constructs a string from the string literal psz using conv to convert it Unicode.

wxString::wxString ( const char *  psz,
size_t  nLength 
)

Constructs a string from the first nLength character of the string literal psz using the current locale encoding to convert it to Unicode (wxConvLibc).

wxString::wxString ( const char *  psz,
const wxMBConv &  conv,
size_t  nLength 
)

Constructs a string from the first nLength character of the string literal psz using conv to convert it Unicode.

wxString::wxString ( const wchar_t *  pwz  ) 

Constructs a string from the string literal pwz.

wxString::wxString ( const wchar_t *  pwz,
size_t  nLength 
)

Constructs a string from the first nLength characters of the string literal pwz.

wxString::wxString ( const wxCharBuffer &  buf  ) 

Constructs a string from buf using the using the current locale encoding to convert it to Unicode.

wxString::wxString ( const wxWCharBuffer &  buf  ) 

Constructs a string from buf.

wxString::wxString ( const std::string &  str  ) 

Constructs a string from str using the using the current locale encoding to convert it to Unicode (wxConvLibc).

wxString::wxString ( const std::wstring &  str  ) 

Constructs a string from str.

wxString::~wxString (  ) 

String destructor.

Note that this is not virtual, so wxString must not be inherited from.

Member Function Documentation

wxString wxString::AfterFirst ( wxUniChar  ch  )  const

Gets all the characters after the first occurrence of ch. Returns the empty string if ch is not found.

wxString wxString::AfterLast ( wxUniChar  ch  )  const

Gets all the characters after the last occurrence of ch. Returns the whole string if ch is not found.

bool wxString::Alloc ( size_t  nLen  ) 

Preallocate enough space for wxString to store nLen characters.

Please note that this method does the same thing as the standard reserve() one and shouldn't be used in new code.

This function may be used to increase speed when the string is constructed by repeated concatenation as in

            // delete all vowels from the string
            wxString DeleteAllVowels(const wxString& original)
            {
                wxString result;

                size_t len = original.length();

                result.Alloc(len);

                for ( size_t n = 0; n < len; n++ )
                {
                    if ( strchr("aeuio", tolower(original[n])) == NULL )
                        result += original[n];
                }

                return result;
            }

because it will avoid the need to reallocate string memory many times (in case of long strings). Note that it does not set the maximal length of a string -- it will still expand if more than nLen characters are stored in it. Also, it does not truncate the existing string (use Truncate() for this) even if its current length is greater than nLen.

Returns:
true if memory was successfully allocated, false otherwise.

wxString& wxString::Append ( const char *  psz  ) 

Appends the string literal psz.

wxString& wxString::Append ( const wchar_t *  pwz  ) 

Appends the wide string literal pwz.

wxString& wxString::Append ( const char *  psz,
size_t  nLen 
)

Appends the string literal psz with max length nLen.

wxString& wxString::Append ( const wchar_t *  pwz,
size_t  nLen 
)

Appends the wide string literal psz with max length nLen.

wxString& wxString::Append ( const wxString &  s  ) 

Appends the string s.

wxString& wxString::Append ( wxUniChar  ch,
size_t  count = 1u 
)

Appends the character ch count times.

wxString wxString::BeforeFirst ( wxUniChar  ch  )  const

Gets all characters before the first occurrence of ch. Returns the whole string if ch is not found.

wxString wxString::BeforeLast ( wxUniChar  ch  )  const

Gets all characters before the last occurrence of ch. Returns the empty string if ch is not found.

wxString wxString::Capitalize (  )  const

Return the copy of the string with the first string character in the upper case and the subsequent ones in the lower case.

Since:
2.9.0
See also:
MakeCapitalized()

void wxString::Clear (  ) 

Empties the string and frees memory occupied by it. See also: Empty()

wxString wxString::Clone (  )  const

Returns a deep copy of the string.

That is, the returned string is guaranteed to not share data with this string when using reference-counted wxString implementation.

This method is primarily useful for passing strings between threads (because wxString is not thread-safe). Unlike creating a copy using wxString(c_str()), Clone() handles embedded NULs correctly.

Since:
2.9.0

int wxString::Cmp ( const wxString &  s  )  const

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 strcmp() function).

See also CmpNoCase(), IsSameAs().

int wxString::CmpNoCase ( 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 strcmp() function).

See also Cmp(), IsSameAs().

bool wxString::operator== ( const wxString &  x,
const wxString &  y 
)

Comparison operators

bool wxString::operator== ( const wxString &  x,
wxUniChar  ch 
)

Comparison operators

bool wxString::operator!= ( const wxString &  x,
const wxString &  y 
)

Comparison operators

bool wxString::operator!= ( const wxString &  x,
wxUniChar  ch 
)

Comparison operators