First step in background erase optimization

[wxWidgets.git] / docs / latex / wx / mbconv.tex

%
% automatically generated by HelpGen from
% ../include/wx/strconv.h at 25/Mar/00 10:20:56
%

\section{\class{wxMBConv}}\label{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. It is itself
a wrapper around the standard libc mbstowcs() and wcstombs() routines, and has
one predefined instance, {\bf wxConvLibc}.

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/strconv.h>

\wxheading{See also}

\helpref{wxCSConv}{wxcsconv}, 
\helpref{wxEncodingConverter}{wxencodingconverter}, 
\helpref{wxMBConv classes overview}{mbconvclasses}

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxMBConv::wxMBConv}\label{wxmbconvwxmbconv}

\func{}{wxMBConv}{\void}

Constructor.

\membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}

\constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t *}{outputBuf}, \param{const char *}{psz}, \param{size\_t }{outputSize}}

Converts from a string {\it psz} in multibyte encoding to Unicode putting the
output into the buffer {\it outputBuf} of the maximum size {\it outputSize} (in wide
characters, not bytes). If {\it outputBuf} is {\tt 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 
{\bf not} include the trailing NUL. But when the function is called with a
non-{\tt NULL} {\it outputBuf}, the {\it outputSize} parameter should be the size of the buffer
and so it {\bf should} take into account the trailing NUL.

\wxheading{Parameters}

\docparam{outputBuf}{the output buffer, may be {\tt NULL} if the caller is only
interested in the length of the resulting string}

\docparam{psz}{the {\tt NUL}-terminated input string, cannot be {\tt NULL}}

\docparam{outputSize}{the size of the output buffer (in wide characters, {\bf including} the
NUL) , ignored if {\it outputBuf} is {\tt NULL}}

\wxheading{Return value}

The length of the converted string (in wide characters, {\bf excluding} the NUL)

\membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}

\constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}

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

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

\membersection{wxMBConv::cMB2WC}\label{wxmbconvcmb2wc}

\constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char* }{psz}}

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

\membersection{wxMBConv::cWC2MB}\label{wxmbconvcwc2mb}

\constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{psz}}

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

\membersection{wxMBConv::cMB2WX}\label{wxmbconvcmb2wx}

\constfunc{const char*}{cMB2WX}{\param{const char* }{psz}}

\constfunc{const wxWCharBuffer}{cMB2WX}{\param{const char* }{psz}}

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

\membersection{wxMBConv::cWX2MB}\label{wxmbconvcwx2mb}

\constfunc{const char*}{cWX2MB}{\param{const wxChar* }{psz}}

\constfunc{const wxCharBuffer}{cWX2MB}{\param{const wxChar* }{psz}}

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

\membersection{wxMBConv::cWC2WX}\label{wxmbconvcwc2wx}

\constfunc{const wchar\_t*}{cWC2WX}{\param{const wchar\_t* }{psz}}

\constfunc{const wxCharBuffer}{cWC2WX}{\param{const wchar\_t* }{psz}}

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

\membersection{wxMBConv::cWX2WC}\label{wxmbconvcwx2wc}

\constfunc{const wchar\_t*}{cWX2WC}{\param{const wxChar* }{psz}}

\constfunc{const wxWCharBuffer}{cWX2WC}{\param{const wxChar* }{psz}}

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