## wxMBConv

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

In the documentation for this and related classes please notice that length of the string refers to the number of characters in the string not counting the terminating `NUL`, if any. While the size of the string is the total number of bytes in the string, including any trailing `NUL`. Thus, length of wide character string `L"foo"` is 3 while its size can be either 8 or 16 depending on whether `wchar_t` is 2 bytes (as under Windows) or 4 (Unix).

Global variables

There are several predefined instances of this class:

wxConvLibc | Uses the standard ANSI C `mbstowcs()` and `wcstombs()` functions to perform the conversions; thus depends on the current locale.
wxConvLocal | Another conversion corresponding to the current locale but this one uses the best available conversion.
wxConvUI | The conversion used for hte standard UI elements such as menu items and buttons. This is a pointer which is initially set to `wxConvLocal` as the program uses the current locale by default but can be set to some specific conversion if the program needs to use a specific encoding for its UI.
wxConvISO8859_1 | Conversion to and from ISO-8859-1 (Latin I) encoding.
wxConvUTF8 | Conversion to and from UTF-8 encoding.
wxConvFile | The appropriate conversion for the file names, depends on the system.

Constants

`wxCONV_FAILED` value is defined as `(size_t)-1` and is returned by the conversion functions instead of the length of the converted string if the conversion fails.

Derived from

No base class

Include files

<wx/strconv.h>

See also

wxCSConv, wxEncodingConverter, wxMBConv classes overview

Members

wxMBConv::wxMBConv
wxMBConv::MB2WC
wxMBConv::WC2MB
wxMBConv::cMB2WC
wxMBConv::cWC2MB
wxMBConv::cMB2WX
wxMBConv::cWX2MB
wxMBConv::cWC2WX
wxMBConv::cWX2WC
wxMBConv::FromWChar
wxMBConv::GetMaxMBNulLen
wxMBConv::GetMBNulLen
wxMBConv::ToWChar

### wxMBConv::wxMBConv

wxMBConv()

Trivial default constructor.

### wxMBConv::MB2WC

virtual size_t MB2WC(wchar_t *out, const char *in, size_t outLen) const

This function is deprecated, please use ToWChar instead

Converts from a string in in multibyte encoding to Unicode putting up to outLen characters into the buffer out.

If out is `NULL`, only the length of the string which would result from the conversion is calculated and returned. Note that this is the length and not size, i.e. the returned value does not include the trailing `NUL`. But when the function is called with a non-`NULL` out buffer, the outLen parameter should be one more to allow to properly `NUL`-terminate the string.

Parameters

out

The output buffer, may be `NULL` if the caller is only interested in the length of the resulting string

in

The `NUL`-terminated input string, cannot be `NULL`

outLen

The length of the output buffer but including `NUL`, ignored if out is `NULL`

Return value

The length of the converted string excluding the trailing `NUL`.

### wxMBConv::WC2MB

virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const

This function is deprecated, please use FromWChar instead

Converts from Unicode to multibyte encoding. The semantics of this function (including the return value meaning) is the same as for MB2WC.

Notice that when the function is called with a non-`NULL` buffer, the n parameter should be the size of the buffer and so it should take into account the trailing `NUL`, which might take two or four bytes for some encodings (UTF-16 and UTF-32) and not one.

### wxMBConv::cMB2WC

const wxWCharBuffer cMB2WC(const char *in) const

const wxWCharBuffer cMB2WC(const char *in, size_t inLen, size_t *outLen) const

Converts from multibyte encoding to Unicode by calling MB2WC, allocating a temporary wxWCharBuffer to hold the result.

The first overload takes a `NUL`-terminated input string. The second one takes a string of exactly the specified length and the string may include or not the trailing `NUL` character(s). If the string is not `NUL`-terminated, a temporary `NUL`-terminated copy of it suitable for passing to MB2WC is made, so it is more efficient to ensure that the string is does have the appropriate number of `NUL` bytes (which is usually 1 but may be 2 or 4 for UTF-16 or UTF-32, see GetMBNulLen), especially for long strings.

If outLen is not-`NULL`, it receives the length of the converted string.

### wxMBConv::cWC2MB

const wxCharBuffer cWC2MB(const wchar_t* in) const

const wxCharBuffer cWC2MB(const wchar_t* in, size_t inLen, size_t *outLen) const

Converts from Unicode to multibyte encoding by calling WC2MB, allocating a temporary wxCharBuffer to hold the result.

The second overload of this function allows to convert a string of the given length inLen, whether it is `NUL`-terminated or not (for wide character strings, unlike for the multibyte ones, a single `NUL` is always enough). But notice that just as with cMB2WC, it is more efficient to pass an already terminated string to this function as otherwise a copy is made internally.

If outLen is not-`NULL`, it receives the length of the converted string.

### wxMBConv::cMB2WX

const char* cMB2WX(const char* psz) const

const wxWCharBuffer cMB2WX(const char* psz) const

Converts from multibyte encoding to the current wxChar type (which depends on whether wxUSE_UNICODE is set to 1). If wxChar is char, it returns the parameter unaltered. If wxChar is wchar_t, it returns the result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct return type (without const).

### wxMBConv::cWX2MB

const char* cWX2MB(const wxChar* psz) const

const wxCharBuffer cWX2MB(const wxChar* psz) const

Converts from the current wxChar type to multibyte encoding. If wxChar is char, it returns the parameter unaltered. If wxChar is wchar_t, it returns the result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct return type (without const).

### wxMBConv::cWC2WX

const wchar_t* cWC2WX(const wchar_t* psz) const

const wxCharBuffer cWC2WX(const wchar_t* psz) const

Converts from Unicode to the current wxChar type. If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is char, it returns the result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct return type (without const).

### wxMBConv::cWX2WC

const wchar_t* cWX2WC(const wxChar* psz) const

const wxWCharBuffer cWX2WC(const wxChar* psz) const

Converts from the current wxChar type to Unicode. If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is char, it returns the result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct return type (without const).

### wxMBConv::FromWChar

virtual size_t FromWChar(wchar_t *dst, size_t dstLen, const char *src, size_t srcLen = wxNO_LEN) const

The most general function for converting a multibyte string to a wide string. The main case is when dst is not `NULL` and srcLen is not `wxNO_LEN` (which is defined as `(size_t)-1`): then the function converts exactly srcLen bytes starting at src into wide string which it output to dst. If the length of the resulting wide string is greater than dstLen, an error is returned. Note that if srcLen bytes don't include `NUL` characters, the resulting wide string is not `NUL`-terminated neither.

If srcLen is `wxNO_LEN`, the function supposes that the string is properly (i.e. as necessary for the encoding handled by this conversion) `NUL`-terminated and converts the entire string, including any trailing `NUL` bytes. In this case the wide string is also `NUL`-terminated.

Finally, if dst is `NULL`, the function returns the length of the needed buffer.

Return value

The number of characters written to dst (or the number of characters which would have been written to it if it were non-`NULL`) on success or `wxCONV_FAILED` on error.

### wxMBConv::GetMaxMBNulLen

const size_t GetMaxMBNulLen()

Returns the maximal value which can be returned by GetMBNulLen for any conversion object. Currently this value is 4.

This method can be used to allocate the buffer with enough space for the trailing `NUL` characters for any encoding.

### wxMBConv::GetMBNulLen

size_t GetMBNulLen() const

This function returns 1 for most of the multibyte encodings in which the string is terminated by a single `NUL`, 2 for UTF-16 and 4 for UTF-32 for which the string is terminated with 2 and 4 `NUL` characters respectively. The other cases are not currently supported and `wxCONV_FAILED` (defined as -1) is returned for them.

### wxMBConv::ToWChar

virtual size_t ToWChar(char_t *dst, size_t dstLen, const wchar_t *src, size_t srcLen = wxNO_LEN) const

This function has the same semantics as FromWChar except that it converts a wide string to multibyte one.