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