X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e19971c37070ce13ed10fd9e6c72c7885daaa70f..d9605e634b503651fd349a3d2c6781b2407ea273:/docs/latex/wx/mbconv.tex diff --git a/docs/latex/wx/mbconv.tex b/docs/latex/wx/mbconv.tex index 8ff0e52809..22d7e99345 100644 --- a/docs/latex/wx/mbconv.tex +++ b/docs/latex/wx/mbconv.tex @@ -1,14 +1,57 @@ -% -% 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} @@ -24,6 +67,7 @@ No base class \helpref{wxEncodingConverter}{wxencodingconverter}, \helpref{wxMBConv classes overview}{mbconvclasses} + \latexignore{\rtfignore{\wxheading{Members}}} @@ -31,61 +75,98 @@ No base class \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}. -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. +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{buf}{the output buffer, may be {\tt NULL} if the caller is only +\docparam{out}{The output buffer, may be \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{in}{The \NUL-terminated input string, cannot be \NULL} -\docparam{n}{the size of the output buffer, ignored if {\it buf} is {\tt 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. +The length of the converted string \emph{excluding} the trailing \NUL. + \membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb} \constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}} +\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-{\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). +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}} @@ -98,6 +179,7 @@ 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}} @@ -109,6 +191,7 @@ 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}} @@ -120,6 +203,7 @@ 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}} @@ -131,3 +215,62 @@ 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). + +\membersection{wxMBConv::FromWChar}\label{wxmbconvfromwchar} + +\constfunc{virtual size\_t}{FromWChar}{\param{char\_t *}{dst}, \param{size\_t }{dstLen}, \param{const wchar\_t *}{src}, \param{size\_t }{srcLen = wxNO\_LEN}} + +This function has the same semantics as \helpref{ToWChar}{wxmbconvtowchar} +except that it converts a wide string to multibyte one. + +\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 \texttt{wxCONV\_FAILED} +(defined as $-1$) is returned for them. + + +\membersection{wxMBConv::ToWChar}\label{wxmbconvtowchar} + +\constfunc{virtual size\_t}{ToWChar}{\param{wchar\_t *}{dst}, \param{size\_t }{dstLen}, \param{const char *}{src}, \param{size\_t }{srcLen = wxNO\_LEN}} + +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 +\texttt{wxNO\_LEN} (which is defined as \texttt{(size\_t)$-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 \texttt{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 \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. + +