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