Correct names of parameters in wxAffineMatrix2D documentation.

[wxWidgets.git] / interface / wx / string.h

diff --git a/interface/wx/string.h b/interface/wx/string.h
index 80f58699d10f5ce944d1018cc5ed48426f73d117..93ff1cbee89fe22ca29491665960a80b3f59c8d5 100644 (file)
--- a/interface/wx/string.h
+++ b/interface/wx/string.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxStringBuffer, wxString
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxStringBuffer, wxString
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -36,208 +36,28 @@
     for important warnings and advices for using it, please read
     the @ref overview_string.
 
     for important warnings and advices for using it, please read
     the @ref overview_string.
 

-    In wxWidgets 3.0 wxString always stores Unicode strings, so you should
+    Since wxWidgets 3.0 wxString always stores Unicode strings, so you should

     be sure to read also @ref overview_unicode.
 
 
     be sure to read also @ref overview_unicode.
 
 

-    @section string_construct Constructors and assignment operators
+    @section string_index Index of the member groups

 
 

-    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.
-
-    @li wxString()
-    @li operator=()
-    @li ~wxString()
-    @li assign()
-
-
-    @section string_len String length
-
-    These functions return the string length and check whether the string
-    is empty or they empty it.
-
-    @li length()
-    @li size()
-    @li Len()
-    @li IsEmpty()
-    @li operator!()
-    @li Empty()
-    @li Clear()
-
-
-    @section string_access 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 @ref overview_debugging "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.
-
-    @li GetChar()
-    @li GetWritableChar()
-    @li SetChar()
-    @li Last()
-    @li operator[]()
-    @li wc_str()
-    @li utf8_str()
-    @li c_str()
-    @li wx_str()
-    @li mb_str()
-    @li fn_str()
-
-
-    @section string_concat 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.
-
-    @li insert()
-    @li append()
-    @li operator<<()
-    @li operator+=()
-    @li operator+()
-    @li Append()
-    @li Prepend()
-
-
-    @section string_comp 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.
-
-    @li compare()
-    @li Cmp()
-    @li CmpNoCase()
-    @li IsSameAs()
-    @li Matches()
-    @li StartsWith()
-    @li EndsWith()
-
-
-    @section string_substring 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.
-
-    @li at()
-    @li substr()
-    @li Mid()
-    @li operator()()
-    @li Left()
-    @li Right()
-    @li BeforeFirst()
-    @li BeforeLast()
-    @li AfterFirst()
-    @li AfterLast()
-    @li StartsWith()
-    @li EndsWith()
-
-
-    @section string_case 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.
-
-    @li MakeUpper()
-    @li Upper()
-    @li MakeLower()
-    @li Lower()
-    @li MakeCapitalized()
-    @li Capitalize()
-
-
-    @section string_search Searching and replacing
-
-    These functions replace the standard @e strchr() and @e strstr()
-    functions.
-
-    @li find()
-    @li rfind()
-    @li replace()
-    @li Find()
-    @li Replace()
-
-
-    @section string_conv 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 @b entire string could be
-    converted to a number.
-
-    @li ToLong()
-    @li ToLongLong()
-    @li ToULong()
-    @li ToULongLong()
-    @li ToDouble()
-
-
-    @section string_fmt 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:
-
-    @li Format()
-    @li FormatV()
-    @li Printf()
-    @li PrintfV()
-    @li operator>>()
-
-
-    @section string_mem 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.
-
-    @li reserve()
-    @li resize()
-    @li Alloc()
-    @li Shrink()
-    @li wxStringBuffer
-    @li wxStringBufferLength
-
-
-    @section string_misc Miscellaneous
-
-    Miscellaneous other string functions.
-
-    @li Trim()
-    @li Truncate()
-    @li Pad()
-
-
-    @section string_compat wxWidgets 1.xx compatibility functions
-
-    The following functions are deprecated.
-    Please consider using @c std::string compatible variants.
-
-    Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(),
-    Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase()
+    Links for quick access to the various categories of wxString functions:
+    - @ref_member_group{ctor, Constructors and assignment operators}
+    - @ref_member_group{length, Length functions}
+    - @ref_member_group{ch_access, Character access functions}
+    - @ref_member_group{conv, Conversions functions}
+    - @ref_member_group{concat, Concatenation functions}
+    - @ref_member_group{cmp, Comparison functions}
+    - @ref_member_group{substring, Substring extraction functions}
+    - @ref_member_group{caseconv, Case conversion functions}
+    - @ref_member_group{search, Searching and replacing functions}
+    - @ref_member_group{numconv, Conversion to numbers functions}
+    - @ref_member_group{fmt, Formatting and printing functions}
+    - @ref_member_group{mem, Memory management functions}
+    - @ref_member_group{misc, Miscellaneous functions}
+    - @ref_member_group{iter, Iterator interface functions}
+    - @ref_member_group{stl, STL interface functions}

 
 
     @library{wxbase}
 
 
     @library{wxbase}


@@ -246,18 +66,17 @@
     @stdobjects
     ::wxEmptyString
 
     @stdobjects
     ::wxEmptyString
 

-    @see @ref overview_string, @ref overview_unicode, wxUString
+    @see @ref overview_string, @ref overview_unicode,
+         @ref group_funcmacro_string "String-related functions", wxUString,
+         wxCharBuffer, wxUniChar, wxStringTokenizer, wxStringBuffer, wxStringBufferLength

 */
 class wxString
 {
 public:
 */
 class wxString
 {
 public:

-    /**
-        An 'invalid' value for string index
-    */
-    static const size_t npos;
-

     /**
         @name Standard types
     /**
         @name Standard types

+
+        Types used with wxString.

     */
     //@{
     typedef wxUniChar value_type;
     */
     //@{
     typedef wxUniChar value_type;


@@ -269,6 +88,19 @@ public:
     typedef wxUniChar const_reference;
     //@}
 
     typedef wxUniChar const_reference;
     //@}
 

+
+    /**
+        @member_group_name{ctor, 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.
+
+        See also the assign() STL-like function.
+    */
+    //@{
+

     /**
        Default constructor
     */
     /**
        Default constructor
     */


@@ -276,68 +108,91 @@ public:
 
     /**
        Creates a string from another string.
 
     /**
        Creates a string from another string.

-        Just increases the ref count by 1.
+       Just increases the ref count by 1.

     */
     wxString(const wxString& stringSrc);
 
     */
     wxString(const wxString& stringSrc);
 

+    /**
+       Construct a string consisting of @a nRepeat copies of ch.
+    */
+    wxString(wxUniChar ch, size_t nRepeat = 1);
+
+    /**
+       Construct a string consisting of @a nRepeat copies of ch.
+    */
+    wxString(wxUniCharRef ch, size_t nRepeat = 1);
+
+    /**
+       Construct a string consisting of @a nRepeat copies of ch
+       converted to Unicode using the current locale encoding.
+    */
+    wxString(char ch, size_t nRepeat = 1);
+
+    /**
+       Construct a string consisting of @a nRepeat copies of ch.
+    */
+    wxString(wchar_t ch, size_t nRepeat = 1);

 
     /**
 
     /**

-       Constructs a string from the string literal @e psz using
+       Constructs a string from the string literal @a psz using

        the current locale encoding to convert it to Unicode (wxConvLibc).
     */
     wxString(const char *psz);
 
     /**
        the current locale encoding to convert it to Unicode (wxConvLibc).
     */
     wxString(const char *psz);
 
     /**

-       Constructs a string from the string literal @e psz using
-       @e conv to convert it Unicode.
+       Constructs a string from the string literal @a psz using
+       @a conv to convert it Unicode.

     */
     wxString(const char *psz, const wxMBConv& conv);
 
     /**
     */
     wxString(const char *psz, const wxMBConv& conv);
 
     /**

-       Constructs a string from the first @e nLength character of the string literal @e psz using
+       Constructs a string from the first @a nLength character of the string literal @a psz using

        the current locale encoding to convert it to Unicode (wxConvLibc).
     */
     wxString(const char *psz, size_t nLength);
 
     /**
        the current locale encoding to convert it to Unicode (wxConvLibc).
     */
     wxString(const char *psz, size_t nLength);
 
     /**

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

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

-       Constructs a string from the string literal @e pwz.
+       Constructs a string from the string literal @a pwz.

     */
     wxString(const wchar_t *pwz);
 
     /**
     */
     wxString(const wchar_t *pwz);
 
     /**

-       Constructs a string from the first @e nLength characters of the string literal @e pwz.
+       Constructs a string from the first @a nLength characters of the string literal @a pwz.

     */
     wxString(const wchar_t *pwz, size_t nLength);
 
     /**
     */
     wxString(const wchar_t *pwz, size_t nLength);
 
     /**

-       Constructs a string from @e buf using the using the current locale
+       Constructs a string from @a buf using the using the current locale

         encoding to convert it to Unicode.
     */
     wxString(const wxCharBuffer& buf);
 
     /**
         encoding to convert it to Unicode.
     */
     wxString(const wxCharBuffer& buf);
 
     /**

-       Constructs a string from @e buf.
+       Constructs a string from @a buf.

     */
     wxString(const wxWCharBuffer& buf);
 
     /**
     */
     wxString(const wxWCharBuffer& buf);
 
     /**

-       Constructs a string from @e str using the using the current locale encoding
+       Constructs a string from @a str using the using the current locale encoding

        to convert it to Unicode (wxConvLibc).
        to convert it to Unicode (wxConvLibc).

+
+       @see ToStdString()

     */
     wxString(const std::string& str);
 
     /**
     */
     wxString(const std::string& str);
 
     /**

-       Constructs a string from @e str.
+       Constructs a string from @a str.
+
+       @see ToStdWstring()

     */
     wxString(const std::wstring& str);
 
     */
     wxString(const std::wstring& str);
 

-

     /**
         String destructor.
 
     /**
         String destructor.
 


@@ -346,444 +201,908 @@ public:
     ~wxString();
 
     /**
     ~wxString();
 
     /**

-        Gets all the characters after the first occurrence of @e ch.
-        Returns the empty string if @e ch is not found.
+        Assignment: see the relative wxString constructor.

     */
     */

-    wxString AfterFirst(wxUniChar ch) const;
+    wxString operator =(const wxString& str);

 
     /**
 
     /**

-        Gets all the characters after the last occurrence of @e ch.
-        Returns the whole string if @e ch is not found.
+        Assignment: see the relative wxString constructor.

     */
     */

-    wxString AfterLast(wxUniChar ch) const;
-
-    /**
-        Preallocate enough space for wxString to store @a nLen characters.
-
-        Please note that this method does the same thing as the standard
-        reserve() one and shouldn't be used in new code.
+    wxString operator =(wxUniChar c);

 
 

-        This function may be used to increase speed when the string is
-        constructed by repeated concatenation as in
+    //@}

 
 

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

 
 

-                size_t len = original.length();

 
 

-                result.Alloc(len);
+    /**
+        @member_group_name{length, String length}

 
 

-                for ( size_t n = 0; n < len; n++ )
-                {
-                    if ( strchr("aeuio", tolower(original[n])) == NULL )
-                        result += original[n];
-                }
+        These functions return the string length and/or check whether the string
+        is empty.

 
 

-                return result;
-            }
-        @endcode
+        See also the length(), size() or empty() STL-like functions.
+    */
+    //@{

 
 

-        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 @a 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 @a nLen.

 
 

-        @return @true if memory was successfully allocated, @false otherwise.
+    /**
+        Returns the length of the string.

     */
     */

-    bool Alloc(size_t nLen);
+    size_t Len() const;

 
     /**
 
     /**

-       Appends the string literal @e psz.
+        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& Append(const char* psz);
+    size_t Length() const;

 
     /**
 
     /**

-       Appends the wide string literal @e pwz.
+        Returns @true if the string is empty.

     */
     */

-    wxString& Append(const wchar_t* pwz);
+    bool IsEmpty() const;

 
     /**
 
     /**

-       Appends the string literal @e psz with max length @e nLen.
+        Returns @true if the string is empty (same as wxString::IsEmpty).
+        This is a wxWidgets 1.xx compatibility function; you should not use it in new
+        code.

     */
     */

-    wxString& Append(const char* psz, size_t nLen);
+    bool IsNull() const;

 
     /**
 
     /**

-       Appends the wide string literal @e psz with max length @e nLen.
+        Empty string is @false, so !string will only return @true if the
+        string is empty.
+
+        @see IsEmpty().

     */
     */

-    wxString& Append(const wchar_t* pwz, size_t nLen);
+    bool operator!() const;
+
+    //@}
+
+

 
     /**
 
     /**

-       Appends the string @e s.
+        @member_group_name{ch_access, 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 @ref overview_debugging "debug builds", but no checks are
+        done in release builds.

     */
     */

-    wxString& Append(const wxString& s);
+    //@{

 
     /**
 
     /**

-       Appends the character @e ch @e count times.
+        Returns the character at position @a n (read-only).

     */
     */

-    wxString &Append(wxUniChar ch, size_t count = 1u);
+    wxUniChar GetChar(size_t n) const;

 
     /**
 
     /**

-        Gets all characters before the first occurrence of @e ch.
-        Returns the whole string if @a ch is not found.
+        wxWidgets compatibility conversion. Same as c_str().

     */
     */

-    wxString BeforeFirst(wxUniChar ch) const;
+    const wxCStrData GetData() const;

 
     /**
 
     /**

-        Gets all characters before the last occurrence of @e ch.
-        Returns the empty string if @a ch is not found.
+        Returns a reference to the character at position @a n.

     */
     */

-    wxString BeforeLast(wxUniChar ch) const;
+    wxUniCharRef GetWritableChar(size_t n);

 
     /**
 
     /**

-        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
+        Returns a writable buffer of at least @a len bytes.

 
 

-        @see MakeCapitalized()
-     */
-    wxString Capitalize() const;
+        It returns a pointer to a new memory block, and the existing data will not be copied.
+        Call UngetWriteBuf() as soon as possible to put the string back into a reasonable state.

 
 

-    /**
-        Empties the string and frees memory occupied by it.
-        See also: Empty()
+        This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead.

     */
     */

-    void Clear();
+    wxStringCharType* GetWriteBuf(size_t len);

 
     /**
 
     /**

-        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
-        @c wxString(c_str()), Clone() handles embedded NULs correctly.
-
-        @since 2.9.0
-     */
-    wxString Clone() const;
+        Puts the string back into a reasonable state (in which it can be used
+        normally), after GetWriteBuf() was called.

 
 

-    /**
-        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 @c strcmp() function).
+        The version of the function without the @a len parameter will calculate the
+        new string length itself assuming that the string is terminated by the first
+        @c 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 @c NULs (it is also slightly more efficient as @c strlen()
+        doesn't have to be called).

 
 

-        See also CmpNoCase(), IsSameAs().
+        This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead.

     */
     */

-    int Cmp(const wxString& s) const;
+    void UngetWriteBuf();

 
     /**
 
     /**

-        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 @c strcmp() function).
-
-        See also Cmp(), IsSameAs().
+        @overload

     */
     */

-    int CmpNoCase(const wxString& s) const;
+    void UngetWriteBuf(size_t len);

 
     /**
 
     /**

-        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.
+        Sets the character at position @e n.

     */
     */

-    bool Contains(const wxString& str) const;
-
+    void SetChar(size_t n, wxUniChar ch);

 
     /**
 
     /**

-        Makes the string empty, but doesn't free memory occupied by the string.
-        See also: Clear().
-    */
-    void Empty();
+        Returns the last character.

 
 

-    /**
-        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 @e rest string if it is not
-        @NULL. Otherwise, the function returns @false and doesn't
-        modify the @e rest.
+        This is a wxWidgets 1.xx compatibility function;
+        you should not use it in new code.

     */
     */

-    bool EndsWith(const wxString& suffix, wxString *rest = NULL) const;
+    wxUniChar Last() const;

 
     /**
 
     /**

-        Searches for the given character @e ch. Returns the position or
-        @c wxNOT_FOUND if not found.
+        Returns a reference to the last character (writable).
+
+        This is a wxWidgets 1.xx compatibility function;
+        you should not use it in new code.

     */
     */

-    int Find(wxUniChar ch, bool fromEnd = false) const;
+    wxUniCharRef Last();

 
     /**
 
     /**

-        Searches for the given string @e sub. Returns the starting position or
-        @c wxNOT_FOUND if not found.
+        Returns the @a i-th character of the string.

     */
     */

-    int Find(const wxString& sub) const;
+    wxUniChar operator [](size_t i) const;

 
 

-    //@{

     /**
     /**

-        Same as Find().
-        This is a wxWidgets 1.xx compatibility function;
-        you should not use it in new code.
+        Returns a writable reference to the @a i-th character of the string.

     */
     */

-    int First(wxUniChar ch) const;
-    int First(const wxString& str) const;
+    wxUniCharRef operator [](size_t i);
+

     //@}
 
     //@}
 

+

     /**
     /**

-        This static function returns the string containing the result of calling
-        Printf() with the passed parameters on it.
+        @member_group_name{conv, Conversions}

 
 

-        @see FormatV(), Printf()
+        This section 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.

     */
     */

-    static wxString Format(const wxString& format, ...);
+    //@{

 
     /**
 
     /**

-        This static function returns the string containing the result of calling
-        PrintfV() with the passed parameters on it.
+        Returns a lightweight intermediate class which is in turn implicitly
+        convertible to both @c const @c char* and to @c const @c wchar_t*.
+        Given this ambiguity it is mostly better to use wc_str(), mb_str() or
+        utf8_str() instead.

 
 

-        @see Format(), PrintfV()
-    */
-    static wxString FormatV(const wxString& format, va_list argptr);
+        Please see the @ref overview_unicode for more information about it.
+
+        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.
+
+        @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
+    */
+    wxCStrData c_str() const;

 
     /**
 
     /**

-        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.
+        Returns an object with string data that is implicitly convertible to
+        @c 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.
+
+        @see c_str()

     */
     */

-    int Freq(wxUniChar ch) const;
+    wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) 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 @e len parameter takes NUL-terminated
-        data.
+        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 a string representation suitable for passing to OS' functions
+        for file handling.
+    */
+    const wchar_t* fn_str() const;
+
+    /**
+        @overload
+    */
+    const char* fn_str() const;
+
+    /**
+        @overload
+    */
+    const wxCharBuffer fn_str() const;
+
+    /**
+        Returns the multibyte (C string) representation of the string
+        using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
+
+        @see wc_str(), utf8_str(), c_str(), wxMBConv
+    */
+    const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
+
+    /**
+        Converts the strings contents to UTF-8 and returns it either as a
+        temporary wxCharBuffer object or as a pointer to the internal
+        string contents in UTF-8 build.
+
+        @see wc_str(), c_str(), mb_str()
+    */
+    const wxScopedCharBuffer utf8_str() const;
+
+    /**
+        Converts the strings contents to the wide character representation
+        and returns it as a temporary wxWCharBuffer object (Unix and OS X)
+        or returns a pointer to the internal string contents in wide character
+        mode (Windows).
+
+        The macro wxWX2WCbuf is defined as the correct return type (without const).
+
+        @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
+    */
+    const wchar_t* wc_str() const;
+
+    /**
+        @overload
+    */
+    const wxWCharBuffer wc_str() const;
+
+    /**
+        Returns an object with string data that is implicitly convertible to
+        @c char* pointer. Note that changes to the returned buffer may or may
+        not be lost (depending on the build) 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.
+
+        @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
+    */
+    wxWritableWCharBuffer wchar_str() const;
+
+    /**
+       Explicit conversion to C string in the internal representation (either
+       wchar_t* or UTF-8-encoded char*, depending on the build).
+    */
+    const wxStringCharType *wx_str() 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
 
         This is a convenience method useful when storing binary data in

-        wxString. It should be used @em only for that purpose and only in
-        conjunction with To8BitData(). Use mb_str() for conversion of character
-        data to known encoding.
+        wxString. It should be used @em only for this purpose. It is only valid
+        to call this method on strings created using From8BitData().

 
         @since 2.8.4
 
 
         @since 2.8.4
 

-        @see wxString::To8BitData()
+        @see wxString::From8BitData()

     */
     */

-    static wxString From8BitData(const char* buf, size_t len);
-    static wxString From8BitData(const char* buf);
-    //@}
+    const wxScopedCharBuffer To8BitData() const;

 
 

-    //@{

     /**
     /**

-        Converts the string or character from an ASCII, 7-bit form
-        to the native wxString representation.
+        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 @ref mb_str() "mb_str" method provides more
+        powerful means of converting wxString to C string.

     */
     */

-    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);
+    const char* ToAscii() const;
+
+    /**
+        @overload
+    */
+    const wxCharBuffer ToAscii() const;
+
+    /**
+        Return the string as an std::string in current locale encoding.
+
+        Note that if the conversion of (Unicode) string contents to the current
+        locale fails, the return string will be empty. Be sure to check for
+        this to avoid silent data loss.
+
+        Instead of using this function it's also possible to write
+        @code
+        std::string s;
+        wxString wxs;
+        ...
+        s = std::string(wxs);
+        @endcode
+        but using ToStdString() may make the code more clear.
+
+        @since 2.9.1
+    */
+    std::string ToStdString() const;
+
+    /**
+        Return the string as an std::wstring.
+
+        Unlike ToStdString(), there is no danger of data loss when using this
+        function.
+
+        @since 2.9.1
+    */
+    std::wstring ToStdWstring() const;
+
+    /**
+        Same as utf8_str().
+    */
+    const wxScopedCharBuffer ToUTF8() const;
+

     //@}
 
     //@}
 

+
+    /**
+        @member_group_name{concat, Concatenation}
+
+        Almost anything may be concatenated (appended to) with a string!
+
+        Note that the various operator<<() overloads work as C++ stream insertion
+        operators. They insert the given value into the string.
+        Precision and format cannot be set using them. Use Printf() instead.
+
+        See also the insert() and append() STL-like functions.
+    */

     //@{
     //@{

+

     /**
     /**

-        Converts C string encoded in UTF-8 to wxString.
+       Appends the string literal @a psz.
+    */
+    wxString& Append(const char* psz);

 
 

-        If @a s is not a valid UTF-8 string, an empty string is returned.
+    /**
+       Appends the wide string literal @a pwz.
+    */
+    wxString& Append(const wchar_t* pwz);

 
 

-        Notice that when using UTF-8 wxWidgets build there is a more efficient
-        alternative to this function called FromUTF8Unchecked() which, unlike
-        this one, doesn't check that the input string is valid.
+    /**
+       Appends the string literal @a psz with max length @a nLen.
+    */
+    wxString& Append(const char* psz, size_t nLen);

 
 

-        @since 2.8.4
+    /**
+       Appends the wide string literal @a psz with max length @a nLen.

     */
     */

-    static wxString FromUTF8(const char* s);
-    static wxString FromUTF8(const char* s, size_t len);
+    wxString& Append(const wchar_t* pwz, size_t nLen);
+
+    /**
+       Appends the string @a s.
+    */
+    wxString& Append(const wxString& s);
+
+    /**
+       Appends the character @a ch @a count times.
+    */
+    wxString &Append(wxUniChar ch, size_t count = 1u);
+
+    /**
+        Prepends @a str to this string, returning a reference to this string.
+    */
+    wxString& Prepend(const wxString& str);
+
+    /**
+        Concatenation: returns a new string equal to the concatenation of the operands.
+    */
+    wxString operator +(const wxString& x, const wxString& y);
+
+    /**
+        @overload
+    */
+    wxString operator +(const wxString& x, wxUniChar y);
+
+    wxString& operator<<(const wxString& s);
+    wxString& operator<<(const char* psz);
+    wxString& operator<<(const wchar_t* pwz);
+    wxString& operator<<(const wxCStrData& psz);
+    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<<(wxUniChar ch);
+    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);
+
+    /**
+        Concatenation in place: the argument is appended to the string.
+    */
+    void operator +=(const wxString& str);
+
+    /**
+        @overload
+    */
+    void operator +=(wxUniChar c);
+

     //@}
 
     //@}
 

+
+    /**
+        @member_group_name{cmp, 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.
+
+        See also the compare() STL-like function.
+    */

     //@{
     //@{

+

     /**
     /**

-        Converts C string encoded in UTF-8 to wxString without checking its
-        validity.
+        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 @c strcmp() function).

 
 

-        This method assumes that @a s is a valid UTF-8 sequence and doesn't do
-        any validation (although an assert failure is triggered in debug builds
-        if the string is invalid). Only use it if you are absolutely sure that
-        @a s is a correct UTF-8 string (e.g. because it comes from another
-        library using UTF-8) and if the performance matters, otherwise use
-        slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8
-        string to this function will result in creating a corrupted wxString
-        and all the subsequent operations on it will be undefined.
+        @see CmpNoCase(), IsSameAs().
+    */
+    int Cmp(const wxString& s) const;

 
 

-        @since 2.8.9
+    /**
+        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 @c strcmp() function).
+
+        @see Cmp(), IsSameAs().

     */
     */

-    static wxString FromUTF8Unchecked(const char* s);
-    static wxString FromUTF8Unchecked(const char* s, size_t len);
+    int CmpNoCase(const wxString& s) const;
+
+    /**
+        Test whether the string is equal to another string @a s.
+
+        The test is case-sensitive if @a caseSensitive is @true (default) or not if it is
+        @false.
+
+        @return @true if the string is equal to the other one, @false otherwise.
+
+        @see Cmp(), CmpNoCase()
+    */
+    bool IsSameAs(const wxString& s, bool caseSensitive = true) const;
+
+    /**
+        Test whether the string is equal to the single character @a ch.
+
+        The test is case-sensitive if @a caseSensitive is @true (default) or not if it is
+        @false.
+
+        @return @true if the string is equal to this character, @false otherwise.
+
+        @see Cmp(), CmpNoCase()
+    */
+    bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const;
+
+    /**
+        Returns @true if the string contents matches a mask containing '*' and '?'.
+    */
+    bool Matches(const wxString& mask) const;
+
+    /**
+        This function can be used to test if the string starts with the specified
+        @a prefix.
+
+        If it does, the function will return @true and put the rest of the string
+        (i.e. after the prefix) into @a rest string if it is not @NULL.
+        Otherwise, the function returns @false and doesn't modify the @a rest.
+    */
+    bool StartsWith(const wxString& prefix, wxString *rest = NULL) 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 @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;
+

     //@}
 
     //@}
 

+

     /**
     /**

-        Returns the character at position @a n (read-only).
+        @member_group_name{substring, 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.
+
+        See also the at() and the substr() STL-like functions.

     */
     */

-    wxUniChar GetChar(size_t n) const;

 
     /**
 
     /**

-        wxWidgets compatibility conversion. Same as c_str().
+        Returns a substring starting at @e first, with length @e count, or the rest of
+        the string if @a count is the default value.

     */
     */

-    const wxCStrData GetData() const;
+    wxString Mid(size_t first, size_t nCount = wxString::npos) const;

 
     /**
 
     /**

-        Returns a reference to the character at position @e n.
+        Returns the part of the string between the indices @a from and @a to
+        inclusive.
+
+        This is a wxWidgets 1.xx compatibility function, use Mid()
+        instead (but note that parameters have different meaning).

     */
     */

-    wxUniCharRef GetWritableChar(size_t n);
+    wxString SubString(size_t from, size_t to) const;

 
     /**
 
     /**

-        Returns a writable buffer of at least @a len bytes.
-        It returns a pointer to a new memory block, and the
-        existing data will not be copied.
-        Call UngetWriteBuf() as soon as possible to put the
-        string back into a reasonable state.
-        This method is deprecated, please use wxStringBuffer or
-        wxStringBufferLength instead.
+        Same as Mid() (substring extraction).

     */
     */

-    wxStringCharType* GetWriteBuf(size_t len);
+    wxString operator()(size_t start, size_t len) 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.
+        Returns the first @a count characters of the string.

     */
     */

-    bool IsAscii() const;
+    wxString Left(size_t count) const;

 
     /**
 
     /**

-        Returns @true if the string is empty.
+        Returns the last @a count characters.

     */
     */

-    bool IsEmpty() const;
+    wxString Right(size_t count) const;

 
     /**
 
     /**

-        Returns @true if the string is empty (same as wxString::IsEmpty).
+        Gets all the characters after the first occurrence of @e ch.
+        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 @e ch is not found.
+    */
+    wxString AfterLast(wxUniChar ch) const;
+
+    /**
+        Gets all characters before the first occurrence of @e ch.
+        Returns the whole string if @a ch is not found.
+
+        @param ch The character to look for.
+        @param rest Filled with the part of the string following the first
+            occurrence of @a ch or cleared if it was not found. The same string
+            is returned by AfterFirst() but it is more efficient to use this
+            output parameter if both the "before" and "after" parts are needed
+            than calling both functions one after the other. This parameter is
+            available in wxWidgets version 2.9.2 and later only.
+        @return Part of the string before the first occurrence of @a ch.
+    */
+    wxString BeforeFirst(wxUniChar ch, wxString *rest = NULL) const;
+
+    /**
+        Gets all characters before the last occurrence of @e ch.
+        Returns the empty string if @a ch is not found.
+
+        @param ch The character to look for.
+        @param rest Filled with the part of the string following the last
+            occurrence of @a ch or the copy of this string if it was not found.
+            The same string is returned by AfterLast() but it is more efficient
+            to use this output parameter if both the "before" and "after" parts
+            are needed than calling both functions one after the other. This
+            parameter is available in wxWidgets version 2.9.2 and later only.
+        @return Part of the string before the last occurrence of @a ch.
+    */
+    wxString BeforeLast(wxUniChar ch, wxString *rest = NULL) const;
+
+    //@}
+
+
+    /**
+        @member_group_name{caseconv, 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.
+    */
+    //@{
+
+    /**
+        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 MakeCapitalized()
+     */
+    wxString Capitalize() const;
+
+    /**
+        Returns this string converted to the lower case.
+
+        @see MakeLower()
+    */
+    wxString Lower() const;
+
+    /**
+        Same as MakeLower.

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

-    bool IsNull() const;
+    void LowerCase();

 
     /**
 
     /**

-        Returns @true if the string is an integer (with possible sign).
+        Converts the first characters of the string to the upper case and all
+        the subsequent ones to the lower case and returns the result.
+
+        @since 2.9.0
+
+        @see Capitalize()
+    */
+    wxString& MakeCapitalized();
+
+    /**
+        Converts all characters to lower case and returns the reference to the
+        modified string.
+
+        @see Lower()
+    */
+    wxString& MakeLower();
+
+    /**
+        Converts all characters to upper case and returns the reference to the
+        modified string.
+
+        @see Upper()
+    */
+    wxString& MakeUpper();
+
+    /**
+        Returns this string converted to upper case.
+
+        @see MakeUpper()
+    */
+    wxString Upper() const;
+
+    /**
+        The same as MakeUpper().
+

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

-    bool IsNumber() const;
+    void UpperCase();
+
+    //@}
+
+
+    /**
+        @member_group_name{search, Searching and replacing}

 
 

+        These functions replace the standard @c strchr() and @c strstr()
+        functions.
+
+        See also the find(), rfind(), replace() STL-like functions.
+    */

     //@{
     //@{

+

     /**
     /**

-        Test whether the string is equal to the single character @e c. The test is
-        case-sensitive if @a caseSensitive is @true (default) or not if it is @c
-        @false.
-        Returns @true if the string is equal to the character, @false otherwise.
-        See also Cmp(), CmpNoCase()
+        Searches for the given character @a ch.
+        Returns the position or @c wxNOT_FOUND if not found.

     */
     */

-    bool IsSameAs(const wxString &s, bool caseSensitive = true) const;
-    bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const;
-    //@}
+    int Find(wxUniChar ch, bool fromEnd = false) 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.
+        Searches for the given string @a 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;
+        you should not use it in new code.

     */
     */

-    bool IsWord() const;
+    int First(wxUniChar ch) const;

 
 

-    //@{

     /**
     /**

-        Returns a reference to the last character (writable).
+        Same as Find().
+

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

-    wxUniCharRef Last();
-    const wxUniChar Last();
-    //@}
+    int First(const wxString& str) const;

 
     /**
 
     /**

-        Returns the first @a count characters of the string.
+        Replace first (or all) occurrences of substring with another one.
+
+        @param strOld
+            The string to search for replacing.
+        @param strNew
+            The substitution string.
+        @param replaceAll
+            If @true a global replace will be done (default), otherwise only the
+            first occurrence will be replaced.
+
+        Returns the number of replacements made.

     */
     */

-    wxString Left(size_t count) const;
+    size_t Replace(const wxString& strOld, const wxString& strNew,
+                   bool replaceAll = true);
+
+    //@}
+
+

 
     /**
 
     /**

-        Returns the length of the string.
-    */
-    size_t Len() const;
+        @member_group_name{numconv, 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 @b entire string could be converted to a
+        number. Notice if there is a valid number in the beginning of the
+        string, it is returned in the output parameter even if the function
+        returns @false because there is more text following it.
+     */
+    //@{

 
     /**
 
     /**

-        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.
+        Attempts to convert the string to a floating point number.
+
+        Returns @true on success (the number is stored in the location pointed to by
+        @a val) or @false if the string does not represent such number (the value of
+        @a val may still be modified in this case).
+
+        Note that unlike ToCDouble() this function uses a localized version of
+        @c wxStrtod() and thus needs as decimal point (and thousands separator) the
+        locale-specific decimal point. Thus you should use this function only when
+        you are sure that this string contains a floating point number formatted with
+        the rules of the locale currently in use (see wxLocale).
+
+        Also notice that even this function is locale-specific it does not
+        support strings with thousands separators in them, even if the current
+        locale uses digits grouping. You may use wxNumberFormatter::FromString()
+        to parse such strings.
+
+        Please refer to the documentation of the standard function @c strtod()
+        for more details about the supported syntax.
+
+        @see ToCDouble(), ToLong(), ToULong()

     */
     */

-    size_t Length() const;
+    bool ToDouble(double* val) const;

 
     /**
 
     /**

-        Returns this string converted to the lower case.
+        Variant of ToDouble() always working in "C" locale.

 
 

-        @see MakeLower()
+        Works like ToDouble() but unlike it this function expects the floating point
+        number to be formatted always with the rules dictated by the "C" locale
+        (in particular, the decimal point must be a dot), independently from the
+        current application-wide locale (see wxLocale).
+
+        @see ToDouble(), ToLong(), ToULong()

     */
     */

-    wxString Lower() const;
+    bool ToCDouble(double* val) const;

 
     /**
 
     /**

-        Same as MakeLower.
-        This is a wxWidgets 1.xx compatibility function; you should not use it in new
-        code.
+        Attempts to convert the string to a signed integer in base @a base.
+
+        Returns @true on success in which case the number is stored in the location
+        pointed to by @a val or @false if the string does not represent a
+        valid number in the given base (the value of @a val may still be
+        modified in this case).
+
+        The value of @a base must be comprised between 2 and 36, inclusive, or
+        be a special value 0 which means that the usual rules of @c C numbers are
+        applied: if the number starts with @c 0x it is considered to be in base
+        16, if it starts with @c 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.
+
+        Note that unlike ToCLong() this function uses a localized version of
+        @c wxStrtol(). Thus you should use this function only when you are sure
+        that this string contains an integer number formatted with
+        the rules of the locale currently in use (see wxLocale).
+
+        As with ToDouble(), this function does not support strings containing
+        thousands separators even if the current locale uses digits grouping.
+        You may use wxNumberFormatter::FromString() to parse such strings.
+
+        Please refer to the documentation of the standard function @c strtol()
+        for more details about the supported syntax.
+
+        @see ToCDouble(), ToDouble(), ToULong()

     */
     */

-    void LowerCase();
+    bool ToLong(long* val, int base = 10) const;

 
     /**
 
     /**

-        Converts the first characters of the string to the upper case and all
-        the subsequent ones to the lower case and returns the result.
+        Variant of ToLong() always working in "C" locale.

 
 

-        @since 2.9.0
+        Works like ToLong() but unlike it this function expects the integer
+        number to be formatted always with the rules dictated by the "C" locale,
+        independently from the current application-wide locale (see wxLocale).

 
 

-        @see Capitalize()
+        @see ToDouble(), ToLong(), ToULong()

     */
     */

-    wxString& MakeCapitalized();
+    bool ToCLong(long* val, int base = 10) const;

 
     /**
 
     /**

-        Converts all characters to lower case and returns the reference to the
-        modified string.
+        This is exactly the same as ToLong() but works with 64 bit integer numbers.

 
 

-        @see Lower()
+        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 ToLong(), ToULongLong()

     */
     */

-    wxString& MakeLower();
+    bool ToLongLong(wxLongLong_t* val, int base = 10) const;

 
     /**
 
     /**

-        Converts all characters to upper case and returns the reference to the
-        modified string.
+        Attempts to convert the string to an unsigned integer in base @a base.

 
 

-        @see Upper()
+        Returns @true on success in which case the number is stored in the
+        location pointed to by @a val or @false if the string does not
+        represent a valid number in the given base (the value of @a val may
+        still be modified in this case).
+
+        Please notice that this function  behaves in the same way as the standard
+        @c strtoul() and so it simply converts negative numbers to unsigned
+        representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
+
+        See ToLong() for the more detailed description of the @a base parameter
+        (and of the locale-specific behaviour of this function).
+
+        @see ToCULong(), ToDouble(), ToLong()

     */
     */

-    wxString& MakeUpper();
+    bool ToULong(unsigned long* val, int base = 10) const;

 
     /**
 
     /**

-        Returns @true if the string contents matches a mask containing '*' and '?'.
+        Variant of ToULong() always working in "C" locale.
+
+        Works like ToULong() but unlike it this function expects the integer
+        number to be formatted always with the rules dictated by the "C" locale,
+        independently from the current application-wide locale (see wxLocale).
+
+        @see ToDouble(), ToLong(), ToULong()

     */
     */

-    bool Matches(const wxString& mask) const;
+    bool ToCULong(unsigned long* val, int base = 10) const;

 
     /**
 
     /**

-        Returns a substring starting at @e first, with length @e count, or the rest of
-        the string if @a count is the default value.
+        This is exactly the same as ToULong() but works with 64 bit integer
+        numbers.
+
+        Please see ToLongLong() for additional remarks.

     */
     */

-    wxString Mid(size_t first, size_t nCount = wxString::npos) const;
+    bool ToULongLong(wxULongLong_t* val, int base = 10) const;

 
 

+    //@}

 
 

-    /**
-        Adds @a count copies of @a pad to the beginning, or to the end of the
-        string (the default).  Removes spaces from the left or from the right (default).
-    */
-    wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true);

 
     /**
 
     /**

-        Prepends @a str to this string, returning a reference to this string.
+        @member_group_name{fmt, Formatting and printing}
+
+        Both formatted versions (Printf/() and stream-like insertion operators
+        exist (for basic types only).
+
+        See also the static Format() and FormatV() functions.

     */
     */

-    wxString& Prepend(const wxString& str);
+    //@{

 
     /**
         Similar to the standard function @e sprintf(). Returns the number of
 
     /**
         Similar to the standard function @e sprintf(). Returns the number of


@@ -791,6 +1110,16 @@ public:
         Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
         Unix98-style positional parameters:
 
         Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
         Unix98-style positional parameters:
 

+        @code
+        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"
+        @endcode
+

         @note This function will use a safe version of @e vsprintf() (usually called
         @e vsnprintf()) whenever available to always allocate the buffer of correct
         size. Unfortunately, this function is not available on all platforms and the
         @note This function will use a safe version of @e vsprintf() (usually called
         @e vsnprintf()) whenever available to always allocate the buffer of correct
         size. Unfortunately, this function is not available on all platforms and the


@@ -805,38 +1134,59 @@ public:
     */
     int PrintfV(const wxString& pszFormat, va_list argPtr);
 
     */
     int PrintfV(const wxString& pszFormat, va_list argPtr);
 

-    //@{
-    /**
-        Removes @a len characters from the string, starting at @e pos.
-        This is a wxWidgets 1.xx compatibility function; you should not use it in new
-        code.
-    */
-    wxString Remove(size_t pos);
-    wxString Remove(size_t pos, size_t len);

     //@}
 
     //@}
 

-    /**
-        Removes the last character.
-    */
-    wxString& RemoveLast(size_t n = 1);

 
     /**
 
     /**

-        Replace first (or all) occurrences of substring with another one.
-        @e replaceAll: global replace (default), or only the first occurrence.
-        Returns the number of replacements made.
-    */
-    size_t Replace(const wxString& strOld, const wxString& strNew,
-                   bool replaceAll = true);
+        @member_group_name{mem, Memory management}

 
 

-    /**
-        Returns the last @a count characters.
+        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.
+
+        See also the reserve() and resize() STL-like functions.

     */
     */

-    wxString Right(size_t count) const;
+    //@{

 
     /**
 
     /**

-        Sets the character at position @e n.
+        Preallocate enough space for wxString to store @a 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
+
+        @code
+            // 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;
+            }
+        @endcode
+
+        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 @a 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 @a nLen.
+
+        @return @true if memory was successfully allocated, @false otherwise.

     */
     */

-    void SetChar(size_t n, wxUniChar ch);
+    bool Alloc(size_t nLen);

 
     /**
         Minimizes the string's memory. This can be useful after a call to
 
     /**
         Minimizes the string's memory. This can be useful after a call to


@@ -845,129 +1195,117 @@ public:
     bool Shrink();
 
     /**
     bool Shrink();
 
     /**

-        This function can be used to test if the string starts with the specified
-        @e prefix. If it does, the function will return @true and put the rest
-        of the string (i.e. after the prefix) into @a rest string if it is not
-        @NULL. Otherwise, the function returns @false and doesn't modify the
-        @e rest.
+        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
+        @c wxString(c_str()), Clone() handles embedded NULs correctly.
+
+        @since 2.9.0
+     */
+    wxString Clone() const;
+
+    /**
+        Empties the string and frees memory occupied by it.
+
+        @see Empty()

     */
     */

-    bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;
+    void Clear();
+
+    //@}
+
+

 
     /**
 
     /**

-        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.
+        @member_group_name{misc, Miscellaneous}
+
+        Miscellaneous other string functions.

     */
     */

-    wxString Strip(stripType s = trailing) const;
+    //@{

 
     /**
 
     /**

-        Returns the part of the string between the indices @a from and @e to
-        inclusive.
-        This is a wxWidgets 1.xx compatibility function, use Mid()
-        instead (but note that parameters have different meaning).
+        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 SubString(size_t from, size_t to) const;
+    bool Contains(const wxString& str) const;

 
 

-    //@{

     /**
     /**

-        Converts the string to an 8-bit string in ISO-8859-1 encoding in the
-        form of a wxCharBuffer (Unicode builds only).
+        Makes the string empty, but doesn't free memory occupied by the string.

 
 

-        This is a convenience method useful when storing binary data in
-        wxString. It should be used @em only for this purpose. It is only valid
-        to call this method on strings created using From8BitData().
+        @see Clear().
+    */
+    void Empty();

 
 

-        @since 2.8.4
+    /**
+        Returns the number of occurrences of @e ch in the string.

 
 

-        @see wxString::From8BitData()
+        This is a wxWidgets 1.xx compatibility function; you should not use it in new code.

     */
     */

-    const char* To8BitData() const;
-    const wxCharBuffer To8BitData() const;
-    //@}
+    int Freq(wxUniChar ch) 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 @ref mb_str() "mb_str" method provides more
-        powerful means of converting wxString to C string.
+        Returns @true if the string contains only ASCII characters.
+        See wxUniChar::IsAscii for more details.
+
+        This is a wxWidgets 1.xx compatibility function; you should not use it in new
+        code.

     */
     */

-    const char* ToAscii() const;
-    const wxCharBuffer ToAscii() const;
-    //@}
+    bool IsAscii() 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 @e val) or @false
-        if the string does not represent such number (the value of @a val is not
-        modified in this case).
+        Returns @true if the string is an integer (with possible sign).

 
 

-        @see ToLong(), ToULong()
+        This is a wxWidgets 1.xx compatibility function; you should not use it in new code.

     */
     */

-    bool ToDouble(double* val) const;
+    bool IsNumber() const;

 
     /**
 
     /**

-        Attempts to convert the string to a signed integer in base @e base. Returns
-        @true on success in which case the number is stored in the location
-        pointed to by @a val or @false if the string does not represent a
-        valid number in the given base (the value of @a val is not modified
-        in this case).
-        The value of @a base must be comprised between 2 and 36, inclusive, or
-        be a special value 0 which means that the usual rules of @c C numbers are
-        applied: if the number starts with @c 0x it is considered to be in base
-        16, if it starts with @c 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.
+        Returns @true if the string is a word.

 
 

-        @see ToDouble(), ToULong()
+        This is a wxWidgets 1.xx compatibility function; you should not use it in new code.

     */
     */

-    bool ToLong(long* val, int base = 10) const;
+    bool IsWord() 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.
+        Adds @a count copies of @a chPad to the beginning, or to the end of the
+        string (the default).

 
 

-        @see ToLong(), ToULongLong()
+        Removes spaces from the left or from the right (default).

     */
     */

-    bool ToLongLong(wxLongLong_t* val, int base = 10) const;
+    wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true);

 
     /**
 
     /**

-        Attempts to convert the string to an unsigned integer in base @e base.
-        Returns @true on success in which case the number is stored in the
-        location pointed to by @a val or @false if the string does not
-        represent a valid number in the given base (the value of @a val is not
-        modified in this case).
+        Removes all characters from the string starting at @a pos.
+        Use Truncate() as a more readable alternative.

 
 

-        Please notice that this function  behaves in the same way as the standard
-        @c strtoul() and so it simply converts negative numbers to unsigned
-        representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
+        This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
+    */
+    wxString& Remove(size_t pos);

 
 

-        See ToLong() for the more detailed description of the @a base parameter.
+    /**
+        Removes @a len characters from the string, starting at @a pos.

 
 

-        @see ToDouble(), ToLong()
+        This is a wxWidgets 1.xx compatibility function; you should not use it in new code.

     */
     */

-    bool ToULong(unsigned long* val, int base = 10) const;
+    wxString& Remove(size_t pos, size_t len);

 
     /**
 
     /**

-        This is exactly the same as ToULong() but works with 64
-        bit integer numbers.
-        Please see ToLongLong() for additional remarks.
+        Removes the last character.

     */
     */

-    bool ToULongLong(wxULongLong_t* val, int base = 10) const;
+    wxString& RemoveLast(size_t n = 1);

 
 

-    //@{

     /**
     /**

-        Same as utf8_str().
+        Strip characters at the front and/or end.
+
+        This is 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.

     */
     */

-    const char* ToUTF8() const;
-    const wxCharBuffer ToUTF8() const;
-    //@}
+    wxString Strip(stripType s = trailing) const;

 
     /**
         Removes white-space (space, tabs, form feed, newline and carriage return) from
 
     /**
         Removes white-space (space, tabs, form feed, newline and carriage return) from


@@ -980,376 +1318,297 @@ public:
     */
     wxString& Truncate(size_t len);
 
     */
     wxString& Truncate(size_t len);
 

-    //@{
-    /**
-        Puts the string back into a reasonable state (in which it can be used
-        normally), after GetWriteBuf() was called.
-
-        The version of the function without the @a len parameter will calculate the
-        new string length itself assuming that the string is terminated by the first
-        @c 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 @c NULs (it is also slightly more efficient as @c strlen()
-        doesn't have to be called).
-
-        This method is deprecated, please use wxStringBuffer or
-        wxStringBufferLength instead.
-    */
-    void UngetWriteBuf();
-    void UngetWriteBuf(size_t len);

     //@}
 
     //@}
 

-    /**
-        Returns this string converted to upper case.

 
 

-        @see MakeUpper()
-    */
-    wxString Upper() const;
+

 
     /**
 
     /**

-        The same as MakeUpper().
+        @member_group_name{iter, Iterator interface}

 
 

-        This is a wxWidgets 1.xx compatibility function; you should not use it in new
-        code.
+        These methods return iterators to the beginning or end of the string.
+
+        Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start)
+        for their documentation.

     */
     */

-    void UpperCase();
+    //@{

 
 

-    /**
-        Returns a lightweight intermediate class which is in turn implicitly
-        convertible to both @c const @c char* and to @c const @c wchar_t*.
-        Given this ambiguity it is mostly better to use wc_str(), mb_str() or
-        utf8_str() instead.
+    const_iterator begin() const;
+    iterator begin();
+    const_iterator end() const;
+    iterator end();

 
 

-        Please see the @ref overview_unicode for more information about it.
+    const_reverse_iterator rbegin() const;
+    reverse_iterator rbegin();
+    const_reverse_iterator rend() const;
+    reverse_iterator rend();
+
+    //@}

 
 

-        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.

 
 

-        @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
-    */
-    wxCStrData c_str() const;

 
     /**
 
     /**

-        Returns an object with string data that is implicitly convertible to
-        @c 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.
+        @member_group_name{stl, STL interface}

 
 

-        @see c_str()
+        The supported STL functions are listed here.
+
+        Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start)
+        for their documentation.

     */
     */

-    wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
+    //@{

 
 

-    /**
-        Returns buffer of the specified type containing the string data.
+    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);
+
+    wxUniChar at(size_t n) const;
+    wxUniCharRef at(size_t n);
+
+    void clear();
+
+    size_type capacity() const;
+
+    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;
+
+    wxCStrData data() 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;
+    size_t find_first_of(const char* sz, size_t nStart = 0) const;
+    size_t find_first_of(const wchar_t* sz, size_t nStart = 0) const;
+    size_t find_first_of(const char* sz, size_t nStart, size_t n) const;
+    size_t find_first_of(const wchar_t* sz, size_t nStart, size_t n) const;
+    size_t find_first_of(wxUniChar 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* sz, size_t nStart = npos) const;
+    size_t find_last_of (const wchar_t* sz, size_t nStart = npos) const;
+    size_t find_last_of(const char* sz, size_t nStart, size_t n) const;
+    size_t find_last_of(const wchar_t* sz, size_t nStart, size_t n) const;
+    size_t find_last_of(wxUniChar c, size_t nStart = npos) const;
+    size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
+    size_t find_first_not_of(const char* sz, size_t nStart = 0) const;
+    size_t find_first_not_of(const wchar_t* sz, size_t nStart = 0) const;
+    size_t find_first_not_of(const char* sz, size_t nStart, size_t n) const;
+    size_t find_first_not_of(const wchar_t* sz, size_t nStart, size_t n) const;
+    size_t find_first_not_of(wxUniChar 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* sz, size_t nStart = npos) const;
+    size_t find_last_not_of(const wchar_t* sz, size_t nStart = npos) const;
+    size_t find_last_not_of(const char* sz, size_t nStart, size_t n) const;
+    size_t find_last_not_of(const wchar_t* sz, size_t nStart, size_t n) 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);
+
+    size_t length() const;
+
+    size_type max_size() const;
+
+    void reserve(size_t sz);
+    void resize(size_t nSize, wxUniChar ch = '\0');
+
+    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;
+
+    size_type size() const;
+    wxString substr(size_t nStart = 0, size_t nLen = npos) const;
+    void swap(wxString& str);

 
 

-        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;
+    // STATIC FUNCTIONS
+    // Keep these functions separated from the other groups or Doxygen gets confused
+    // -----------------------------------------------------------------------------

 
 

-    //@{

     /**
     /**

-        Returns string representation suitable for passing to OS' functions
-        for file handling.
+        An 'invalid' value for string index

     */
     */

-    const wchar_t* fn_str() const;
-    const char* fn_str() const;
-    const wxCharBuffer fn_str() const;
-    //@}
+    static const size_t npos;

 
     /**
 
     /**

-        Returns the multibyte (C string) representation of the string
-        using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
+        This static function returns the string containing the result of calling
+        Printf() with the passed parameters on it.

 
 

-        @see wc_str(), utf8_str(), c_str(), wxMBConv
+        @see FormatV(), Printf()

     */
     */

-    const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
+    static wxString Format(const wxString& format, ...);

 
     /**
 
     /**

-        Extraction from a stream.
+        This static function returns the string containing the result of calling
+        PrintfV() with the passed parameters on it.
+
+        @see Format(), PrintfV()

     */
     */

-    friend istream operator>>(istream& is, wxString& str);
+    static wxString FormatV(const wxString& format, va_list argptr);

 
     //@{
     /**
 
     //@{
     /**

-        These functions work as C++ stream insertion operators. They insert the
-        given value into the string. Precision and format cannot be set using them.
-        Use Printf() instead.
-    */
-    wxString& operator<<(const wxString& s);
-    wxString& operator<<(const char* psz);
-    wxString& operator<<(const wchar_t* pwz);
-    wxString& operator<<(const wxCStrData& psz);
-    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);
-    //@}
+        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 @e len parameter takes NUL-terminated
+        data.

 
 

-    /**
-        Same as Mid() (substring extraction).
-    */
-    wxString operator()(size_t start, size_t len) const;
+        This is a convenience method useful when storing binary data in
+        wxString. It should be used @em only for that purpose and only in
+        conjunction with To8BitData(). Use mb_str() for conversion of character
+        data to known encoding.

 
 

-    //@{
-    /**
-        Concatenation: 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, wxUniChar y);
-    //@}
+        @since 2.8.4

 
 

-    //@{
-    /**
-        Concatenation in place: the argument is appended to the string.
+        @see wxString::To8BitData()

     */
     */

-    void operator +=(const wxString& str);
-    void operator +=(wxUniChar c);
+    static wxString From8BitData(const char* buf, size_t len);
+    static wxString From8BitData(const char* buf);

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        Assignment: the effect of each operation is the same as for the corresponding
-        constructor (see wxString constructors).
+        Converts the string or character from an ASCII, 7-bit form
+        to the native wxString representation.

     */
     */

-    wxString operator =(const wxString& str);
-    wxString operator =(wxUniChar c);
+    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);

     //@}
 
     //@}
 

-    //@{

     /**
     /**

-        Element extraction.
-    */
-    wxUniChar operator [](size_t i) const;
-    wxUniCharRef operator [](size_t i);
-    //@}
+        Returns a string with the textual representation of the number in C
+        locale.

 
 

-    /**
-        Empty string is @false, so !string will only return @true if the
-        string is empty.
+        Unlike FromDouble() the string returned by this function always uses
+        the period character as decimal separator, independently of the current
+        locale. Otherwise its behaviour is identical to the other function.

 
 

-        See also IsEmpty().
-    */
-    bool operator!() const;
+        @since 2.9.1

 
 

+        @see ToCDouble()
+     */
+    static wxString FromCDouble(double val, int precision = -1);

 
 

-    //@{

     /**
     /**

-        Converts the strings contents to UTF-8 and returns it either as a
-        temporary wxCharBuffer object or as a pointer to the internal
-        string contents in UTF-8 build.
-
-        @see wc_str(), c_str(), mb_str()
-    */
-    const char* utf8_str() const;
-    const wxCharBuffer utf8_str() const;
-    //@}
+        Returns a string with the textual representation of the number.

 
 

-    //@{
-    /**
-        Converts the strings contents to the wide character represention
-        and returns it as a temporary wxWCharBuffer object (Unix and OS X)
-        or returns a pointer to the internal string contents in wide character
-        mode (Windows).
+        For the default value of @a precision, this function behaves as a
+        simple wrapper for @code wxString::Format("%g", val) @endcode. If @a
+        precision is positive (or zero), the @c %.Nf format is used with the
+        given precision value.

 
 

-        The macro wxWX2WCbuf is defined as the correct return
-        type (without const).
+        Notice that the string returned by this function uses the decimal
+        separator appropriate for the current locale, e.g. @c "," and not a
+        period in French locale. Use FromCDouble() if this is unwanted.

 
 

-        @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
-    */
-    const wchar_t* wc_str() const;
-    const wxWCharBuffer wc_str() const;
-    //@}
+        @param val
+            The value to format.
+        @param precision
+            The number of fractional digits to use in or -1 to use the most
+            appropriate format. This parameter is new in wxWidgets 2.9.2.

 
 

-    /**
-        Returns an object with string data that is implicitly convertible to
-        @c char* pointer. Note that changes to the returned buffer may or may
-        not be lost (depending on the build) 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.
+        @since 2.9.1

 
 

-        @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
-    */
-    wxWritableWCharBuffer wchar_str() const;
+        @see ToDouble()
+     */
+    static wxString FromDouble(double val, int precision = -1);

 
 

+    //@{

     /**
     /**

-       Explicit conversion to C string in the internal representation (either
-       wchar_t* or UTF-8-encoded char*, depending on the build).
-    */
-    const wxStringCharType *wx_str() const;
+        Converts C string encoded in UTF-8 to wxString.

 
 

+        If @a s is not a valid UTF-8 string, an empty string is returned.

 
 

-    /**
-        @name Iterator interface
+        Notice that when using UTF-8 wxWidgets build there is a more efficient
+        alternative to this function called FromUTF8Unchecked() which, unlike
+        this one, doesn't check that the input string is valid.

 
 

-        These methods return iterators to the beginnnig or
-        end of the string.
+        @since 2.8.4

     */
     */

-    //@{
-        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();
+    static wxString FromUTF8(const char* s);
+    static wxString FromUTF8(const char* s, size_t len);

     //@}
 
     //@}
 

+    //@{

     /**
     /**

-        @name STL interface
+        Converts C string encoded in UTF-8 to wxString without checking its
+        validity.
+
+        This method assumes that @a s is a valid UTF-8 sequence and doesn't do
+        any validation (although an assert failure is triggered in debug builds
+        if the string is invalid). Only use it if you are absolutely sure that
+        @a s is a correct UTF-8 string (e.g. because it comes from another
+        library using UTF-8) and if the performance matters, otherwise use
+        slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8
+        string to this function will result in creating a corrupted wxString
+        and all the subsequent operations on it will be undefined.

 
 

-        The supported STL functions are listed here. Please see any
-        STL reference for their documentation.
+        @since 2.8.9

     */
     */

-    //@{
-        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);
-
-        wxUniChar at(size_t n) const;
-        wxUniCharRef at(size_t n);
-
-        void clear();
-
-        size_type capacity() const;
-
-        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;
-
-        wxCStrData data() 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;
-        size_t find_first_of(const char* sz, size_t nStart = 0) const;
-        size_t find_first_of(const wchar_t* sz, size_t nStart = 0) const;
-        size_t find_first_of(const char* sz, size_t nStart, size_t n) const;
-        size_t find_first_of(const wchar_t* sz, size_t nStart, size_t n) const;
-        size_t find_first_of(wxUniChar 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* sz, size_t nStart = npos) const;
-        size_t find_last_of (const wchar_t* sz, size_t nStart = npos) const;
-        size_t find_last_of(const char* sz, size_t nStart, size_t n) const;
-        size_t find_last_of(const wchar_t* sz, size_t nStart, size_t n) const;
-        size_t find_last_of(wxUniChar c, size_t nStart = npos) const;
-        size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
-        size_t find_first_not_of(const char* sz, size_t nStart = 0) const;
-        size_t find_first_not_of(const wchar_t* sz, size_t nStart = 0) const;
-        size_t find_first_not_of(const char* sz, size_t nStart, size_t n) const;
-        size_t find_first_not_of(const wchar_t* sz, size_t nStart, size_t n) const;
-        size_t find_first_not_of(wxUniChar 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* sz, size_t nStart = npos) const;
-        size_t find_last_not_of(const wchar_t* sz, size_t nStart = npos) const;
-        size_t find_last_not_of(const char* sz, size_t nStart, size_t n) const;
-        size_t find_last_not_of(const wchar_t* sz, size_t nStart, size_t n) 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);
-
-        size_t length() const;
-
-        size_type max_size() const;
-
-        void reserve(size_t sz);
-        void resize(size_t nSize, wxUniChar ch = '\0');
-
-        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;
-
-        size_type size() const;
-        wxString substr(size_t nStart = 0, size_t nLen = npos) const;
-        void swap(wxString& str);
+    static wxString FromUTF8Unchecked(const char* s);
+    static wxString FromUTF8Unchecked(const char* s, size_t len);

     //@}
 };
 
     //@}
 };
 

-/** @addtogroup group_string_operators */
+
+

 //@{
 /**
 //@{
 /**

-    Comparison operators for wxString.
+    Comparison operator for string types.

 */
 inline bool operator==(const wxString& s1, const wxString& s2);
 inline bool operator!=(const wxString& s1, const wxString& s2);
 */
 inline bool operator==(const wxString& s1, const wxString& s2);
 inline bool operator!=(const wxString& s1, const wxString& s2);


@@ -1369,9 +1628,11 @@ inline bool operator==(const wxString& s1, const wxCharBuffer& s2);
 inline bool operator==(const wxCharBuffer& s1, const wxString& s2);
 inline bool operator!=(const wxString& s1, const wxCharBuffer& s2);
 inline bool operator!=(const wxCharBuffer& s1, const wxString& s2);
 inline bool operator==(const wxCharBuffer& s1, const wxString& s2);
 inline bool operator!=(const wxString& s1, const wxCharBuffer& s2);
 inline bool operator!=(const wxCharBuffer& s1, const wxString& s2);

+//@}

 
 

+//@{

 /**
 /**

-    Comparison operators with wxUniChar or wxUniCharRef.
+    Comparison operators char types.

 */
 inline bool operator==(const wxUniChar& c, const wxString& s);
 inline bool operator==(const wxUniCharRef& c, const wxString& s);
 */
 inline bool operator==(const wxUniChar& c, const wxString& s);
 inline bool operator==(const wxUniCharRef& c, const wxString& s);


@@ -1401,7 +1662,6 @@ wxString wxEmptyString;
 
 
 
 
 
 

-

 /**
     @class wxStringBufferLength
 
 /**
     @class wxStringBufferLength
 


@@ -1416,16 +1676,13 @@ wxString wxEmptyString;
 
     @code
         wxString theAnswer;
 
     @code
         wxString theAnswer;

-        wxStringBuffer theAnswerBuffer(theAnswer, 1024);
+        wxStringBufferLength theAnswerBuffer(theAnswer, 1024);

         int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
         theAnswerBuffer.SetLength(nLength);
         if ( theAnswer != "42" )
             wxLogError("Something is very wrong!");
     @endcode
 
         int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
         theAnswerBuffer.SetLength(nLength);
         if ( theAnswer != "42" )
             wxLogError("Something is very wrong!");
     @endcode
 

-    @todo
-        the example above does not make use of wxStringBufferLength??
-

     Note that the exact usage of this depends on whether or not wxUSE_STL is
     enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
     character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
     Note that the exact usage of this depends on whether or not wxUSE_STL is
     enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
     character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from


@@ -1524,3 +1781,29 @@ public:
     */
     wxStringCharType* operator wxStringCharType *();
 };
     */
     wxStringCharType* operator wxStringCharType *();
 };

+
+
+/** @addtogroup group_funcmacro_string */
+//@{
+
+/**
+    Allows to extend a function with the signature:
+    @code bool SomeFunc(const wxUniChar& c) @endcode
+    which operates on a single character, to an entire wxString.
+
+    E.g. if you want to check if an entire string contains only digits,
+    you can do:
+    @code
+        if (wxStringCheck<wxIsdigit>(myString))
+            ... // the entire string contains oly digits!
+        else
+            ... // at least one character of myString is not a digit
+    @endcode
+
+    @return @true if the given function returns a non-zero value for all
+            characters of the @a val string.
+*/
+template<bool (T)(const wxUniChar& c)>
+    inline bool wxStringCheck(const wxString& val);
+
+//@}