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