// Purpose: interface of wxMBConvUTF7
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@library{wxbase}
@category{conv}
- @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxCSConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxMBConv
{
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.
@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;
/**
@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;
/**
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;
//@{
/**
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;
//@{
/**
/**
@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;
};
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, @ref overview_mbconv
*/
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
{
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
*/
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
{
@library{wxbase}
@category{conv}
- @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxCSConv : public wxMBConv
{
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