[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* }{buf}, \param{const char* }{psz}, \param{size\_t }{n}}

Converts from a string {\it psz} in multibyte encoding to Unicode putting the
output into the buffer {\it buf} of the size {\it n} (in wide characters, not
bytes). If {\it buf} is {\tt NULL}, nothing is written to it but 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} buffer, the {\it n} parameter should be the size of the buffer
and so it {\bf should} take into account the trailing NUL.

\wxheading{Parameters}

\docparam{buf}{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{n}{the size of the output buffer, ignored if {\it buf} is {\tt NULL}}

\wxheading{Return value}

The length of the converted string.

\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}.


\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).
Commit	Line	Data
f6bcfd97 BP	1	%
	2	% automatically generated by HelpGen from
	3	% ../include/wx/strconv.h at 25/Mar/00 10:20:56
	4	%
	5
	6	\section{\class{wxMBConv}}\label{wxmbconv}
	7
	8	This class is the base class of a hierarchy of classes capable of converting
	9	text strings between multibyte (SBCS or DBCS) encodings and Unicode. It is itself
	10	a wrapper around the standard libc mbstowcs() and wcstombs() routines, and has
	11	one predefined instance, {\bf wxConvLibc}.
	12
	13	\wxheading{Derived from}
	14
	15	No base class
	16
	17	\wxheading{Include files}
	18
	19	<wx/strconv.h>
	20
	21	\wxheading{See also}
	22
	23	\helpref{wxCSConv}{wxcsconv},
	24	\helpref{wxEncodingConverter}{wxencodingconverter},
	25	\helpref{wxMBConv classes overview}{mbconvclasses}
	26
	27	\latexignore{\rtfignore{\wxheading{Members}}}
	28
	29
	30	\membersection{wxMBConv::wxMBConv}\label{wxmbconvwxmbconv}
	31
	32	\func{}{wxMBConv}{\void}
	33
	34	Constructor.
	35
	36	\membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}
	37
	38	\constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t* }{buf}, \param{const char* }{psz}, \param{size\_t }{n}}
	39
2b5f62a0 VZ	40	Converts from a string {\it psz} in multibyte encoding to Unicode putting the
	41	output into the buffer {\it buf} of the size {\it n} (in wide characters, not
	42	bytes). If {\it buf} is {\tt NULL}, nothing is written to it but the length of
	43	the string which would result from the conversion is calculated and returned.
	44	Note that this is the length and not size, i.e. the returned value does
	45	{\bf not} include the trailing NUL. But when the function is called with a
	46	non-{\tt NULL} buffer, the {\it n} parameter should be the size of the buffer
	47	and so it {\bf should} take into account the trailing NUL.
	48
	49	\wxheading{Parameters}
	50
	51	\docparam{buf}{the output buffer, may be {\tt NULL} if the caller is only
	52	interested in the length of the resulting string}
	53
	54	\docparam{psz}{the {\tt NUL}-terminated input string, cannot be {\tt NULL}}
	55
	56	\docparam{n}{the size of the output buffer, ignored if {\it buf} is {\tt NULL}}
	57
	58	\wxheading{Return value}
	59
	60	The length of the converted string.
f6bcfd97 BP	61
	62	\membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}
	63
	64	\constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}
	65
2b5f62a0 VZ	66	Converts from Unicode to multibyte encoding. The semantics of this function
	67	(including the return value meaning) is the same as for
	68	\helpref{MB2WC}{wxmbconvmb2wc}.
	69
f6bcfd97 BP	70
	71	\membersection{wxMBConv::cMB2WC}\label{wxmbconvcmb2wc}
	72
	73	\constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char* }{psz}}
	74
	75	Converts from multibyte encoding to Unicode by calling MB2WC,
	76	allocating a temporary wxWCharBuffer to hold the result.
	77
	78	\membersection{wxMBConv::cWC2MB}\label{wxmbconvcwc2mb}
	79
	80	\constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{psz}}
	81
	82	Converts from Unicode to multibyte encoding by calling WC2MB,
	83	allocating a temporary wxCharBuffer to hold the result.
	84
	85	\membersection{wxMBConv::cMB2WX}\label{wxmbconvcmb2wx}
	86
	87	\constfunc{const char}{cMB2WX}{\param{const char }{psz}}
	88
	89	\constfunc{const wxWCharBuffer}{cMB2WX}{\param{const char* }{psz}}
	90
	91	Converts from multibyte encoding to the current wxChar type
	92	(which depends on whether wxUSE\_UNICODE is set to 1). If wxChar is char,
	93	it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
	94	result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct
	95	return type (without const).
	96
	97	\membersection{wxMBConv::cWX2MB}\label{wxmbconvcwx2mb}
	98
	99	\constfunc{const char}{cWX2MB}{\param{const wxChar }{psz}}
	100
	101	\constfunc{const wxCharBuffer}{cWX2MB}{\param{const wxChar* }{psz}}
	102
	103	Converts from the current wxChar type to multibyte encoding. If wxChar is char,
	104	it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
	105	result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct
	106	return type (without const).
	107
	108	\membersection{wxMBConv::cWC2WX}\label{wxmbconvcwc2wx}
	109
	110	\constfunc{const wchar\_t}{cWC2WX}{\param{const wchar\_t }{psz}}
	111
	112	\constfunc{const wxCharBuffer}{cWC2WX}{\param{const wchar\_t* }{psz}}
	113
	114	Converts from Unicode to the current wxChar type. If wxChar is wchar\_t,
	115	it returns the parameter unaltered. If wxChar is char, it returns the
	116	result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct
	117	return type (without const).
	118
	119	\membersection{wxMBConv::cWX2WC}\label{wxmbconvcwx2wc}
	120
	121	\constfunc{const wchar\_t}{cWX2WC}{\param{const wxChar }{psz}}
	122
	123	\constfunc{const wxWCharBuffer}{cWX2WC}{\param{const wxChar* }{psz}}
	124
	125	Converts from the current wxChar type to Unicode. If wxChar is wchar\_t,
	126	it returns the parameter unaltered. If wxChar is char, it returns the
	127	result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
	128	return type (without const).
	129