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