Move SetDefaultTimeout to wxProtocol and set it to 60 seconds for both wxHTTP and...

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

diff --git a/interface/wx/string.h b/interface/wx/string.h
index 2cbf9d48d7d08657d6a649063a84d5a283064bb3..80f58699d10f5ce944d1018cc5ed48426f73d117 100644 (file)
--- a/interface/wx/string.h
+++ b/interface/wx/string.h
@@ -1,279 +1,252 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        string.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        string.h

-// Purpose:     interface of wxStringBuffer
+// Purpose:     interface of wxStringBuffer, wxString

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+

 /**
 /**

-    @class wxStringBuffer
+    @class wxString

 
 

-    This tiny class allows to conveniently access the wxString
-    internal buffer as a writable pointer without any risk of forgetting to restore
-    the string to the usable state later.
+    The wxString class has been completely rewritten for wxWidgets 3.0
+    and this change was actually the main reason for the calling that
+    version wxWidgets 3.0.

 
 

-    For example, assuming you have a low-level OS function called
-    @c GetMeaningOfLifeAsString(char *) returning the value in the provided
-    buffer (which must be writable, of course) you might call it like this:
+    wxString is a class representing a Unicode character string.
+    wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined)
+    to store its content (unless this is not supported by the compiler or disabled
+    specifically when building wxWidgets) and it therefore inherits
+    many features from @c std::basic_string. (Note that most implementations of
+    @c std::basic_string are thread-safe and don't use reference counting.)
+
+    These @c std::basic_string standard functions are only listed here, but
+    they are not fully documented in this manual; see the STL documentation
+    (http://www.cppreference.com/wiki/string/start) for more info.
+    The behaviour of all these functions is identical to the behaviour
+    described there.

 
 

-    @code
-    wxString theAnswer;
-        GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
-        if ( theAnswer != "42" )
-        {
-            wxLogError("Something is very wrong!");
-        }
-    @endcode
+    You may notice that wxString sometimes has several functions which do
+    the same thing like Length(), Len() and length() which all return the
+    string length. In all cases of such duplication the @c std::string
+    compatible methods should be used.

 
 

-    Note that the exact usage of this depends on whether on 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 wxString, keeping the same
-    buffer
-    wxString uses intact.  In other words, relying on wxStringBuffer containing the
-    old
-    wxString data is probably not a good idea if you want to build your program in
-    both
-    with and without wxUSE_STL.
+    For informations about the internal encoding used by wxString and
+    for important warnings and advices for using it, please read
+    the @ref overview_string.

 
 

-    @library{wxbase}
-    @category{FIXME}
-*/
-class wxStringBuffer
-{
-public:
-    /**
-        Constructs a writable string buffer object associated with the given string
-        and containing enough space for at least @a len characters. Basically, this
-        is equivalent to calling wxString::GetWriteBuf and
-        saving the result.
-    */
-    wxStringBuffer(const wxString& str, size_t len);
+    In wxWidgets 3.0 wxString always stores Unicode strings, so you should
+    be sure to read also @ref overview_unicode.

 
 

-    /**
-        Restores the string passed to the constructor to the usable state by calling
-        wxString::UngetWriteBuf on it.
-    */
-    ~wxStringBuffer();

 
 

-    /**
-        Returns the writable pointer to a buffer of the size at least equal to the
-        length specified in the constructor.
-    */
-    wxStringCharType* operator wxStringCharType *();
-};
+    @section string_construct 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.
+
+    @li wxString()
+    @li operator=()
+    @li ~wxString()
+    @li assign()

 
 
 
 

-/**
-    @class wxString
+    @section string_len String length

 
 

-    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. 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:
+    These functions return the string length and check whether the string
+    is empty or they empty it.

 
 

-    @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
+    @li length()
+    @li size()
+    @li Len()
+    @li IsEmpty()
+    @li operator!()
+    @li Empty()
+    @li Clear()

 
 

-    Please see the
-    @ref overview_string "wxString overview" and the
-    @ref overview_unicode "Unicode overview" for more information
-    about it.

 
 

-    wxString uses the current locale encoding to convert any C string
-    literal to Unicode. The same is done for converting to and from
-    @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.
+    @section string_access Character access

 
 

-    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.
+    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()

 
 

-    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 wc_str() method 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()
-
-        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}
 
     @stdobjects
 
     @library{wxbase}
     @category{data}
 
     @stdobjects

-    ::Objects:, ::wxEmptyString,
+    ::wxEmptyString

 
 

-    @see @ref overview_string "wxString overview", @ref overview_unicode
-    "Unicode overview"
+    @see @ref overview_string, @ref overview_unicode, wxUString

 */
 class wxString
 {
 */
 class wxString
 {


@@ -302,8 +275,8 @@ public:
     wxString();
 
     /**
     wxString();
 
     /**

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

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


@@ -343,8 +316,8 @@ public:
     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 encoding to convert it to Unicode.
+       Constructs a string from @e buf using the using the current locale
+        encoding to convert it to Unicode.

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


@@ -366,8 +339,9 @@ public:
 
 
     /**
 
 
     /**

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

     */
     ~wxString();
 
     */
     ~wxString();
 


@@ -430,7 +404,7 @@ public:
     /**
        Appends the wide string literal @e pwz.
     */
     /**
        Appends the wide string literal @e pwz.
     */

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

 
     /**
        Appends the string literal @e psz with max length @e nLen.
 
     /**
        Appends the string literal @e psz with max length @e nLen.


@@ -440,12 +414,12 @@ public:
     /**
        Appends the wide string literal @e psz with max length @e nLen.
     */
     /**
        Appends the wide string literal @e psz with max length @e nLen.
     */

-    wxString& Append(const wchar_t* pwz, size_t nLen)
+    wxString& Append(const wchar_t* pwz, size_t nLen);

 
     /**
        Appends the string @e s.
     */
 
     /**
        Appends the string @e s.
     */

-    wxString &Append(const wxString &s);
+    wxString& Append(const wxString& s);

 
     /**
        Appends the character @e ch @e count times.
 
     /**
        Appends the character @e ch @e count times.


@@ -464,6 +438,15 @@ public:
     */
     wxString BeforeLast(wxUniChar ch) const;
 
     */
     wxString BeforeLast(wxUniChar ch) const;
 

+    /**
+        Return the copy of the string with the first string character in the
+        upper case and the subsequent ones in the lower case.
+
+        @since 2.9.0
+
+        @see MakeCapitalized()
+     */
+    wxString Capitalize() const;

 
     /**
         Empties the string and frees memory occupied by it.
 
     /**
         Empties the string and frees memory occupied by it.


@@ -505,26 +488,6 @@ public:
     */
     int CmpNoCase(const wxString& s) const;
 
     */
     int CmpNoCase(const wxString& s) const;
 

-
-    //@{
-    /**
-        Comparison operators
-    */
-    bool operator ==(const wxString& x, const wxString& y);
-    bool operator ==(const wxString& x, wxUniChar ch);
-    bool operator !=(const wxString& x, const wxString& y);
-    bool operator !=(const wxString& x, wxUniChar ch);
-    bool operator(const wxString& x, const wxString& y);
-    bool operator(const wxString& x, wxUniChar ch);
-    bool operator =(const wxString& x, const wxString& y);
-    bool operator =(const wxString& x, wxUniChar ch);
-    bool operator(const wxString& x, const wxString& y);
-    bool operator(const wxString& x, wxUniChar ch);
-    bool operator =(const wxString& x, const wxString& y);
-    bool operator =(const wxString& x, wxUniChar ch);
-    //@}
-
-

     /**
         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
     /**
         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


@@ -576,7 +539,7 @@ public:
 
         @see FormatV(), Printf()
     */
 
         @see FormatV(), Printf()
     */

-    static wxString Format(const wxChar format, ...);
+    static wxString Format(const wxString& format, ...);

 
     /**
         This static function returns the string containing the result of calling
 
     /**
         This static function returns the string containing the result of calling


@@ -584,7 +547,7 @@ public:
 
         @see Format(), PrintfV()
     */
 
         @see Format(), PrintfV()
     */

-    static wxString FormatV(const wxChar format, va_list argptr);
+    static wxString FormatV(const wxString& format, va_list argptr);

 
     /**
         Returns the number of occurrences of @e ch in the string.
 
     /**
         Returns the number of occurrences of @e ch in the string.


@@ -628,14 +591,39 @@ public:
     //@{
     /**
         Converts C string encoded in UTF-8 to wxString.
     //@{
     /**
         Converts C string encoded in UTF-8 to wxString.

-        Note that this method assumes that @a s is a valid UTF-8 sequence and
-        doesn't do any validation in release builds, it's validity is only checked in
-        debug builds.
+
+        If @a s is not a valid UTF-8 string, an empty string is returned.
+
+        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.
+
+        @since 2.8.4

     */
     static wxString FromUTF8(const char* s);
     static wxString FromUTF8(const char* s, size_t len);
     //@}
 
     */
     static wxString FromUTF8(const char* s);
     static wxString FromUTF8(const char* s, size_t len);
     //@}
 

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

     /**
         Returns the character at position @a n (read-only).
     */
     /**
         Returns the character at position @a n (read-only).
     */


@@ -644,7 +632,7 @@ public:
     /**
         wxWidgets compatibility conversion. Same as c_str().
     */
     /**
         wxWidgets compatibility conversion. Same as c_str().
     */

-    const wxCStrData* GetData() const;
+    const wxCStrData GetData() const;

 
     /**
         Returns a reference to the character at position @e n.
 
     /**
         Returns a reference to the character at position @e n.


@@ -736,6 +724,8 @@ public:
 
     /**
         Returns this string converted to the lower case.
 
     /**
         Returns this string converted to the lower case.

+
+        @see MakeLower()

     */
     wxString Lower() const;
 
     */
     wxString Lower() const;
 


@@ -747,12 +737,28 @@ public:
     void LowerCase();
 
     /**
     void LowerCase();
 
     /**

-        Converts all characters to lower case and returns the result.
+        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();
 
     /**
     */
     wxString& MakeLower();
 
     /**

-        Converts all characters to upper case and returns the result.
+        Converts all characters to upper case and returns the reference to the
+        modified string.
+
+        @see Upper()

     */
     wxString& MakeUpper();
 
     */
     wxString& MakeUpper();
 


@@ -765,15 +771,14 @@ public:
         Returns a substring starting at @e first, with length @e count, or the rest of
         the string if @a count is the default value.
     */
         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;
+    wxString Mid(size_t first, size_t nCount = wxString::npos) 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).
     */
 
 
     /**
         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 pad = ' ',
-                 bool fromRight = true);
+    wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true);

 
     /**
         Prepends @a str to this string, returning a reference to this string.
 
     /**
         Prepends @a str to this string, returning a reference to this string.


@@ -791,14 +796,14 @@ public:
         size. Unfortunately, this function is not available on all platforms and the
         dangerous @e vsprintf() will be used then which may lead to buffer overflows.
     */
         size. Unfortunately, this function is not available on all platforms and the
         dangerous @e vsprintf() will be used then which may lead to buffer overflows.
     */

-    int Printf(const wxChar* pszFormat, ...);
+    int Printf(const wxString& pszFormat, ...);

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

-    int PrintfV(const wxChar* pszFormat, va_list argPtr);
+    int PrintfV(const wxString& pszFormat, va_list argPtr);

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


@@ -813,7 +818,7 @@ public:
     /**
         Removes the last character.
     */
     /**
         Removes the last character.
     */

-    wxString RemoveLast();
+    wxString& RemoveLast(size_t n = 1);

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


@@ -837,7 +842,7 @@ public:
         Minimizes the string's memory. This can be useful after a call to
         Alloc() if too much memory were preallocated.
     */
         Minimizes the string's memory. This can be useful after a call to
         Alloc() if too much memory were preallocated.
     */

-    void Shrink();
+    bool Shrink();

 
     /**
         This function can be used to test if the string starts with the specified
 
     /**
         This function can be used to test if the string starts with the specified


@@ -886,7 +891,7 @@ public:
         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
         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 mbstr() mb_str method provides more
+        characters. The @ref mb_str() "mb_str" method provides more

         powerful means of converting wxString to C string.
     */
     const char* ToAscii() const;
         powerful means of converting wxString to C string.
     */
     const char* ToAscii() const;


@@ -901,7 +906,7 @@ public:
 
         @see ToLong(), ToULong()
     */
 
         @see ToLong(), ToULong()
     */

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

 
     /**
         Attempts to convert the string to a signed integer in base @e base. Returns
 
     /**
         Attempts to convert the string to a signed integer in base @e base. Returns


@@ -919,7 +924,7 @@ public:
 
         @see ToDouble(), ToULong()
     */
 
         @see ToDouble(), ToULong()
     */

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

 
     /**
         This is exactly the same as ToLong() but works with 64
 
     /**
         This is exactly the same as ToLong() but works with 64


@@ -930,37 +935,38 @@ public:
 
         @see ToLong(), ToULongLong()
     */
 
         @see ToLong(), ToULongLong()
     */

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

 
     /**
         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
 
     /**
         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). 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.
+        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.

 
         @see ToDouble(), ToLong()
     */
 
         @see ToDouble(), ToLong()
     */

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

 
     /**
         This is exactly the same as ToULong() but works with 64
         bit integer numbers.
         Please see ToLongLong() for additional remarks.
     */
 
     /**
         This is exactly the same as ToULong() but works with 64
         bit integer numbers.
         Please see ToLongLong() for additional remarks.
     */

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

 
     //@{
     /**
         Same as utf8_str().
     */
     const char* ToUTF8() const;
 
     //@{
     /**
         Same as utf8_str().
     */
     const char* ToUTF8() const;

-    const wxCharBuffer ToUF8() const;
+    const wxCharBuffer ToUTF8() const;

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


@@ -977,16 +983,16 @@ public:
     //@{
     /**
         Puts the string back into a reasonable state (in which it can be used
     //@{
     /**
         Puts the string back into a reasonable state (in which it can be used

-        normally), after
-        GetWriteBuf() was called.
+        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).
         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
+
+        This method is deprecated, please use wxStringBuffer or

         wxStringBufferLength instead.
     */
     void UngetWriteBuf();
         wxStringBufferLength instead.
     */
     void UngetWriteBuf();


@@ -995,11 +1001,14 @@ public:
 
     /**
         Returns this string converted to upper case.
 
     /**
         Returns this string converted to upper case.

+
+        @see MakeUpper()

     */
     wxString Upper() const;
 
     /**
     */
     wxString Upper() const;
 
     /**

-        The same as MakeUpper.
+        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.
     */


@@ -1010,17 +1019,16 @@ public:
         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.
         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.

-        
-        Please see the @ref overview_unicode "Unicode overview" for more
-        information about it.
-        
+
+        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.
         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()
     */
         @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
     */

-    const wxCStrData c_str() const;
+    wxCStrData c_str() const;

 
     /**
         Returns an object with string data that is implicitly convertible to
 
     /**
         Returns an object with string data that is implicitly convertible to


@@ -1046,7 +1054,9 @@ public:
         buffer will contain the conversion of the string to the encoding of the
         current locale (and so can fail).
 
         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.
+        @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
         @return
             buffer containing the string contents in the specified type,
             notice that it may be @NULL if the conversion failed (e.g. Unicode


@@ -1068,8 +1078,8 @@ public:
 
     /**
         Returns the multibyte (C string) representation of the string
 
     /**
         Returns the multibyte (C string) representation of the string

-        using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer. 
-        
+        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;
         @see wc_str(), utf8_str(), c_str(), wxMBConv
     */
     const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;


@@ -1077,25 +1087,37 @@ public:
     /**
         Extraction from a stream.
     */
     /**
         Extraction from a stream.
     */

-    friend istream operator(istream& is, wxString& str);
+    friend istream operator>>(istream& is, wxString& str);

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

-        These functions work as C++ stream insertion operators: they insert the given
-        value into the string. Precision or format cannot be set using them, you can
-        use Printf() for this.
-    */
-    wxString operator(const wxString& str);
-    wxString operator(wxUniChar ch);
-    wxString operator(int i);
-    wxString operator(float f);
-    wxString operator(double d);
+        These functions work as C++ stream insertion operators. They insert the
+        given value into the string. Precision 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);

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

-        Same as Mid (substring extraction).
+        Same as Mid() (substring extraction).

     */
     */

-    wxString operator ()(size_t start, size_t len);
+    wxString operator()(size_t start, size_t len) const;

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


@@ -1117,7 +1139,7 @@ public:
     //@{
     /**
         Assignment: the effect of each operation is the same as for the corresponding
     //@{
     /**
         Assignment: the effect of each operation is the same as for the corresponding

-        constructor (see @ref construct() "wxString constructors").
+        constructor (see wxString constructors).

     */
     wxString operator =(const wxString& str);
     wxString operator =(wxUniChar c);
     */
     wxString operator =(const wxString& str);
     wxString operator =(wxUniChar c);


@@ -1145,7 +1167,7 @@ public:
         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.

-        
+

         @see wc_str(), c_str(), mb_str()
     */
     const char* utf8_str() const;
         @see wc_str(), c_str(), mb_str()
     */
     const char* utf8_str() const;


@@ -1155,14 +1177,14 @@ public:
     //@{
     /**
         Converts the strings contents to the wide character represention
     //@{
     /**
         Converts the strings contents to the wide character represention

-        and returns it as a temporary wxWCharBuffer object (Unix and OS X) 
+        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).
 
         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 uf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
+        @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()

     */
     const wchar_t* wc_str() const;
     const wxWCharBuffer wc_str() const;
     */
     const wchar_t* wc_str() const;
     const wxWCharBuffer wc_str() const;


@@ -1179,7 +1201,7 @@ public:
     */
     wxWritableWCharBuffer wchar_str() const;
 
     */
     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).
     */
        Explicit conversion to C string in the internal representation (either
        wchar_t* or UTF-8-encoded char*, depending on the build).
     */


@@ -1211,14 +1233,6 @@ public:
         STL reference for their documentation.
     */
     //@{
         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 wxString& str, size_t pos, size_t n);
         wxString& append(const wxString& str);
         wxString& append(const char *sz, size_t n);


@@ -1233,8 +1247,13 @@ public:
         wxString& assign(size_t n, wxUniChar ch);
         wxString& assign(const_iterator first, const_iterator last);
 
         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();
 
         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,
         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,


@@ -1244,6 +1263,8 @@ public:
         int compare(size_t nStart, size_t nLen,
               const wchar_t* 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);
         bool empty() const;
 
         wxString& erase(size_type pos = 0, size_type n = npos);


@@ -1254,6 +1275,28 @@ public:
         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(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 wxString& str);
         wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);


@@ -1264,49 +1307,95 @@ public:
         void insert(iterator it, const_iterator first, const_iterator last);
         void insert(iterator it, size_type n, 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,
         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);
+                          const wxString& str, size_t nStart2, size_t nLen2);

         wxString& replace(size_t nStart, size_t nLen,
         wxString& replace(size_t nStart, size_t nLen,

-                    const char* sz, size_t nCount);
+                          const char* sz, size_t nCount);

         wxString& replace(size_t nStart, size_t nLen,
         wxString& replace(size_t nStart, size_t nLen,

-                    const wchar_t* sz, size_t nCount);
+                          const wchar_t* sz, size_t nCount);

         wxString& replace(size_t nStart, size_t nLen,
         wxString& replace(size_t nStart, size_t nLen,

-                    const wxString& s, size_t nCount);
+                          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,
         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);
+                          const_iterator first1, const_iterator last1);

         wxString& replace(iterator first, iterator last,
         wxString& replace(iterator first, iterator last,

-                    const char *first1, const char *last1);
+                          const char *first1, const char *last1);

         wxString& replace(iterator first, iterator last,
         wxString& replace(iterator first, iterator last,

-                    const wchar_t *first1, const wchar_t *last1);
+                          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_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;
         wxString substr(size_t nStart = 0, size_t nLen = npos) const;

-

         void swap(wxString& str);
         void swap(wxString& str);

-

     //@}
     //@}

-

 };
 
 };
 

+/** @addtogroup group_string_operators */
+//@{
+/**
+    Comparison operators for wxString.
+*/
+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);
+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 wxCStrData& s2);
+inline bool operator==(const wxCStrData& s1, const wxString& s2);
+inline bool operator!=(const wxString& s1, const wxCStrData& s2);
+inline bool operator!=(const wxCStrData& s1, const wxString& s2);
+inline bool operator==(const wxString& s1, const wxWCharBuffer& s2);
+inline bool operator==(const wxWCharBuffer& s1, const wxString& s2);
+inline bool operator!=(const wxString& s1, const wxWCharBuffer& s2);
+inline bool operator!=(const wxWCharBuffer& 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 wxString& s1, const wxCharBuffer& s2);
+inline bool operator!=(const wxCharBuffer& s1, const wxString& s2);

 
 /**
 
 /**

-    FIXME
+    Comparison operators with wxUniChar or wxUniCharRef.

 */
 */

-wxString Objects:
-;
+inline bool operator==(const wxUniChar& c, const wxString& s);
+inline bool operator==(const wxUniCharRef& c, const wxString& s);
+inline bool operator==(char c, const wxString& s);
+inline bool operator==(wchar_t c, const wxString& s);
+inline bool operator==(int c, const wxString& s);
+inline bool operator==(const wxString& s, const wxUniChar& c);
+inline bool operator==(const wxString& s, const wxUniCharRef& c);
+inline bool operator==(const wxString& s, char c);
+inline bool operator==(const wxString& s, wchar_t c);
+inline bool operator!=(const wxUniChar& c, const wxString& s);
+inline bool operator!=(const wxUniCharRef& c, const wxString& s);
+inline bool operator!=(char c, const wxString& s);
+inline bool operator!=(wchar_t c, const wxString& s);
+inline bool operator!=(int c, const wxString& s);
+inline bool operator!=(const wxString& s, const wxUniChar& c);
+inline bool operator!=(const wxString& s, const wxUniCharRef& c);
+inline bool operator!=(const wxString& s, char c);
+inline bool operator!=(const wxString& s, wchar_t c);
+//@}

 
 /**
 
 /**

-    FIXME
+    The global wxString instance of an empty string.
+    Used extensively in the entire wxWidgets API.

 */
 wxString wxEmptyString;
 
 */
 wxString wxEmptyString;
 


@@ -1316,51 +1405,48 @@ wxString wxEmptyString;
 /**
     @class wxStringBufferLength
 
 /**
     @class wxStringBufferLength
 

-    This tiny class allows to conveniently access the wxString
-    internal buffer as a writable pointer without any risk of forgetting to restore
-    the string to the usable state later, and allows the user to set the internal
-    length of the string.
+    This tiny class allows you to conveniently access the wxString internal buffer
+    as a writable pointer without any risk of forgetting to restore the string to
+    the usable state later, and allows the user to set the internal length of the string.

 
     For example, assuming you have a low-level OS function called
 
     For example, assuming you have a low-level OS function called

-    @c int GetMeaningOfLifeAsString(char *) copying the value in the provided
+    @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided

     buffer (which must be writable, of course), and returning the actual length
     of the string, you might call it like this:
 
     @code
     buffer (which must be writable, of course), and returning the actual length
     of the string, you might call it like this:
 
     @code

-    wxString theAnswer;
+        wxString theAnswer;

         wxStringBuffer theAnswerBuffer(theAnswer, 1024);
         int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
         theAnswerBuffer.SetLength(nLength);
         if ( theAnswer != "42" )
         wxStringBuffer theAnswerBuffer(theAnswer, 1024);
         int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
         theAnswerBuffer.SetLength(nLength);
         if ( theAnswer != "42" )

-        {

             wxLogError("Something is very wrong!");
             wxLogError("Something is very wrong!");

-        }

     @endcode
 
     @endcode
 

-    Note that the exact usage of this depends on whether on 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 wxString, keeping the same
-    buffer
-    wxString uses intact.  In other words, relying on wxStringBuffer containing the
-    old
-    wxString data is probably not a good idea if you want to build your program in
-    both
-    with and without wxUSE_STL.
+    @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
+    wxString, keeping the same buffer wxString uses intact. In other words,
+    relying on wxStringBuffer containing the old wxString data is not a good
+    idea if you want to build your program both with and without wxUSE_STL.

 
 

-    Note that SetLength @c must be called before wxStringBufferLength destructs.
+    Note that wxStringBuffer::SetLength @b must be called before
+    wxStringBufferLength destructs.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{data}

 */
 class wxStringBufferLength
 {
 public:
     /**
         Constructs a writable string buffer object associated with the given string
 */
 class wxStringBufferLength
 {
 public:
     /**
         Constructs a writable string buffer object associated with the given string

-        and containing enough space for at least @a len characters. Basically, this
-        is equivalent to calling wxString::GetWriteBuf and
+        and containing enough space for at least @a len characters.
+
+        Basically, this is equivalent to calling wxString::GetWriteBuf and

         saving the result.
     */
     wxStringBufferLength(const wxString& str, size_t len);
         saving the result.
     */
     wxStringBufferLength(const wxString& str, size_t len);


@@ -1374,6 +1460,7 @@ public:
     /**
         Sets the internal length of the string referred to by wxStringBufferLength to
         @a nLength characters.
     /**
         Sets the internal length of the string referred to by wxStringBufferLength to
         @a nLength characters.

+

         Must be called before wxStringBufferLength destructs.
     */
     void SetLength(size_t nLength);
         Must be called before wxStringBufferLength destructs.
     */
     void SetLength(size_t nLength);


@@ -1385,3 +1472,55 @@ public:
     wxChar* operator wxChar *();
 };
 
     wxChar* operator wxChar *();
 };
 

+
+/**
+    @class wxStringBuffer
+
+    This tiny class allows you to conveniently access the wxString internal buffer
+    as a writable pointer without any risk of forgetting to restore the string
+    to the usable state later.
+
+    For example, assuming you have a low-level OS function called
+    @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided
+    buffer (which must be writable, of course) you might call it like this:
+
+    @code
+        wxString theAnswer;
+        GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
+        if ( theAnswer != "42" )
+            wxLogError("Something is very wrong!");
+    @endcode
+
+    Note that the exact usage of this depends on whether or not @c wxUSE_STL is
+    enabled. If @c wxUSE_STL is enabled, wxStringBuffer creates a separate empty
+    character buffer, and if @c wxUSE_STL is disabled, it uses GetWriteBuf() from
+    wxString, keeping the same buffer wxString uses intact. In other words,
+    relying on wxStringBuffer containing the old wxString data is not a good
+    idea if you want to build your program both with and without @c wxUSE_STL.
+
+    @library{wxbase}
+    @category{data}
+*/
+class wxStringBuffer
+{
+public:
+    /**
+        Constructs a writable string buffer object associated with the given string
+        and containing enough space for at least @a len characters.
+        Basically, this is equivalent to calling wxString::GetWriteBuf() and
+        saving the result.
+    */
+    wxStringBuffer(const wxString& str, size_t len);
+
+    /**
+        Restores the string passed to the constructor to the usable state by calling
+        wxString::UngetWriteBuf() on it.
+    */
+    ~wxStringBuffer();
+
+    /**
+        Returns the writable pointer to a buffer of the size at least equal to the
+        length specified in the constructor.
+    */
+    wxStringCharType* operator wxStringCharType *();
+};