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.
  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{wxConvLocal}}{Another conversion corresponding to the
  34 current locale but this one uses the best available conversion.}
  35 \twocolitem{\textbf{wxConvISO8859\_1}}{Conversion to and from ISO-8859-1 (Latin I)
  36 encoding.}
  37 \twocolitem{\textbf{wxConvUTF8}}{Conversion to and from UTF-8 encoding.}
  38 \twocolitem{\textbf{wxConvFile}}{The appropriate conversion for the file names,
  39 depends on the system.}
  40 % \twocolitem{\textbf{wxConvCurrent}}{Not really clear what is it for...}
  41 \end{twocollist}
  42
  43
  44 \wxheading{Constants}
  45
  46 \texttt{wxCONV\_FAILED} value is defined as \texttt{(size\_t)$-1$} and is
  47 returned by the conversion functions instead of the length of the converted
  48 string if the conversion fails.
  49
  50
  51 \wxheading{Derived from}
  52
  53 No base class
  54
  55 \wxheading{Include files}
  56
  57 <wx/strconv.h>
  58
  59 \wxheading{See also}
  60
  61 \helpref{wxCSConv}{wxcsconv},
  62 \helpref{wxEncodingConverter}{wxencodingconverter},
  63 \helpref{wxMBConv classes overview}{mbconvclasses}
  64
  65
  66 \latexignore{\rtfignore{\wxheading{Members}}}
  67
  68
  69 \membersection{wxMBConv::wxMBConv}\label{wxmbconvwxmbconv}
  70
  71 \func{}{wxMBConv}{\void}
  72
  73 Trivial default constructor.
  74
  75
  76 \membersection{wxMBConv::MB2WC}\label{wxmbconvmb2wc}
  77
  78 \constfunc{virtual size\_t}{MB2WC}{\param{wchar\_t *}{out}, \param{const char *}{in}, \param{size\_t }{outLen}}
  79
  80 \deprecated{\helpref{ToWChar}{wxmbconvtowchar}}
  81
  82 Converts from a string \arg{in} in multibyte encoding to Unicode putting up to
  83 \arg{outLen} characters into the buffer \arg{out}.
  84
  85 If \arg{out} is \NULL, only the length of the string which would result from
  86 the conversion is calculated and returned. Note that this is the length and not
  87 size, i.e. the returned value does \emph{not} include the trailing \NUL. But
  88 when the function is called with a non-\NULL \arg{out} buffer, the \arg{outLen}
  89 parameter should be one more to allow to properly \NUL-terminate the string.
  90
  91 \wxheading{Parameters}
  92
  93 \docparam{out}{The output buffer, may be \NULL if the caller is only
  94 interested in the length of the resulting string}
  95
  96 \docparam{in}{The \NUL-terminated input string, cannot be \NULL}
  97
  98 \docparam{outLen}{The length of the output buffer but \emph{including}
  99 \NUL, ignored if \arg{out} is \NULL}
 100
 101 \wxheading{Return value}
 102
 103 The length of the converted string \emph{excluding} the trailing \NUL.
 104
 105
 106 \membersection{wxMBConv::WC2MB}\label{wxmbconvwc2mb}
 107
 108 \constfunc{virtual size\_t}{WC2MB}{\param{char* }{buf}, \param{const wchar\_t* }{psz}, \param{size\_t }{n}}
 109
 110 \deprecated{\helpref{FromWChar}{wxmbconvfromwchar}}
 111
 112 Converts from Unicode to multibyte encoding. The semantics of this function
 113 (including the return value meaning) is the same as for
 114 \helpref{MB2WC}{wxmbconvmb2wc}.
 115
 116 Notice that when the function is called with a non-\NULL buffer, the
 117 {\it n} parameter should be the size of the buffer and so it \emph{should} take
 118 into account the trailing \NUL, which might take two or four bytes for some
 119 encodings (UTF-16 and UTF-32) and not one.
 120
 121
 122 \membersection{wxMBConv::cMB2WC}\label{wxmbconvcmb2wc}
 123
 124 \constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char *}{in}}
 125
 126 \constfunc{const wxWCharBuffer}{cMB2WC}{\param{const char *}{in}, \param{size\_t }{inLen}, \param{size\_t }{*outLen}}
 127
 128 Converts from multibyte encoding to Unicode by calling
 129 \helpref{MB2WC}{wxmbconvmb2wc}, allocating a temporary wxWCharBuffer to hold
 130 the result.
 131
 132 The first overload takes a \NUL-terminated input string. The second one takes a
 133 string of exactly the specified length and the string may include or not the
 134 trailing \NUL character(s). If the string is not \NUL-terminated, a temporary
 135 \NUL-terminated copy of it suitable for passing to \helpref{MB2WC}{wxmbconvmb2wc}
 136 is made, so it is more efficient to ensure that the string is does have the
 137 appropriate number of \NUL bytes (which is usually $1$ but may be $2$ or $4$
 138 for UTF-16 or UTF-32, see \helpref{GetMBNulLen}{wxmbconvgetmbnullen}),
 139 especially for long strings.
 140
 141 If \arg{outLen} is not-\NULL, it receives the length of the converted
 142 string.
 143
 144
 145 \membersection{wxMBConv::cWC2MB}\label{wxmbconvcwc2mb}
 146
 147 \constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{in}}
 148
 149 \constfunc{const wxCharBuffer}{cWC2MB}{\param{const wchar\_t* }{in}, \param{size\_t }{inLen}, \param{size\_t }{*outLen}}
 150
 151 Converts from Unicode to multibyte encoding by calling WC2MB,
 152 allocating a temporary wxCharBuffer to hold the result.
 153
 154 The second overload of this function allows to convert a string of the given
 155 length \arg{inLen}, whether it is \NUL-terminated or not (for wide character
 156 strings, unlike for the multibyte ones, a single \NUL is always enough).
 157 But notice that just as with \helpref{cMB2WC}{wxmbconvmb2wc}, it is more
 158 efficient to pass an already terminated string to this function as otherwise a
 159 copy is made internally.
 160
 161 If \arg{outLen} is not-\NULL, it receives the length of the converted
 162 string.
 163
 164
 165 \membersection{wxMBConv::cMB2WX}\label{wxmbconvcmb2wx}
 166
 167 \constfunc{const char*}{cMB2WX}{\param{const char* }{psz}}
 168
 169 \constfunc{const wxWCharBuffer}{cMB2WX}{\param{const char* }{psz}}
 170
 171 Converts from multibyte encoding to the current wxChar type
 172 (which depends on whether wxUSE\_UNICODE is set to 1). If wxChar is char,
 173 it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
 174 result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct
 175 return type (without const).
 176
 177
 178 \membersection{wxMBConv::cWX2MB}\label{wxmbconvcwx2mb}
 179
 180 \constfunc{const char*}{cWX2MB}{\param{const wxChar* }{psz}}
 181
 182 \constfunc{const wxCharBuffer}{cWX2MB}{\param{const wxChar* }{psz}}
 183
 184 Converts from the current wxChar type to multibyte encoding. If wxChar is char,
 185 it returns the parameter unaltered. If wxChar is wchar\_t, it returns the
 186 result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct
 187 return type (without const).
 188
 189
 190 \membersection{wxMBConv::cWC2WX}\label{wxmbconvcwc2wx}
 191
 192 \constfunc{const wchar\_t*}{cWC2WX}{\param{const wchar\_t* }{psz}}
 193
 194 \constfunc{const wxCharBuffer}{cWC2WX}{\param{const wchar\_t* }{psz}}
 195
 196 Converts from Unicode to the current wxChar type. If wxChar is wchar\_t,
 197 it returns the parameter unaltered. If wxChar is char, it returns the
 198 result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct
 199 return type (without const).
 200
 201
 202 \membersection{wxMBConv::cWX2WC}\label{wxmbconvcwx2wc}
 203
 204 \constfunc{const wchar\_t*}{cWX2WC}{\param{const wxChar* }{psz}}
 205
 206 \constfunc{const wxWCharBuffer}{cWX2WC}{\param{const wxChar* }{psz}}
 207
 208 Converts from the current wxChar type to Unicode. If wxChar is wchar\_t,
 209 it returns the parameter unaltered. If wxChar is char, it returns the
 210 result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct
 211 return type (without const).
 212
 213
 214 \membersection{wxMBConv::FromWChar}\label{wxmbconvfromwchar}
 215
 216 \constfunc{virtual size\_t}{FromWChar}{\param{wchar\_t *}{dst}, \param{size\_t }{dstLen}, \param{const char *}{src}, \param{size\_t }{srcLen = $-1$}}
 217
 218 The most general function for converting a multibyte string to a wide string.
 219 The main case is when \arg{dst} is not \NULL and \arg{srcLen} is not $-1$: then
 220 the function converts exactly \arg{srcLen} bytes starting at \arg{src} into
 221 wide string which it output to \arg{dst}. If the length of the resulting wide
 222 string is greater than \arg{dstLen}, an error is returned. Note that if
 223 \arg{srcLen} bytes don't include \NUL characters, the resulting wide string is
 224 not \NUL-terminated neither.
 225
 226 If \arg{srcLen} is $-1$, the function supposes that the string is properly
 227 (i.e. as necessary for the encoding handled by this conversion) \NUL-terminated
 228 and converts the entire string, including any trailing \NUL bytes. In this case
 229 the wide string is also \NUL-terminated.
 230
 231 Finally, if \arg{dst} is \NULL, the function returns the length of the needed
 232 buffer.
 233
 234 \wxheading{Return value}
 235
 236 The number of characters written to \arg{dst} (or the number of characters
 237 which would have been written to it if it were non-\NULL) on success or
 238 \texttt{wxCONV\_FAILED} on error.
 239
 240
 241 \membersection{wxMBConv::GetMaxMBNulLen}\label{wxmbconvgetmaxmbnullen}
 242
 243 \func{const size\_t}{GetMaxMBNulLen}{\void}
 244
 245 Returns the maximal value which can be returned by
 246 \helpref{GetMBNulLen}{wxmbconvgetmbnullen} for any conversion object. Currently
 247 this value is $4$.
 248
 249 This method can be used to allocate the buffer with enough space for the
 250 trailing \NUL characters for any encoding.
 251
 252
 253 \membersection{wxMBConv::GetMBNulLen}\label{wxmbconvgetmbnullen}
 254
 255 \constfunc{size\_t}{GetMBNulLen}{\void}
 256
 257 This function returns $1$ for most of the multibyte encodings in which the
 258 string is terminated by a single \NUL, $2$ for UTF-16 and $4$ for UTF-32 for
 259 which the string is terminated with $2$ and $4$ \NUL characters respectively.
 260 The other cases are not currently supported and $-1$ is returned for them.
 261
 262
 263 \membersection{wxMBConv::ToWChar}\label{wxmbconvtowchar}
 264
 265 \constfunc{virtual size\_t}{ToWChar}{\param{char\_t *}{dst}, \param{size\_t }{dstLen}, \param{const wchar\_t *}{src}, \param{size\_t }{srcLen = $-1$}}
 266
 267 This function has the same semantics as \helpref{FromWChar}{wxmbconvfromwchar}
 268 except that it converts a wide string to multibyte one.
 269
 270