X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/328f5751e8a06727b137189fe04891a9f43bfc8b..e98e625cbbe269f109b2296a045a657cba00fede:/interface/strconv.h?ds=inline diff --git a/interface/strconv.h b/interface/strconv.h index 7e76e2125a..1843a27e13 100644 --- a/interface/strconv.h +++ b/interface/strconv.h @@ -1,214 +1,356 @@ ///////////////////////////////////////////////////////////////////////////// // Name: strconv.h -// Purpose: documentation for wxMBConvUTF7 class +// Purpose: interface of wxMBConvUTF7 // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// /** - @class wxMBConvUTF7 + @class wxMBConv @wxheader{strconv.h} - This class converts between the UTF-7 encoding and Unicode. - It has one predefined instance, @b wxConvUTF7. + This class is the base class of a hierarchy of classes capable of + converting text strings between multibyte (SBCS or DBCS) encodings and + Unicode. + + This is an abstract base class which defines the operations implemented by + all different conversion classes. The derived classes don't add any new + operations of their own (except, possibly, some non-default constructors) + and so you should simply use this class ToWChar() and FromWChar() (or + cMB2WC() and cWC2MB()) methods with the objects of the derived class. - @b WARNING: this class is not implemented yet. + In the documentation for this and related classes please notice that + length of the string refers to the number of characters in the string + not counting the terminating @c NUL, if any. While the size of the string + is the total number of bytes in the string, including any trailing @c NUL. + Thus, length of wide character string @c L"foo" is 3 while its size can + be either 8 or 16 depending on whether @c wchar_t is 2 bytes (as + under Windows) or 4 (Unix). @library{wxbase} - @category{FIXME} + @category{conv} - @seealso - wxMBConvUTF8, @ref overview_mbconvclasses "wxMBConv classes overview" + @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" */ -class wxMBConvUTF7 : public wxMBConv +class wxMBConv { public: /** - Converts from UTF-7 encoding to Unicode. Returns the size of the destination - buffer. + Trivial default constructor. */ - size_t MB2WC(wchar_t* buf, const char* psz, size_t n) const; + wxMBConv(); /** - Converts from Unicode to UTF-7 encoding. Returns the size of the destination - buffer. - */ - size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; -}; + This pure virtual function is overridden in each of the derived classes + to return a new copy of the object it is called on. + It is used for copying the conversion objects while preserving their + dynamic type. + */ + virtual wxMBConv* Clone() const = 0; -/** - @class wxMBConvUTF8 - @wxheader{strconv.h} - - This class converts between the UTF-8 encoding and Unicode. - It has one predefined instance, @b wxConvUTF8. - - @library{wxbase} - @category{FIXME} - - @seealso - wxMBConvUTF7, @ref overview_mbconvclasses "wxMBConv classes overview" -*/ -class wxMBConvUTF8 : public wxMBConv -{ -public: /** - Converts from UTF-8 encoding to Unicode. Returns the size of the destination - buffer. + This function returns 1 for most of the multibyte encodings in which the + string is terminated by a single @c NUL, 2 for UTF-16 and 4 for UTF-32 for + which the string is terminated with 2 and 4 @c NUL characters respectively. + The other cases are not currently supported and @c wxCONV_FAILED + (defined as -1) is returned for them. */ - size_t MB2WC(wchar_t* buf, const char* psz, size_t n) const; + size_t GetMBNulLen() const; /** - Converts from Unicode to UTF-8 encoding. Returns the size of the destination - buffer. + Returns the maximal value which can be returned by GetMBNulLen() for + any conversion object. + + Currently this value is 4. + + This method can be used to allocate the buffer with enough space for the + trailing @c NUL characters for any encoding. */ - size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; -}; + const size_t GetMaxMBNulLen(); + /** + Convert multibyte string to a wide character one. -/** - @class wxMBConvUTF16 - @wxheader{strconv.h} + This is the most general function for converting a multibyte string to + a wide string, cMB2WC() may be often more convenient, however this + function is the most efficient one as it allows to avoid any + unnecessary copying. - This class is used to convert between multibyte encodings and UTF-16 Unicode - encoding (also known as UCS-2). Unlike UTF-8 encoding, - UTF-16 uses words and not bytes and hence depends on the byte ordering: - big or little endian. Hence this class is provided in two versions: - wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself is just a typedef - for one of them (native for the given platform, e.g. LE under Windows and BE - under Mac). + The main case is when @a dst is not @NULL and @a srcLen is not + @c wxNO_LEN (which is defined as @c (size_t)-1): then the function + converts exactly @a srcLen bytes starting at @a src into wide string + which it output to @e dst. If the length of the resulting wide + string is greater than @e dstLen, an error is returned. Note that if + @a srcLen bytes don't include @c NUL characters, the resulting wide + string is not @c NUL-terminated neither. - @library{wxbase} - @category{FIXME} + If @a srcLen is @c wxNO_LEN, the function supposes that the string is + properly (i.e. as necessary for the encoding handled by this + conversion) @c NUL-terminated and converts the entire string, including + any trailing @c NUL bytes. In this case the wide string is also @c + NUL-terminated. + + Finally, if @a dst is @NULL, the function returns the length of the + needed buffer. + + Example of use of this function: + @code + size_t dstLen = conv.ToWChar(NULL, 0, src); + if ( dstLen == wxCONV_FAILED ) + ... handle error ... + wchar_t *dst = new wchar_t[dstLen]; + if ( conv.ToWChar(dst, dstLen, src) == wxCONV_FAILED ) + ... handle error ... + @endcode + + Notice that when passing the explicit source length the output will + @e not be @c NUL terminated if you pass @c strlen(str) as parameter. + Either leave @a srcLen as default @c wxNO_LEN or add one to @c strlen + result if you want the output to be @c NUL terminated. + + @param dst + Pointer to output buffer of the size of at least @a dstLen or @NULL. + @param dstLen + Maximal number of characters to be written to the output buffer if + @dst is non-@NULL, unused otherwise. + @param src + Point to the source string, must not be @NULL. + @param + The number of characters of the source string to convert or @c + wxNO_LEN (default parameter) to convert everything up to and + including the terminating @c NUL character(s). + @return + The number of character written (or which would have been written + if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. + */ + virtual size_t ToWChar(wchar_t* dst, size_t dstLen, + const char* src, + size_t srcLen = wxNO_LEN) const; - @seealso - wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconvclasses "wxMBConv classes - overview" -*/ -class wxMBConvUTF16 : public wxMBConv -{ -public: /** - Converts from UTF-16 encoding to Unicode. Returns the size of the destination - buffer. + Converts wide character string to multibyte. + + This function has the same semantics as ToWChar() except that it + converts a wide string to multibyte one. As with ToWChar(), it may be + more convenient to use cWC2MB() when working with @c NUL terminated + strings. + + @param dst + Pointer to output buffer of the size of at least @a dstLen or @NULL. + @param dstLen + Maximal number of characters to be written to the output buffer if + @dst is non-@NULL, unused otherwise. + @param src + Point to the source string, must not be @NULL. + @param + The number of characters of the source string to convert or @c + wxNO_LEN (default parameter) to convert everything up to and + including the terminating @c NUL character. + @return + The number of character written (or which would have been written + if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. */ - size_t MB2WC(wchar_t* buf, const char* psz, size_t n) const; + virtual size_t FromWChar(char* dst, size_t dstLen, + const wchar_t* src, + size_t srcLen = wxNO_LEN) const; + //@{ /** - Converts from Unicode to UTF-16 encoding. Returns the size of the destination - buffer. + Converts from multibyte encoding to Unicode by calling MB2WC() and + allocating a temporary wxWCharBuffer to hold the result. + + The first overload takes a @c NUL-terminated input string. The second + one takes a string of exactly the specified length and the string may + include or not the trailing @c NUL character(s). If the string is not + @c NUL-terminated, a temporary @c NUL-terminated copy of it suitable + for passing to wxMBConv::MB2WC is made, so it is more efficient to + ensure that the string is does have the appropriate number of @c NUL + bytes (which is usually 1 but may be 2 or 4 for UTF-16 or UTF-32, see + wxMBConv::GetMBNulLen), especially for long strings. + + If @a outLen is not-@NULL, it receives the length of the converted + string. */ - size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; -}; + const wxWCharBuffer cMB2WC(const char* in) const; + const wxWCharBuffer cMB2WC(const char* in, size_t inLen, size_t *outLen) const; + //@} + //@{ + /** + Converts from multibyte encoding to the current wxChar type (which + depends on whether wxUSE_UNICODE is set to 1). -/** - @class wxCSConv - @wxheader{strconv.h} + If wxChar is char, it returns the parameter unaltered. If wxChar is + wchar_t, it returns the result in a wxWCharBuffer. The macro wxMB2WXbuf + is defined as the correct return type (without const). + */ + const char* cMB2WX(const char* psz) const; + const wxWCharBuffer cMB2WX(const char* psz) const; + //@} - This class converts between any character sets and Unicode. - It has one predefined instance, @b wxConvLocal, for the - default user character set. + //@{ + /** + Converts from Unicode to multibyte encoding by calling WC2MB and + allocating a temporary wxCharBuffer to hold the result. - @library{wxbase} - @category{FIXME} + The second overload of this function allows to convert a string of the + given length @e inLen, whether it is @c NUL-terminated or not (for wide + character strings, unlike for the multibyte ones, a single @c NUL is + always enough). But notice that just as with @ref wxMBConv::mb2wc + cMB2WC, it is more efficient to pass an already terminated string to + this function as otherwise a copy is made internally. If @a outLen is + not-@NULL, it receives the length of the converted string. + */ + const wxCharBuffer cWC2MB(const wchar_t* in) const; + const wxCharBuffer cWC2MB(const wchar_t* in, size_t inLen, size_t *outLen) const; + //@} - @seealso - wxMBConv, wxEncodingConverter, @ref overview_mbconvclasses "wxMBConv classes - overview" -*/ -class wxCSConv : public wxMBConv -{ -public: //@{ /** - Constructor. You may specify either the name of the character set you want to - convert from/to or an encoding constant. If the character set name (or the - encoding) is not recognized, ISO 8859-1 is used as fall back. + Converts from Unicode to the current wxChar type. + + If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is + char, it returns the result in a wxCharBuffer. The macro wxWC2WXbuf is + defined as the correct return type (without const). */ - wxCSConv(const wxChar* charset); - wxCSConv(wxFontEncoding encoding); + const wchar_t* cWC2WX(const wchar_t* psz) const; + const wxCharBuffer cWC2WX(const wchar_t* psz) const; //@} + //@{ /** - Destructor frees any resources needed to perform the conversion. + Converts from the current wxChar type to multibyte encoding. + + If wxChar is char, it returns the parameter unaltered. If wxChar is + wchar_t, it returns the result in a wxCharBuffer. The macro wxWX2MBbuf + is defined as the correct return type (without const). */ - ~wxCSConv(); + const char* cWX2MB(const wxChar* psz) const; + const wxCharBuffer cWX2MB(const wxChar* psz) const; + //@} + //@{ /** - Returns @true if the charset (or the encoding) given at constructor is really - available to use. Returns @false if ISO 8859-1 will be used instead. - Note this does not mean that a given string will be correctly converted. - A malformed string may still make conversion functions return @c wxCONV_FAILED. - This function is new since wxWidgets version 2.8.2 + Converts from the current wxChar type to Unicode. + + If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is + char, it returns the result in a wxWCharBuffer. The macro wxWX2WCbuf is + defined as the correct return type (without const). */ - bool IsOk() const; + const wchar_t* cWX2WC(const wxChar* psz) const; + const wxWCharBuffer cWX2WC(const wxChar* psz) const; + //@} /** - Converts from the selected character set to Unicode. Returns length of string - written to destination buffer. + @deprecated This function is deprecated, please use ToWChar() instead. + + Converts from a string @a in in multibyte encoding to Unicode putting up to + @a outLen characters into the buffer @e out. + + If @a out is @NULL, only the length of the string which would result + from the conversion is calculated and returned. Note that this is the + length and not size, i.e. the returned value does not include the + trailing @c NUL. But when the function is called with a non-@NULL @a + out buffer, the @a outLen parameter should be one more to allow to + properly @c NUL-terminate the string. + + @param out + The output buffer, may be @NULL if the caller is only + interested in the length of the resulting string + @param in + The NUL-terminated input string, cannot be @NULL + @param outLen + The length of the output buffer but including + NUL, ignored if out is @NULL + + @return The length of the converted string excluding the trailing NUL. */ - size_t MB2WC(wchar_t* buf, const char* psz, size_t n) const; + virtual size_t MB2WC(wchar_t* out, const char* in, size_t outLen) const; /** - Converts from Unicode to the selected character set. Returns length of string - written to destination buffer. + @deprecated This function is deprecated, please use FromWChar() instead. + + Converts from Unicode to multibyte encoding. + The semantics of this function (including the return value meaning) is + the same as for wxMBConv::MB2WC. Notice that when the function is + called with a non-@NULL buffer, the @a n parameter should be the size + of the buffer and so it should take into account the trailing @c NUL, + which might take two or four bytes for some encodings (UTF-16 and + UTF-32) and not one. */ - size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; + virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; }; /** - @class wxMBConvFile + @class wxMBConvUTF7 @wxheader{strconv.h} - This class used to define the class instance - @b wxConvFileName, but nowadays @b wxConvFileName is - either of type wxConvLibc (on most platforms) or wxConvUTF8 - (on MacOS X). @b wxConvFileName converts filenames between - filesystem multibyte encoding and Unicode. @b wxConvFileName - can also be set to a something else at run-time which is used - e.g. by wxGTK to use a class which checks the environment - variable @b G_FILESYSTEM_ENCODING indicating that filenames - should not be interpreted as UTF8 and also for converting - invalid UTF8 characters (e.g. if there is a filename in iso8859_1) - to strings with octal values. + This class converts between the UTF-7 encoding and Unicode. + It has one predefined instance, @b wxConvUTF7. - Since some platforms (such as Win32) use Unicode in the filenames, - and others (such as Unix) use multibyte encodings, this class should only - be used directly if wxMBFILES is defined to 1. A convenience macro, - wxFNCONV, is defined to wxConvFileName-cWX2MB in this case. You could - use it like this: + Notice that, unlike all the other conversion objects, this converter is + stateful, i.e. it remembers its state from the last call to its ToWChar() + or FromWChar() and assumes it is called on the continuation of the same + string when the same method is called again. This assumption is only made + if an explicit length is specified as parameter to these functions as if an + entire @c NUL terminated string is processed the state doesn't need to be + remembered. - @code - wxChar *name = wxT("rawfile.doc"); - FILE *fil = fopen(wxFNCONV(name), "r"); - @endcode + This also means that, unlike the other predefined conversion objects, + @b wxConvUTF7 is @em not thread-safe. + + @library{wxbase} + @category{conv} + + @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvUTF7 : public wxMBConv +{ +}; - (although it would be better to use wxFopen(name, wxT("r")) in this case.) + + +/** + @class wxMBConvUTF8 + @wxheader{strconv.h} + + This class converts between the UTF-8 encoding and Unicode. + It has one predefined instance, @b wxConvUTF8. @library{wxbase} - @category{FIXME} + @category{conv} - @seealso - @ref overview_mbconvclasses "wxMBConv classes overview" + @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview" */ -class wxMBConvFile : public wxMBConv +class wxMBConvUTF8 : public wxMBConv { -public: - /** - Converts from multibyte filename encoding to Unicode. Returns the size of the - destination buffer. - */ - size_t MB2WC(wchar_t* buf, const char* psz, size_t n) const; +}; - /** - Converts from Unicode to multibyte filename encoding. Returns the size of the - destination buffer. - */ - size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; + + +/** + @class wxMBConvUTF16 + @wxheader{strconv.h} + + This class is used to convert between multibyte encodings and UTF-16 Unicode + encoding (also known as UCS-2). + + Unlike UTF-8 encoding, UTF-16 uses words and not bytes and hence depends + on the byte ordering: big or little endian. Hence this class is provided in + two versions: wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself + is just a typedef for one of them (native for the given platform, e.g. LE + under Windows and BE under Mac). + + @library{wxbase} + @category{conv} + + @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvUTF16 : public wxMBConv +{ }; @@ -216,242 +358,126 @@ public: @class wxMBConvUTF32 @wxheader{strconv.h} - This class is used to convert between multibyte encodings and UTF-32 Unicode - encoding (also known as UCS-4). Unlike UTF-8 encoding, - UTF-32 uses (double) words and not bytes and hence depends on the byte ordering: - big or little endian. Hence this class is provided in two versions: - wxMBConvUTF32LE and wxMBConvUTF32BE and wxMBConvUTF32 itself is just a typedef - for one of them (native for the given platform, e.g. LE under Windows and BE - under Mac). + This class is used to convert between multibyte encodings and UTF-32 + Unicode encoding (also known as UCS-4). + Unlike UTF-8 encoding, UTF-32 uses (double) words and not bytes and hence + depends on the byte ordering: big or little endian. Hence this class is + provided in two versions: wxMBConvUTF32LE and wxMBConvUTF32BE and + wxMBConvUTF32 itself is just a typedef for one of them (native for the + given platform, e.g. LE under Windows and BE under Mac). @library{wxbase} - @category{FIXME} + @category{conv} - @seealso - wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconvclasses "wxMBConv classes - overview" + @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview" */ class wxMBConvUTF32 : public wxMBConv { -public: - /** - Converts from UTF-32 encoding to Unicode. Returns the size of the destination - buffer. - */ - size_t MB2WC(wchar_t* buf, const char* psz, size_t n) const; - - /** - Converts from Unicode to UTF-32 encoding. Returns the size of the destination - buffer. - */ - size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; }; + + /** - @class wxMBConv + @class wxCSConv @wxheader{strconv.h} - This class is the base class of a hierarchy of classes capable of converting - text strings between multibyte (SBCS or DBCS) encodings and Unicode. + This class converts between any character set supported by the system and + Unicode. - In the documentation for this and related classes please notice that - length of the string refers to the number of characters in the string - not counting the terminating @c NUL, if any. While the size of the string - is the total number of bytes in the string, including any trailing @c NUL. - Thus, length of wide character string @c L"foo" is 3 while its size can - be either 8 or 16 depending on whether @c wchar_t is 2 bytes (as - under Windows) or 4 (Unix). + Please notice that this class uses system-provided conversion functions, + e.g. @c MultiByteToWideChar() and @c WideCharToMultiByte() under MSW and @c + iconv(3) under Unix systems and as such may support different encodings and + different encoding names on different platforms (although all relatively + common encodings are supported should be supported everywhere). + + It has one predefined instance, @b wxConvLocal, for the default user + character set. @library{wxbase} - @category{FIXME} + @category{conv} - @seealso - wxCSConv, wxEncodingConverter, @ref overview_mbconvclasses "wxMBConv classes - overview" + @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" */ -class wxMBConv +class wxCSConv : public wxMBConv { public: /** - Trivial default constructor. - */ - wxMBConv(); + Constructor. - /** - This pure virtual function is overridden in each of the derived classes to - return a new copy of the object it is called on. It is used for copying the - conversion objects while preserving their dynamic type. - */ - virtual wxMBConv* Clone() const; + You can specify the name of the character set you want to convert + from/to. If the character set name is not recognized, ISO 8859-1 is + used as fall back, use IsOk() to test for this. - /** - This function has the same semantics as ToWChar() - except that it converts a wide string to multibyte one. + @param charset The name of the encoding, shouldn't be empty. */ - virtual size_t FromWChar(char* dst, size_t dstLen, - const wchar_t* src, - size_t srcLen = wxNO_LEN) const; + wxCSConv(const wxString& charset); /** - This function returns 1 for most of the multibyte encodings in which the - string is terminated by a single @c NUL, 2 for UTF-16 and 4 for UTF-32 for - which the string is terminated with 2 and 4 @c NUL characters respectively. - The other cases are not currently supported and @c wxCONV_FAILED - (defined as -1) is returned for them. - */ - size_t GetMBNulLen() const; + Constructor. - /** - Returns the maximal value which can be returned by - GetMBNulLen() for any conversion object. Currently - this value is 4. - This method can be used to allocate the buffer with enough space for the - trailing @c NUL characters for any encoding. - */ - const size_t GetMaxMBNulLen(); + You can specify an encoding constant for the character set you want to + convert from/to. Use IsOk() after construction to check whether the + encoding is supported by the current system. - /** - This function is deprecated, please use ToWChar() instead - Converts from a string @a in in multibyte encoding to Unicode putting up to - @a outLen characters into the buffer @e out. - If @a out is @NULL, only the length of the string which would result from - the conversion is calculated and returned. Note that this is the length and not - size, i.e. the returned value does not include the trailing @c NUL. But - when the function is called with a non-@NULL @a out buffer, the @a outLen - parameter should be one more to allow to properly @c NUL-terminate the string. - - @param out - The output buffer, may be @NULL if the caller is only - interested in the length of the resulting string - @param in - The NUL-terminated input string, cannot be @NULL - @param outLen - The length of the output buffer but including - NUL, ignored if out is @NULL - - @returns The length of the converted string excluding the trailing NUL. + @param encoding Any valid (i.e. not wxFONTENCODING_MAX) font encoding. */ - virtual size_t MB2WC(wchar_t* out, const char* in, - size_t outLen) const; + wxCSConv(wxFontEncoding encoding); /** - The most general function for converting a multibyte string to a wide string. - The main case is when @a dst is not @NULL and @a srcLen is not - @c wxNO_LEN (which is defined as @c (size_t)-1): then - the function converts exactly @a srcLen bytes starting at @a src into - wide string which it output to @e dst. If the length of the resulting wide - string is greater than @e dstLen, an error is returned. Note that if - @a srcLen bytes don't include @c NUL characters, the resulting wide string is - not @c NUL-terminated neither. - If @a srcLen is @c wxNO_LEN, the function supposes that the string is - properly (i.e. as necessary for the encoding handled by this conversion) - @c NUL-terminated and converts the entire string, including any trailing @c NUL - bytes. In this case the wide string is also @c NUL-terminated. - Finally, if @a dst is @NULL, the function returns the length of the needed - buffer. - */ - virtual size_t ToWChar(wchar_t* dst, size_t dstLen, - const char* src, - size_t srcLen = wxNO_LEN) const; + Returns @true if the charset (or the encoding) given at constructor is + really available to use. - /** - This function is deprecated, please use FromWChar() instead - Converts from Unicode to multibyte encoding. The semantics of this function - (including the return value meaning) is the same as for - wxMBConv::MB2WC. - Notice that when the function is called with a non-@NULL buffer, the - @a n parameter should be the size of the buffer and so it should take - into account the trailing @c NUL, which might take two or four bytes for some - encodings (UTF-16 and UTF-32) and not one. - */ - virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; + Returns @false if ISO 8859-1 will be used instead. - //@{ - /** - Converts from multibyte encoding to Unicode by calling - wxMBConv::MB2WC, allocating a temporary wxWCharBuffer to hold - the result. - The first overload takes a @c NUL-terminated input string. The second one takes - a - string of exactly the specified length and the string may include or not the - trailing @c NUL character(s). If the string is not @c NUL-terminated, a - temporary - @c NUL-terminated copy of it suitable for passing to wxMBConv::MB2WC - is made, so it is more efficient to ensure that the string is does have the - appropriate number of @c NUL bytes (which is usually 1 but may be 2 or 4 - for UTF-16 or UTF-32, see wxMBConv::GetMBNulLen), - especially for long strings. - If @a outLen is not-@NULL, it receives the length of the converted - string. - */ - const wxWCharBuffer cMB2WC(const char* in) const; - const const wxWCharBuffer cMB2WC(const char* in, - size_t inLen, - size_t outLen) const; - //@} + Note this does not mean that a given string will be correctly + converted. A malformed string may still make conversion functions + return @c wxCONV_FAILED. - //@{ - /** - Converts from multibyte encoding to the current wxChar type - (which depends on whether wxUSE_UNICODE is set to 1). If wxChar is char, - it returns the parameter unaltered. If wxChar is wchar_t, it returns the - result in a wxWCharBuffer. The macro wxMB2WXbuf is defined as the correct - return type (without const). + @since 2.8.2 */ - const char* cMB2WX(const char* psz) const; - const const wxWCharBuffer cMB2WX(const char* psz) const; - //@} + bool IsOk() const; +}; - //@{ - /** - Converts from Unicode to multibyte encoding by calling WC2MB, - allocating a temporary wxCharBuffer to hold the result. - The second overload of this function allows to convert a string of the given - length @e inLen, whether it is @c NUL-terminated or not (for wide character - strings, unlike for the multibyte ones, a single @c NUL is always enough). - But notice that just as with @ref wxMBConv::mb2wc cMB2WC, it is more - efficient to pass an already terminated string to this function as otherwise a - copy is made internally. - If @a outLen is not-@NULL, it receives the length of the converted - string. - */ - const wxCharBuffer cWC2MB(const wchar_t* in) const; - const const wxCharBuffer cWC2MB(const wchar_t* in, - size_t inLen, - size_t outLen) const; - //@} - //@{ - /** - Converts from Unicode to the current wxChar type. If wxChar is wchar_t, - it returns the parameter unaltered. If wxChar is char, it returns the - result in a wxCharBuffer. The macro wxWC2WXbuf is defined as the correct - return type (without const). - */ - const wchar_t* cWC2WX(const wchar_t* psz) const; - const const wxCharBuffer cWC2WX(const wchar_t* psz) const; - //@} - //@{ - /** - Converts from the current wxChar type to multibyte encoding. If wxChar is char, - it returns the parameter unaltered. If wxChar is wchar_t, it returns the - result in a wxCharBuffer. The macro wxWX2MBbuf is defined as the correct - return type (without const). - */ - const char* cWX2MB(const wxChar* psz) const; - const const wxCharBuffer cWX2MB(const wxChar* psz) const; - //@} +/** + @class wxMBConvFile + @wxheader{strconv.h} - //@{ - /** - Converts from the current wxChar type to Unicode. If wxChar is wchar_t, - it returns the parameter unaltered. If wxChar is char, it returns the - result in a wxWCharBuffer. The macro wxWX2WCbuf is defined as the correct - return type (without const). - */ - const wchar_t* cWX2WC(const wxChar* psz) const; - const const wxWCharBuffer cWX2WC(const wxChar* psz) const; - //@} + This class used to define the class instance @b wxConvFileName, but + nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms) + or wxConvUTF8 (on MacOS X). + + @b wxConvFileName converts filenames between filesystem multibyte encoding + and Unicode. @b wxConvFileName can also be set to a something else at + run-time which is used e.g. by wxGTK to use a class which checks the + environment variable @b G_FILESYSTEM_ENCODING indicating that filenames + should not be interpreted as UTF8 and also for converting invalid UTF8 + characters (e.g. if there is a filename in iso8859_1) to strings with octal + values. + + Since some platforms (such as Win32) use Unicode in the filenames, + and others (such as Unix) use multibyte encodings, this class should only + be used directly if wxMBFILES is defined to 1. A convenience macro, + @c wxFNCONV, is defined to @c wxConvFileName->cWX2MB in this case. You + could use it like this: + + @code + wxChar *name = wxT("rawfile.doc"); + FILE *fil = fopen(wxFNCONV(name), "r"); + @endcode + + (although it would be better to just use wxFopen(name, "r") in this + particular case, you only need to use this class for functions taking file + names not wrapped by wxWidgets.) + + @library{wxbase} + @category{conv} + + @see @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvFile : public wxMBConv +{ +public: };