X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4050e98de9c43a9fa60dffb35202d89d749ba081..3fbba098a22ccaf72fbc640482b94146b374c372:/interface/wx/strconv.h diff --git a/interface/wx/strconv.h b/interface/wx/strconv.h index e52666d64b..c5384a8e43 100644 --- a/interface/wx/strconv.h +++ b/interface/wx/strconv.h @@ -3,7 +3,7 @@ // Purpose: interface of wxMBConvUTF7 // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -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 @@ -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. @@ -116,16 +116,16 @@ public: @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. */ - 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; /** @@ -143,16 +143,16 @@ public: @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. */ - 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; /** @@ -174,8 +174,25 @@ 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; + + /** + 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; //@{ /** @@ -201,8 +218,25 @@ 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; + + /** + 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; //@{ /** @@ -243,7 +277,7 @@ public: /** @deprecated This function is deprecated, please use ToWChar() instead. - Converts from a string @a in in multibyte encoding to Unicode putting up to + Converts from a string @a in multibyte encoding to Unicode putting up to @a outLen characters into the buffer @e out. If @a out is @NULL, only the length of the string which would result @@ -253,6 +287,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 +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 - 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 +349,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 +366,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 +389,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 +410,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 +437,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 { @@ -455,7 +503,7 @@ public: could use it like this: @code - wxChar *name = wxT("rawfile.doc"); + wxChar *name = "rawfile.doc"; FILE *fil = fopen(wxFNCONV(name), "r"); @endcode @@ -466,7 +514,7 @@ public: @library{wxbase} @category{conv} - @see @ref overview_mbconv "wxMBConv classes overview" + @see @ref overview_mbconv */ class wxMBConvFile : public wxMBConv {