// Purpose: interface of wxMBConvUTF7
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@library{wxbase}
@category{conv}
- @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxCSConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxMBConv
{
The other cases are not currently supported and @c wxCONV_FAILED
(defined as -1) is returned for them.
*/
- size_t GetMBNulLen() const;
+ virtual size_t GetMBNulLen() const;
/**
Returns the maximal value which can be returned by GetMBNulLen() for
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();
+ static size_t GetMaxMBNulLen();
/**
Convert multibyte string to a wide character one.
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.
+ @a 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
+ @param srcLen
+ 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,
+ virtual size_t ToWChar(wchar_t* dst, size_t dstLen, const char* src,
size_t srcLen = wxNO_LEN) const;
/**
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.
+ @a 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
+ @param srcLen
+ 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.
*/
- virtual size_t FromWChar(char* dst, size_t dstLen,
- const wchar_t* src,
+ virtual size_t FromWChar(char* dst, size_t dstLen, const wchar_t* src,
size_t srcLen = wxNO_LEN) const;
- //@{
/**
- Converts from multibyte encoding to Unicode by calling MB2WC() and
+ Converts from multibyte encoding to Unicode by calling ToWChar() 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.
+ This function is a convenient wrapper around ToWChar() as it takes care
+ of allocating the buffer of the necessary size itself. Its parameters
+ have the same meaning as for ToWChar(), in particular @a inLen can be
+ specified explicitly in which case exactly that many characters are
+ converted and @a outLen receives (if non-@NULL) exactly the
+ corresponding number of wide characters, whether the last one of them
+ is @c NUL or not. However if @c inLen is @c wxNO_LEN, then @c outLen
+ doesn't count the trailing @c NUL even if it is always present in this
+ case.
+
+ Finally notice that if the conversion fails, the returned buffer is
+ invalid and @a outLen is set to 0 (and not @c wxCONV_FAILED for
+ compatibility concerns).
*/
- const wxWCharBuffer cMB2WC(const char* in) const;
- const wxWCharBuffer cMB2WC(const char* in, size_t inLen, size_t *outLen) const;
- //@}
+ const wxWCharBuffer cMB2WC(const char* in,
+ size_t inLen,
+ size_t *outLen) const;
+
+ /**
+ Converts a char buffer to wide char one.
+
+ This is the most convenient and safest conversion function as you
+ don't have to deal with the buffer lengths directly. Use it if the
+ input buffer is known not to be empty or if you are sure that the
+ conversion is going to succeed -- otherwise, use the overload above to
+ be able to distinguish between empty input and conversion failure.
+
+ @return
+ The buffer containing the converted text, empty if the input was
+ empty or if the conversion failed.
+
+ @since 2.9.1
+ */
+ const wxWCharBuffer cMB2WC(const wxCharBuffer& buf) const;
//@{
/**
const wxWCharBuffer cMB2WX(const char* psz) const;
//@}
- //@{
/**
- Converts from Unicode to multibyte encoding by calling WC2MB and
+ Converts from Unicode to multibyte encoding by calling FromWChar() and
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.
+ This function is a convenient wrapper around FromWChar() as it takes
+ care of allocating the buffer of necessary size itself.
+
+ Its parameters have the same meaning as the corresponding parameters of
+ FromWChar(), please see the description of cMB2WC() for more details.
*/
- const wxCharBuffer cWC2MB(const wchar_t* in) const;
- const wxCharBuffer cWC2MB(const wchar_t* in, size_t inLen, size_t *outLen) const;
- //@}
+ const wxCharBuffer cWC2MB(const wchar_t* in,
+ size_t inLen,
+ size_t *outLen) const;
+
+ /**
+ Converts a wide char buffer to char one.
+
+ This is the most convenient and safest conversion function as you
+ don't have to deal with the buffer lengths directly. Use it if the
+ input buffer is known not to be empty or if you are sure that the
+ conversion is going to succeed -- otherwise, use the overload above to
+ be able to distinguish between empty input and conversion failure.
+
+ @return
+ The buffer containing the converted text, empty if the input was
+ empty or if the conversion failed.
+
+ @since 2.9.1
+ */
+ const wxCharBuffer cWC2MB(const wxWCharBuffer& buf) const;
//@{
/**
/**
@deprecated This function is deprecated, please use ToWChar() instead.
- Converts from a string @a in in multibyte encoding to Unicode putting up to
+ Converts from a string @a 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
out buffer, the @a outLen parameter should be one more to allow to
properly @c NUL-terminate the string.
+ So to properly use this function you need to write:
+ @code
+ size_t lenConv = conv.MB2WC(NULL, in, 0);
+ if ( lenConv == wxCONV_FAILED )
+ ... handle error ...
+ // allocate 1 more character for the trailing NUL and also pass
+ // the size of the buffer to the function now
+ wchar_t *out = new wchar_t[lenConv + 1];
+ if ( conv.MB2WC(out, in, lenConv + 1) == wxCONV_FAILED )
+ ... handle error ...
+ @endcode
+ For this and other reasons, ToWChar() is strongly recommended as a
+ replacement.
+
@param out
The output buffer, may be @NULL if the caller is only
interested in the length of the resulting string
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.
+ UTF-32) and not one, i.e. GetMBNulLen().
*/
virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const;
};
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, @ref overview_mbconv
*/
class wxMBConvUTF7 : public wxMBConv
{
@library{wxbase}
@category{conv}
- @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF7, @ref overview_mbconv
*/
class wxMBConvUTF8 : public wxMBConv
{
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv
*/
class wxMBConvUTF16 : public wxMBConv
{
@library{wxbase}
@category{conv}
- @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv
*/
class wxMBConvUTF32 : public wxMBConv
{
@library{wxbase}
@category{conv}
- @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview"
+ @see wxMBConv, wxEncodingConverter, @ref overview_mbconv
*/
class wxCSConv : public wxMBConv
{
/**
- @class wxMBConvFile
-
- 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).
+ Conversion object used for converting file names from their external
+ representation to the one used inside the program.
@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
+ run-time which is used e.g. by wxGTK to use an object 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
+ and others (such as Unix) use multibyte encodings, this object 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");
+ wxChar *name = "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
+ particular case, you only need to use this object for functions taking file
names not wrapped by wxWidgets.)
@library{wxbase}
@category{conv}
- @see @ref overview_mbconv "wxMBConv classes overview"
+ @see @ref overview_mbconv
*/
-class wxMBConvFile : public wxMBConv
-{
-public:
-};
+extern wxMBConv* wxConvFileName;
projects / wxWidgets.git / blobdiff