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