[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).
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
75736a9c	38	\constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t }{outputBuf}, \param{const char }{psz}, \param{size\_t }{outputSize}}
f6bcfd97	39
2b5f62a0	40	Converts from a string {\it psz} in multibyte encoding to Unicode putting the
75736a9c DS	41	output into the buffer {\it outputBuf} of the maximum size {\it outputSize} (in wide
	42	characters, not bytes). If {\it outputBuf} is {\tt NULL}, only the length of the
	43	string which would result from the conversion is calculated and returned.
2b5f62a0 VZ	44	Note that this is the length and not size, i.e. the returned value does
2b5f62a0 VZ	45	{\bf not} include the trailing NUL. But when the function is called with a
75736a9c	46	non-{\tt NULL} {\it outputBuf}, the {\it outputSize} parameter should be the size of the buffer
2b5f62a0 VZ	47	and so it {\bf should} take into account the trailing NUL.
	48
	49	\wxheading{Parameters}
	50
75736a9c	51	\docparam{outputBuf}{the output buffer, may be {\tt NULL} if the caller is only
2b5f62a0 VZ	52	interested in the length of the resulting string}
	53
	54	\docparam{psz}{the {\tt NUL}-terminated input string, cannot be {\tt NULL}}
	55
75736a9c DS	56	\docparam{outputSize}{the size of the output buffer (in wide characters, {\bf including} the
75736a9c DS	57	NUL) , ignored if {\it outputBuf} is {\tt NULL}}
2b5f62a0 VZ	58
	59	\wxheading{Return value}
	60
75736a9c	61	The length of the converted string (in wide characters, {\bf excluding} the NUL)
f6bcfd97 BP	62
	63	\membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}
	64
	65	\constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}
	66
2b5f62a0 VZ	67	Converts from Unicode to multibyte encoding. The semantics of this function
	68	(including the return value meaning) is the same as for
	69	\helpref{MB2WC}{wxmbconvmb2wc}.
	70
e19971c3 VZ	71	Notice that when the function is called with a non-{\tt NULL} buffer, the
	72	{\it n} parameter should be the size of the buffer and so it {\bf should} take
	73	into account the trailing NUL, which might take two or four bytes for some
	74	encodings (UTF-16 and UTF-32).
f6bcfd97 BP	75
	76	\membersection{wxMBConv::cMB2WC}\label{wxmbconvcmb2wc}
	77
	78	\constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char* }{psz}}
	79
	80	Converts from multibyte encoding to Unicode by calling MB2WC,
	81	allocating a temporary wxWCharBuffer to hold the result.
	82
	83	\membersection{wxMBConv::cWC2MB}\label{wxmbconvcwc2mb}
	84
	85	\constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{psz}}
	86
	87	Converts from Unicode to multibyte encoding by calling WC2MB,
	88	allocating a temporary wxCharBuffer to hold the result.
	89
	90	\membersection{wxMBConv::cMB2WX}\label{wxmbconvcmb2wx}
	91
	92	\constfunc{const char}{cMB2WX}{\param{const char }{psz}}
	93
	94	\constfunc{const wxWCharBuffer}{cMB2WX}{\param{const char* }{psz}}
	95
	96	Converts from multibyte encoding to the current wxChar type
	97	(which depends on whether wxUSE\_UNICODE is set to 1). If wxChar is char,
	98	it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
	99	result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct
	100	return type (without const).
	101
	102	\membersection{wxMBConv::cWX2MB}\label{wxmbconvcwx2mb}
	103
	104	\constfunc{const char}{cWX2MB}{\param{const wxChar }{psz}}
	105
	106	\constfunc{const wxCharBuffer}{cWX2MB}{\param{const wxChar* }{psz}}
	107
	108	Converts from the current wxChar type to multibyte encoding. If wxChar is char,
	109	it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
	110	result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct
	111	return type (without const).
	112
	113	\membersection{wxMBConv::cWC2WX}\label{wxmbconvcwc2wx}
	114
	115	\constfunc{const wchar\_t}{cWC2WX}{\param{const wchar\_t }{psz}}
	116
	117	\constfunc{const wxCharBuffer}{cWC2WX}{\param{const wchar\_t* }{psz}}
	118
	119	Converts from Unicode to the current wxChar type. If wxChar is wchar\_t,
	120	it returns the parameter unaltered. If wxChar is char, it returns the
	121	result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct
	122	return type (without const).
	123
	124	\membersection{wxMBConv::cWX2WC}\label{wxmbconvcwx2wc}
	125
	126	\constfunc{const wchar\_t}{cWX2WC}{\param{const wxChar }{psz}}
	127
	128	\constfunc{const wxWCharBuffer}{cWX2WC}{\param{const wxChar* }{psz}}
	129
	130	Converts from the current wxChar type to Unicode. If wxChar is wchar\_t,
	131	it returns the parameter unaltered. If wxChar is char, it returns the
	132	result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
	133	return type (without const).
	134