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