handle error in GetDataSize()

[wxWidgets.git] / interface / wx / strconv.h

diff --git a/interface/wx/strconv.h b/interface/wx/strconv.h
index 4bb86830427a8bb6d2438b2b20d28751cc04b919..eb4bafedb3ed2f8a91f2a1dfbe634a047f1cf736 100644 (file)
--- a/interface/wx/strconv.h
+++ b/interface/wx/strconv.h
@@ -30,7 +30,7 @@
     @library{wxbase}
     @category{conv}
 
-    @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxCSConv, wxEncodingConverter, @ref overview_mbconv
 */
 class wxMBConv
 {
@@ -56,7 +56,7 @@ public:
         The other cases are not currently supported and @c wxCONV_FAILED
         (defined as -1) is returned for them.
     */
-    size_t GetMBNulLen() const;
+    virtual size_t GetMBNulLen() const;
 
     /**
         Returns the maximal value which can be returned by GetMBNulLen() for
@@ -113,13 +113,14 @@ public:
             Pointer to output buffer of the size of at least @a dstLen or @NULL.
         @param dstLen
             Maximal number of characters to be written to the output buffer if
-            @dst is non-@NULL, unused otherwise.
+            @a dst is non-@NULL, unused otherwise.
         @param src
             Point to the source string, must not be @NULL.
-        @param
-            The number of characters of the source string to convert or @c
-            wxNO_LEN (default parameter) to convert everything up to and
+        @param srcLen
+            The number of characters of the source string to convert or
+            @c wxNO_LEN (default parameter) to convert everything up to and
             including the terminating @c NUL character(s).
+
         @return
             The number of character written (or which would have been written
             if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
@@ -140,13 +141,14 @@ public:
             Pointer to output buffer of the size of at least @a dstLen or @NULL.
         @param dstLen
             Maximal number of characters to be written to the output buffer if
-            @dst is non-@NULL, unused otherwise.
+            @a dst is non-@NULL, unused otherwise.
         @param src
             Point to the source string, must not be @NULL.
-        @param
-            The number of characters of the source string to convert or @c
-            wxNO_LEN (default parameter) to convert everything up to and
+        @param srcLen
+            The number of characters of the source string to convert or
+            @c wxNO_LEN (default parameter) to convert everything up to and
             including the terminating @c NUL character.
+
         @return
             The number of character written (or which would have been written
             if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
@@ -253,6 +255,20 @@ public:
         out buffer, the @a outLen parameter should be one more to allow to
         properly @c NUL-terminate the string.
 
+        So to properly use this function you need to write:
+        @code
+            size_t lenConv = conv.MB2WC(NULL, in, 0);
+            if ( lenConv == wxCONV_FAILED )
+                ... handle error ...
+            // allocate 1 more character for the trailing NUL and also pass
+            // the size of the buffer to the function now
+            wchar_t *out = new wchar_t[lenConv + 1];
+            if ( conv.MB2WC(out, in, lenConv + 1) == wxCONV_FAILED )
+                ... handle error ...
+        @endcode
+        For this and other reasons, ToWChar() is strongly recommended as a
+        replacement.
+
         @param out
             The output buffer, may be @NULL if the caller is only
             interested in the length of the resulting string
@@ -275,7 +291,7 @@ public:
         called with a non-@NULL buffer, the @a n parameter should be the size
         of the buffer and so it should take into account the trailing @c NUL,
         which might take two or four bytes for some encodings (UTF-16 and
-        UTF-32) and not one.
+        UTF-32) and not one, i.e. GetMBNulLen().
     */
     virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const;
 };
@@ -301,7 +317,7 @@ public:
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, @ref overview_mbconv
 */
 class wxMBConvUTF7 : public wxMBConv
 {
@@ -318,7 +334,7 @@ class wxMBConvUTF7 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF7, @ref overview_mbconv
 */
 class wxMBConvUTF8 : public wxMBConv
 {
@@ -341,7 +357,7 @@ class wxMBConvUTF8 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
 */
 class wxMBConvUTF16 : public wxMBConv
 {
@@ -362,7 +378,7 @@ class wxMBConvUTF16 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv
 */
 class wxMBConvUTF32 : public wxMBConv
 {
@@ -389,7 +405,7 @@ class wxMBConvUTF32 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
-    @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
 */
 class wxCSConv : public wxMBConv
 {
@@ -466,7 +482,7 @@ public:
     @library{wxbase}
     @category{conv}
 
-    @see @ref overview_mbconv "wxMBConv classes overview"
+    @see @ref overview_mbconv
 */
 class wxMBConvFile : public wxMBConv
 {