mention the ambiguities which arise when passing wxString[.c_str()] to functions overloaded to take both char* and wchar_t* (see #9507)

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

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()) { ... }
 
-- Return type of wxString::c_str() is now wxCStrData struct and not
+- Return type of wxString::c_str() is now a helper wxCStrData struct and not
-  const wxChar*. wxCStrData is implicitly convertible to const char* and
+  const wxChar*. wxCStrData is implicitly convertible to both "const char *"
-  const wchar_t*, so this only presents a problem if the compiler cannot
+  and "const wchar_t *", so this only presents a problem if the compiler cannot
-  convert the type. In particular, Borland C++ and DigitalMars compilers
+  apply the conversion. This can happen in 2 cases:
-  don't correctly convert operator?: operands to the same type and fail with
+  
-  compilation error instead. This can be worked around by explicitly casting
+  + There is an ambiguity because the function being called is overloaded to
-  to const wxChar*:
+    take both "const char *" and "const wchar_t *" as the compiler can't choose
-     wxLogError(_("error: %s"), !err.empty() ? (const wxChar*)err.c_str() : "")
+    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*.
@@ -143,7 +155,7 @@ Changes in behaviour which may result in compilation errors
 
 - 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.
 

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