mention the ambiguities which arise when passing wxString[.c_str()] to functions...

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

diff --git a/docs/changes.txt b/docs/changes.txt
index 38d7898aa8c4c2db668e48dc5e79d7a15c64ec65..236303ae5ea097f080316f3e342d0a814ad8920e 100644 (file)
--- a/docs/changes.txt
+++ b/docs/changes.txt
@@ -122,14 +122,26 @@ Changes in behaviour which may result in compilation errors
   and has to be replaced with this:
      switch (str[i].GetValue()) { ... }
 
   and has to be replaced with this:
      switch (str[i].GetValue()) { ... }
 

-- Return type of wxString::c_str() is now wxCStrData struct and not
-  const wxChar*. wxCStrData is implicitly convertible to const char* and
-  const wchar_t*, so this only presents a problem if the compiler cannot
-  convert the type. In particular, Borland C++ and DigitalMars compilers
-  don't correctly convert operator?: operands to the same type and fail with
-  compilation error instead. This can be worked around by explicitly casting
-  to const wxChar*:
-     wxLogError(_("error: %s"), !err.empty() ? (const wxChar*)err.c_str() : "")
+- Return type of wxString::c_str() is now a helper wxCStrData struct and not
+  const wxChar*. wxCStrData is implicitly convertible to both "const char *"
+  and "const wchar_t *", so this only presents a problem if the compiler cannot
+  apply the conversion. This can happen in 2 cases:
+  
+  + There is an ambiguity because the function being called is overloaded to
+    take both "const char *" and "const wchar_t *" as the compiler can't choose
+    between them. In this case you may use s.wx_str() to call the function
+    matching the current build (Unicode or not) or s.mb_str() or s.wc_str() to
+    explicitly select narrow or wide version of it.
+
+    Notice that such functions are normally not very common but unfortunately
+    Microsoft decided to extend their STL with standard-incompatible overloads
+    of some functions accepting "const wchar_t *" so you may need to replace
+    some occurrences of c_str() with wx_str() when using MSVC 8 or later.
+
+  + Some compilers, notably Borland C++ and DigitalMars, don't correctly
+    convert operator?: operands to the same type and fail with compilation
+    error instead. This can be worked around by explicitly casting to const
+    wxChar*: wxLogError(_("error: %s"), !err.empty() ? (const wxChar*)err.c_str() : "")

 
 - wxCtime() and wxAsctime() return char*; this is incompatible with Unicode
   build in wxWidgets 2.8 that returned wchar_t*.
 
 - wxCtime() and wxAsctime() return char*; this is incompatible with Unicode
   build in wxWidgets 2.8 that returned wchar_t*.


@@ -143,7 +155,7 @@ Changes in behaviour which may result in compilation errors
 
 - Virtual wxHtmlParser::AddText() takes wxString, not wxChar*, argument now.
 
 
 - Virtual wxHtmlParser::AddText() takes wxString, not wxChar*, argument now.
 

-- Functions that took wxChar* arguments that could by NULL in wxWidgets 2.8.
+- Functions that took wxChar* arguments that could by NULL in wxWidgets 2.8

   are deprecated and passing NULL to them won't compile anymore, wxEmptyString
   must be used instead.
 
   are deprecated and passing NULL to them won't compile anymore, wxEmptyString
   must be used instead.
 

diff --git a/docs/doxygen/overviews/changes_since28.h b/docs/doxygen/overviews/changes_since28.h
index 0f7846ccdb7b50c77025fa3f490b6f2d5d5f448f..73ea3787f113eff97b3701c3be2d0f79fb2f59ac 100644 (file)
--- a/docs/doxygen/overviews/changes_since28.h
+++ b/docs/doxygen/overviews/changes_since28.h
@@ -46,6 +46,22 @@ passing it to @c printf() will now result in a crash. It is strongly advised to
 recompile your code with a compiler warning about passing non-POD objects to
 vararg functions, such as g++.
 
 recompile your code with a compiler warning about passing non-POD objects to
 vararg functions, such as g++.
 

+The change of the type of wxString::c_str() can also result in compilation
+errors when passing its result to a function overloaded to take both narrow and
+wide strings and in this case you must select the version which you really want
+to use, e.g.:
+@code
+    void OpenLogFile(const char *filename);
+    void OpenLogFile(const wchar_t *filename);
+
+    wxString s;
+    OpenLogFile(s);             // ERROR: ambiguity
+    OpenLogFile(s.c_str());     // ERROR: ambiguity
+    OpenLogFile(s.wx_str());    // OK: function called depends on the build
+    OpenLogFile(s.mb_str());    // OK: always calls narrow string overload
+    OpenLogFile(s.wc_str());    // OK: always calls wide string overload
+@endcode
+

 The other class of incompatible changes is due to modifying some virtual
 methods to use @c wxString parameters instead of @c const @c wxChar* ones to
 make them accept both narrow and wide strings. This is not a problem if you
 The other class of incompatible changes is due to modifying some virtual
 methods to use @c wxString parameters instead of @c const @c wxChar* ones to
 make them accept both narrow and wide strings. This is not a problem if you