]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/strconv.h
no real changes, just reformat before starting really modifying
[wxWidgets.git] / interface / wx / strconv.h
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
34 */
35 class wxMBConv
36 {
37 public:
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 virtual 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 srcLen
120 The number of characters of the source string to convert or
121 @c wxNO_LEN (default parameter) to convert everything up to and
122 including the terminating @c NUL character(s).
123
124 @return
125 The number of character written (or which would have been written
126 if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
127 */
128 virtual size_t ToWChar(wchar_t* dst, size_t dstLen,
129 const char* src,
130 size_t srcLen = wxNO_LEN) const;
131
132 /**
133 Converts wide character string to multibyte.
134
135 This function has the same semantics as ToWChar() except that it
136 converts a wide string to multibyte one. As with ToWChar(), it may be
137 more convenient to use cWC2MB() when working with @c NUL terminated
138 strings.
139
140 @param dst
141 Pointer to output buffer of the size of at least @a dstLen or @NULL.
142 @param dstLen
143 Maximal number of characters to be written to the output buffer if
144 @a dst is non-@NULL, unused otherwise.
145 @param src
146 Point to the source string, must not be @NULL.
147 @param srcLen
148 The number of characters of the source string to convert or
149 @c wxNO_LEN (default parameter) to convert everything up to and
150 including the terminating @c NUL character.
151
152 @return
153 The number of character written (or which would have been written
154 if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error.
155 */
156 virtual size_t FromWChar(char* dst, size_t dstLen,
157 const wchar_t* src,
158 size_t srcLen = wxNO_LEN) const;
159
160 /**
161 Converts from multibyte encoding to Unicode by calling ToWChar() and
162 allocating a temporary wxWCharBuffer to hold the result.
163
164 This function is a convenient wrapper around ToWChar() as it takes care
165 of allocating the buffer of the necessary size itself. Its parameters
166 have the same meaning as for ToWChar(), in particular @a inLen can be
167 specified explicitly in which case exactly that many characters are
168 converted and @a outLen receives (if non-@NULL) exactly the
169 corresponding number of wide characters, whether the last one of them
170 is @c NUL or not. However if @c inLen is @c wxNO_LEN, then @c outLen
171 doesn't count the trailing @c NUL even if it is always present in this
172 case.
173
174 Finally notice that if the conversion fails, the returned buffer is
175 invalid and @a outLen is set to 0 (and not @c wxCONV_FAILED for
176 compatibility concerns).
177 */
178 const wxWCharBuffer cMB2WC(const char* in,
179 size_t inLen = wxNO_LEN,
180 size_t *outLen = NULL) const;
181
182 //@{
183 /**
184 Converts from multibyte encoding to the current wxChar type (which
185 depends on whether wxUSE_UNICODE is set to 1).
186
187 If wxChar is char, it returns the parameter unaltered. If wxChar is
188 wchar_t, it returns the result in a wxWCharBuffer. The macro wxMB2WXbuf
189 is defined as the correct return type (without const).
190 */
191 const char* cMB2WX(const char* psz) const;
192 const wxWCharBuffer cMB2WX(const char* psz) const;
193 //@}
194
195 /**
196 Converts from Unicode to multibyte encoding by calling FromWChar() and
197 allocating a temporary wxCharBuffer to hold the result.
198
199 This function is a convenient wrapper around FromWChar() as it takes
200 care of allocating the buffer of necessary size itself.
201
202 Its parameters have the same meaning as the corresponding parameters of
203 FromWChar(), please see the description of cMB2WC() for more details.
204 */
205 const wxCharBuffer cWC2MB(const wchar_t* in,
206 size_t inLen = wxNO_LEN,
207 size_t *outLen = NULL) const;
208
209 //@{
210 /**
211 Converts from Unicode to the current wxChar type.
212
213 If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is
214 char, it returns the result in a wxCharBuffer. The macro wxWC2WXbuf is
215 defined as the correct return type (without const).
216 */
217 const wchar_t* cWC2WX(const wchar_t* psz) const;
218 const wxCharBuffer cWC2WX(const wchar_t* psz) const;
219 //@}
220
221 //@{
222 /**
223 Converts from the current wxChar type to multibyte encoding.
224
225 If wxChar is char, it returns the parameter unaltered. If wxChar is
226 wchar_t, it returns the result in a wxCharBuffer. The macro wxWX2MBbuf
227 is defined as the correct return type (without const).
228 */
229 const char* cWX2MB(const wxChar* psz) const;
230 const wxCharBuffer cWX2MB(const wxChar* psz) const;
231 //@}
232
233 //@{
234 /**
235 Converts from the current wxChar type to Unicode.
236
237 If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is
238 char, it returns the result in a wxWCharBuffer. The macro wxWX2WCbuf is
239 defined as the correct return type (without const).
240 */
241 const wchar_t* cWX2WC(const wxChar* psz) const;
242 const wxWCharBuffer cWX2WC(const wxChar* psz) const;
243 //@}
244
245 /**
246 @deprecated This function is deprecated, please use ToWChar() instead.
247
248 Converts from a string @a in in multibyte encoding to Unicode putting up to
249 @a outLen characters into the buffer @e out.
250
251 If @a out is @NULL, only the length of the string which would result
252 from the conversion is calculated and returned. Note that this is the
253 length and not size, i.e. the returned value does not include the
254 trailing @c NUL. But when the function is called with a non-@NULL @a
255 out buffer, the @a outLen parameter should be one more to allow to
256 properly @c NUL-terminate the string.
257
258 So to properly use this function you need to write:
259 @code
260 size_t lenConv = conv.MB2WC(NULL, in, 0);
261 if ( lenConv == wxCONV_FAILED )
262 ... handle error ...
263 // allocate 1 more character for the trailing NUL and also pass
264 // the size of the buffer to the function now
265 wchar_t *out = new wchar_t[lenConv + 1];
266 if ( conv.MB2WC(out, in, lenConv + 1) == wxCONV_FAILED )
267 ... handle error ...
268 @endcode
269 For this and other reasons, ToWChar() is strongly recommended as a
270 replacement.
271
272 @param out
273 The output buffer, may be @NULL if the caller is only
274 interested in the length of the resulting string
275 @param in
276 The NUL-terminated input string, cannot be @NULL
277 @param outLen
278 The length of the output buffer but including
279 NUL, ignored if out is @NULL
280
281 @return The length of the converted string excluding the trailing NUL.
282 */
283 virtual size_t MB2WC(wchar_t* out, const char* in, size_t outLen) const;
284
285 /**
286 @deprecated This function is deprecated, please use FromWChar() instead.
287
288 Converts from Unicode to multibyte encoding.
289 The semantics of this function (including the return value meaning) is
290 the same as for wxMBConv::MB2WC. Notice that when the function is
291 called with a non-@NULL buffer, the @a n parameter should be the size
292 of the buffer and so it should take into account the trailing @c NUL,
293 which might take two or four bytes for some encodings (UTF-16 and
294 UTF-32) and not one, i.e. GetMBNulLen().
295 */
296 virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const;
297 };
298
299
300 /**
301 @class wxMBConvUTF7
302
303 This class converts between the UTF-7 encoding and Unicode.
304 It has one predefined instance, @b wxConvUTF7.
305
306 Notice that, unlike all the other conversion objects, this converter is
307 stateful, i.e. it remembers its state from the last call to its ToWChar()
308 or FromWChar() and assumes it is called on the continuation of the same
309 string when the same method is called again. This assumption is only made
310 if an explicit length is specified as parameter to these functions as if an
311 entire @c NUL terminated string is processed the state doesn't need to be
312 remembered.
313
314 This also means that, unlike the other predefined conversion objects,
315 @b wxConvUTF7 is @em not thread-safe.
316
317 @library{wxbase}
318 @category{conv}
319
320 @see wxMBConvUTF8, @ref overview_mbconv
321 */
322 class wxMBConvUTF7 : public wxMBConv
323 {
324 };
325
326
327
328 /**
329 @class wxMBConvUTF8
330
331 This class converts between the UTF-8 encoding and Unicode.
332 It has one predefined instance, @b wxConvUTF8.
333
334 @library{wxbase}
335 @category{conv}
336
337 @see wxMBConvUTF7, @ref overview_mbconv
338 */
339 class wxMBConvUTF8 : public wxMBConv
340 {
341 };
342
343
344
345 /**
346 @class wxMBConvUTF16
347
348 This class is used to convert between multibyte encodings and UTF-16 Unicode
349 encoding (also known as UCS-2).
350
351 Unlike UTF-8 encoding, UTF-16 uses words and not bytes and hence depends
352 on the byte ordering: big or little endian. Hence this class is provided in
353 two versions: wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself
354 is just a typedef for one of them (native for the given platform, e.g. LE
355 under Windows and BE under Mac).
356
357 @library{wxbase}
358 @category{conv}
359
360 @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
361 */
362 class wxMBConvUTF16 : public wxMBConv
363 {
364 };
365
366
367 /**
368 @class wxMBConvUTF32
369
370 This class is used to convert between multibyte encodings and UTF-32
371 Unicode encoding (also known as UCS-4).
372 Unlike UTF-8 encoding, UTF-32 uses (double) words and not bytes and hence
373 depends on the byte ordering: big or little endian. Hence this class is
374 provided in two versions: wxMBConvUTF32LE and wxMBConvUTF32BE and
375 wxMBConvUTF32 itself is just a typedef for one of them (native for the
376 given platform, e.g. LE under Windows and BE under Mac).
377
378 @library{wxbase}
379 @category{conv}
380
381 @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv
382 */
383 class wxMBConvUTF32 : public wxMBConv
384 {
385 };
386
387
388
389
390 /**
391 @class wxCSConv
392
393 This class converts between any character set supported by the system and
394 Unicode.
395
396 Please notice that this class uses system-provided conversion functions,
397 e.g. @c MultiByteToWideChar() and @c WideCharToMultiByte() under MSW and @c
398 iconv(3) under Unix systems and as such may support different encodings and
399 different encoding names on different platforms (although all relatively
400 common encodings are supported should be supported everywhere).
401
402 It has one predefined instance, @b wxConvLocal, for the default user
403 character set.
404
405 @library{wxbase}
406 @category{conv}
407
408 @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
409 */
410 class wxCSConv : public wxMBConv
411 {
412 public:
413 /**
414 Constructor.
415
416 You can specify the name of the character set you want to convert
417 from/to. If the character set name is not recognized, ISO 8859-1 is
418 used as fall back, use IsOk() to test for this.
419
420 @param charset The name of the encoding, shouldn't be empty.
421 */
422 wxCSConv(const wxString& charset);
423
424 /**
425 Constructor.
426
427 You can specify an encoding constant for the character set you want to
428 convert from/to. Use IsOk() after construction to check whether the
429 encoding is supported by the current system.
430
431 @param encoding Any valid (i.e. not wxFONTENCODING_MAX) font encoding.
432 */
433 wxCSConv(wxFontEncoding encoding);
434
435 /**
436 Returns @true if the charset (or the encoding) given at constructor is
437 really available to use.
438
439 Returns @false if ISO 8859-1 will be used instead.
440
441 Note this does not mean that a given string will be correctly
442 converted. A malformed string may still make conversion functions
443 return @c wxCONV_FAILED.
444
445 @since 2.8.2
446 */
447 bool IsOk() const;
448 };
449
450
451
452 /**
453 @class wxMBConvFile
454
455 This class used to define the class instance @b wxConvFileName, but
456 nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms)
457 or wxConvUTF8 (on MacOS X).
458
459 @b wxConvFileName converts filenames between filesystem multibyte encoding
460 and Unicode. @b wxConvFileName can also be set to a something else at
461 run-time which is used e.g. by wxGTK to use a class which checks the
462 environment variable @b G_FILESYSTEM_ENCODING indicating that filenames
463 should not be interpreted as UTF8 and also for converting invalid UTF8
464 characters (e.g. if there is a filename in iso8859_1) to strings with octal
465 values.
466
467 Since some platforms (such as Win32) use Unicode in the filenames,
468 and others (such as Unix) use multibyte encodings, this class should only
469 be used directly if wxMBFILES is defined to 1. A convenience macro,
470 @c wxFNCONV, is defined to @c wxConvFileName->cWX2MB in this case. You
471 could use it like this:
472
473 @code
474 wxChar *name = wxT("rawfile.doc");
475 FILE *fil = fopen(wxFNCONV(name), "r");
476 @endcode
477
478 (although it would be better to just use wxFopen(name, "r") in this
479 particular case, you only need to use this class for functions taking file
480 names not wrapped by wxWidgets.)
481
482 @library{wxbase}
483 @category{conv}
484
485 @see @ref overview_mbconv
486 */
487 class wxMBConvFile : public wxMBConv
488 {
489 public:
490 };