docs/latex/wx/mbconv.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        mbconv.tex
   3 %% Purpose:     wxMBConv documentation
   4 %% Author:      Ove Kaaven, Vadim Zeitlin
   5 %% Created:     2000-03-25
   6 %% RCS-ID:      $Id$
   7 %% Copyright:   (c) 2000 Ove Kaaven
   8 %%              (c) 2003-2006 Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12
  13 \section{\class{wxMBConv}}\label{wxmbconv}
  14
  15 This class is the base class of a hierarchy of classes capable of converting
  16 text strings between multibyte (SBCS or DBCS) encodings and Unicode.
  17
  18 In the documentation for this and related classes please notice that
  19 \emph{length} of the string refers to the number of characters in the string
  20 not counting the terminating \NUL, if any. While the \emph{size} of the string
  21 is the total number of bytes in the string, including any trailing {\NUL}s.
  22 Thus, length of wide character string \texttt{L"foo"} is $3$ while its size can
  23 be either $8$ or $16$ depending on whether \texttt{wchar\_t} is $2$ bytes (as
  24 under Windows) or $4$ (Unix).
  25
  26 \wxheading{Global variables}
  27
  28 There are several predefined instances of this class:
  29 \begin{twocollist}
  30 \twocolitem{\textbf{wxConvLibc}}{Uses the standard ANSI C \texttt{mbstowcs()} and
  31 \texttt{wcstombs()} functions to perform the conversions; thus depends on the
  32 current locale.}
  33 \twocolitem{\textbf{wxConvFile}}{The appropriate conversion for the file names,
  34 depends on the system.}
  35 \end{twocollist}
  36
  37 \wxheading{Derived from}
  38
  39 No base class
  40
  41 \wxheading{Include files}
  42
  43 <wx/strconv.h>
  44
  45 \wxheading{See also}
  46
  47 \helpref{wxCSConv}{wxcsconv},
  48 \helpref{wxEncodingConverter}{wxencodingconverter},
  49 \helpref{wxMBConv classes overview}{mbconvclasses}
  50
  51 \latexignore{\rtfignore{\wxheading{Members}}}
  52
  53
  54 \membersection{wxMBConv::wxMBConv}\label{wxmbconvwxmbconv}
  55
  56 \func{}{wxMBConv}{\void}
  57
  58 Constructor.
  59
  60 \membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}
  61
  62 \constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t *}{out}, \param{const char *}{in}, \param{size\_t }{outLen}}
  63
  64 Converts from a string \arg{in} in multibyte encoding to Unicode putting up to
  65 \arg{outLen} characters into the buffer \arg{out}.
  66
  67 If \arg{out} is \NULL, only the length of the string which would result from
  68 the conversion is calculated and returned. Note that this is the length and not
  69 size, i.e. the returned value does \emph{not} include the trailing \NUL. But
  70 when the function is called with a non-\NULL \arg{out} buffer, the \arg{outLen}
  71 parameter should be one more to allow to properly \NUL-terminate the string.
  72
  73 \wxheading{Parameters}
  74
  75 \docparam{out}{The output buffer, may be \NULL if the caller is only
  76 interested in the length of the resulting string}
  77
  78 \docparam{in}{The \NUL-terminated input string, cannot be \NULL}
  79
  80 \docparam{outLen}{The length of the output buffer but \emph{including}
  81 \NUL, ignored if \arg{out} is \NULL}
  82
  83 \wxheading{Return value}
  84
  85 The length of the converted string \emph{excluding} the trailing {\NUL}.
  86
  87
  88 \membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}
  89
  90 \constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}
  91
  92 Converts from Unicode to multibyte encoding. The semantics of this function
  93 (including the return value meaning) is the same as for
  94 \helpref{MB2WC}{wxmbconvmb2wc}.
  95
  96 Notice that when the function is called with a non-\NULL buffer, the
  97 {\it n} parameter should be the size of the buffer and so it \emph{should} take
  98 into account the trailing NUL, which might take two or four bytes for some
  99 encodings (UTF-16 and UTF-32) and not one.
 100
 101
 102 \membersection{wxMBConv::cMB2WC}\label{wxmbconvcmb2wc}
 103
 104 \constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char *}{in}}
 105
 106 \constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char *}{in}, \param{size\_t }{inLen}, \param{size\_t }{*outLen}}
 107
 108 Converts from multibyte encoding to Unicode by calling
 109 \helpref{MB2WC}{wxmbconvmb2wc}, allocating a temporary wxWCharBuffer to hold
 110 the result.
 111
 112 The first overload takes a \NUL-terminated input string. The second one takes a
 113 string of exactly the specified length and the string may include or not the
 114 trailing {\NUL}s. If the string is not \NUL-terminated, a temporary
 115 \NUL-terminated copy of it suitable for passing to \helpref{MB2WC}{wxmbconvmb2wc}
 116 is made, so it is more efficient to ensure that the string is does have the
 117 appropriate number of \NUL bytes (which is usually $1$ but may be $2$ or $4$
 118 for UTF-16 or UTF-32), especially for long strings.
 119
 120 If \arg{outLen} is not-\NULL, it receives the length of the converted
 121 string.
 122
 123
 124 \membersection{wxMBConv::cWC2MB}\label{wxmbconvcwc2mb}
 125
 126 \constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{in}}
 127
 128 \constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{in}, \param{size\_t }{inLen}, \param{size\_t }{*outLen}}
 129
 130 Converts from Unicode to multibyte encoding by calling WC2MB,
 131 allocating a temporary wxCharBuffer to hold the result.
 132
 133 The second overload of this function allows to convert a string of the given
 134 length \arg{inLen}, whether it is \NUL-terminated or not (for wide character
 135 strings, unlike for the multibyte ones, a single \NUL is always enough).
 136 But notice that just as with \helpref{cMB2WC}{wxmbconvmb2wc}, it is more
 137 efficient to pass an already terminated string to this function as otherwise a
 138 copy is made internally.
 139
 140 If \arg{outLen} is not-\NULL, it receives the length of the converted
 141 string.
 142
 143
 144 \membersection{wxMBConv::cMB2WX}\label{wxmbconvcmb2wx}
 145
 146 \constfunc{const char*}{cMB2WX}{\param{const char* }{psz}}
 147
 148 \constfunc{const wxWCharBuffer}{cMB2WX}{\param{const char* }{psz}}
 149
 150 Converts from multibyte encoding to the current wxChar type
 151 (which depends on whether wxUSE\_UNICODE is set to 1). If wxChar is char,
 152 it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
 153 result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct
 154 return type (without const).
 155
 156
 157 \membersection{wxMBConv::cWX2MB}\label{wxmbconvcwx2mb}
 158
 159 \constfunc{const char*}{cWX2MB}{\param{const wxChar* }{psz}}
 160
 161 \constfunc{const wxCharBuffer}{cWX2MB}{\param{const wxChar* }{psz}}
 162
 163 Converts from the current wxChar type to multibyte encoding. If wxChar is char,
 164 it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
 165 result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct
 166 return type (without const).
 167
 168
 169 \membersection{wxMBConv::cWC2WX}\label{wxmbconvcwc2wx}
 170
 171 \constfunc{const wchar\_t*}{cWC2WX}{\param{const wchar\_t* }{psz}}
 172
 173 \constfunc{const wxCharBuffer}{cWC2WX}{\param{const wchar\_t* }{psz}}
 174
 175 Converts from Unicode to the current wxChar type. If wxChar is wchar\_t,
 176 it returns the parameter unaltered. If wxChar is char, it returns the
 177 result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct
 178 return type (without const).
 179
 180
 181 \membersection{wxMBConv::cWX2WC}\label{wxmbconvcwx2wc}
 182
 183 \constfunc{const wchar\_t*}{cWX2WC}{\param{const wxChar* }{psz}}
 184
 185 \constfunc{const wxWCharBuffer}{cWX2WC}{\param{const wxChar* }{psz}}
 186
 187 Converts from the current wxChar type to Unicode. If wxChar is wchar\_t,
 188 it returns the parameter unaltered. If wxChar is char, it returns the
 189 result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
 190 return type (without const).
 191