]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/string.h
Ticket #9592: gtk-choice-setcolumns.2.diff
[wxWidgets.git] / interface / string.h
index c82e2eb3957d9d2977432f4f5a5fcb8a48fc7066..25c36a1d8d16e443d02f468a0f0836d0e8aebabc 100644 (file)
@@ -63,7 +63,7 @@ public:
         Returns the writable pointer to a buffer of the size at least equal to the
         length specified in the constructor.
     */
-    wxChar* operator wxChar *();
+    wxStringCharType* operator wxStringCharType *();
 };
 
 
@@ -72,29 +72,199 @@ public:
     @class wxString
     @wxheader{string.h}
 
-    wxString is a class representing a character string. It uses 
-    reference counting and copy-on-write internally and is not
-    thread-safe. Please see the 
-    @ref overview_string "wxString overview" and the 
-    @ref overview_unicode "Unicode overview" for more information
-    about it.
-    
+    wxString is a class representing a Unicode character string.
+    wxString uses @c std::string internally to store its content
+    unless this is not supported by the compiler or disabled
+    specifically when building wxWidgets. Therefore wxString
+    inherits many features from @c std::string's. Most
+    implementations of @std::string are thread-safe and don't
+    use reference counting. By default, wxString uses @c std::string
+    internally even if wxUSE_STL is not defined.
+
     Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per
     character wchar_t) under Windows and UTF-8 under Unix, Linux and
-    OS X to store its content. Much work has been done to make
-    existing code using ANSI string literals work as before.
+    OS X to store its content. Much work has been done to make existing
+    code using ANSI string literals work as before. If you need to have a
+    wxString that uses wchar_t on Unix and Linux, too, you can specify
+    this on the command line with the @c configure @c --disable-utf8 switch.
+
+    As a consequence of this change, iterating over a wxString by index
+    can become inefficient in UTF8 mode and iterators should be used instead:
 
-    wxString implements most of the methods of the
-    std::string class. These standard functions are not documented in
-    this manual, please see the STL documentation. The behaviour of
-    all these functions is identical to the behaviour described there.
+    @code
+    wxString s = "hello";
+    wxString::const_iterator i;
+    for (i = s.begin(); i != s.end(); ++i)
+    {
+        wxUniChar uni_ch = *i;
+        // do something with it
+    }
+    @endcode
+
+    Please see the
+    @ref overview_string "wxString overview" and the
+    @ref overview_unicode "Unicode overview" for more information
+    about it.
 
-    You may notice that wxString sometimes has many functions which do
-    the same thing like, for example, wxString::Length, wxString::Len and @c length()
-    which all return the string length. In all cases of such duplication the @c std::string
-    compatible method (@c length() in this case, always the lowercase version) should be
-    used as it will ensure smoother transition to @c std::string when wxWidgets
-    starts using it instead of wxString.
+    wxString uses the current locale encoding to convert any C string
+    literal to Unicode. The same is done for converting to and from
+    @c std::string and for the return value of c_str(). For this
+    conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv.
+
+    wxString implements most of the methods of the @c std::string class.
+    These standard functions are only listed here, but they are not
+    fully documented in this manual. Please see the STL documentation.
+    The behaviour of all these functions is identical to the behaviour
+    described there.
+
+    You may notice that wxString sometimes has several functions which do
+    the same thing like, for example, Length(), Len() and length() which
+    all return the string length. In all cases of such duplication the
+    @c std::string compatible method should be used.
+
+        Anything may be concatenated (appended to) with a string. However, you can't
+        append something to a C string (including literal constants), so to do this it
+        should be converted to a wxString first.
+
+        @li operator<<()
+        @li operator+=()
+        @li operator+()
+        @li Append()
+        @li Prepend()
+
+        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()
+
+        The MakeXXX() variants modify the string in place, while the other functions
+        return a new string which contains the original text converted to the upper or
+        lower case and leave the original string unchanged.
+
+        @li MakeUpper()
+        @li Upper()
+        @li MakeLower()
+        @li Lower()
+
+        Many functions in this section take a character index in the string. As with C
+        strings and/or arrays, the indices start from 0, so the first character of a
+        string is string[0]. Attempt to access a character beyond the end of the
+        string (which may be even 0 if the string is empty) will provoke an assert
+        failure in @ref overview_debugging "debug build", but no checks are
+        done in release builds.
+        This section also contains both implicit and explicit conversions to C style
+        strings. Although implicit conversion is quite convenient, it is advised to use
+        explicit c_str() method for the sake of clarity.
+
+        @li GetChar()
+        @li GetWritableChar()
+        @li SetChar()
+        @li Last()
+        @li operator[]()
+        @li c_str()
+        @li mb_str()
+        @li wc_str()
+        @li fn_str()
+
+        The default comparison function Cmp() is case-sensitive and
+        so is the default version of IsSameAs(). For case
+        insensitive comparisons you should use CmpNoCase() or
+        give a second parameter to IsSameAs. This last function is may be more
+        convenient if only equality of the strings matters because it returns a boolean
+        @true value if the strings are the same and not 0 (which is usually @false
+        in C)as Cmp() does.
+        Matches() is a poor man's regular expression matcher: it only understands
+        '*' and '?' metacharacters in the sense of DOS command line interpreter.
+        StartsWith() is helpful when parsing a line of text which should start
+        with some predefined prefix and is more efficient than doing direct string
+        comparison as you would also have to precalculate the length of the prefix then.
+
+        @li Cmp()
+        @li CmpNoCase()
+        @li IsSameAs()
+        @li Matches()
+        @li StartsWith()
+        @li EndsWith()
+
+        The string provides functions for conversion to signed and unsigned integer and
+        floating point numbers. All three functions take a pointer to the variable to
+        put the numeric value in and return @true if the @b entire string could be
+        converted to a number.
+
+        @li ToLong()
+        @li ToLongLong()
+        @li ToULong()
+        @li ToULongLong()
+        @li ToDouble()
+
+        These are "advanced" functions and they will be needed quite 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 Alloc()
+        @li Shrink()
+        @li wxStringBuffer
+        @li wxStringBufferLength
+
+        Misc. other string functions.
+
+        @li Trim()
+        @li Truncate()
+        @li Pad()
+
+        These functions return the string length and check whether the string
+        is empty or empty it.
+
+        @li Len()
+        @li IsEmpty()
+        @li operator!()
+        @li Empty()
+        @li Clear()
+
+
+        These functions allow to extract substring from this string. All of them don't
+        modify the original string and return a new string containing the extracted
+        substring.
+
+        @li Mid()
+        @li operator()()
+        @li Left()
+        @li Right()
+        @li BeforeFirst()
+        @li BeforeLast()
+        @li AfterFirst()
+        @li AfterLast()
+        @li StartsWith()
+        @li EndsWith()
+
+        These functions replace the standard @e strchr() and @e strstr()
+        functions.
+
+        @li Find()
+        @li Replace()
+
+        Both formatted versions (Printf/() and stream-like insertion operators
+        exist (for basic types only). Additionally, the Format() function allows
+        to use simply append formatted value to a string:
+
+        @li Format()
+        @li FormatV()
+        @li Printf()
+        @li PrintfV()
+        @li operator>>()
+
+        These functions are deprecated, please consider using new wxWidgets 2.0
+        functions instead of them (or, even better, std::string compatible variants).
+
+        Contains(), First(), Freq(), IsAscii(), IsNull(),
+        IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(),
+        SubString(), UpperCase()
 
     @library{wxbase}
     @category{data}
@@ -108,74 +278,92 @@ public:
 class wxString
 {
 public:
+    /**
+        An 'invalid' value for string index
+    */
+    static const size_t npos;
+
+    /**
+        @name Standard types
+    */
+    //@{
+    typedef wxUniChar value_type;
+    typedef wxUniChar char_type;
+    typedef wxUniCharRef reference;
+    typedef wxChar* pointer;
+    typedef const wxChar* const_pointer;
+    typedef size_t size_type;
+    typedef wxUniChar const_reference;
+    //@}
+
     /**
        Default constructor
     */
     wxString();
-    
+
     /**
-       Creates a string from another string. Just increases the ref 
+       Creates a string from another string. Just increases the ref
        count by 1.
     */
     wxString(const wxString& stringSrc);
-    
+
 
     /**
-       Constructs a string from the string literal @c psz using
-       the current locale encoding to convert it to Unicode.
+       Constructs a string from the string literal @e psz using
+       the current locale encoding to convert it to Unicode (wxConvLibc).
     */
     wxString(const char *psz);
 
     /**
-       Constructs a string from the string literal @c psz using
-       @c conv to convert it Unicode.
+       Constructs a string from the string literal @e psz using
+       @e conv to convert it Unicode.
     */
     wxString(const char *psz, const wxMBConv& conv);
 
     /**
-       Constructs a string from the first @ nLength character of the string literal @c psz using
-       the current locale encoding to convert it to Unicode.
+       Constructs a string from the first @e nLength character of the string literal @e psz using
+       the current locale encoding to convert it to Unicode (wxConvLibc).
     */
     wxString(const char *psz, size_t nLength);
 
     /**
-       Constructs a string from the first @ nLength character of the string literal @c psz using
-       @c conv to convert it Unicode.
+       Constructs a string from the first @e nLength character of the string literal @e psz using
+       @e conv to convert it Unicode.
     */
     wxString(const char *psz, const wxMBConv& conv, size_t nLength);
 
     /**
-       Constructs a string from the string literal @c pwz.
+       Constructs a string from the string literal @e pwz.
     */
     wxString(const wchar_t *pwz);
 
     /**
-       Constructs a string from the first @ nLength characters of the string literal @c pwz.
+       Constructs a string from the first @e nLength characters of the string literal @e pwz.
     */
     wxString(const wchar_t *pwz, size_t nLength);
 
     /**
-       Constructs a string from @c buf using the using
+       Constructs a string from @e buf using the using
        the current locale encoding to convert it to Unicode.
     */
     wxString(const wxCharBuffer& buf);
-    
+
     /**
-       Constructs a string from @c buf.
+       Constructs a string from @e buf.
     */
     wxString(const wxWCharBuffer& buf);
 
     /**
-       Constructs a string from @str using the using
-       the current locale encoding to convert it to Unicode.
+       Constructs a string from @e str using the using the current locale encoding
+       to convert it to Unicode (wxConvLibc).
     */
     wxString(const std::string& str);
-    
+
     /**
-       Constructs a string from @str.
+       Constructs a string from @str.
     */
     wxString(const std::wstring& str);
-    
+
 
     /**
         String destructor. Note that this is not virtual, so wxString must not be
@@ -185,15 +373,15 @@ public:
 
     /**
         Gets all the characters after the first occurrence of @e ch.
-        Returns the empty string if @a ch is not found.
+        Returns the empty string if @e ch is not found.
     */
-    wxString AfterFirst(wxChar ch) const;
+    wxString AfterFirst(wxUniChar ch) const;
 
     /**
         Gets all the characters after the last occurrence of @e ch.
-        Returns the whole string if @a ch is not found.
+        Returns the whole string if @e ch is not found.
     */
-    wxString AfterLast(wxChar ch) const;
+    wxString AfterLast(wxUniChar ch) const;
 
     /**
         Preallocate enough space for wxString to store @a nLen characters.
@@ -234,75 +422,47 @@ public:
     */
     bool Alloc(size_t nLen);
 
-    //@{
     /**
-        Concatenates character @a ch to this string, @a count times, returning a
-        reference
-        to it.
+       Appends the string literal @e psz.
     */
-    wxString Append(const wxChar* psz);
-    wxString Append(wxChar ch, int count = 1);
-    //@}
+    wxString& Append(const char* psz);
 
     /**
-        Gets all characters before the first occurrence of @e ch.
-        Returns the whole string if @a ch is not found.
+       Appends the wide string literal @e pwz.
     */
-    wxString BeforeFirst(wxChar ch) const;
+    wxString& Append(const wchar_t* pwz)
 
     /**
-        Gets all characters before the last occurrence of @e ch.
-        Returns the empty string if @a ch is not found.
+       Appends the string literal @e psz with max length @e nLen.
     */
-    wxString BeforeLast(wxChar ch) const;
+    wxString& Append(const char* psz, size_t nLen);
 
     /**
-        The MakeXXX() variants modify the string in place, while the other functions
-        return a new string which contains the original text converted to the upper or
-        lower case and leave the original string unchanged.
-        MakeUpper()
-
-        Upper()
-
-        MakeLower()
-
-        Lower()
+       Appends the wide string literal @e psz with max length @e nLen.
     */
-
+    wxString& Append(const wchar_t* pwz, size_t nLen)
 
     /**
-        Many functions in this section take a character index in the string. As with C
-        strings and/or arrays, the indices start from 0, so the first character of a
-        string is string[0]. Attempt to access a character beyond the end of the
-        string (which may be even 0 if the string is empty) will provoke an assert
-        failure in @ref overview_debuggingoverview "debug build", but no checks are
-        done in
-        release builds.
-        This section also contains both implicit and explicit conversions to C style
-        strings. Although implicit conversion is quite convenient, it is advised to use
-        explicit @ref cstr() c_str method for the sake of clarity. Also
-        see overview() for the cases where it is necessary to
-        use it.
-        GetChar()
-
-        GetWritableChar()
-
-        SetChar()
-
-        Last()
-
-        @ref operatorbracket() "operator []"
-
-        @ref cstr() c_str
-
-        @ref mbstr() mb_str
+       Appends the string @e s.
+    */
+    wxString &Append(const wxString &s);
 
-        @ref wcstr() wc_str
+    /**
+       Appends the character @e ch @e count times.
+    */
+    wxString &Append(wxUniChar ch, size_t count = 1u);
 
-        @ref fnstr() fn_str
+    /**
+        Gets all characters before the first occurrence of @e ch.
+        Returns the whole string if @a ch is not found.
+    */
+    wxString BeforeFirst(wxUniChar ch) const;
 
-        @ref operatorconstcharpt() "operator const char*"
+    /**
+        Gets all characters before the last occurrence of @e ch.
+        Returns the empty string if @a ch is not found.
     */
+    wxString BeforeLast(wxUniChar ch) const;
 
 
     /**
@@ -325,114 +485,45 @@ public:
      */
     wxString Clone() const;
 
-    //@{
     /**
         Case-sensitive comparison.
-        Returns a positive value if the string is greater than the argument, zero if
-        it is equal to it or a negative value if it is less than the argument (same
-        semantics
-        as the standard @e strcmp() function).
+        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 CmpNoCase(), IsSameAs().
     */
     int Cmp(const wxString& s) const;
-    const int Cmp(const wxChar* psz) const;
-    //@}
 
-    //@{
     /**
         Case-insensitive comparison.
-        Returns a positive value if the string is greater than the argument, zero if
-        it is equal to it or a negative value if it is less than the argument (same
-        semantics
-        as the standard @e strcmp() function).
+        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().
     */
     int CmpNoCase(const wxString& s) const;
-    const int CmpNoCase(const wxChar* psz) const;
-    //@}
-
-    /**
-        Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.
-        This is a wxWidgets 1.xx compatibility function; use Cmp() instead.
-    */
-    int CompareTo(const wxChar* psz, caseCompare cmp = exact) const;
-
-    /**
-        The default comparison function Cmp() is case-sensitive and
-        so is the default version of IsSameAs(). For case
-        insensitive comparisons you should use CmpNoCase() or
-        give a second parameter to IsSameAs. This last function is may be more
-        convenient if only equality of the strings matters because it returns a boolean
-        @true value if the strings are the same and not 0 (which is usually @false in
-        C)
-        as @c Cmp() does.
-        Matches() is a poor man's regular expression matcher:
-        it only understands '*' and '?' metacharacters in the sense of DOS command line
-        interpreter.
-        StartsWith() is helpful when parsing a line of
-        text which should start with some predefined prefix and is more efficient than
-        doing direct string comparison as you would also have to precalculate the
-        length of the prefix then.
-        Cmp()
-
-        CmpNoCase()
-
-        IsSameAs()
-
-        Matches()
-
-        StartsWith()
-
-        EndsWith()
-    */
 
 
     //@{
     /**
-
+        Comparison operators
     */
     bool operator ==(const wxString& x, const wxString& y);
-    bool operator ==(const wxString& x, const wxChar* t);
+    bool operator ==(const wxString& x, wxUniChar ch);
     bool operator !=(const wxString& x, const wxString& y);
-    bool operator !=(const wxString& x, const wxChar* t);
+    bool operator !=(const wxString& x, wxUniChar ch);
     bool operator(const wxString& x, const wxString& y);
-    bool operator(const wxString& x, const wxChar* t);
+    bool operator(const wxString& x, wxUniChar ch);
     bool operator =(const wxString& x, const wxString& y);
-    bool operator =(const wxString& x, const wxChar* t);
+    bool operator =(const wxString& x, wxUniChar ch);
     bool operator(const wxString& x, const wxString& y);
-    bool operator(const wxString& x, const wxChar* t);
+    bool operator(const wxString& x, wxUniChar ch);
     bool operator =(const wxString& x, const wxString& y);
-    bool operator =(const wxString& x, const wxChar* t);
+    bool operator =(const wxString& x, wxUniChar ch);
     //@}
 
-    /**
-        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.
-        @ref operatorout() "operator "
-
-        @ref plusequal() "operator +="
-
-        @ref operatorplus() "operator +"
-
-        Append()
-
-        Prepend()
-    */
-
-
-    /**
-        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.
-        @ref construct() wxString
-
-        @ref operatorassign() "operator ="
-
-        @ref destruct() ~wxString
-    */
-
 
     /**
         Returns @true if target appears anywhere in wxString; else @false.
@@ -441,22 +532,6 @@ public:
     */
     bool Contains(const wxString& str) const;
 
-    /**
-        The string provides functions for conversion to signed and unsigned integer and
-        floating point numbers. All three functions take a pointer to the variable to
-        put the numeric value in and return @true if the @b entire string could be
-        converted to a number.
-        ToLong()
-
-        ToLongLong()
-
-        ToULong()
-
-        ToULongLong()
-
-        ToDouble()
-    */
-
 
     /**
         Makes the string empty, but doesn't free memory occupied by the string.
@@ -467,30 +542,32 @@ public:
     /**
         This function can be used to test if the string ends with the specified
         @e suffix. If it does, the function will return @true and put the
-        beginning of the string before the suffix into @a rest string if it is not
+        beginning of the string before the suffix into @e rest string if it is not
         @NULL. Otherwise, the function returns @false and doesn't
         modify the @e rest.
     */
-    bool EndsWith(const wxString& suffix, wxString rest = NULL) const;
+    bool EndsWith(const wxString& suffix, wxString *rest = NULL) const;
 
-    //@{
     /**
-        Searches for the given string. Returns the starting index, or @c wxNOT_FOUND if
-        not found.
+        Searches for the given character @e ch. Returns the position or
+        @c wxNOT_FOUND if not found.
     */
     int Find(wxUniChar ch, bool fromEnd = false) const;
-    const int Find(const wxString& sub) const;
-    //@}
+
+    /**
+        Searches for the given string @e sub. Returns the starting position or
+        @c wxNOT_FOUND if not found.
+    */
+    int Find(const wxString& sub) const;
 
     //@{
     /**
         Same as Find().
-        This is a wxWidgets 1.xx compatibility function; you should not use it in new
-        code.
+        This is a wxWidgets 1.xx compatibility function;
+        you should not use it in new code.
     */
-    int First(wxChar c) const;
-    int First(const wxChar* psz) const;
-    const int First(const wxString& str) const;
+    int First(wxUniChar ch) const;
+    int First(const wxString& str) const;
     //@}
 
     /**
@@ -510,22 +587,27 @@ public:
     static wxString FormatV(const wxChar format, va_list argptr);
 
     /**
-        Returns the number of occurrences of @a ch in the string.
-        This is a wxWidgets 1.xx compatibility function; you should not use it in new
-        code.
+        Returns the number of occurrences of @e ch in the string.
+        This is a wxWidgets 1.xx compatibility function; you should not
+        use it in new code.
     */
-    int Freq(wxChar ch) const;
+    int Freq(wxUniChar ch) const;
 
     //@{
     /**
-        Converts given buffer of binary data from 8-bit string to wxString. In Unicode
-        build, the string is interpreted as being in ISO-8859-1 encoding. The version
-        without @a len parameter takes NUL-terminated data.
-        This is a convenience method useful when storing binary data in wxString.
+        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.
+
+        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.
 
         @since 2.8.4
 
-        @see wxString::To8BitData
+        @see wxString::To8BitData()
     */
     static wxString From8BitData(const char* buf, size_t len);
     static wxString From8BitData(const char* buf);
@@ -534,10 +616,7 @@ public:
     //@{
     /**
         Converts the string or character from an ASCII, 7-bit form
-        to the native wxString representation. Most useful when using
-        a Unicode build of wxWidgets (note the use of @c char instead of @c wxChar).
-        Use @ref construct() "wxString constructors" if you
-        need to convert from another charset.
+        to the native wxString representation.
     */
     static wxString FromAscii(const char* s);
     static wxString FromAscii(const unsigned char* s);
@@ -560,40 +639,28 @@ public:
     /**
         Returns the character at position @a n (read-only).
     */
-    wxChar GetChar(size_t n) const;
+    wxUniChar GetChar(size_t n) const;
 
     /**
-        wxWidgets compatibility conversion. Returns a constant pointer to the data in
-        the string.
+        wxWidgets compatibility conversion. Same as c_str().
     */
-    const wxChar* GetData() const;
+    const wxCStrData* GetData() const;
 
     /**
         Returns a reference to the character at position @e n.
     */
-    wxChar GetWritableChar(size_t n);
+    wxUniCharRef GetWritableChar(size_t n);
 
     /**
         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
+        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.
     */
-    wxChar* GetWriteBuf(size_t len);
-
-    //@{
-    /**
-        Same as Find().
-        This is a wxWidgets 1.xx compatibility function; you should not use it in new
-        code.
-    */
-    size_t Index(wxChar ch) const;
-    const size_t Index(const wxChar* sz) const;
-    //@}
+    wxStringCharType* GetWriteBuf(size_t len);
 
     /**
         Returns @true if the string contains only ASCII characters.
@@ -629,8 +696,8 @@ public:
         Returns @true if the string is equal to the character, @false otherwise.
         See also Cmp(), CmpNoCase()
     */
-    bool IsSameAs(const wxChar* psz, bool caseSensitive = true) const;
-    const bool IsSameAs(wxChar c, bool caseSensitive = true) const;
+    bool IsSameAs(const wxString &s, bool caseSensitive = true) const;
+    bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const;
     //@}
 
     /**
@@ -643,11 +710,11 @@ public:
     //@{
     /**
         Returns a reference to the last character (writable).
-        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.
     */
-    wxChar Last();
-    const wxChar Last();
+    wxUniCharRef Last();
+    const wxUniChar Last();
     //@}
 
     /**
@@ -682,64 +749,36 @@ public:
     /**
         Converts all characters to lower case and returns the result.
     */
-    wxString MakeLower();
+    wxString& MakeLower();
 
     /**
         Converts all characters to upper case and returns the result.
     */
-    wxString MakeUpper();
+    wxString& MakeUpper();
 
     /**
         Returns @true if the string contents matches a mask containing '*' and '?'.
     */
     bool Matches(const wxString& mask) const;
 
-    /**
-        These are "advanced" functions and they will be needed quite 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.
-        Alloc()
-
-        Shrink()
-
-        wxStringBuffer
-
-        wxStringBufferLength
-    */
-
-
     /**
         Returns a substring starting at @e first, with length @e count, or the rest of
         the string if @a count is the default value.
     */
     wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const;
 
-    /**
-        Other string functions.
-        Trim()
-
-        Truncate()
-
-        Pad()
-    */
-
 
     /**
-        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).
+        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, wxChar pad = ' ',
+    wxString& Pad(size_t count, wxUniChar pad = ' ',
                  bool fromRight = true);
 
     /**
         Prepends @a str to this string, returning a reference to this string.
     */
-    wxString Prepend(const wxString& str);
+    wxString& Prepend(const wxString& str);
 
     /**
         Similar to the standard function @e sprintf(). Returns the number of
@@ -789,19 +828,10 @@ public:
     */
     wxString Right(size_t count) const;
 
-    /**
-        These functions replace the standard @e strchr() and @e strstr()
-        functions.
-        Find()
-
-        Replace()
-    */
-
-
     /**
         Sets the character at position @e n.
     */
-    void SetChar(size_t n, wxChar ch);
+    void SetChar(size_t n, wxUniChar ch);
 
     /**
         Minimizes the string's memory. This can be useful after a call to
@@ -816,22 +846,7 @@ public:
         @NULL. Otherwise, the function returns @false and doesn't modify the
         @e rest.
     */
-    bool StartsWith(const wxString& prefix, wxString rest = NULL) const;
-
-    /**
-        These functions return the string length and check whether the string is empty
-        or empty it.
-        Len()
-
-        IsEmpty()
-
-        @ref operatornot() operator!
-
-        Empty()
-
-        Clear()
-    */
-
+    bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;
 
     /**
         Strip characters at the front and/or end. The same as Trim except that it
@@ -849,44 +864,21 @@ public:
     */
     wxString SubString(size_t from, size_t to) const;
 
-    /**
-        These functions allow to extract substring from this string. All of them don't
-        modify the original string and return a new string containing the extracted
-        substring.
-        Mid()
-
-        @ref operatorparenth() operator
-
-        Left()
-
-        Right()
-
-        BeforeFirst()
-
-        BeforeLast()
-
-        AfterFirst()
-
-        AfterLast()
-
-        StartsWith()
-
-        EndsWith()
-    */
-
-
     //@{
     /**
-        Converts the string to an 8-bit string in ISO-8859-1 encoding in the form of
-        a wxCharBuffer (Unicode builds only).
-        This is a convenience method useful when storing binary data in wxString.
+        Converts the string to an 8-bit string in ISO-8859-1 encoding in the
+        form of a wxCharBuffer (Unicode builds only).
+
+        This is a convenience method useful when storing binary data in
+        wxString. 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
 
-        @see wxString::From8BitData
+        @see wxString::From8BitData()
     */
     const char* To8BitData() const;
-    const const wxCharBuffer To8BitData() const;
+    const wxCharBuffer To8BitData() const;
     //@}
 
     //@{
@@ -898,7 +890,7 @@ public:
         powerful means of converting wxString to C string.
     */
     const char* ToAscii() const;
-    const const wxCharBuffer ToAscii() const;
+    const wxCharBuffer ToAscii() const;
     //@}
 
     /**
@@ -965,22 +957,22 @@ public:
 
     //@{
     /**
-        Same as @ref wxString::utf8str utf8_str.
+        Same as utf8_str().
     */
     const char* ToUTF8() const;
-    const const wxCharBuffer ToUF8() const;
+    const wxCharBuffer ToUF8() const;
     //@}
 
     /**
         Removes white-space (space, tabs, form feed, newline and carriage return) from
         the left or from the right end of the string (right is default).
     */
-    wxString Trim(bool fromRight = true);
+    wxString& Trim(bool fromRight = true);
 
     /**
         Truncate the string to the given length.
     */
-    wxString Truncate(size_t len);
+    wxString& Truncate(size_t len);
 
     //@{
     /**
@@ -1014,78 +1006,71 @@ public:
     void UpperCase();
 
     /**
-        Both formatted versions (wxString::Printf) and stream-like
-        insertion operators exist (for basic types only). Additionally, the
-        Format() function allows to use simply append
-        formatted value to a string:
-
-        Format()
-
-        FormatV()
-
-        Printf()
-
-        PrintfV()
-
-        @ref operatorout() "operator "
-    */
-
+        Returns a pointer to the string data (@c const char* when using UTF-8
+        internally, @c const wchar_t* when using UCS-2 internally).
 
-    /**
-        Returns a pointer to the string data (@c const char* in ANSI build,
-        @c const wchar_t* in Unicode build).
         Note that the returned value is not convertible to @c char* or
-        @c wchar_t*, use @ref charstr() char_str or
-        @ref wcharstr() wchar_string if you need to pass string value
-        to a function expecting non-const pointer.
-
-        @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref
-             fnstr() fn_str, @ref charstr() char_str, @ref
-             wcharstr() wchar_string
+        @c wchar_t*, use char_str() or wchar_str() if you need to pass
+        string value to a function expecting non-const pointer.
     */
-    const wxChar* c_str() const;
+    const 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.
+        don't have const-correct API. Use wxStringBuffer if you want to modify
+        the string.
 
-        @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref
-             fnstr() fn_str, @ref cstr() c_str, @ref
-             wcharstr() wchar_str
+        @see c_str()
     */
     wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
 
-    //@{
     /**
-        Returns string representation suitable for passing to OS' functions for
-        file handling. In ANSI build, this is same as @ref cstr() c_str.
-        In Unicode build, returned value can be either wide character string
-        or C string in charset matching the @c wxConvFileName object, depending on
-        the OS.
+        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.
 
-        @see wxMBConv, @ref wcstr() wc_str, @ref wcstr() mb_str
+        Notice that retrieving a char buffer in UTF-8 build will return the
+        internal string representation in UTF-8 while in wchar_t build the char
+        buffer will contain the conversion of the string to the encoding of the
+        current locale (and so can fail).
+
+        @param len If non-@NULL, filled with the length of the returned buffer.
+        @return
+            buffer containing the string contents in the specified type,
+            notice that it may be @NULL if the conversion failed (e.g. Unicode
+            string couldn't be converted to the current encoding when @a T is
+            @c char).
+     */
+    template <typename T>
+    wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const;
+
+    //@{
+    /**
+        Returns string representation suitable for passing to OS' functions
+        for file handling.
     */
     const wchar_t* fn_str() const;
-    const const char* fn_str() const;
-    const const wxCharBuffer fn_str() const;
+    const char* fn_str() const;
+    const wxCharBuffer fn_str() const;
     //@}
 
     //@{
     /**
         Returns multibyte (C string) representation of the string.
         In Unicode build, converts using @e conv's wxMBConv::cWC2MB
-        method and returns wxCharBuffer. In ANSI build, this function is same
-        as @ref cstr() c_str.
+        method and returns wxCharBuffer. In ANSI build, this function
+        is same as c_str().
         The macro wxWX2MBbuf is defined as the correct return type (without const).
 
-        @see wxMBConv, @ref cstr() c_str, @ref wcstr() wc_str, @ref
-             fnstr() fn_str, @ref charstr() char_str
+        @see wxMBConv, c_str(), wc_str(), fn_str(), char_str()
     */
     const char* mb_str(const wxMBConv& conv = wxConvLibc) const;
-    const const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
+    const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
     //@}
 
     /**
@@ -1097,12 +1082,10 @@ public:
     /**
         These functions work as C++ stream insertion operators: they insert the given
         value into the string. Precision or format cannot be set using them, you can
-        use
-        Printf() for this.
+        use Printf() for this.
     */
     wxString operator(const wxString& str);
-    wxString operator(const wxChar* psz);
-    wxString operator(wxChar ch);
+    wxString operator(wxUniChar ch);
     wxString operator(int i);
     wxString operator(float f);
     wxString operator(double d);
@@ -1115,13 +1098,11 @@ public:
 
     //@{
     /**
-        Concatenation: all these operators return a new string equal to the
+        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, const wxChar* y);
-    wxString operator +(const wxString& x, wxChar y);
-    wxString operator +(const wxChar* x, const wxString& y);
+    wxString operator +(const wxString& x, wxUniChar y);
     //@}
 
     //@{
@@ -1129,8 +1110,7 @@ public:
         Concatenation in place: the argument is appended to the string.
     */
     void operator +=(const wxString& str);
-    void operator +=(const wxChar* psz);
-    void operator +=(wxChar c);
+    void operator +=(wxUniChar c);
     //@}
 
     //@{
@@ -1139,64 +1119,49 @@ public:
         constructor (see @ref construct() "wxString constructors").
     */
     wxString operator =(const wxString& str);
-    wxString operator =(const wxChar* psz);
-    wxString operator =(wxChar c);
+    wxString operator =(wxUniChar c);
     //@}
 
     //@{
     /**
         Element extraction.
     */
-    wxChar operator [](size_t i) const;
-    wxChar operator [](size_t i) const;
-    const wxChar operator [](int i) const;
-    wxChar operator [](int i) const;
+    wxUniChar operator [](size_t i) const;
+    wxUniCharRef operator [](size_t i);
     //@}
 
     /**
-        Implicit conversion to a C string.
-    */
-    operator const wxChar*() const;
+        Empty string is @false, so !string will only return @true if the
+        string is empty.
 
-    /**
-        Empty string is @false, so !string will only return @true if the string is
-        empty.
-        This allows the tests for @NULLness of a @e const wxChar * pointer and emptiness
-        of the string to look the same in the code and makes it easier to port old code
-        to wxString.
         See also IsEmpty().
     */
     bool operator!() const;
 
-    /**
-        The supported functions are only listed here, please see any STL reference for
-        their documentation.
-    */
-
 
     //@{
     /**
-        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.
+        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.
     */
     const char* utf8_str() const;
-    const const wxCharBuffer utf8_str() const;
+    const wxCharBuffer utf8_str() const;
     //@}
 
     //@{
     /**
-        Returns wide character representation of the string.
-        In ANSI build, converts using @e conv's wxMBConv::cMB2WC
-        method and returns wxWCharBuffer. In Unicode build, this function is same
-        as @ref cstr() c_str.
-        The macro wxWX2WCbuf is defined as the correct return type (without const).
+        Converts the strings contents to the wide character represention
+        and returns it as a temporary wxWCharBuffer object or returns a
+        pointer to the internal string contents in wide character mode.
+
+        The macro wxWX2WCbuf is defined as the correct return
+        type (without const).
 
-        @see wxMBConv, @ref cstr() c_str, @ref wcstr() mb_str, @ref
-             fnstr() fn_str, @ref wcharstr() wchar_str
+        @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str()
     */
-    const wchar_t* wc_str(const wxMBConv& conv) const;
-    const const wxWCharBuffer wc_str(const wxMBConv& conv) const;
+    const wchar_t* wc_str() const;
+    const wxWCharBuffer wc_str() const;
     //@}
 
     /**
@@ -1206,47 +1171,120 @@ public:
         passing strings to legacy libraries that don't have const-correct API. Use
         wxStringBuffer if you want to modify the string.
 
-        @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref
-             fnstr() fn_str, @ref cstr() c_str, @ref
-             charstr() char_str
+        @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
     */
     wxWritableWCharBuffer wchar_str() const;
 
     /**
-        These functions are deprecated, please consider using new wxWidgets 2.0
-        functions instead of them (or, even better, std::string compatible variants).
-        CompareTo()
+        @name Iterator interface
 
-        Contains()
-
-        First()
-
-        Freq()
-
-        Index()
-
-        IsAscii()
-
-        IsNull()
-
-        IsNumber()
-
-        IsWord()
-
-        Last()
-
-        Length()
-
-        LowerCase()
+        These methods return iterators to the beginnnig or
+        end of the string.
+    */
+    //@{
+        const_iterator begin() const;
+        iterator begin();
+        const_iterator end() const;
+        iterator end();
+
+        const_reverse_iterator rbegin() const;
+        reverse_iterator rbegin();
+        const_reverse_iterator rend() const;
+        reverse_iterator rend();
+    //@}
 
-        Remove()
+    /**
+        @name STL interface
 
-        Strip()
+        The supported STL functions are listed here. Please see any
+        STL reference for their documentation.
+    */
+    //@{
+        size_t length() const;
+        size_type size() const;
+        size_type max_size() const;
+        size_type capacity() const;
+        void reserve(size_t sz);
+
+        void resize(size_t nSize, wxUniChar ch = '\0');
+
+        wxString& append(const wxString& str, size_t pos, size_t n);
+        wxString& append(const wxString& str);
+        wxString& append(const char *sz, size_t n);
+        wxString& append(const wchar_t *sz, size_t n);
+        wxString& append(size_t n, wxUniChar ch);
+        wxString& append(const_iterator first, const_iterator last);
+
+        wxString& assign(const wxString& str, size_t pos, size_t n);
+        wxString& assign(const wxString& str);
+        wxString& assign(const char *sz, size_t n);
+        wxString& assign(const wchar_t *sz, size_t n);
+        wxString& assign(size_t n, wxUniChar ch);
+        wxString& assign(const_iterator first, const_iterator last);
+
+        void clear();
+
+        int compare(const wxString& str) const;
+        int compare(size_t nStart, size_t nLen, const wxString& str) const;
+        int compare(size_t nStart, size_t nLen,
+              const wxString& str, size_t nStart2, size_t nLen2) const;
+        int compare(size_t nStart, size_t nLen,
+              const char* sz, size_t nCount = npos) const;
+        int compare(size_t nStart, size_t nLen,
+              const wchar_t* sz, size_t nCount = npos) const;
+
+        bool empty() const;
+
+        wxString& erase(size_type pos = 0, size_type n = npos);
+        iterator erase(iterator first, iterator last);
+        iterator erase(iterator first);
+
+        size_t find(const wxString& str, size_t nStart = 0) const;
+        size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
+        size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const;
+        size_t find(wxUniChar ch, size_t nStart = 0) const;
+
+        wxString& insert(size_t nPos, const wxString& str);
+        wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);
+        wxString& insert(size_t nPos, const char *sz, size_t n);
+        wxString& insert(size_t nPos, const wchar_t *sz, size_t n);
+        wxString& insert(size_t nPos, size_t n, wxUniChar ch);
+        iterator insert(iterator it, wxUniChar ch);
+        void insert(iterator it, const_iterator first, const_iterator last);
+        void insert(iterator it, size_type n, wxUniChar ch);
+
+        wxString& replace(size_t nStart, size_t nLen, const wxString& str);
+        wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch);
+        wxString& replace(size_t nStart, size_t nLen,
+                    const wxString& str, size_t nStart2, size_t nLen2);
+        wxString& replace(size_t nStart, size_t nLen,
+                    const char* sz, size_t nCount);
+        wxString& replace(size_t nStart, size_t nLen,
+                    const wchar_t* sz, size_t nCount);
+        wxString& replace(size_t nStart, size_t nLen,
+                    const wxString& s, size_t nCount);
+        wxString& replace(iterator first, iterator last, const wxString& s);
+        wxString& replace(iterator first, iterator last, const char* s, size_type n);
+        wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n);
+        wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch);
+        wxString& replace(iterator first, iterator last,
+                    const_iterator first1, const_iterator last1);
+        wxString& replace(iterator first, iterator last,
+                    const char *first1, const char *last1);
+        wxString& replace(iterator first, iterator last,
+                    const wchar_t *first1, const wchar_t *last1);
+
+        size_t rfind(const wxString& str, size_t nStart = npos) const;
+        size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const;
+        size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const;
+        size_t rfind(wxUniChar ch, size_t nStart = npos) const;
+
+        wxString substr(size_t nStart = 0, size_t nLen = npos) const;
+
+        void swap(wxString& str);
 
-        SubString()
+    //@}
 
-        UpperCase()
-    */
 };