#708: Improved documentation and guarantee in case of failure.

src/convert.cpp

@@ -71,8 +71,8 @@ EXIV2_RCSID("@(#) $Id$")
 // local declarations
 namespace {
 #if defined WIN32 && !defined __CYGWIN__
-    // Convert string charset with Windows MSVC functions.
-    bool convertStringCharsetMsvc(std::string& str, const char* from, const char* to);
+    // Convert string charset with Windows functions.
+    bool convertStringCharsetWindows(std::string& str, const char* from, const char* to);
 #endif
 #if defined EXV_HAVE_ICONV
     // Convert string charset with iconv.
@@ -1335,7 +1335,7 @@ namespace Exiv2 {
 #if defined EXV_HAVE_ICONV
         ret = convertStringCharsetIconv(str, from, to);
 #elif defined WIN32 && !defined __CYGWIN__
-        ret = convertStringCharsetMsvc(str, from, to);
+        ret = convertStringCharsetWindows(str, from, to);
 #else
 # ifndef SUPPRESS_WARNINGS
         EXV_WARNING << "Charset conversion required but no character mapping functionality available.\n";
@@ -1490,16 +1490,18 @@ namespace {
         // Update the convertStringCharset() documentation if you add more here!
     };
 
-    bool convertStringCharsetMsvc(std::string& str, const char* from, const char* to)
+    bool convertStringCharsetWindows(std::string& str, const char* from, const char* to)
     {
         bool ret = false;
         const ConvFctList* p = find(convFctList, std::make_pair(from, to));
-        if (p) ret = p->convFct_(str);
+        std::string tmpstr = str;
+        if (p) ret = p->convFct_(tmpstr);
 #ifndef SUPPRESS_WARNINGS
         else {
             EXV_WARNING << "No Windows function to map character string from " << from << " to " << to << " available.\n";
         }
 #endif
+        if (ret) str = tmpstr;
         return ret;
     }
 

src/convert.hpp

@@ -81,29 +81,32 @@ namespace Exiv2 {
 
     /*!
       @brief Convert character encoding of \em str from \em from to \em to.
-             The string is modified and its size may change.
-
-      This function uses the iconv library, if Exiv2 was compiled with iconv
-      support.  Otherwise, on Windows, it uses MSVC functions to support a
-      limited number of conversions and issues a warning if an unsupported
-      conversion is attempted. The conversions supported on Windows without
-      iconv are:
-
-      from: UTF-8 to: UCS-2BE<br>
-      from: UTF-8 to: UCS-2LE<br>
-      from: UCS-2BE to: UTF-8<br>
-      from: UCS-2BE to: UCS-2LE<br>
-      from: UCS-2LE to: UTF-8<br>
-      from: UCS-2LE to: UCS-2BE<br>
-      from: ISO-8859-1 to: UTF-8<br>
-      from: ASCII to: UTF-8<br>
-
-      If the function is called but Exiv2 was not compiled with iconv support
-      and can't use Windows MSVC functions, it issues a warning.
+             If the function succeeds, \em str contains the result string.
+
+      This function uses the iconv library, if the %Exiv2 library was compiled
+      with iconv support.  Otherwise, on Windows, it uses Windows functions to
+      support a limited number of conversions and fails with a warning if an
+      unsupported conversion is attempted.  If the function is called but %Exiv2
+      was not compiled with iconv support and can't use Windows functions, it
+      fails with a warning.
+
+      The conversions supported on Windows without iconv are:
+
+      <TABLE>
+      <TR><TD class="indexkey"><B>from</B></TD><TD class="indexkey">to</TD></TR>
+      <TR><TD class="indexvalue">UTF-8</TD>     <TD class="indexvalue">UCS-2BE</TD></TR>
+      <TR><TD class="indexvalue">UTF-8</TD>     <TD class="indexvalue">UCS-2LE</TD></TR>
+      <TR><TD class="indexvalue">UCS-2BE</TD>   <TD class="indexvalue">UTF-8</TD></TR>
+      <TR><TD class="indexvalue">UCS-2BE</TD>   <TD class="indexvalue">UCS-2LE</TD></TR>
+      <TR><TD class="indexvalue">UCS-2LE</TD>   <TD class="indexvalue">UTF-8</TD></TR>
+      <TR><TD class="indexvalue">UCS-2LE</TD>   <TD class="indexvalue">UCS-2BE</TD></TR>
+      <TR><TD class="indexvalue">ISO-8859-1</TD><TD class="indexvalue">UTF-8</TD></TR>
+      <TR><TD class="indexvalue">ASCII</TD>     <TD class="indexvalue">UTF-8</TD></TR>
+      </TABLE>
 
       @param str  The string to convert. It is updated to the converted string,
                   which may have a different size. If the function call fails,
-                  the string may have been modified.
+                  the string is not modified.
       @param from Charset in which the input string is encoded as a name
                   understood by \c iconv_open(3).
       @param to   Charset to convert the string to as a name