mention the problem with writing enums to wxConfig (see #8656)

[wxWidgets.git] / interface / string.h

diff --git a/interface/string.h b/interface/string.h
index 21e0e70d495ff0b3c29a9a5f73d6bc3b6ae9982d..97dfe25336d00629ac11bd5cb8b1ff0b9ad8ccdb 100644 (file)
--- a/interface/string.h
+++ b/interface/string.h
@@ -72,35 +72,61 @@ public:
     @class wxString
     @wxheader{string.h}
 
     @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
     
     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:
+    
+    @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.

 
 

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

 
 

-    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 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.
         
 
         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 @ref operatorout() "operator "
+        @li operator<<()

         @li operator+=()
         @li operator+()
         @li Append()
         @li operator+=()
         @li operator+()
         @li Append()


@@ -124,7 +150,6 @@ public:
         @li MakeLower()
         @li Lower()
 
         @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
         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


@@ -284,58 +309,58 @@ public:
     
 
     /**
     
 
     /**

-       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);
 
     /**
     */
     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);
 
     /**
     */
     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);
 
     /**
     */
     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);
 
     /**
     */
     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);
 
     /**
     */
     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);
 
     /**
     */
     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);
     
     /**
        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);
 
     /**
     */
     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);
     
     /**
     */
     wxString(const std::string& str);
     
     /**

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

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


@@ -348,13 +373,13 @@ public:
 
     /**
         Gets all the characters after the first occurrence of @e ch.
 
     /**
         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(wxUniChar ch) const;
 
     /**
         Gets all the characters after the last occurrence of @e ch.
     */
     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(wxUniChar ch) const;
 
     */
     wxString AfterLast(wxUniChar ch) const;
 


@@ -397,15 +422,35 @@ public:
     */
     bool Alloc(size_t nLen);
 
     */
     bool Alloc(size_t nLen);
 

-    //@{

     /**
     /**

-       Appends the string or string literal or character.
+       Appends the string literal @e psz.
+    */
+    wxString& Append(const char* psz);
+
+    /**
+       Appends the wide string literal @e pwz.
+    */
+    wxString& Append(const wchar_t* pwz)
+
+    /**
+       Appends the string literal @e psz with max length @e nLen.

     */
     wxString& Append(const char* psz, size_t nLen);
     */
     wxString& Append(const char* psz, size_t 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.
+    */

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

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

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

-    //@}

 
     /**
         Gets all characters before the first occurrence of @e ch.
 
     /**
         Gets all characters before the first occurrence of @e ch.


@@ -444,7 +489,7 @@ public:
         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
         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).
+        argument (same semantics as the standard @c strcmp() function).

         
         See also CmpNoCase(), IsSameAs().
     */
         
         See also CmpNoCase(), IsSameAs().
     */


@@ -454,7 +499,7 @@ public:
         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
         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).
+        argument (same semantics as the standard @c strcmp() function).

         
         See also Cmp(), IsSameAs().
     */
         
         See also Cmp(), IsSameAs().
     */


@@ -497,20 +542,23 @@ 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
     /**
         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.
     */
         @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
+        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;
         @c wxNOT_FOUND if not found.
     */
     int Find(wxUniChar ch, bool fromEnd = false) 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;
     int Find(const wxString& sub) const;

-    //@}

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


@@ -539,9 +587,9 @@ public:
     static wxString FormatV(const wxChar format, va_list argptr);
 
     /**
     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(wxUniChar ch) const;
 
     */
     int Freq(wxUniChar ch) const;
 


@@ -549,7 +597,7 @@ public:
     /**
         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
     /**
         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
+        encoding. The version without @e len parameter takes NUL-terminated

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


@@ -798,7 +846,7 @@ public:
         @NULL. Otherwise, the function returns @false and doesn't modify the
         @e rest.
     */
         @NULL. Otherwise, the function returns @false and doesn't modify the
         @e rest.
     */

-    bool StartsWith(const wxString& prefix, wxString rest = NULL) const;
+    bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;

 
     /**
         Strip characters at the front and/or end. The same as Trim except that it
 
     /**
         Strip characters at the front and/or end. The same as Trim except that it


@@ -830,7 +878,7 @@ public:
         @see wxString::From8BitData()
     */
     const char* To8BitData() const;
         @see wxString::From8BitData()
     */
     const char* To8BitData() const;

-    const const wxCharBuffer To8BitData() const;
+    const wxCharBuffer To8BitData() const;

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


@@ -842,7 +890,7 @@ public:
         powerful means of converting wxString to C string.
     */
     const char* ToAscii() const;
         powerful means of converting wxString to C string.
     */
     const char* ToAscii() const;

-    const const wxCharBuffer ToAscii() const;
+    const wxCharBuffer ToAscii() const;

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


@@ -912,7 +960,7 @@ public:
         Same as utf8_str().
     */
     const char* ToUTF8() const;
         Same as utf8_str().
     */
     const char* ToUTF8() const;

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

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


@@ -999,7 +1047,7 @@ public:
         @see wxMBConv, c_str(), wc_str(), fn_str(), char_str()
     */
     const char* mb_str(const wxMBConv& conv = wxConvLibc) const;
         @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;

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