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 licence
   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
  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     virtual 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     static 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             @a dst is non-@NULL, unused otherwise.
 117         @param src
 118             Point to the source string, must not be @NULL.
 119         @param srcLen
 120             The number of characters of the source string to convert or
 121             @c wxNO_LEN (default parameter) to convert everything up to and
 122             including the terminating @c NUL character(s).
 123
 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, 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             @a dst is non-@NULL, unused otherwise.
 144         @param src
 145             Point to the source string, must not be @NULL.
 146         @param srcLen
 147             The number of characters of the source string to convert or
 148             @c wxNO_LEN (default parameter) to convert everything up to and
 149             including the terminating @c NUL character.
 150
 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, const wchar_t* src,
 156                              size_t srcLen = wxNO_LEN) const;
 157
 158     /**
 159         Converts from multibyte encoding to Unicode by calling ToWChar() and
 160         allocating a temporary wxWCharBuffer to hold the result.
 161
 162         This function is a convenient wrapper around ToWChar() as it takes care
 163         of allocating the buffer of the necessary size itself. Its parameters
 164         have the same meaning as for ToWChar(), in particular @a inLen can be
 165         specified explicitly in which case exactly that many characters are
 166         converted and @a outLen receives (if non-@NULL) exactly the
 167         corresponding number of wide characters, whether the last one of them
 168         is @c NUL or not. However if @c inLen is @c wxNO_LEN, then @c outLen
 169         doesn't count the trailing @c NUL even if it is always present in this
 170         case.
 171
 172         Finally notice that if the conversion fails, the returned buffer is
 173         invalid and @a outLen is set to 0 (and not @c wxCONV_FAILED for
 174         compatibility concerns).
 175     */
 176     const wxWCharBuffer cMB2WC(const char* in,
 177                                size_t inLen,
 178                                size_t *outLen) const;
 179
 180     /**
 181         Converts a char buffer to wide char one.
 182
 183         This is the most convenient and safest conversion function as you
 184         don't have to deal with the buffer lengths directly. Use it if the
 185         input buffer is known not to be empty or if you are sure that the
 186         conversion is going to succeed -- otherwise, use the overload above to
 187         be able to distinguish between empty input and conversion failure.
 188
 189         @return
 190             The buffer containing the converted text, empty if the input was
 191             empty or if the conversion failed.
 192
 193         @since 2.9.1
 194      */
 195     const wxWCharBuffer cMB2WC(const wxCharBuffer& buf) const;
 196
 197     //@{
 198     /**
 199         Converts from multibyte encoding to the current wxChar type (which
 200         depends on whether wxUSE_UNICODE is set to 1).
 201
 202         If wxChar is char, it returns the parameter unaltered. If wxChar is
 203         wchar_t, it returns the result in a wxWCharBuffer. The macro wxMB2WXbuf
 204         is defined as the correct return type (without const).
 205     */
 206     const char* cMB2WX(const char* psz) const;
 207     const wxWCharBuffer cMB2WX(const char* psz) const;
 208     //@}
 209
 210     /**
 211         Converts from Unicode to multibyte encoding by calling FromWChar() and
 212         allocating a temporary wxCharBuffer to hold the result.
 213
 214         This function is a convenient wrapper around FromWChar() as it takes
 215         care of allocating the buffer of necessary size itself.
 216
 217         Its parameters have the same meaning as the corresponding parameters of
 218         FromWChar(), please see the description of cMB2WC() for more details.
 219     */
 220     const wxCharBuffer cWC2MB(const wchar_t* in,
 221                               size_t inLen,
 222                               size_t *outLen) const;
 223
 224     /**
 225         Converts a wide char buffer to char one.
 226
 227         This is the most convenient and safest conversion function as you
 228         don't have to deal with the buffer lengths directly. Use it if the
 229         input buffer is known not to be empty or if you are sure that the
 230         conversion is going to succeed -- otherwise, use the overload above to
 231         be able to distinguish between empty input and conversion failure.
 232
 233         @return
 234             The buffer containing the converted text, empty if the input was
 235             empty or if the conversion failed.
 236
 237         @since 2.9.1
 238      */
 239     const wxCharBuffer cWC2MB(const wxWCharBuffer& buf) const;
 240
 241     //@{
 242     /**
 243         Converts from Unicode to the current wxChar type.
 244
 245         If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is
 246         char, it returns the result in a wxCharBuffer. The macro wxWC2WXbuf is
 247         defined as the correct return type (without const).
 248     */
 249     const wchar_t* cWC2WX(const wchar_t* psz) const;
 250     const wxCharBuffer cWC2WX(const wchar_t* psz) const;
 251     //@}
 252
 253     //@{
 254     /**
 255         Converts from the current wxChar type to multibyte encoding.
 256
 257         If wxChar is char, it returns the parameter unaltered. If wxChar is
 258         wchar_t, it returns the result in a wxCharBuffer. The macro wxWX2MBbuf
 259         is defined as the correct return type (without const).
 260     */
 261     const char* cWX2MB(const wxChar* psz) const;
 262     const wxCharBuffer cWX2MB(const wxChar* psz) const;
 263     //@}
 264
 265     //@{
 266     /**
 267         Converts from the current wxChar type to Unicode.
 268
 269         If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is
 270         char, it returns the result in a wxWCharBuffer. The macro wxWX2WCbuf is
 271         defined as the correct return type (without const).
 272     */
 273     const wchar_t* cWX2WC(const wxChar* psz) const;
 274     const wxWCharBuffer cWX2WC(const wxChar* psz) const;
 275     //@}
 276
 277     /**
 278         @deprecated This function is deprecated, please use ToWChar() instead.
 279
 280         Converts from a string @a in in multibyte encoding to Unicode putting up to
 281         @a outLen characters into the buffer @e out.
 282
 283         If @a out is @NULL, only the length of the string which would result
 284         from the conversion is calculated and returned. Note that this is the
 285         length and not size, i.e. the returned value does not include the
 286         trailing @c NUL. But when the function is called with a non-@NULL @a
 287         out buffer, the @a outLen parameter should be one more to allow to
 288         properly @c NUL-terminate the string.
 289
 290         So to properly use this function you need to write:
 291         @code
 292             size_t lenConv = conv.MB2WC(NULL, in, 0);
 293             if ( lenConv == wxCONV_FAILED )
 294                 ... handle error ...
 295             // allocate 1 more character for the trailing NUL and also pass
 296             // the size of the buffer to the function now
 297             wchar_t *out = new wchar_t[lenConv + 1];
 298             if ( conv.MB2WC(out, in, lenConv + 1) == wxCONV_FAILED )
 299                 ... handle error ...
 300         @endcode
 301         For this and other reasons, ToWChar() is strongly recommended as a
 302         replacement.
 303
 304         @param out
 305             The output buffer, may be @NULL if the caller is only
 306             interested in the length of the resulting string
 307         @param in
 308             The NUL-terminated input string, cannot be @NULL
 309         @param outLen
 310             The length of the output buffer but including
 311             NUL, ignored if out is @NULL
 312
 313         @return The length of the converted string excluding the trailing NUL.
 314     */
 315     virtual size_t MB2WC(wchar_t* out, const char* in, size_t outLen) const;
 316
 317     /**
 318         @deprecated This function is deprecated, please use FromWChar() instead.
 319
 320         Converts from Unicode to multibyte encoding.
 321         The semantics of this function (including the return value meaning) is
 322         the same as for wxMBConv::MB2WC. Notice that when the function is
 323         called with a non-@NULL buffer, the @a n parameter should be the size
 324         of the buffer and so it should take into account the trailing @c NUL,
 325         which might take two or four bytes for some encodings (UTF-16 and
 326         UTF-32) and not one, i.e. GetMBNulLen().
 327     */
 328     virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const;
 329 };
 330
 331
 332 /**
 333     @class wxMBConvUTF7
 334
 335     This class converts between the UTF-7 encoding and Unicode.
 336     It has one predefined instance, @b wxConvUTF7.
 337
 338     Notice that, unlike all the other conversion objects, this converter is
 339     stateful, i.e. it remembers its state from the last call to its ToWChar()
 340     or FromWChar() and assumes it is called on the continuation of the same
 341     string when the same method is called again. This assumption is only made
 342     if an explicit length is specified as parameter to these functions as if an
 343     entire @c NUL terminated string is processed the state doesn't need to be
 344     remembered.
 345
 346     This also means that, unlike the other predefined conversion objects,
 347     @b wxConvUTF7 is @em not thread-safe.
 348
 349     @library{wxbase}
 350     @category{conv}
 351
 352     @see wxMBConvUTF8, @ref overview_mbconv
 353 */
 354 class wxMBConvUTF7 : public wxMBConv
 355 {
 356 };
 357
 358
 359
 360 /**
 361     @class wxMBConvUTF8
 362
 363     This class converts between the UTF-8 encoding and Unicode.
 364     It has one predefined instance, @b wxConvUTF8.
 365
 366     @library{wxbase}
 367     @category{conv}
 368
 369     @see wxMBConvUTF7, @ref overview_mbconv
 370 */
 371 class wxMBConvUTF8 : public wxMBConv
 372 {
 373 };
 374
 375
 376
 377 /**
 378     @class wxMBConvUTF16
 379
 380     This class is used to convert between multibyte encodings and UTF-16 Unicode
 381     encoding (also known as UCS-2).
 382
 383     Unlike UTF-8 encoding, UTF-16 uses words and not bytes and hence depends
 384     on the byte ordering: big or little endian. Hence this class is provided in
 385     two versions: wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself
 386     is just a typedef for one of them (native for the given platform, e.g. LE
 387     under Windows and BE under Mac).
 388
 389     @library{wxbase}
 390     @category{conv}
 391
 392     @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
 393 */
 394 class wxMBConvUTF16 : public wxMBConv
 395 {
 396 };
 397
 398
 399 /**
 400     @class wxMBConvUTF32
 401
 402     This class is used to convert between multibyte encodings and UTF-32
 403     Unicode encoding (also known as UCS-4).
 404     Unlike UTF-8 encoding, UTF-32 uses (double) words and not bytes and hence
 405     depends on the byte ordering: big or little endian. Hence this class is
 406     provided in two versions: wxMBConvUTF32LE and wxMBConvUTF32BE and
 407     wxMBConvUTF32 itself is just a typedef for one of them (native for the
 408     given platform, e.g. LE under Windows and BE under Mac).
 409
 410     @library{wxbase}
 411     @category{conv}
 412
 413     @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv
 414 */
 415 class wxMBConvUTF32 : public wxMBConv
 416 {
 417 };
 418
 419
 420
 421
 422 /**
 423     @class wxCSConv
 424
 425     This class converts between any character set supported by the system and
 426     Unicode.
 427
 428     Please notice that this class uses system-provided conversion functions,
 429     e.g. @c MultiByteToWideChar() and @c WideCharToMultiByte() under MSW and @c
 430     iconv(3) under Unix systems and as such may support different encodings and
 431     different encoding names on different platforms (although all relatively
 432     common encodings are supported should be supported everywhere).
 433
 434     It has one predefined instance, @b wxConvLocal, for the default user
 435     character set.
 436
 437     @library{wxbase}
 438     @category{conv}
 439
 440     @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
 441 */
 442 class wxCSConv : public wxMBConv
 443 {
 444 public:
 445     /**
 446         Constructor.
 447
 448         You can specify the name of the character set you want to convert
 449         from/to. If the character set name is not recognized, ISO 8859-1 is
 450         used as fall back, use IsOk() to test for this.
 451
 452         @param charset The name of the encoding, shouldn't be empty.
 453     */
 454     wxCSConv(const wxString& charset);
 455
 456     /**
 457         Constructor.
 458
 459         You can specify an encoding constant for the character set you want to
 460         convert from/to. Use IsOk() after construction to check whether the
 461         encoding is supported by the current system.
 462
 463         @param encoding Any valid (i.e. not wxFONTENCODING_MAX) font encoding.
 464     */
 465     wxCSConv(wxFontEncoding encoding);
 466
 467     /**
 468         Returns @true if the charset (or the encoding) given at constructor is
 469         really available to use.
 470
 471         Returns @false if ISO 8859-1 will be used instead.
 472
 473         Note this does not mean that a given string will be correctly
 474         converted. A malformed string may still make conversion functions
 475         return @c wxCONV_FAILED.
 476
 477         @since 2.8.2
 478     */
 479     bool IsOk() const;
 480 };
 481
 482
 483
 484 /**
 485     @class wxMBConvFile
 486
 487     This class used to define the class instance @b wxConvFileName, but
 488     nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms)
 489     or wxConvUTF8 (on MacOS X).
 490
 491     @b wxConvFileName converts filenames between filesystem multibyte encoding
 492     and Unicode. @b wxConvFileName can also be set to a something else at
 493     run-time which is used e.g. by wxGTK to use a class which checks the
 494     environment variable @b G_FILESYSTEM_ENCODING indicating that filenames
 495     should not be interpreted as UTF8 and also for converting invalid UTF8
 496     characters (e.g. if there is a filename in iso8859_1) to strings with octal
 497     values.
 498
 499     Since some platforms (such as Win32) use Unicode in the filenames,
 500     and others (such as Unix) use multibyte encodings, this class should only
 501     be used directly if wxMBFILES is defined to 1. A convenience macro,
 502     @c wxFNCONV, is defined to @c wxConvFileName->cWX2MB in this case. You
 503     could use it like this:
 504
 505     @code
 506     wxChar *name = "rawfile.doc";
 507     FILE *fil = fopen(wxFNCONV(name), "r");
 508     @endcode
 509
 510     (although it would be better to just use wxFopen(name, "r") in this
 511     particular case, you only need to use this class for functions taking file
 512     names not wrapped by wxWidgets.)
 513
 514     @library{wxbase}
 515     @category{conv}
 516
 517     @see @ref overview_mbconv
 518 */
 519 class wxMBConvFile : public wxMBConv
 520 {
 521 public:
 522 };