X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3c4f71cc3d63fb7bdfbd6cec3e39c8a8679f3e60..0f5a779f12cc426da00474c1a70db8096e9e991a:/interface/encconv.h?ds=sidebyside diff --git a/interface/encconv.h b/interface/encconv.h index 4e4c5940de..a7821321ce 100644 --- a/interface/encconv.h +++ b/interface/encconv.h @@ -10,18 +10,25 @@ @class wxEncodingConverter @wxheader{encconv.h} - This class is capable of converting strings between two - 8-bit encodings/charsets. It can also convert from/to Unicode (but only - if you compiled wxWidgets with wxUSE_WCHAR_T set to 1). Only a limited subset - of encodings is supported by wxEncodingConverter: + This class is capable of converting strings between two 8-bit encodings/charsets. + It can also convert from/to Unicode (but only if you compiled wxWidgets + with wxUSE_WCHAR_T set to 1). + + Only a limited subset of encodings is supported by wxEncodingConverter: @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and @c wxFONTENCODING_KOI8. + @note + + Please use wxMBConv classes instead if possible. wxCSConv has much better + support for various encodings than wxEncodingConverter. + wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode + of operation (see wxEncodingConverter::Init()). + @library{wxbase} @category{misc} - @see wxFontMapper, wxMBConv, @ref overview_nonenglishoverview "Writing - non-English applications" + @see wxFontMapper, wxMBConv, @ref overview_nonenglish */ class wxEncodingConverter : public wxObject { @@ -33,88 +40,146 @@ public: /** Return @true if (any text in) multibyte encoding @a encIn can be converted to - another one (@e encOut) losslessly. - Do not call this method with @c wxFONTENCODING_UNICODE as either - parameter, it doesn't make sense (always works in one sense and always depends + another one (@a encOut) losslessly. + + Do not call this method with @c wxFONTENCODING_UNICODE as either parameter, + it doesn't make sense (always works in one sense and always depends on the text to convert in the other). */ static bool CanConvert(wxFontEncoding encIn, wxFontEncoding encOut); - //@{ /** - Convert wxString and return new wxString object. + @name Conversion functions + + @{ + */ + /** + Convert input string according to settings passed to Init() and writes + the result to output. + + All the Convert() function overloads return @true if the conversion was + lossless and @false if at least one of the characters couldn't be converted + was and replaced with '?' in the output. + + Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is + considered a lossless operation. + + @note You must call Init() before using this method! + + @note wchar_t versions of the method are not available if wxWidgets was + compiled with @c wxUSE_WCHAR_T set to 0. */ bool Convert(const char* input, char* output) const; - const bool Convert(const wchar_t* input, wchar_t* output) const; - const bool Convert(const char* input, wchar_t* output) const; - const bool Convert(const wchar_t* input, char* output) const; - const bool Convert(char* str) const; - const bool Convert(wchar_t* str) const; - const wxString Convert(const wxString& input) const; + bool Convert(const wchar_t* input, wchar_t* output) const; + bool Convert(const char* input, wchar_t* output) const; + bool Convert(const wchar_t* input, char* output) const; + + /** + Convert input string according to settings passed to Init() in-place, + i.e. write the result to the same memory area. + + See the Convert(const char*,char*) const overload for more info. + */ + bool Convert(char* str) const; + bool Convert(wchar_t* str) const; + + /** + Convert a wxString and return a new wxString object. + + See the Convert(const char*,char*) const overload for more info. + */ + wxString Convert(const wxString& input) const; //@} + /** - Similar to - GetPlatformEquivalents(), - but this one will return ALL + Similar to GetPlatformEquivalents(), but this one will return ALL equivalent encodings, regardless of the platform, and including itself. - This platform's encodings are before others in the array. And again, if @a enc - is in the array, - it is the very first item in it. + + This platform's encodings are before others in the array. + And again, if @a enc is in the array, it is the very first item in it. */ static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc); /** - Return equivalents for given font that are used - under given platform. Supported platforms: - wxPLATFORM_UNIX - wxPLATFORM_WINDOWS - wxPLATFORM_OS2 - wxPLATFORM_MAC - wxPLATFORM_CURRENT + Return equivalents for given font that are used under given platform. + + Supported platforms: + @li wxPLATFORM_UNIX + @li wxPLATFORM_WINDOWS + @li wxPLATFORM_OS2 + @li wxPLATFORM_MAC + @li wxPLATFORM_CURRENT + wxPLATFORM_CURRENT means the platform this binary was compiled for. + Examples: - Equivalence is defined in terms of convertibility: - two encodings are equivalent if you can convert text between - then without losing information (it may - and will - happen - that you lose special chars like quotation marks or em-dashes - but you shouldn't lose any diacritics and language-specific - characters when converting between equivalent encodings). + @verbatim + current platform enc returned value + ---------------------------------------------- + unix CP1250 {ISO8859_2} + unix ISO8859_2 {ISO8859_2} + windows ISO8859_2 {CP1250} + unix CP1252 {ISO8859_1,ISO8859_15} + @endverbatim + + Equivalence is defined in terms of convertibility: two encodings are + equivalent if you can convert text between then without losing + information (it may - and will - happen that you lose special chars + like quotation marks or em-dashes but you shouldn't lose any diacritics + and language-specific characters when converting between equivalent encodings). + Remember that this function does @b NOT check for presence of fonts in system. It only tells you what are most suitable encodings. (It usually returns only one encoding.) + + @note Note that argument enc itself may be present in the returned array, + so that you can, as a side-effect, detect whether the encoding is + native for this platform or not. + + @note Convert() is not limited to converting between equivalent encodings, + it can convert between two arbitrary encodings. + + @note If @a enc is present in the returned array, then it is always the first + item of it. + + @note Please note that the returned array may contain no items at all. */ static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc, - int platform = wxPLATFORM_CURRENT); + int platform = wxPLATFORM_CURRENT); /** - Initialize conversion. Both output or input encoding may - be wxFONTENCODING_UNICODE, but only if wxUSE_ENCODING is set to 1. - All subsequent calls to Convert() - will interpret its argument + Initialize the conversion. + + Both output or input encoding may be wxFONTENCODING_UNICODE, but only + if wxUSE_ENCODING is set to 1. + + All subsequent calls to Convert() will interpret its argument as a string in @a input_enc encoding and will output string in @a output_enc encoding. + You must call this method before calling Convert. You may call it more than once in order to switch to another conversion. - @e Method affects behaviour of Convert() in case input character - cannot be converted because it does not exist in output encoding: - @b wxCONVERT_STRICT - - follow behaviour of GNU Recode - - just copy unconvertible characters to output and don't change them - (its integer value will stay the same) - - @b wxCONVERT_SUBSTITUTE + @a method affects behaviour of Convert() in case input character + cannot be converted because it does not exist in output encoding: - try some (lossy) substitutions - - e.g. replace unconvertible latin capitals with acute by ordinary - capitals, replace en-dash or em-dash by '-' etc. + @li @b wxCONVERT_STRICT: follow behaviour of GNU Recode - just copy + unconvertible characters to output and don't change them + (its integer value will stay the same) + @li @b wxCONVERT_SUBSTITUTE: try some (lossy) substitutions - e.g. + replace unconvertible latin capitals with acute by ordinary + capitals, replace en-dash or em-dash by '-' etc. Both modes guarantee that output string will have same length as input string. + + @return @false if given conversion is impossible, @true otherwise + (conversion may be impossible either if you try to convert + to Unicode with non-Unicode build of wxWidgets or if input + or output encoding is not supported). */ bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc, int method = wxCONVERT_STRICT);