reorder the classes, putting first the basic ones and towards the end of the file...

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

diff --git a/interface/wx/strconv.h b/interface/wx/strconv.h
index a234e7e06d310f224468915dabfe442d106ff263..22e9de28508c7253641fc525945db9e088cb7864 100644 (file)
--- a/interface/wx/strconv.h
+++ b/interface/wx/strconv.h
@@ -67,7 +67,7 @@ public:
         This method can be used to allocate the buffer with enough space for the
         trailing @c NUL characters for any encoding.
     */
-    const size_t GetMaxMBNulLen();
+    static size_t GetMaxMBNulLen();
 
     /**
         Convert multibyte string to a wide character one.
@@ -125,8 +125,7 @@ public:
             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.
     */
-    virtual size_t ToWChar(wchar_t* dst, size_t dstLen,
-                           const char* src,
+    virtual size_t ToWChar(wchar_t* dst, size_t dstLen, const char* src,
                            size_t srcLen = wxNO_LEN) const;
 
     /**
@@ -153,8 +152,7 @@ public:
             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.
     */
-    virtual size_t FromWChar(char* dst, size_t dstLen,
-                             const wchar_t* src,
+    virtual size_t FromWChar(char* dst, size_t dstLen, const wchar_t* src,
                              size_t srcLen = wxNO_LEN) const;
 
     /**
@@ -176,8 +174,8 @@ public:
         compatibility concerns).
     */
     const wxWCharBuffer cMB2WC(const char* in,
-                               size_t inLen = wxNO_LEN,
-                               size_t *outLen = NULL) const;
+                               size_t inLen,
+                               size_t *outLen) const;
 
     //@{
     /**
@@ -203,8 +201,8 @@ public:
         FromWChar(), please see the description of cMB2WC() for more details.
     */
     const wxCharBuffer cWC2MB(const wchar_t* in,
-                              size_t inLen = wxNO_LEN,
-                              size_t *outLen = NULL) const;
+                              size_t inLen,
+                              size_t *outLen) const;
 
     //@{
     /**
@@ -255,6 +253,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
@@ -277,7 +289,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;
 };