backported wxString::From/ToUTF8 to 2.8 for forward compatibility with wx3

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_8_BRANCH@45861 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/changes.txt

@@ -97,8 +97,9 @@ All:
 - Fix wxStringOutputStream::Write() in Unicode build when the argument
   overlaps UTF-8 characters boundary
 - Account for lines without newline at the end in wxExecute()
-- Added wxString::char_str(), wchar_str(), From8BitData() and To8BitData()
-  methods for forward compatiblity with wxWidgets 3
+- Added wxString::char_str(), wchar_str(), From8BitData(), To8BitData(),
+  FromUTF8(), ToUTF8() and utf8_str() methods for forward compatiblity
+  with wxWidgets 3
 
 All (Unix):
 

docs/latex/wx/wxstring.tex

@@ -781,6 +781,19 @@ Use \helpref{wxString constructors}{wxstringconstruct} if you
 need to convert from another charset.
 
 
+\membersection{wxString::FromUTF8}\label{wxstringfromutf8}
+
+\func{static wxString }{FromUTF8}{\param{const char*}{ s}}
+
+\func{static wxString }{FromUTF8}{\param{const char*}{ s}, \param{size\_t}{ len}}
+
+Converts C string encoded in UTF-8 to wxString.
+
+Note that this method assumes that \arg{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.
+
+
 \membersection{wxString::GetChar}\label{wxstringgetchar}
 
 \constfunc{wxChar}{GetChar}{\param{size\_t}{ n}}
@@ -1164,12 +1177,10 @@ This is a convenience method useful when storing binary data in wxString.
 
 \constfunc{const char*}{ToAscii}{\void}
 
-Converts the string to an ASCII, 7-bit string (ANSI builds only).
-
 \constfunc{const wxCharBuffer}{ToAscii}{\void}
 
 Converts the string to an ASCII, 7-bit string in the form of
-a wxCharBuffer (Unicode builds only).
+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 \helpref{mb\_str}{wxstringmbstr} method provides more
@@ -1261,6 +1272,15 @@ bit integer numbers.
 Please see \helpref{ToLongLong}{wxstringtolonglong} for additional remarks.
 
 
+\membersection{wxString::ToUTF8}\label{wxstringtoutf8}
+
+\constfunc{const wxCharBuffer}{ToUF8}{\void}
+
+Same as \helpref{utf8\_str}{wxstringutf8str}.
+
+\newsince{2.8.4}
+
+
 \membersection{wxString::Trim}\label{wxstringtrim}
 
 \func{wxString\&}{Trim}{\param{bool}{ fromRight = true}}
@@ -1310,6 +1330,16 @@ The same as MakeUpper.
 This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
 
 
+\membersection{wxString::utf8\_str}\label{wxstringutf8str}
+
+\constfunc{const wxCharBuffer}{utf8\_str}{\void}
+
+Converts the strings contents to UTF-8 and returns it as a temporary
+wxCharBuffer object.
+
+\newsince{2.8.4}
+
+
 \membersection{wxString::wc\_str}\label{wxstringwcstr}
 
 \constfunc{const wchar\_t*}{wc\_str}{\param{wxMBConv\&}{ conv}}

include/wx/string.h

@@ -863,6 +863,30 @@ public:
     const char *ToAscii() const { return c_str(); }
 #endif // Unicode/!Unicode
 
+#if wxABI_VERSION >= 20804
+    // conversion to/from UTF-8:
+#if wxUSE_UNICODE
+    static wxString FromUTF8(const char *utf8)
+      { return wxString(utf8, wxConvUTF8); }
+    static wxString FromUTF8(const char *utf8, size_t len)
+      { return wxString(utf8, wxConvUTF8, len); }
+    const wxCharBuffer utf8_str() const { return mb_str(wxConvUTF8); }
+    const wxCharBuffer ToUTF8() const { return utf8_str(); }
+#elif wxUSE_WCHAR_T // ANSI
+    static wxString FromUTF8(const char *utf8)
+      { return wxString(wxConvUTF8.cMB2WC(utf8)); }
+    static wxString FromUTF8(const char *utf8, size_t len)
+    {
+      size_t wlen;
+      wxWCharBuffer buf(wxConvUTF8.cMB2WC(utf8, len == npos ? wxNO_LEN : len, &wlen));
+      return wxString(buf.data(), wxConvLibc, wlen);
+    }
+    const wxCharBuffer utf8_str() const
+      { return wxConvUTF8.cWC2MB(wc_str(wxConvLibc)); }
+    const wxCharBuffer ToUTF8() const { return utf8_str(); }
+#endif // Unicode/ANSI
+#endif // wxABI_VERSION >= 20804
+
 #if wxABI_VERSION >= 20804
     // functions for storing binary data in wxString:
 #if wxUSE_UNICODE