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     Notice that, unlike all the other conversion objects, this converter is
 295     stateful, i.e. it remembers its state from the last call to its ToWChar()
 296     or FromWChar() and assumes it is called on the continuation of the same
 297     string when the same method is called again. This assumption is only made
 298     if an explicit length is specified as parameter to these functions as if an
 299     entire @c NUL terminated string is processed the state doesn't need to be
 300     remembered.
 301
 302     This also means that, unlike the other predefined conversion objects,
 303     @b wxConvUTF7 is @em not thread-safe.
 304
 305     @library{wxbase}
 306     @category{conv}
 307
 308     @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
 309 */
 310 class wxMBConvUTF7 : public wxMBConv
 311 {
 312 };
 313
 314
 315
 316 /**
 317     @class wxMBConvUTF8
 318     @wxheader{strconv.h}
 319
 320     This class converts between the UTF-8 encoding and Unicode.
 321     It has one predefined instance, @b wxConvUTF8.
 322
 323     @library{wxbase}
 324     @category{conv}
 325
 326     @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview"
 327 */
 328 class wxMBConvUTF8 : public wxMBConv
 329 {
 330 };
 331
 332
 333
 334 /**
 335     @class wxMBConvUTF16
 336     @wxheader{strconv.h}
 337
 338     This class is used to convert between multibyte encodings and UTF-16 Unicode
 339     encoding (also known as UCS-2).
 340
 341     Unlike UTF-8 encoding, UTF-16 uses words and not bytes and hence depends
 342     on the byte ordering: big or little endian. Hence this class is provided in
 343     two versions: wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself
 344     is just a typedef for one of them (native for the given platform, e.g. LE
 345     under Windows and BE under Mac).
 346
 347     @library{wxbase}
 348     @category{conv}
 349
 350     @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
 351 */
 352 class wxMBConvUTF16 : public wxMBConv
 353 {
 354 };
 355
 356
 357 /**
 358     @class wxMBConvUTF32
 359     @wxheader{strconv.h}
 360
 361     This class is used to convert between multibyte encodings and UTF-32
 362     Unicode encoding (also known as UCS-4).
 363     Unlike UTF-8 encoding, UTF-32 uses (double) words and not bytes and hence
 364     depends on the byte ordering: big or little endian. Hence this class is
 365     provided in two versions: wxMBConvUTF32LE and wxMBConvUTF32BE and
 366     wxMBConvUTF32 itself is just a typedef for one of them (native for the
 367     given platform, e.g. LE under Windows and BE under Mac).
 368
 369     @library{wxbase}
 370     @category{conv}
 371
 372     @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview"
 373 */
 374 class wxMBConvUTF32 : public wxMBConv
 375 {
 376 };
 377
 378
 379
 380
 381 /**
 382     @class wxCSConv
 383     @wxheader{strconv.h}
 384
 385     This class converts between any character set supported by the system and
 386     Unicode.
 387
 388     Please notice that this class uses system-provided conversion functions,
 389     e.g. @c MultiByteToWideChar() and @c WideCharToMultiByte() under MSW and @c
 390     iconv(3) under Unix systems and as such may support different encodings and
 391     different encoding names on different platforms (although all relatively
 392     common encodings are supported should be supported everywhere).
 393
 394     It has one predefined instance, @b wxConvLocal, for the default user
 395     character set.
 396
 397     @library{wxbase}
 398     @category{conv}
 399
 400     @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
 401 */
 402 class wxCSConv : public wxMBConv
 403 {
 404 public:
 405     /**
 406         Constructor.
 407
 408         You can specify the name of the character set you want to convert
 409         from/to. If the character set name is not recognized, ISO 8859-1 is
 410         used as fall back, use IsOk() to test for this.
 411
 412         @param charset The name of the encoding, shouldn't be empty.
 413     */
 414     wxCSConv(const wxString& charset);
 415
 416     /**
 417         Constructor.
 418
 419         You can specify an encoding constant for the character set you want to
 420         convert from/to. Use IsOk() after construction to check whether the
 421         encoding is supported by the current system.
 422
 423         @param encoding Any valid (i.e. not wxFONTENCODING_MAX) font encoding.
 424     */
 425     wxCSConv(wxFontEncoding encoding);
 426
 427     /**
 428         Returns @true if the charset (or the encoding) given at constructor is
 429         really available to use.
 430
 431         Returns @false if ISO 8859-1 will be used instead.
 432
 433         Note this does not mean that a given string will be correctly
 434         converted. A malformed string may still make conversion functions
 435         return @c wxCONV_FAILED.
 436
 437         @since 2.8.2
 438     */
 439     bool IsOk() const;
 440 };
 441
 442
 443
 444 /**
 445     @class wxMBConvFile
 446     @wxheader{strconv.h}
 447
 448     This class used to define the class instance @b wxConvFileName, but
 449     nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms)
 450     or wxConvUTF8 (on MacOS X).
 451
 452     @b wxConvFileName converts filenames between filesystem multibyte encoding
 453     and Unicode. @b wxConvFileName can also be set to a something else at
 454     run-time which is used e.g. by wxGTK to use a class which checks the
 455     environment variable @b G_FILESYSTEM_ENCODING indicating that filenames
 456     should not be interpreted as UTF8 and also for converting invalid UTF8
 457     characters (e.g. if there is a filename in iso8859_1) to strings with octal
 458     values.
 459
 460     Since some platforms (such as Win32) use Unicode in the filenames,
 461     and others (such as Unix) use multibyte encodings, this class should only
 462     be used directly if wxMBFILES is defined to 1. A convenience macro,
 463     @c wxFNCONV, is defined to @c wxConvFileName->cWX2MB in this case. You
 464     could use it like this:
 465
 466     @code
 467     wxChar *name = wxT("rawfile.doc");
 468     FILE *fil = fopen(wxFNCONV(name), "r");
 469     @endcode
 470
 471     (although it would be better to just use wxFopen(name, "r") in this
 472     particular case, you only need to use this class for functions taking file
 473     names not wrapped by wxWidgets.)
 474
 475     @library{wxbase}
 476     @category{conv}
 477
 478     @see @ref overview_mbconv "wxMBConv classes overview"
 479 */
 480 class wxMBConvFile : public wxMBConv
 481 {
 482 public:
 483 };