// Purpose: interface of wxMBConvUTF7
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@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
@library{wxbase}
@category{conv}
- @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxCSConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxMBConv
{
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
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.
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;
/**
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;
+
+ /**
+ 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;
//@{
/**
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;
+
+ /**
+ 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;
//@{
/**
/**
@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
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
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;
};
/**
@class wxMBConvUTF7
- @wxheader{strconv.h}
This class converts between the UTF-7 encoding and Unicode.
It has one predefined instance, @b wxConvUTF7.
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, @ref overview_mbconv
*/
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.
@library{wxbase}
@category{conv}
- @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF7, @ref overview_mbconv
*/
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).
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
*/
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).
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv
*/
class wxMBConvUTF32 : public wxMBConv
{
/**
@class wxCSConv
- @wxheader{strconv.h}
This class converts between any character set supported by the system and
Unicode.
@library{wxbase}
@category{conv}
- @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxCSConv : public wxMBConv
{
/**
@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)
could use it like this:
@code
- wxChar *name = wxT("rawfile.doc");
+ wxChar *name = "rawfile.doc";
FILE *fil = fopen(wxFNCONV(name), "r");
@endcode
@library{wxbase}
@category{conv}
- @see @ref overview_mbconv "wxMBConv classes overview"
+ @see @ref overview_mbconv
*/
class wxMBConvFile : public wxMBConv
{
projects / wxWidgets.git / blobdiff