fixing wrong version commit

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

diff --git a/interface/wx/strconv.h b/interface/wx/strconv.h
index 1843a27e1364c4d4a67f03cb25620457091c7206..2f1f55eda869a1ebef5b11153845e4ec9cc50bb1 100644 (file)
--- a/interface/wx/strconv.h
+++ b/interface/wx/strconv.h
@@ -8,7 +8,6 @@
 
 /**
     @class wxMBConv
 
 /**
     @class wxMBConv

-    @wxheader{strconv.h}

 
     This class is the base class of a hierarchy of classes capable of
     converting text strings between multibyte (SBCS or DBCS) encodings and
 
     This class is the base class of a hierarchy of classes capable of
     converting text strings between multibyte (SBCS or DBCS) encodings and


@@ -31,7 +30,7 @@
     @library{wxbase}
     @category{conv}
 
     @library{wxbase}
     @category{conv}
 

-    @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxCSConv, wxEncodingConverter, @ref overview_mbconv

 */
 class wxMBConv
 {
 */
 class wxMBConv
 {


@@ -57,7 +56,7 @@ public:
         The other cases are not currently supported and @c wxCONV_FAILED
         (defined as -1) is returned for them.
     */
         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
 
     /**
         Returns the maximal value which can be returned by GetMBNulLen() for


@@ -68,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.
     */
         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.
 
     /**
         Convert multibyte string to a wide character one.


@@ -114,19 +113,19 @@ 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
             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 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).
             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.
     */
         @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.
     */

-    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;
 
     /**
                            size_t srcLen = wxNO_LEN) const;
 
     /**


@@ -141,41 +140,59 @@ 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
             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 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.
             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.
     */
         @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.
     */

-    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;
 
                              size_t srcLen = wxNO_LEN) const;
 

-    //@{

     /**
     /**

-        Converts from multibyte encoding to Unicode by calling MB2WC() and
+        Converts from multibyte encoding to Unicode by calling ToWChar() and

         allocating a temporary wxWCharBuffer to hold the result.
 
         allocating a temporary wxWCharBuffer to hold the result.
 

-        The first overload takes a @c NUL-terminated input string. The second
-        one takes a string of exactly the specified length and the string may
-        include or not the trailing @c NUL character(s). If the string is not
-        @c NUL-terminated, a temporary @c NUL-terminated copy of it suitable
-        for passing to wxMBConv::MB2WC is made, so it is more efficient to
-        ensure that the string is does have the appropriate number of @c NUL
-        bytes (which is usually 1 but may be 2 or 4 for UTF-16 or UTF-32, see
-        wxMBConv::GetMBNulLen), especially for long strings.
-
-        If @a outLen is not-@NULL, it receives the length of the converted
-        string.
+        This function is a convenient wrapper around ToWChar() as it takes care
+        of allocating the buffer of the necessary size itself. Its parameters
+        have the same meaning as for ToWChar(), in particular @a inLen can be
+        specified explicitly in which case exactly that many characters are
+        converted and @a outLen receives (if non-@NULL) exactly the
+        corresponding number of wide characters, whether the last one of them
+        is @c NUL or not. However if @c inLen is @c wxNO_LEN, then @c outLen
+        doesn't count the trailing @c NUL even if it is always present in this
+        case.
+
+        Finally notice that if the conversion fails, the returned buffer is
+        invalid and @a outLen is set to 0 (and not @c wxCONV_FAILED for
+        compatibility concerns).

     */
     */

-    const wxWCharBuffer cMB2WC(const char* in) const;
-    const wxWCharBuffer cMB2WC(const char* in, size_t inLen, size_t *outLen) const;
-    //@}
+    const wxWCharBuffer cMB2WC(const char* in,
+                               size_t inLen,
+                               size_t *outLen) const;
+
+    /**
+        Converts a char buffer to wide char one.
+
+        This is the most convenient and safest conversion function as you
+        don't have to deal with the buffer lengths directly. Use it if the
+        input buffer is known not to be empty or if you are sure that the
+        conversion is going to succeed -- otherwise, use the overload above to
+        be able to distinguish between empty input and conversion failure.
+
+        @return
+            The buffer containing the converted text, empty if the input was
+            empty or if the conversion failed.
+
+        @since 2.9.1
+     */
+    const wxWCharBuffer cMB2WC(const wxCharBuffer& buf) const;

 
     //@{
     /**
 
     //@{
     /**


@@ -190,22 +207,36 @@ public:
     const wxWCharBuffer cMB2WX(const char* psz) const;
     //@}
 
     const wxWCharBuffer cMB2WX(const char* psz) const;
     //@}
 

-    //@{

     /**
     /**

-        Converts from Unicode to multibyte encoding by calling WC2MB and
+        Converts from Unicode to multibyte encoding by calling FromWChar() and

         allocating a temporary wxCharBuffer to hold the result.
 
         allocating a temporary wxCharBuffer to hold the result.
 

-        The second overload of this function allows to convert a string of the
-        given length @e inLen, whether it is @c NUL-terminated or not (for wide
-        character strings, unlike for the multibyte ones, a single @c NUL is
-        always enough). But notice that just as with @ref wxMBConv::mb2wc
-        cMB2WC, it is more efficient to pass an already terminated string to
-        this function as otherwise a copy is made internally. If @a outLen is
-        not-@NULL, it receives the length of the converted string.
+        This function is a convenient wrapper around FromWChar() as it takes
+        care of allocating the buffer of necessary size itself.
+
+        Its parameters have the same meaning as the corresponding parameters of
+        FromWChar(), please see the description of cMB2WC() for more details.

     */
     */

-    const wxCharBuffer cWC2MB(const wchar_t* in) const;
-    const wxCharBuffer cWC2MB(const wchar_t* in, size_t inLen, size_t *outLen) const;
-    //@}
+    const wxCharBuffer cWC2MB(const wchar_t* in,
+                              size_t inLen,
+                              size_t *outLen) const;
+
+    /**
+        Converts a wide char buffer to char one.
+
+        This is the most convenient and safest conversion function as you
+        don't have to deal with the buffer lengths directly. Use it if the
+        input buffer is known not to be empty or if you are sure that the
+        conversion is going to succeed -- otherwise, use the overload above to
+        be able to distinguish between empty input and conversion failure.
+
+        @return
+            The buffer containing the converted text, empty if the input was
+            empty or if the conversion failed.
+
+        @since 2.9.1
+     */
+    const wxCharBuffer cWC2MB(const wxWCharBuffer& buf) const;

 
     //@{
     /**
 
     //@{
     /**


@@ -256,6 +287,20 @@ public:
         out buffer, the @a outLen parameter should be one more to allow to
         properly @c NUL-terminate the string.
 
         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
         @param out
             The output buffer, may be @NULL if the caller is only
             interested in the length of the resulting string


@@ -278,7 +323,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
         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;
 };
     */
     virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const;
 };


@@ -286,7 +331,6 @@ public:
 
 /**
     @class wxMBConvUTF7
 
 /**
     @class wxMBConvUTF7

-    @wxheader{strconv.h}

 
     This class converts between the UTF-7 encoding and Unicode.
     It has one predefined instance, @b wxConvUTF7.
 
     This class converts between the UTF-7 encoding and Unicode.
     It has one predefined instance, @b wxConvUTF7.


@@ -305,7 +349,7 @@ public:
     @library{wxbase}
     @category{conv}
 
     @library{wxbase}
     @category{conv}
 

-    @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, @ref overview_mbconv

 */
 class wxMBConvUTF7 : public wxMBConv
 {
 */
 class wxMBConvUTF7 : public wxMBConv
 {


@@ -315,7 +359,6 @@ class wxMBConvUTF7 : public wxMBConv
 
 /**
     @class wxMBConvUTF8
 
 /**
     @class wxMBConvUTF8

-    @wxheader{strconv.h}

 
     This class converts between the UTF-8 encoding and Unicode.
     It has one predefined instance, @b wxConvUTF8.
 
     This class converts between the UTF-8 encoding and Unicode.
     It has one predefined instance, @b wxConvUTF8.


@@ -323,7 +366,7 @@ class wxMBConvUTF7 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
     @library{wxbase}
     @category{conv}
 

-    @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF7, @ref overview_mbconv

 */
 class wxMBConvUTF8 : public wxMBConv
 {
 */
 class wxMBConvUTF8 : public wxMBConv
 {


@@ -333,7 +376,6 @@ class wxMBConvUTF8 : public wxMBConv
 
 /**
     @class wxMBConvUTF16
 
 /**
     @class wxMBConvUTF16

-    @wxheader{strconv.h}

 
     This class is used to convert between multibyte encodings and UTF-16 Unicode
     encoding (also known as UCS-2).
 
     This class is used to convert between multibyte encodings and UTF-16 Unicode
     encoding (also known as UCS-2).


@@ -347,7 +389,7 @@ class wxMBConvUTF8 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
     @library{wxbase}
     @category{conv}
 

-    @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv

 */
 class wxMBConvUTF16 : public wxMBConv
 {
 */
 class wxMBConvUTF16 : public wxMBConv
 {


@@ -356,7 +398,6 @@ class wxMBConvUTF16 : public wxMBConv
 
 /**
     @class wxMBConvUTF32
 
 /**
     @class wxMBConvUTF32

-    @wxheader{strconv.h}

 
     This class is used to convert between multibyte encodings and UTF-32
     Unicode encoding (also known as UCS-4).
 
     This class is used to convert between multibyte encodings and UTF-32
     Unicode encoding (also known as UCS-4).


@@ -369,7 +410,7 @@ class wxMBConvUTF16 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
     @library{wxbase}
     @category{conv}
 

-    @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv

 */
 class wxMBConvUTF32 : public wxMBConv
 {
 */
 class wxMBConvUTF32 : public wxMBConv
 {


@@ -380,7 +421,6 @@ class wxMBConvUTF32 : public wxMBConv
 
 /**
     @class wxCSConv
 
 /**
     @class wxCSConv

-    @wxheader{strconv.h}

 
     This class converts between any character set supported by the system and
     Unicode.
 
     This class converts between any character set supported by the system and
     Unicode.


@@ -397,7 +437,7 @@ class wxMBConvUTF32 : public wxMBConv
     @library{wxbase}
     @category{conv}
 
     @library{wxbase}
     @category{conv}
 

-    @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+    @see wxMBConv, wxEncodingConverter, @ref overview_mbconv

 */
 class wxCSConv : public wxMBConv
 {
 */
 class wxCSConv : public wxMBConv
 {


@@ -443,7 +483,6 @@ public:
 
 /**
     @class wxMBConvFile
 
 /**
     @class wxMBConvFile

-    @wxheader{strconv.h}

 
     This class used to define the class instance @b wxConvFileName, but
     nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms)
 
     This class used to define the class instance @b wxConvFileName, but
     nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms)


@@ -464,7 +503,7 @@ public:
     could use it like this:
 
     @code
     could use it like this:
 
     @code

-    wxChar *name = wxT("rawfile.doc");
+    wxChar *name = "rawfile.doc";

     FILE *fil = fopen(wxFNCONV(name), "r");
     @endcode
 
     FILE *fil = fopen(wxFNCONV(name), "r");
     @endcode
 


@@ -475,7 +514,7 @@ public:
     @library{wxbase}
     @category{conv}
 
     @library{wxbase}
     @category{conv}
 

-    @see @ref overview_mbconv "wxMBConv classes overview"
+    @see @ref overview_mbconv

 */
 class wxMBConvFile : public wxMBConv
 {
 */
 class wxMBConvFile : public wxMBConv
 {