]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/strconv.h
fix default argument values
[wxWidgets.git] / interface / wx / strconv.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: strconv.h
3// Purpose: interface of wxMBConvUTF7
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxMBConv
11
12 This class is the base class of a hierarchy of classes capable of
13 converting text strings between multibyte (SBCS or DBCS) encodings and
14 Unicode.
15
16 This is an abstract base class which defines the operations implemented by
17 all different conversion classes. The derived classes don't add any new
18 operations of their own (except, possibly, some non-default constructors)
19 and so you should simply use this class ToWChar() and FromWChar() (or
20 cMB2WC() and cWC2MB()) methods with the objects of the derived class.
21
22 In the documentation for this and related classes please notice that
23 length of the string refers to the number of characters in the string
24 not counting the terminating @c NUL, if any. While the size of the string
25 is the total number of bytes in the string, including any trailing @c NUL.
26 Thus, length of wide character string @c L"foo" is 3 while its size can
27 be either 8 or 16 depending on whether @c wchar_t is 2 bytes (as
28 under Windows) or 4 (Unix).
29
30 @library{wxbase}
31 @category{conv}
32
33 @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
34*/
35class wxMBConv
36{
37public:
38 /**
39 Trivial default constructor.
40 */
41 wxMBConv();
42
43 /**
44 This pure virtual function is overridden in each of the derived classes
45 to return a new copy of the object it is called on.
46
47 It is used for copying the conversion objects while preserving their
48 dynamic type.
49 */
50 virtual wxMBConv* Clone() const = 0;
51
52 /**
53 This function returns 1 for most of the multibyte encodings in which the
54 string is terminated by a single @c NUL, 2 for UTF-16 and 4 for UTF-32 for
55 which the string is terminated with 2 and 4 @c NUL characters respectively.
56 The other cases are not currently supported and @c wxCONV_FAILED
57 (defined as -1) is returned for them.
58 */
59 size_t GetMBNulLen() const;
60
61 /**
62 Returns the maximal value which can be returned by GetMBNulLen() for
63 any conversion object.
64
65 Currently this value is 4.
66
67 This method can be used to allocate the buffer with enough space for the
68 trailing @c NUL characters for any encoding.
69 */
70 const size_t GetMaxMBNulLen();
71
72 /**
73 Convert multibyte string to a wide character one.
74
75 This is the most general function for converting a multibyte string to
76 a wide string, cMB2WC() may be often more convenient, however this
77 function is the most efficient one as it allows to avoid any
78 unnecessary copying.
79
80 The main case is when @a dst is not @NULL and @a srcLen is not
81 @c wxNO_LEN (which is defined as @c (size_t)-1): then the function
82 converts exactly @a srcLen bytes starting at @a src into wide string
83 which it output to @e dst. If the length of the resulting wide
84 string is greater than @e dstLen, an error is returned. Note that if
85 @a srcLen bytes don't include @c NUL characters, the resulting wide
86 string is not @c NUL-terminated neither.
87
88 If @a srcLen is @c wxNO_LEN, the function supposes that the string is
89 properly (i.e. as necessary for the encoding handled by this
90 conversion) @c NUL-terminated and converts the entire string, including
91 any trailing @c NUL bytes. In this case the wide string is also @c
92 NUL-terminated.
93
94 Finally, if @a dst is @NULL, the function returns the length of the
95 needed buffer.
96
97 Example of use of this function:
98 @code
99 size_t dstLen = conv.ToWChar(NULL, 0, src);
100 if ( dstLen == wxCONV_FAILED )
101 ... handle error ...
102 wchar_t *dst = new wchar_t[dstLen];
103 if ( conv.ToWChar(dst, dstLen, src) == wxCONV_FAILED )
104 ... handle error ...
105 @endcode
106
107 Notice that when passing the explicit source length the output will
108 @e not be @c NUL terminated if you pass @c strlen(str) as parameter.
109 Either leave @a srcLen as default @c wxNO_LEN or add one to @c strlen
110 result if you want the output to be @c NUL terminated.
111
112 @param dst
113 Pointer to output buffer of the size of at least @a dstLen or @NULL.
114 @param dstLen
115 Maximal number of characters to be written to the output buffer if
116 @a dst is non-@NULL, unused otherwise.
117 @param src
118 Point to the source string, must not be @NULL.
119 @param
120 The number of characters of the source string to convert or @c
121 wxNO_LEN (default parameter) to convert everything up to and
122 including the terminating @c NUL character(s).
123 @return
124 The number of character written (or which would have been written
125 if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
126 */
127 virtual size_t ToWChar(wchar_t* dst, size_t dstLen,
128 const char* src,
129 size_t srcLen = wxNO_LEN) const;
130
131 /**
132 Converts wide character string to multibyte.
133
134 This function has the same semantics as ToWChar() except that it
135 converts a wide string to multibyte one. As with ToWChar(), it may be
136 more convenient to use cWC2MB() when working with @c NUL terminated
137 strings.
138
139 @param dst
140 Pointer to output buffer of the size of at least @a dstLen or @NULL.
141 @param dstLen
142 Maximal number of characters to be written to the output buffer if
143 @a dst is non-@NULL, unused otherwise.
144 @param src
145 Point to the source string, must not be @NULL.
146 @param
147 The number of characters of the source string to convert or @c
148 wxNO_LEN (default parameter) to convert everything up to and
149 including the terminating @c NUL character.
150 @return
151 The number of character written (or which would have been written
152 if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
153 */
154 virtual size_t FromWChar(char* dst, size_t dstLen,
155 const wchar_t* src,
156 size_t srcLen = wxNO_LEN) const;
157
158 /**
159 Converts from multibyte encoding to Unicode by calling ToWChar() and
160 allocating a temporary wxWCharBuffer to hold the result.
161
162 This function is a convenient wrapper around ToWChar() as it takes care
163 of allocating the buffer of the necessary size itself. Its parameters
164 have the same meaning as for ToWChar(), in particular @a inLen can be
165 specified explicitly in which case exactly that many characters are
166 converted and @a outLen receives (if non-@NULL) exactly the
167 corresponding number of wide characters, whether the last one of them
168 is @c NUL or not. However if @c inLen is @c wxNO_LEN, then @c outLen
169 doesn't count the trailing @c NUL even if it is always present in this
170 case.
171
172 Finally notice that if the conversion fails, the returned buffer is
173 invalid and @a outLen is set to 0 (and not @c wxCONV_FAILED for
174 compatibility concerns).
175 */
176 const wxWCharBuffer cMB2WC(const char* in,
177 size_t inLen = wxNO_LEN,
178 size_t *outLen = NULL) const;
179
180 //@{
181 /**
182 Converts from multibyte encoding to the current wxChar type (which
183 depends on whether wxUSE_UNICODE is set to 1).
184
185 If wxChar is char, it returns the parameter unaltered. If wxChar is
186 wchar_t, it returns the result in a wxWCharBuffer. The macro wxMB2WXbuf
187 is defined as the correct return type (without const).
188 */
189 const char* cMB2WX(const char* psz) const;
190 const wxWCharBuffer cMB2WX(const char* psz) const;
191 //@}
192
193 /**
194 Converts from Unicode to multibyte encoding by calling FromWChar() and
195 allocating a temporary wxCharBuffer to hold the result.
196
197 This function is a convenient wrapper around FromWChar() as it takes
198 care of allocating the buffer of necessary size itself.
199
200 Its parameters have the same meaning as the corresponding parameters of
201 FromWChar(), please see the description of cMB2WC() for more details.
202 */
203 const wxCharBuffer cWC2MB(const wchar_t* in,
204 size_t inLen = wxNO_LEN,
205 size_t *outLen = NULL) const;
206
207 //@{
208 /**
209 Converts from Unicode to the current wxChar type.
210
211 If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is
212 char, it returns the result in a wxCharBuffer. The macro wxWC2WXbuf is
213 defined as the correct return type (without const).
214 */
215 const wchar_t* cWC2WX(const wchar_t* psz) const;
216 const wxCharBuffer cWC2WX(const wchar_t* psz) const;
217 //@}
218
219 //@{
220 /**
221 Converts from the current wxChar type to multibyte encoding.
222
223 If wxChar is char, it returns the parameter unaltered. If wxChar is
224 wchar_t, it returns the result in a wxCharBuffer. The macro wxWX2MBbuf
225 is defined as the correct return type (without const).
226 */
227 const char* cWX2MB(const wxChar* psz) const;
228 const wxCharBuffer cWX2MB(const wxChar* psz) const;
229 //@}
230
231 //@{
232 /**
233 Converts from the current wxChar type to Unicode.
234
235 If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is
236 char, it returns the result in a wxWCharBuffer. The macro wxWX2WCbuf is
237 defined as the correct return type (without const).
238 */
239 const wchar_t* cWX2WC(const wxChar* psz) const;
240 const wxWCharBuffer cWX2WC(const wxChar* psz) const;
241 //@}
242
243 /**
244 @deprecated This function is deprecated, please use ToWChar() instead.
245
246 Converts from a string @a in in multibyte encoding to Unicode putting up to
247 @a outLen characters into the buffer @e out.
248
249 If @a out is @NULL, only the length of the string which would result
250 from the conversion is calculated and returned. Note that this is the
251 length and not size, i.e. the returned value does not include the
252 trailing @c NUL. But when the function is called with a non-@NULL @a
253 out buffer, the @a outLen parameter should be one more to allow to
254 properly @c NUL-terminate the string.
255
256 @param out
257 The output buffer, may be @NULL if the caller is only
258 interested in the length of the resulting string
259 @param in
260 The NUL-terminated input string, cannot be @NULL
261 @param outLen
262 The length of the output buffer but including
263 NUL, ignored if out is @NULL
264
265 @return The length of the converted string excluding the trailing NUL.
266 */
267 virtual size_t MB2WC(wchar_t* out, const char* in, size_t outLen) const;
268
269 /**
270 @deprecated This function is deprecated, please use FromWChar() instead.
271
272 Converts from Unicode to multibyte encoding.
273 The semantics of this function (including the return value meaning) is
274 the same as for wxMBConv::MB2WC. Notice that when the function is
275 called with a non-@NULL buffer, the @a n parameter should be the size
276 of the buffer and so it should take into account the trailing @c NUL,
277 which might take two or four bytes for some encodings (UTF-16 and
278 UTF-32) and not one.
279 */
280 virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const;
281};
282
283
284/**
285 @class wxMBConvUTF7
286
287 This class converts between the UTF-7 encoding and Unicode.
288 It has one predefined instance, @b wxConvUTF7.
289
290 Notice that, unlike all the other conversion objects, this converter is
291 stateful, i.e. it remembers its state from the last call to its ToWChar()
292 or FromWChar() and assumes it is called on the continuation of the same
293 string when the same method is called again. This assumption is only made
294 if an explicit length is specified as parameter to these functions as if an
295 entire @c NUL terminated string is processed the state doesn't need to be
296 remembered.
297
298 This also means that, unlike the other predefined conversion objects,
299 @b wxConvUTF7 is @em not thread-safe.
300
301 @library{wxbase}
302 @category{conv}
303
304 @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
305*/
306class wxMBConvUTF7 : public wxMBConv
307{
308};
309
310
311
312/**
313 @class wxMBConvUTF8
314
315 This class converts between the UTF-8 encoding and Unicode.
316 It has one predefined instance, @b wxConvUTF8.
317
318 @library{wxbase}
319 @category{conv}
320
321 @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview"
322*/
323class wxMBConvUTF8 : public wxMBConv
324{
325};
326
327
328
329/**
330 @class wxMBConvUTF16
331
332 This class is used to convert between multibyte encodings and UTF-16 Unicode
333 encoding (also known as UCS-2).
334
335 Unlike UTF-8 encoding, UTF-16 uses words and not bytes and hence depends
336 on the byte ordering: big or little endian. Hence this class is provided in
337 two versions: wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself
338 is just a typedef for one of them (native for the given platform, e.g. LE
339 under Windows and BE under Mac).
340
341 @library{wxbase}
342 @category{conv}
343
344 @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
345*/
346class wxMBConvUTF16 : public wxMBConv
347{
348};
349
350
351/**
352 @class wxMBConvUTF32
353
354 This class is used to convert between multibyte encodings and UTF-32
355 Unicode encoding (also known as UCS-4).
356 Unlike UTF-8 encoding, UTF-32 uses (double) words and not bytes and hence
357 depends on the byte ordering: big or little endian. Hence this class is
358 provided in two versions: wxMBConvUTF32LE and wxMBConvUTF32BE and
359 wxMBConvUTF32 itself is just a typedef for one of them (native for the
360 given platform, e.g. LE under Windows and BE under Mac).
361
362 @library{wxbase}
363 @category{conv}
364
365 @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview"
366*/
367class wxMBConvUTF32 : public wxMBConv
368{
369};
370
371
372
373
374/**
375 @class wxCSConv
376
377 This class converts between any character set supported by the system and
378 Unicode.
379
380 Please notice that this class uses system-provided conversion functions,
381 e.g. @c MultiByteToWideChar() and @c WideCharToMultiByte() under MSW and @c
382 iconv(3) under Unix systems and as such may support different encodings and
383 different encoding names on different platforms (although all relatively
384 common encodings are supported should be supported everywhere).
385
386 It has one predefined instance, @b wxConvLocal, for the default user
387 character set.
388
389 @library{wxbase}
390 @category{conv}
391
392 @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
393*/
394class wxCSConv : public wxMBConv
395{
396public:
397 /**
398 Constructor.
399
400 You can specify the name of the character set you want to convert
401 from/to. If the character set name is not recognized, ISO 8859-1 is
402 used as fall back, use IsOk() to test for this.
403
404 @param charset The name of the encoding, shouldn't be empty.
405 */
406 wxCSConv(const wxString& charset);
407
408 /**
409 Constructor.
410
411 You can specify an encoding constant for the character set you want to
412 convert from/to. Use IsOk() after construction to check whether the
413 encoding is supported by the current system.
414
415 @param encoding Any valid (i.e. not wxFONTENCODING_MAX) font encoding.
416 */
417 wxCSConv(wxFontEncoding encoding);
418
419 /**
420 Returns @true if the charset (or the encoding) given at constructor is
421 really available to use.
422
423 Returns @false if ISO 8859-1 will be used instead.
424
425 Note this does not mean that a given string will be correctly
426 converted. A malformed string may still make conversion functions
427 return @c wxCONV_FAILED.
428
429 @since 2.8.2
430 */
431 bool IsOk() const;
432};
433
434
435
436/**
437 @class wxMBConvFile
438
439 This class used to define the class instance @b wxConvFileName, but
440 nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms)
441 or wxConvUTF8 (on MacOS X).
442
443 @b wxConvFileName converts filenames between filesystem multibyte encoding
444 and Unicode. @b wxConvFileName can also be set to a something else at
445 run-time which is used e.g. by wxGTK to use a class which checks the
446 environment variable @b G_FILESYSTEM_ENCODING indicating that filenames
447 should not be interpreted as UTF8 and also for converting invalid UTF8
448 characters (e.g. if there is a filename in iso8859_1) to strings with octal
449 values.
450
451 Since some platforms (such as Win32) use Unicode in the filenames,
452 and others (such as Unix) use multibyte encodings, this class should only
453 be used directly if wxMBFILES is defined to 1. A convenience macro,
454 @c wxFNCONV, is defined to @c wxConvFileName->cWX2MB in this case. You
455 could use it like this:
456
457 @code
458 wxChar *name = wxT("rawfile.doc");
459 FILE *fil = fopen(wxFNCONV(name), "r");
460 @endcode
461
462 (although it would be better to just use wxFopen(name, "r") in this
463 particular case, you only need to use this class for functions taking file
464 names not wrapped by wxWidgets.)
465
466 @library{wxbase}
467 @category{conv}
468
469 @see @ref overview_mbconv "wxMBConv classes overview"
470*/
471class wxMBConvFile : public wxMBConv
472{
473public:
474};