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