clarified the parameters of MB2WC and WC2MB a little in the docs/headers

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

diff --git a/docs/latex/wx/mbconv.tex b/docs/latex/wx/mbconv.tex
index 8ff0e5280989212eaa1e11607eed63f1623969ab..3d5e4a07b4210a5aba9600dd4ffa14583df39171 100644 (file)
--- a/docs/latex/wx/mbconv.tex
+++ b/docs/latex/wx/mbconv.tex
@@ -35,29 +35,30 @@ Constructor.
 
 \membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}
 
-\constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t* }{buf}, \param{const char* }{psz}, \param{size\_t }{n}}
+\constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t *}{outputBuf}, \param{const char *}{psz}, \param{size\_t }{outputSize}}
 
 Converts from a string {\it psz} in multibyte encoding to Unicode putting the
-output into the buffer {\it buf} of the size {\it n} (in wide characters, not
-bytes). If {\it buf} is {\tt NULL}, nothing is written to it but the length of
-the string which would result from the conversion is calculated and returned.
+output into the buffer {\it outputBuf} of the maximum size {\it outputSize} (in wide
+characters, not bytes). If {\it outputBuf} is {\tt NULL}, only the length of the
+string which would result from the conversion is calculated and returned.
 Note that this is the length and not size, i.e. the returned value does 
 {\bf not} include the trailing NUL. But when the function is called with a
-non-{\tt NULL} buffer, the {\it n} parameter should be the size of the buffer
+non-{\tt NULL} {\it outputBuf}, the {\it outputSize} parameter should be the size of the buffer
 and so it {\bf should} take into account the trailing NUL.
 
 \wxheading{Parameters}
 
-\docparam{buf}{the output buffer, may be {\tt NULL} if the caller is only
+\docparam{outputBuf}{the output buffer, may be {\tt NULL} if the caller is only
 interested in the length of the resulting string}
 
 \docparam{psz}{the {\tt NUL}-terminated input string, cannot be {\tt NULL}}
 
-\docparam{n}{the size of the output buffer, ignored if {\it buf} is {\tt NULL}}
+\docparam{outputSize}{the size of the output buffer (in wide characters, {\bf including} the
+NUL) , ignored if {\it outputBuf} is {\tt NULL}}
 
 \wxheading{Return value}
 
-The length of the converted string.
+The length of the converted string (in wide characters, {\bf excluding} the NUL)
 
 \membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}
 

diff --git a/include/wx/strconv.h b/include/wx/strconv.h
index 9248f2cb7e9732214942952047b898296ea22360..59aefd6a5c3de1d9b489a2967776c36a358b7b41 100644 (file)
--- a/include/wx/strconv.h
+++ b/include/wx/strconv.h
@@ -42,9 +42,9 @@ public:
     // the actual conversion takes place here
     //
     // note that n is the size of the output buffer, not the length of input
-    // (which is always supposed to be NUL-terminated)
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const = 0;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const = 0;
+    // (the latter is always supposed to be NUL-terminated)
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const = 0;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const = 0;
 
     // MB <-> WC
     const wxWCharBuffer cMB2WC(const char *psz) const;
@@ -75,8 +75,8 @@ public:
 class WXDLLIMPEXP_BASE wxMBConvLibc : public wxMBConv
 {
 public:
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 };
 
 // not very accurately named because it is not necessarily of type wxMBConvLibc
@@ -91,8 +91,8 @@ WXDLLIMPEXP_DATA_BASE(extern wxMBConv&) wxConvLibc;
 class WXDLLIMPEXP_BASE wxMBConvUTF7 : public wxMBConv
 {
 public:
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 };
 
 WXDLLIMPEXP_DATA_BASE(extern wxMBConvUTF7&) wxConvUTF7;
@@ -104,8 +104,8 @@ WXDLLIMPEXP_DATA_BASE(extern wxMBConvUTF7&) wxConvUTF7;
 class WXDLLIMPEXP_BASE wxMBConvUTF8 : public wxMBConv
 {
 public:
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 };
 
 WXDLLIMPEXP_DATA_BASE(extern wxMBConvUTF8&) wxConvUTF8;
@@ -117,8 +117,8 @@ WXDLLIMPEXP_DATA_BASE(extern wxMBConvUTF8&) wxConvUTF8;
 class WXDLLIMPEXP_BASE wxMBConvUTF16LE : public wxMBConv
 {
 public:
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 };
 
 // ----------------------------------------------------------------------------
@@ -128,8 +128,8 @@ public:
 class WXDLLIMPEXP_BASE wxMBConvUTF16BE : public wxMBConv
 {
 public:
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 };
 
 // ----------------------------------------------------------------------------
@@ -139,8 +139,8 @@ public:
 class WXDLLIMPEXP_BASE wxMBConvUTF32LE : public wxMBConv
 {
 public:
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 };
 
 // ----------------------------------------------------------------------------
@@ -150,8 +150,8 @@ public:
 class WXDLLIMPEXP_BASE wxMBConvUTF32BE : public wxMBConv
 {
 public:
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 };
 
 // ----------------------------------------------------------------------------
@@ -173,8 +173,8 @@ public:
 
     wxCSConv& operator=(const wxCSConv& conv);
 
-    virtual size_t MB2WC(wchar_t *buf, const char *psz, size_t n) const;
-    virtual size_t WC2MB(char *buf, const wchar_t *psz, size_t n) const;
+    virtual size_t MB2WC(wchar_t *outputBuf, const char *psz, size_t outputSize) const;
+    virtual size_t WC2MB(char *outputBuf, const wchar_t *psz, size_t outputSize) const;
 
     void Clear() ;