X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..97d13342cc2ac77e21c38115cc6ebecac930f92a:/interface/wx/strconv.h diff --git a/interface/wx/strconv.h b/interface/wx/strconv.h index 1843a27e13..174133388e 100644 --- a/interface/wx/strconv.h +++ b/interface/wx/strconv.h @@ -8,7 +8,6 @@ /** @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 @@ -31,7 +30,7 @@ @library{wxbase} @category{conv} - @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" + @see wxCSConv, wxEncodingConverter, @ref overview_mbconv */ 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. */ - size_t GetMBNulLen() const; + virtual size_t GetMBNulLen() const; /** 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. */ - const size_t GetMaxMBNulLen(); + static size_t GetMaxMBNulLen(); /** 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 - @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. */ - 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; /** @@ -141,41 +140,42 @@ 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. */ - 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; - //@{ /** - 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. - 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; //@{ /** @@ -190,22 +190,19 @@ public: 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. - 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; //@{ /** @@ -256,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 @@ -278,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; }; @@ -286,7 +297,6 @@ public: /** @class wxMBConvUTF7 - @wxheader{strconv.h} This class converts between the UTF-7 encoding and Unicode. It has one predefined instance, @b wxConvUTF7. @@ -305,7 +315,7 @@ public: @library{wxbase} @category{conv} - @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview" + @see wxMBConvUTF8, @ref overview_mbconv */ class wxMBConvUTF7 : public wxMBConv { @@ -315,7 +325,6 @@ class wxMBConvUTF7 : public wxMBConv /** @class wxMBConvUTF8 - @wxheader{strconv.h} This class converts between the UTF-8 encoding and Unicode. It has one predefined instance, @b wxConvUTF8. @@ -323,7 +332,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 { @@ -333,7 +342,6 @@ class wxMBConvUTF8 : public wxMBConv /** @class wxMBConvUTF16 - @wxheader{strconv.h} This class is used to convert between multibyte encodings and UTF-16 Unicode encoding (also known as UCS-2). @@ -347,7 +355,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 { @@ -356,7 +364,6 @@ class wxMBConvUTF16 : public wxMBConv /** @class wxMBConvUTF32 - @wxheader{strconv.h} This class is used to convert between multibyte encodings and UTF-32 Unicode encoding (also known as UCS-4). @@ -369,7 +376,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 { @@ -380,7 +387,6 @@ class wxMBConvUTF32 : public wxMBConv /** @class wxCSConv - @wxheader{strconv.h} This class converts between any character set supported by the system and Unicode. @@ -397,7 +403,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 { @@ -443,7 +449,6 @@ public: /** @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) @@ -464,7 +469,7 @@ public: could use it like this: @code - wxChar *name = wxT("rawfile.doc"); + wxChar *name = "rawfile.doc"; FILE *fil = fopen(wxFNCONV(name), "r"); @endcode @@ -475,7 +480,7 @@ public: @library{wxbase} @category{conv} - @see @ref overview_mbconv "wxMBConv classes overview" + @see @ref overview_mbconv */ class wxMBConvFile : public wxMBConv {