-%
-% automatically generated by HelpGen from
-% ../include/wx/strconv.h at 25/Mar/00 10:20:56
-%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: mbconv.tex
+%% Purpose: wxMBConv documentation
+%% Author: Ove Kaaven, Vadim Zeitlin
+%% Created: 2000-03-25
+%% RCS-ID: $Id$
+%% Copyright: (c) 2000 Ove Kaaven
+%% (c) 2003-2006 Vadim Zeitlin
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\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}.
+text strings between multibyte (SBCS or DBCS) encodings and Unicode.
+
+In the documentation for this and related classes please notice that
+\emph{length} of the string refers to the number of characters in the string
+not counting the terminating \NUL, if any. While the \emph{size} of the string
+is the total number of bytes in the string, including any trailing \NUL.
+Thus, length of wide character string \texttt{L"foo"} is $3$ while its size can
+be either $8$ or $16$ depending on whether \texttt{wchar\_t} is $2$ bytes (as
+under Windows) or $4$ (Unix).
+
+\wxheading{Global variables}
+
+There are several predefined instances of this class:
+\begin{twocollist}
+\twocolitem{\textbf{wxConvLibc}}{Uses the standard ANSI C \texttt{mbstowcs()} and
+\texttt{wcstombs()} functions to perform the conversions; thus depends on the
+current locale.}
+\twocolitem{\textbf{wxConvLocal}}{Another conversion corresponding to the
+current locale but this one uses the best available conversion.}
+\twocolitem{\textbf{wxConvUI}}{The conversion used for hte standard UI elements
+such as menu items and buttons. This is a pointer which is initially set to
+\texttt{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.}
+\twocolitem{\textbf{wxConvISO8859\_1}}{Conversion to and from ISO-8859-1 (Latin I)
+encoding.}
+\twocolitem{\textbf{wxConvUTF8}}{Conversion to and from UTF-8 encoding.}
+\twocolitem{\textbf{wxConvFile}}{The appropriate conversion for the file names,
+depends on the system.}
+% \twocolitem{\textbf{wxConvCurrent}}{Not really clear what is it for...}
+\end{twocollist}
+
+
+\wxheading{Constants}
+
+\texttt{wxCONV\_FAILED} value is defined as \texttt{(size\_t)$-1$} and is
+returned by the conversion functions instead of the length of the converted
+string if the conversion fails.
+
\wxheading{Derived from}
\helpref{wxEncodingConverter}{wxencodingconverter},
\helpref{wxMBConv classes overview}{mbconvclasses}
+
\latexignore{\rtfignore{\wxheading{Members}}}
\func{}{wxMBConv}{\void}
-Constructor.
+Trivial default constructor.
+
\membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}
-\constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t* }{buf}, \param{const char* }{psz}, \param{size\_t }{n}}
+\constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t *}{out}, \param{const char *}{in}, \param{size\_t }{outLen}}
+
+\deprecated{\helpref{ToWChar}{wxmbconvtowchar}}
+
+Converts from a string \arg{in} in multibyte encoding to Unicode putting up to
+\arg{outLen} characters into the buffer \arg{out}.
+
+If \arg{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 \emph{not} include the trailing \NUL. But
+when the function is called with a non-\NULL \arg{out} buffer, the \arg{outLen}
+parameter should be one more to allow to properly \NUL-terminate the string.
+
+\wxheading{Parameters}
+
+\docparam{out}{The output buffer, may be \NULL if the caller is only
+interested in the length of the resulting string}
+
+\docparam{in}{The \NUL-terminated input string, cannot be \NULL}
+
+\docparam{outLen}{The length of the output buffer but \emph{including}
+\NUL, ignored if \arg{out} is \NULL}
+
+\wxheading{Return value}
+
+The length of the converted string \emph{excluding} the trailing \NUL.
-Converts from multibyte encoding to Unicode, using the libc routine mbstowcs()
-(this is overridden by derived classes). Returns the size of the destination buffer.
\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, using the libc routine wcstombs()
-(this is overridden by derived classes). Returns the size of the destination buffer.
+\deprecated{\helpref{FromWChar}{wxmbconvfromwchar}}
+
+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-\NULL buffer, the
+{\it n} parameter should be the size of the buffer and so it \emph{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.
+
\membersection{wxMBConv::cMB2WC}\label{wxmbconvcmb2wc}
-\constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char* }{psz}}
+\constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char *}{in}}
+
+\constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char *}{in}, \param{size\_t }{inLen}, \param{size\_t }{*outLen}}
+
+Converts from multibyte encoding to Unicode by calling
+\helpref{MB2WC}{wxmbconvmb2wc}, 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 \helpref{MB2WC}{wxmbconvmb2wc}
+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 \helpref{GetMBNulLen}{wxmbconvgetmbnullen}),
+especially for long strings.
+
+If \arg{outLen} is not-\NULL, it receives the length of the converted
+string.
-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}}
+\constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{in}}
+
+\constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{in}, \param{size\_t }{inLen}, \param{size\_t }{*outLen}}
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 \arg{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 \helpref{cMB2WC}{wxmbconvmb2wc}, it is more
+efficient to pass an already terminated string to this function as otherwise a
+copy is made internally.
+
+If \arg{outLen} is not-\NULL, it receives the length of the converted
+string.
+
+
\membersection{wxMBConv::cMB2WX}\label{wxmbconvcmb2wx}
\constfunc{const char*}{cMB2WX}{\param{const char* }{psz}}
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}}
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}}
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}}
result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
return type (without const).
+
+\membersection{wxMBConv::FromWChar}\label{wxmbconvfromwchar}
+
+\constfunc{virtual size\_t}{FromWChar}{\param{wchar\_t *}{dst}, \param{size\_t }{dstLen}, \param{const char *}{src}, \param{size\_t }{srcLen = $-1$}}
+
+The most general function for converting a multibyte string to a wide string.
+The main case is when \arg{dst} is not \NULL and \arg{srcLen} is not $-1$: then
+the function converts exactly \arg{srcLen} bytes starting at \arg{src} into
+wide string which it output to \arg{dst}. If the length of the resulting wide
+string is greater than \arg{dstLen}, an error is returned. Note that if
+\arg{srcLen} bytes don't include \NUL characters, the resulting wide string is
+not \NUL-terminated neither.
+
+If \arg{srcLen} is $-1$, 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 \arg{dst} is \NULL, the function returns the length of the needed
+buffer.
+
+\wxheading{Return value}
+
+The number of characters written to \arg{dst} (or the number of characters
+which would have been written to it if it were non-\NULL) on success or
+\texttt{wxCONV\_FAILED} on error.
+
+
+\membersection{wxMBConv::GetMaxMBNulLen}\label{wxmbconvgetmaxmbnullen}
+
+\func{const size\_t}{GetMaxMBNulLen}{\void}
+
+Returns the maximal value which can be returned by
+\helpref{GetMBNulLen}{wxmbconvgetmbnullen} 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.
+
+
+\membersection{wxMBConv::GetMBNulLen}\label{wxmbconvgetmbnullen}
+
+\constfunc{size\_t}{GetMBNulLen}{\void}
+
+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 $-1$ is returned for them.
+
+
+\membersection{wxMBConv::ToWChar}\label{wxmbconvtowchar}
+
+\constfunc{virtual size\_t}{ToWChar}{\param{char\_t *}{dst}, \param{size\_t }{dstLen}, \param{const wchar\_t *}{src}, \param{size\_t }{srcLen = $-1$}}
+
+This function has the same semantics as \helpref{FromWChar}{wxmbconvfromwchar}
+except that it converts a wide string to multibyte one.
+
+
projects / wxWidgets.git / blobdiff