| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxMBConv Class Referenceabstract
Class List by Category » Text Conversion

`#include <wx/strconv.h>`

Inheritance diagram for wxMBConv:
[legend]

## Detailed Description

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

This is an abstract base class which defines the operations implemented by all different conversion classes. The derived classes don't add any new operations of their own (except, possibly, some non-default constructors) and so you should simply use this class ToWChar() and FromWChar() (or cMB2WC() and cWC2MB()) methods with the objects of the derived class.

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).

##

Library: wxBase
Category: Text Conversion

See also
  wxCSConv, wxEncodingConverter, wxMBConv Overview

## Public Member Functions
| wxMBConv ()
| Trivial default constructor. More...
virtual wxMBConv * | Clone () const =0
| This pure virtual function is overridden in each of the derived classes to return a new copy of the object it is called on. More...
virtual size_t | GetMaxCharLen () const
| This function must be overridden in the derived classes to return the maximum length, in bytes, of a single Unicode character representation in this encoding. More...
virtual 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. More...
virtual bool | IsUTF8 () const
| Return true if the converter's charset is UTF-8. More...
virtual size_t | ToWChar (wchar_t *dst, size_t dstLen, const char *src, size_t srcLen=wxNO_LEN) const
| Convert multibyte string to a wide character one. More...
virtual size_t | FromWChar (char *dst, size_t dstLen, const wchar_t *src, size_t srcLen=wxNO_LEN) const
| Converts wide character string to multibyte. More...
wxWCharBuffer | cMB2WC (const char *in, size_t inLen, size_t *outLen) const
| Converts from multibyte encoding to Unicode by calling ToWChar() and allocating a temporary wxWCharBuffer to hold the result. More...
wxWCharBuffer | cMB2WC (const wxCharBuffer &buf) const
| Converts a char buffer to wide char one. More...
wxWCharBuffer | cMB2WX (const char *psz) const
| Converts from multibyte encoding to `wchar_t`. More...
wxCharBuffer | cWC2MB (const wchar_t *in, size_t inLen, size_t *outLen) const
| Converts from Unicode to multibyte encoding by calling FromWChar() and allocating a temporary wxCharBuffer to hold the result. More...
wxCharBuffer | cWC2MB (const wxWCharBuffer &buf) const
| Converts a wide char buffer to char one. More...
virtual size_t | MB2WC (wchar_t *out, const char *in, size_t outLen) const
virtual size_t | WC2MB (char *buf, const wchar_t *psz, size_t n) const
const wchar_t * | cWC2WX (const wchar_t *psz) const
| Converts from Unicode to the current wxChar type. More...
wxCharBuffer | cWC2WX (const wchar_t *psz) const
| Converts from Unicode to the current wxChar type. More...
const char * | cWX2MB (const wxChar *psz) const
| Converts from the current wxChar type to multibyte encoding. More...
wxCharBuffer | cWX2MB (const wxChar *psz) const
| Converts from the current wxChar type to multibyte encoding. More...
const wchar_t * | cWX2WC (const wxChar *psz) const
| Converts from the current wxChar type to Unicode. More...
wxWCharBuffer | cWX2WC (const wxChar *psz) const
| Converts from the current wxChar type to Unicode. More...

## Static Public Member Functions
static size_t | GetMaxMBNulLen ()
| Returns the maximal value which can be returned by GetMBNulLen() for any conversion object. More...

## Constructor & Destructor Documentation

## ◆ wxMBConv()

wxMBConv::wxMBConv | ( |  | ) |

Trivial default constructor.

## Member Function Documentation

## ◆ Clone()

virtual wxMBConv* wxMBConv::Clone | ( |  | ) | const
| pure virtual

This pure virtual function is overridden in each of the derived classes to return a new copy of the object it is called on.

It is used for copying the conversion objects while preserving their dynamic type.

## ◆ cMB2WC() [1/2]

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

Converts from multibyte encoding to Unicode by calling ToWChar() and allocating a temporary wxWCharBuffer to hold the result.

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 inLen can be specified explicitly in which case exactly that many characters are converted and outLen receives (if non-null) exactly the corresponding number of wide characters, whether the last one of them is `NUL` or not. However if `inLen` is `wxNO_LEN`, then `outLen` doesn't count the trailing `NUL` even if it is always present in this case.

Finally notice that if the conversion fails, the returned buffer is invalid and outLen is set to 0 (and not `wxCONV_FAILED` for compatibility concerns).

## ◆ cMB2WC() [2/2]

wxWCharBuffer wxMBConv::cMB2WC | ( | const wxCharBuffer & | buf | ) | 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.

Returns
  The buffer containing the converted text, empty if the input was empty or if the conversion failed.

Since
  2.9.1

## ◆ cMB2WX()

wxWCharBuffer wxMBConv::cMB2WX | ( | const char * | psz | ) | const

Converts from multibyte encoding to `wchar_t`.

## ◆ cWC2MB() [1/2]

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

Converts from Unicode to multibyte encoding by calling FromWChar() and allocating a temporary wxCharBuffer to hold the result.

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.

## ◆ cWC2MB() [2/2]

wxCharBuffer wxMBConv::cWC2MB | ( | const wxWCharBuffer & | buf | ) | 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.

Returns
  The buffer containing the converted text, empty if the input was empty or if the conversion failed.

Since
  2.9.1

## ◆ cWC2WX() [1/2]

const wchar_t* wxMBConv::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).

## ◆ cWC2WX() [2/2]

wxCharBuffer wxMBConv::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).

## ◆ cWX2MB() [1/2]

const char* wxMBConv::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).

## ◆ cWX2MB() [2/2]

wxCharBuffer wxMBConv::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).

## ◆ cWX2WC() [1/2]

const wchar_t* wxMBConv::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).

## ◆ cWX2WC() [2/2]

wxWCharBuffer wxMBConv::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).

## ◆ FromWChar()

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

Converts wide character string to multibyte.

This function has the same semantics as ToWChar() except that it converts a wide string to multibyte one. As with ToWChar(), it may be more convenient to use cWC2MB() when working with `NUL` terminated strings.

Parameters

  dst | Pointer to output buffer of the size of at least dstLen or nullptr.
  dstLen | Maximal number of characters to be written to the output buffer if dst is non-null, unused otherwise.
  src | Point to the source string, must not be nullptr.
  srcLen | The number of characters of the source string to convert or `wxNO_LEN` (default parameter) to convert everything up to and including the terminating `NUL` character.

Returns
  If dst is non-null, the number of characters actually written to it. If dst is nullptr, the returned value is at least equal to the number of characters that would have been written out if it were non-null, but can be larger than it under the platforms using UTF-16 as `wchar_t` encoding (this allows a useful optimization in the implementation of this function for UTF-32). In any case, `wxCONV_FAILED` is returned on conversion error.

## ◆ GetMaxCharLen()

virtual size_t wxMBConv::GetMaxCharLen | ( |  | ) | const
| virtual

This function must be overridden in the derived classes to return the maximum length, in bytes, of a single Unicode character representation in this encoding.

As a consequence, the conversion object must be able to decode any valid sequence of bytes in the corresponding encoding if it's at least that many bytes long, but may fail if it is shorter. For example, for UTF-8 the maximum character length is 4, as 3 bytes or less may be insufficient to represent a Unicode character in UTF-8, but 4 are always enough.

For compatibility reasons, this method is not pure virtual and returns 1 by default in the base class, however it should be always overridden in the derived classes.

Since
  3.1.3

## ◆ GetMaxMBNulLen()

static size_t wxMBConv::GetMaxMBNulLen | ( |  | ) |
| static

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.

## ◆ GetMBNulLen()

virtual size_t wxMBConv::GetMBNulLen | ( |  | ) | const
| virtual

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.

## ◆ IsUTF8()

virtual bool wxMBConv::IsUTF8 | ( |  | ) | const
| virtual

Return true if the converter's charset is UTF-8.

This is provided to optimize creating wxStrings from the `char*` strings returned by this converter, as they can be directly used with wxString::FromUTF8() or even wxString::FromUTF8Unchecked() when this method returns true.

This function is universally available since wxWidgets 3.1.1 (it was previously only available in some of the build configurations).

## ◆ MB2WC()

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

Deprecated:
  This function is deprecated, please use ToWChar() instead.

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

If out is nullptr, 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.

So to properly use this function you need to write:

size_t lenConv = conv.MB2WC(nullptr, 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 ...

For this and other reasons, ToWChar() is strongly recommended as a replacement.

Parameters

  out | The output buffer, may be nullptr if the caller is only interested in the length of the resulting string
  in | The NUL-terminated input string, cannot be nullptr
  outLen | The length of the output buffer but including NUL, ignored if out is nullptr

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

## ◆ ToWChar()

virtual size_t wxMBConv::ToWChar | ( | wchar_t * | dst,
|  | size_t | dstLen,
|  | const char * | src,
|  | size_t | srcLen = `wxNO_LEN`
| ) |  | const
| virtual

Convert multibyte string to a wide character one.

This is the most general function for converting a multibyte string to a wide string, cMB2WC() may be often more convenient, however this function is the most efficient one as it allows avoiding any unnecessary copying.

The main case is when dst is not nullptr 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` either.

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 nullptr, the function returns the length of the needed buffer.

Example of use of this function:

size_t dstLen = conv.ToWChar(nullptr, 0, src);
if ( dstLen == wxCONV_FAILED )
... handle error ...
wchar_t *dst = new wchar_t[dstLen];
if ( conv.ToWChar(dst, dstLen, src) == wxCONV_FAILED )
... handle error ...

Notice that when passing the explicit source length the output will not be `NUL` terminated if you pass `strlen(str)` as parameter. Either leave srcLen as default `wxNO_LEN` or add one to `strlen` result if you want the output to be `NUL` terminated.

Parameters

  dst | Pointer to output buffer of the size of at least dstLen or nullptr.
  dstLen | Maximal number of characters to be written to the output buffer if dst is non-null, unused otherwise.
  src | Point to the source string, must not be nullptr.
  srcLen | The number of characters of the source string to convert or `wxNO_LEN` (default parameter) to convert everything up to and including the terminating `NUL` character(s).

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

## ◆ WC2MB()

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

Deprecated:
  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 wxMBConv::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, i.e. GetMBNulLen().