Contents Up Previous Next

wxString

wxString is a class representing a character string. Please see the wxString overview for more information about it.

As explained there, 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.

You may notice that wxString sometimes has many 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 std::string-compatible method (length() in this case, always the lowercase version) should be used as it will ensure smoother transition to std::string when wxWidgets starts using it instead of wxString.

Derived from

None

Include files

<wx/string.h>

Predefined objects

Objects:

wxEmptyString

See also

wxString overview, Unicode overview

Function groups

Constructors and assignment operators
String length
Character access
Concatenation
Comparison
Substring extraction
Case conversion
Searching and replacing
Conversion to numbers
Writing values into the string
Memory management
Miscellaneous
wxWidgets 1.xx compatibility functions
std::string compatibility functions
wxString::wxString
wxString::~wxString
wxString::Alloc
wxString::Append
wxString::AfterFirst
wxString::AfterLast
wxString::BeforeFirst
wxString::BeforeLast
wxString::c_str
wxString::char_str
wxString::Clear
wxString::Cmp
wxString::CmpNoCase
wxString::CompareTo
wxString::Contains
wxString::Empty
wxString::Find
wxString::First
wxString::fn_str
wxString::Format
wxString::FormatV
wxString::Freq
wxString::From8BitData
wxString::FromAscii
wxString::FromUTF8
wxString::GetChar
wxString::GetData
wxString::GetWritableChar
wxString::GetWriteBuf
wxString::Index
wxString::IsAscii
wxString::IsEmpty
wxString::IsNull
wxString::IsNumber
wxString::IsSameAs
wxString::IsWord
wxString::Last
wxString::Left
wxString::Len
wxString::Length
wxString::Lower
wxString::LowerCase
wxString::MakeLower
wxString::MakeUpper
wxString::Matches
wxString::mb_str
wxString::Mid
wxString::Pad
wxString::Prepend
wxString::Printf
wxString::PrintfV
wxString::Remove
wxString::RemoveLast
wxString::Replace
wxString::Right
wxString::SetChar
wxString::Shrink
wxString::StartsWith
wxString::EndsWith
wxString::Strip
wxString::SubString
wxString::To8BitData
wxString::ToAscii
wxString::ToDouble
wxString::ToLong
wxString::ToLongLong
wxString::ToULong
wxString::ToULongLong
wxString::ToUTF8
wxString::Trim
wxString::Truncate
wxString::UngetWriteBuf
wxString::Upper
wxString::UpperCase
wxString::utf8_str
wxString::wc_str
wxString::wchar_str
wxString::operator!
wxString::operator =
wxString::operator +
wxString::operator +=
wxString::operator []
wxString::operator ()
wxString::operator <<
wxString::operator >>
wxString::operator const wxChar*
Comparison operators


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.

wxString
operator =
~wxString


String length

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

Len
IsEmpty
operator!
Empty
Clear


Character access

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 string (which may be even 0 if the string is empty) will provoke an assert failure in debug build, 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, it is advised to use explicit c_str() method for the sake of clarity. Also see overview for the cases where it is necessary to use it.

GetChar
GetWritableChar
SetChar
Last
operator []
c_str
mb_str
wc_str
fn_str
operator const char*


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.

operator <<
operator +=
operator +
Append
Prepend


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 may be 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 then.

Cmp
CmpNoCase
IsSameAs
Matches
StartsWith
EndsWith


Substring extraction

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.

Mid
operator()
Left
Right
BeforeFirst
BeforeLast
AfterFirst
AfterLast
StartsWith
EndsWith


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.

MakeUpper
Upper
MakeLower
Lower


Searching and replacing

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

Find
Replace


Conversion to numbers

The string provides functions for conversion to signed and unsigned integer and floating point numbers. All three 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.

ToLong
ToLongLong
ToULong
ToULongLong
ToDouble


Writing values into the string

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

    // the following 2 snippets are equivalent

    wxString s = "...";
    s += wxString::Format("%d", n);

    wxString s;
    s.Printf("...%d", n);
Format
FormatV
Printf
PrintfV
operator <<


Memory management

These are "advanced" functions and they will be needed quite rarely. Alloc and Shrink are only interesting for optimization purposes. GetWriteBuf may be very useful when working with some external API which requires the caller to provide a writable buffer, but extreme care should be taken when using it: before performing any other operation on the string UngetWriteBuf must be called!

Alloc
Shrink
GetWriteBuf
UngetWriteBuf


Miscellaneous

Other string functions.

Trim
Truncate
Pad


wxWidgets 1.xx compatibility functions

These functions are deprecated, please consider using new wxWidgets 2.0 functions instead of them (or, even better, std::string compatible variants).

CompareTo
Contains
First
Freq
Index
IsAscii
IsNull
IsNumber
IsWord
Last
Length
LowerCase
Remove
Strip
SubString
UpperCase


std::string compatibility functions

The supported functions are only listed here, please see any STL reference for their documentation.

    // take nLen chars starting at nPos
  wxString(const wxString& str, size_t nPos, size_t nLen);
    // take all characters from pStart to pEnd (poor man's iterators)
  wxString(const void *pStart, const void *pEnd);

  // lib.string.capacity
    // return the length of the string
  size_t size() const;
    // return the length of the string
  size_t length() const;
    // return the maximum size of the string
  size_t max_size() const;
    // resize the string, filling the space with c if c != 0
  void resize(size_t nSize, char ch = '\0');
    // delete the contents of the string
  void clear();
    // returns true if the string is empty
  bool empty() const;

  // lib.string.access
    // return the character at position n
  char at(size_t n) const;
    // returns the writable character at position n
  char& at(size_t n);

  // lib.string.modifiers
    // append a string
  wxString& append(const wxString& str);
    // append elements str[pos], ..., str[pos+n]
  wxString& append(const wxString& str, size_t pos, size_t n);
    // append first n (or all if n == npos) characters of sz
  wxString& append(const char *sz, size_t n = npos);

    // append n copies of ch
  wxString& append(size_t n, char ch);

    // same as `this_string = str'
  wxString& assign(const wxString& str);
    // same as ` = str[pos..pos + n]
  wxString& assign(const wxString& str, size_t pos, size_t n);
    // same as `= first n (or all if n == npos) characters of sz'
  wxString& assign(const char *sz, size_t n = npos);
    // same as `= n copies of ch'
  wxString& assign(size_t n, char ch);

    // insert another string
  wxString& insert(size_t nPos, const wxString& str);
    // insert n chars of str starting at nStart (in str)
  wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);

    // insert first n (or all if n == npos) characters of sz
  wxString& insert(size_t nPos, const char *sz, size_t n = npos);
    // insert n copies of ch
  wxString& insert(size_t nPos, size_t n, char ch);

    // delete characters from nStart to nStart + nLen
  wxString& erase(size_t nStart = 0, size_t nLen = npos);

    // replaces the substring of length nLen starting at nStart
  wxString& replace(size_t nStart, size_t nLen, const char* sz);
    // replaces the substring with nCount copies of ch
  wxString& replace(size_t nStart, size_t nLen, size_t nCount, char ch);
    // replaces a substring with another substring
  wxString& replace(size_t nStart, size_t nLen,
                    const wxString& str, size_t nStart2, size_t nLen2);
    // replaces the substring with first nCount chars of sz
    wxString& replace(size_t nStart, size_t nLen,
                      const char* sz, size_t nCount);

    // swap two strings
  void swap(wxString& str);

    // All find() functions take the nStart argument which specifies the
    // position to start the search on, the default value is 0. All functions
    // return npos if there were no match.

    // find a substring
  size_t find(const wxString& str, size_t nStart = 0) const;

    // find first n characters of sz
  size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;

    // find the first occurrence of character ch after nStart
  size_t find(char ch, size_t nStart = 0) const;

    // rfind() family is exactly like find() but works right to left

    // as find, but from the end
  size_t rfind(const wxString& str, size_t nStart = npos) const;

    // as find, but from the end
  size_t rfind(const char* sz, size_t nStart = npos,
          size_t n = npos) const;
    // as find, but from the end
  size_t rfind(char ch, size_t nStart = npos) const;

    // find first/last occurrence of any character in the set

    //
  size_t find_first_of(const wxString& str, size_t nStart = 0) const;
    //
  size_t find_first_of(const char* sz, size_t nStart = 0) const;
    // same as find(char, size_t)
  size_t find_first_of(char c, size_t nStart = 0) const;
    //
  size_t find_last_of (const wxString& str, size_t nStart = npos) const;
    //
  size_t find_last_of (const char* s, size_t nStart = npos) const;
    // same as rfind(char, size_t)
  size_t find_last_of (char c, size_t nStart = npos) const;

    // find first/last occurrence of any character not in the set

    //
  size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
    //
  size_t find_first_not_of(const char* s, size_t nStart = 0) const;
    //
  size_t find_first_not_of(char ch, size_t nStart = 0) const;
    //
  size_t find_last_not_of(const wxString& str, size_t nStart=npos) const;
    //
  size_t find_last_not_of(const char* s, size_t nStart = npos) const;
    //
  size_t find_last_not_of(char ch, size_t nStart = npos) const;

    // All compare functions return a negative, zero or positive value
    // if the [sub]string is less, equal or greater than the compare() argument.

    // just like strcmp()
  int compare(const wxString& str) const;
    // comparison with a substring
  int compare(size_t nStart, size_t nLen, const wxString& str) const;
    // comparison of 2 substrings
  int compare(size_t nStart, size_t nLen,
              const wxString& str, size_t nStart2, size_t nLen2) const;
    // just like strcmp()
  int compare(const char* sz) const;
    // substring comparison with first nCount characters of sz
  int compare(size_t nStart, size_t nLen,
              const char* sz, size_t nCount = npos) const;

  // substring extraction
  wxString substr(size_t nStart = 0, size_t nLen = npos) const;


wxString::wxString

wxString()

Default constructor. Initializes the string to "" (empty string).

wxString(const wxString& x)

Copy constructor.

wxString(wxChar ch, size_t n = 1)

Constructs a string of n copies of character ch.

wxString(const wxChar* psz, size_t nLength = wxSTRING_MAXLEN)

Takes first nLength characters from the C string psz. The default value of wxSTRING_MAXLEN means to take all the string.

Note that this constructor may be used even if psz points to a buffer with binary data (i.e. containing NUL characters) as long as you provide the correct value for nLength. However, the default form of it works only with strings without intermediate NULs because it uses strlen() to calculate the effective length and it would not give correct results otherwise.

wxString(const unsigned char* psz, size_t nLength = wxSTRING_MAXLEN)

For compilers using unsigned char: takes first nLength characters from the C string psz. The default value of wxSTRING_MAXLEN means take all the string. For ANSI builds only (note the use of char instead of wxChar).

Constructors with conversion

The following constructors allow you to construct wxString from a wide string in ANSI build or from a C string in Unicode build.

wxString(const wchar_t* psz, wxMBConv& conv, size_t nLength = wxSTRING_MAXLEN)

Initializes the string from first nLength characters of wide string. The default value of wxSTRING_MAXLEN means take all the string. In ANSI build, conv's WC2MB method is called to convert psz to wide string. It is ignored in Unicode build.

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

Initializes the string from first nLength characters of C string. The default value of wxSTRING_MAXLEN means take all the string. In Unicode build, conv's MB2WC method is called to convert psz to wide string. It is ignored in ANSI build.

See also

wxMBConv classes, mb_str, wc_str


wxString::~wxString

~wxString()

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


wxString::Alloc

void Alloc(size_t nLen)

Preallocate enough space for wxString to store nLen characters. 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


wxString::Append

wxString& Append(const wxChar* psz)

Concatenates psz to this string, returning a reference to it.

wxString& Append(wxChar ch, int count = 1)

Concatenates character ch to this string, count times, returning a reference to it.


wxString::AfterFirst

wxString AfterFirst(wxChar ch) const

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


wxString::AfterLast

wxString AfterLast(wxChar ch) const

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


wxString::BeforeFirst

wxString BeforeFirst(wxChar ch) const

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


wxString::BeforeLast

wxString BeforeLast(wxChar ch) const

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


wxString::c_str

const wxChar * c_str() const

Returns a pointer to the string data (const char* in ANSI build, const wchar_t* in Unicode build).

Note that the returned value will not be convertible to char* or wchar_t* in wxWidgets 3, consider using char_str or wchar_string if you need to pass string value to a function expecting non-const pointer.

See also

mb_str, wc_str, fn_str, char_str, wchar_string


wxString::char_str

wxWritableCharBuffer char_str(wxMBConv& conv = wxConvLibc) const

Returns an object with string data that is implicitly convertible to char* pointer. Note that any change to the returned buffer is lost and so this function is only usable for passing strings to legacy libraries that don't have const-correct API. Use wxStringBuffer if you want to modify the string.

This function is new since wxWidgets version 2.8.4

See also

mb_str, wc_str, fn_str, c_str, wchar_str


wxString::Clear

void Clear()

Empties the string and frees memory occupied by it.

See also: Empty


wxString::Cmp

int Cmp(const wxString& s) const

int Cmp(const wxChar* psz) 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.


wxString::CmpNoCase

int CmpNoCase(const wxString& s) const

int CmpNoCase(const wxChar* psz) 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.


wxString::CompareTo

enum wxString::caseCompare {exact, ignoreCase};
int CompareTo(const wxChar* psz, caseCompare cmp = exact) const

Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.

This is a wxWidgets 1.xx compatibility function; use Cmp instead.


wxString::Contains

bool Contains(const wxString& str) const

Returns true if target appears anywhere in wxString; else false.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::Empty

void Empty()

Makes the string empty, but doesn't free memory occupied by the string.

See also: Clear().


wxString::Find

int Find(wxChar ch, bool fromEnd = false) const

Searches for the given character. Returns the starting index, or wxNOT_FOUND if not found.

int Find(const wxChar* sz) const

Searches for the given string. Returns the starting index, or wxNOT_FOUND if not found.


wxString::First

int First(wxChar c)

int First(const wxChar* psz) const

int First(const wxString& str) const

Same as Find.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::fn_str

const wchar_t* fn_str() const

const char* fn_str() const

const wxCharBuffer fn_str() const

Returns string representation suitable for passing to OS' functions for file handling. In ANSI build, this is same as c_str. In Unicode build, returned value can be either wide character string or C string in charset matching the wxConvFileName object, depending on the OS.

See also

wxMBConv, wc_str, mb_str


wxString::Format

static wxString Format(const wxChar *format, ...)

This static function returns the string containing the result of calling Printf with the passed parameters on it.

See also

FormatV, Printf


wxString::FormatV

static wxString FormatV(const wxChar *format, va_list argptr)

This static function returns the string containing the result of calling PrintfV with the passed parameters on it.

See also

Format, PrintfV


wxString::Freq

int Freq(wxChar ch) const

Returns the number of occurrences of ch in the string.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::From8BitData

static wxString From8BitData(const char* buf, size_tlen)

static wxString From8BitData(const char* buf)

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 len parameter takes NUL-terminated data.

This is a convenience method useful when storing binary data in wxString.

This function is new since wxWidgets version 2.8.4

See also

To8BitData


wxString::FromAscii

static wxString FromAscii(const char* s)

static wxString FromAscii(const char c)

Converts the string or character from an ASCII, 7-bit form to the native wxString representation. Most useful when using a Unicode build of wxWidgets (note the use of char instead of wxChar). Use wxString constructors if you need to convert from another charset.


wxString::FromUTF8

static wxString FromUTF8(const char* s)

static wxString FromUTF8(const char* s, size_t len)

Converts C string encoded in UTF-8 to wxString.

Note that this method assumes that s is a valid UTF-8 sequence and doesn't do any validation in release builds, it's validity is only checked in debug builds.


wxString::GetChar

wxChar GetChar(size_t n) const

Returns the character at position n (read-only).


wxString::GetData

const wxChar* GetData() const

wxWidgets compatibility conversion. Returns a constant pointer to the data in the string.


wxString::GetWritableChar

wxChar& GetWritableChar(size_t n)

Returns a reference to the character at position n.


wxString::GetWriteBuf

wxChar* GetWriteBuf(size_t len)

Returns a writable buffer of at least len bytes. It returns a pointer to a new memory block, and the existing data will not be copied.

Call wxString::UngetWriteBuf as soon as possible to put the string back into a reasonable state.


wxString::Index

size_t Index(wxChar ch) const

size_t Index(const wxChar* sz) const

Same as wxString::Find.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::IsAscii

bool IsAscii() const

Returns true if the string contains only ASCII characters.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::IsEmpty

bool IsEmpty() const

Returns true if the string is empty.


wxString::IsNull

bool IsNull() const

Returns true if the string is empty (same as IsEmpty).

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::IsNumber

bool IsNumber() const

Returns true if the string is an integer (with possible sign).

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::IsSameAs

bool IsSameAs(const wxChar* psz, bool caseSensitive = true) const

Test for string equality, case-sensitive (default) or not.

caseSensitive is true by default (case matters).

Returns true if strings are equal, false otherwise.

See also Cmp, CmpNoCase

bool IsSameAs(wxChar c, bool caseSensitive = true) const

Test whether the string is equal to the single character c. The test is case-sensitive if caseSensitive is true (default) or not if it is false.

Returns true if the string is equal to the character, false otherwise.

See also Cmp, CmpNoCase


wxString::IsWord

bool IsWord() const

Returns true if the string is a word.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::Last

wxChar Last() const

Returns the last character.

wxChar& Last()

Returns a reference to the last character (writable).

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::Left

wxString Left(size_t count) const

Returns the first count characters of the string.


wxString::Len

size_t Len() const

Returns the length of the string.


wxString::Length

size_t Length() const

Returns the length of the string (same as Len).

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::Lower

wxString Lower() const

Returns this string converted to the lower case.


wxString::LowerCase

void LowerCase()

Same as MakeLower.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::MakeLower

wxString& MakeLower()

Converts all characters to lower case and returns the result.


wxString::MakeUpper

wxString& MakeUpper()

Converts all characters to upper case and returns the result.


wxString::Matches

bool Matches(const wxChar* szMask) const

Returns true if the string contents matches a mask containing '*' and '?'.


wxString::mb_str

const char* mb_str(wxMBConv& conv) const

const wxCharBuffer mb_str(wxMBConv& conv) const

Returns multibyte (C string) representation of the string. In Unicode build, converts using conv's cWC2MB method and returns wxCharBuffer. In ANSI build, this function is same as c_str. The macro wxWX2MBbuf is defined as the correct return type (without const).

See also

wxMBConv, c_str, wc_str, fn_str, char_str


wxString::Mid

wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const

Returns a substring starting at first, with length count, or the rest of the string if count is the default value.


wxString::Pad

wxString& Pad(size_t count, wxChar pad = ' ', bool fromRight = true)

Adds count copies of pad to the beginning, or to the end of the string (the default).

Removes spaces from the left or from the right (default).


wxString::Prepend

wxString& Prepend(const wxString& str)

Prepends str to this string, returning a reference to this string.


wxString::Printf

int Printf(const wxChar* pszFormat, ...)

Similar to the standard function sprintf(). Returns the number of characters written, or an integer less than zero on error.

Note that if wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports Unix98-style positional parameters:

    wxString str;

    str.Printf(wxT("%d %d %d"), 1, 2, 3);
    // str now contains "1 2 3"

    str.Printf(wxT("%2$d %3$d %1$d"), 1, 2, 3);
    // str now contains "2 3 1"
NB: This function will use a safe version of vsprintf() (usually called vsnprintf()) whenever available to always allocate the buffer of correct size. Unfortunately, this function is not available on all platforms and the dangerous vsprintf() will be used then which may lead to buffer overflows.


wxString::PrintfV

int PrintfV(const wxChar* pszFormat, va_list argPtr)

Similar to vprintf. Returns the number of characters written, or an integer less than zero on error.


wxString::Remove

wxString& Remove(size_t pos)

Same as Truncate. Removes the portion from pos to the end of the string.

wxString& Remove(size_t pos, size_t len)

Removes len characters from the string, starting at pos.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::RemoveLast

wxString& RemoveLast()

Removes the last character.


wxString::Replace

size_t Replace(const wxChar* szOld, const wxChar* szNew, bool replaceAll = true)

Replace first (or all) occurrences of substring with another one.

replaceAll: global replace (default), or only the first occurrence.

Returns the number of replacements made.


wxString::Right

wxString Right(size_t count) const

Returns the last count characters.


wxString::SetChar

void SetChar(size_t n, wxCharch)

Sets the character at position n.


wxString::Shrink

void Shrink()

Minimizes the string's memory. This can be useful after a call to Alloc() if too much memory were preallocated.


wxString::StartsWith

bool StartsWith(const wxChar *prefix, wxString *rest = NULL) const

This function can be used to test if the string starts with the specified prefix. If it does, the function will return true and put the rest of the string (i.e. after the prefix) into rest string if it is not NULL. Otherwise, the function returns false and doesn't modify the rest.


wxString::EndsWith

bool EndsWith(const wxChar *suffix, wxString *rest = NULL) const

This function can be used to test if the string ends with the specified suffix. If it does, the function will return true and put the beginning of the string before the suffix into rest string if it is not NULL. Otherwise, the function returns false and doesn't modify the rest.


wxString::Strip

enum wxString::stripType {leading = 0x1, trailing = 0x2, both = 0x3};
wxString Strip(stripType s = trailing) const

Strip characters at the front and/or end. The same as Trim except that it doesn't change this string.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::SubString

wxString SubString(size_t from, size_t to) const

Returns the part of the string between the indices from and to inclusive.

This is a wxWidgets 1.xx compatibility function, use Mid instead (but note that parameters have different meaning).


wxString::To8BitData

const char* To8BitData() const

Converts the string to an 8-bit string (ANSI builds only).

const wxCharBuffer To8BitData() const

Converts the string to an 8-bit string in ISO-8859-1 encoding in the form of a wxCharBuffer (Unicode builds only).

This is a convenience method useful when storing binary data in wxString.

This function is new since wxWidgets version 2.8.4

See also

From8BitData


wxString::ToAscii

const char* ToAscii() const

const wxCharBuffer ToAscii() const

Converts the string to an ASCII, 7-bit string in the form of a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).

Note that this conversion only works if the string contains only ASCII characters. The mb_str method provides more powerful means of converting wxString to C string.


wxString::ToDouble

bool ToDouble(double *val) const

Attempts to convert the string to a floating point number. Returns true on success (the number is stored in the location pointed to by val) or false if the string does not represent such number.

See also

wxString::ToLong,
wxString::ToULong


wxString::ToLong

bool ToLong(long *val, int base = 10) const

Attempts to convert the string to a signed integer in base base. Returns true on success in which case the number is stored in the location pointed to by val or false if the string does not represent a valid number in the given base.

The value of base must be comprised between 2 and 36, inclusive, or be a special value 0 which means that the usual rules of C numbers are applied: if the number starts with 0x it is considered to be in base 16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that you may not want to specify the base 0 if you are parsing the numbers which may have leading zeroes as they can yield unexpected (to the user not familiar with C) results.

See also

wxString::ToDouble,
wxString::ToULong


wxString::ToLongLong

bool ToLongLong(wxLongLong_t *val, int base = 10) const

This is exactly the same as ToLong but works with 64 bit integer numbers.

Notice that currently it doesn't work (always returns false) if parsing of 64 bit numbers is not supported by the underlying C run-time library. Compilers with C99 support and Microsoft Visual C++ version 7 and higher do support this.

See also

wxString::ToLong,
wxString::ToULongLong


wxString::ToULong

bool ToULong(unsigned long *val, int base = 10) const

Attempts to convert the string to an unsigned integer in base base. Returns true on success in which case the number is stored in the location pointed to by val or false if the string does not represent a valid number in the given base. Please notice that this function behaves in the same way as the standard strtoul() and so it simply converts negative numbers to unsigned representation instead of rejecting them (e.g. -1 is returned as ULONG_MAX).

See wxString::ToLong for the more detailed description of the base parameter.

See also

wxString::ToDouble,
wxString::ToLong


wxString::ToULongLong

bool ToULongLong(wxULongLong_t *val, int base = 10) const

This is exactly the same as ToULong but works with 64 bit integer numbers.

Please see ToLongLong for additional remarks.


wxString::ToUTF8

const wxCharBuffer ToUF8() const

Same as utf8_str.

This function is new since wxWidgets version 2.8.4


wxString::Trim

wxString& Trim(bool fromRight = true)

Removes white-space (space, tabs, form feed, newline and carriage return) from the left or from the right end of the string (right is default).


wxString::Truncate

wxString& Truncate(size_t len)

Truncate the string to the given length.


wxString::UngetWriteBuf

void UngetWriteBuf()

void UngetWriteBuf(size_t len)

Puts the string back into a reasonable state (in which it can be used normally), after wxString::GetWriteBuf was called.

The version of the function without the len parameter will calculate the new string length itself assuming that the string is terminated by the first NUL character in it while the second one will use the specified length and thus is the only version which should be used with the strings with embedded NULs (it is also slightly more efficient as strlen() doesn't have to be called).


wxString::Upper

wxString Upper() const

Returns this string converted to upper case.


wxString::UpperCase

void UpperCase()

The same as MakeUpper.

This is a wxWidgets 1.xx compatibility function; you should not use it in new code.


wxString::utf8_str

const wxCharBuffer utf8_str() const

Converts the strings contents to UTF-8 and returns it as a temporary wxCharBuffer object.

This function is new since wxWidgets version 2.8.4


wxString::wc_str

const wchar_t* wc_str(wxMBConv& conv) const

const wxWCharBuffer wc_str(wxMBConv& conv) const

Returns wide character representation of the string. In ANSI build, converts using conv's cMB2WC method and returns wxWCharBuffer. In Unicode build, this function is same as c_str. The macro wxWX2WCbuf is defined as the correct return type (without const).

See also

wxMBConv, c_str, mb_str, fn_str, wchar_str


wxString::wchar_str

wxWritableWCharBuffer wchar_str() const

Returns an object with string data that is implicitly convertible to char* pointer. Note that any change to the returned buffer is lost and so this function is only usable for passing strings to legacy libraries that don't have const-correct API. Use wxStringBuffer if you want to modify the string.

This function is new since wxWidgets version 2.8.4

See also

mb_str, wc_str, fn_str, c_str, char_str


wxString::operator!

bool operator!() const

Empty string is false, so !string will only return true if the string is empty. This allows the tests for NULLness of a const wxChar * pointer and emptiness of the string to look the same in the code and makes it easier to port old code to wxString.

See also IsEmpty().


wxString::operator =

wxString& operator =(const wxString& str)

wxString& operator =(const wxChar* psz)

wxString& operator =(wxChar c)

Assignment: the effect of each operation is the same as for the corresponding constructor (see wxString constructors).


wxString::operator +

Concatenation: all these operators return a new string equal to the concatenation of the operands.

wxString operator +(const wxString& x, const wxString& y)

wxString operator +(const wxString& x, const wxChar* y)

wxString operator +(const wxString& x, wxChar y)

wxString operator +(const wxChar* x, const wxString& y)


wxString::operator +=

void operator +=(const wxString& str)

void operator +=(const wxChar* psz)

void operator +=(wxChar c)

Concatenation in place: the argument is appended to the string.


wxString::operator []

wxChar& operator [](size_t i)

wxChar operator [](size_t i) const

wxChar& operator [](int i)

wxChar operator [](int i) const

Element extraction.


wxString::operator ()

wxString operator ()(size_t start, size_t len)

Same as Mid (substring extraction).


wxString::operator <<

wxString& operator <<(const wxString& str)

wxString& operator <<(const wxChar* psz)

wxString& operator <<(wxChar ch)

Same as +=.

wxString& operator <<(int i)

wxString& operator <<(float f)

wxString& operator <<(double d)

These functions work as C++ stream insertion operators: they insert the given value into the string. Precision or format cannot be set using them, you can use Printf for this.


wxString::operator >>

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

Extraction from a stream.


wxString::operator const wxChar*

operator const wxChar*() const

Implicit conversion to a C string.


Comparison operators

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

bool operator ==(const wxString& x, const wxChar* t)

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

bool operator !=(const wxString& x, const wxChar* t)

bool operator >(const wxString& x, const wxString& y)

bool operator >(const wxString& x, const wxChar* t)

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

bool operator >=(const wxString& x, const wxChar* t)

bool operator <(const wxString& x, const wxString& y)

bool operator <(const wxString& x, const wxChar* t)

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

bool operator <=(const wxString& x, const wxChar* t)

Remarks

These comparisons are case-sensitive.