192 lines
7.1 KiB
Objective-C
192 lines
7.1 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: encconv.h
|
|
// Purpose: interface of wxEncodingConverter
|
|
// Author: wxWidgets team
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
@class wxEncodingConverter
|
|
|
|
This class is capable of converting strings between two 8-bit encodings/charsets.
|
|
It can also convert from/to Unicode.
|
|
|
|
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{conv}
|
|
|
|
@see wxFontMapper, wxMBConv, @ref overview_nonenglish
|
|
*/
|
|
class wxEncodingConverter : public wxObject
|
|
{
|
|
public:
|
|
/**
|
|
Constructor.
|
|
*/
|
|
wxEncodingConverter();
|
|
|
|
/**
|
|
Return @true if (any text in) multibyte encoding @a encIn can be converted to
|
|
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);
|
|
|
|
/**
|
|
@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!
|
|
*/
|
|
bool Convert(const char* input, char* output) 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.
|
|
|
|
With this overload, the conversion result is written to the same memory
|
|
area from which the input is read.
|
|
|
|
See the Convert(const char*,char*) const overload for more info.
|
|
*/
|
|
bool Convert(char* str) const;
|
|
|
|
/**
|
|
Convert input string according to settings passed to Init() in-place.
|
|
|
|
With this overload, the conversion result is written to the same memory
|
|
area from which the input is read.
|
|
|
|
See the Convert(const wchar_t*,wchar_t*) const overload for more info.
|
|
*/
|
|
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
|
|
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.
|
|
*/
|
|
static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc);
|
|
|
|
/**
|
|
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:
|
|
|
|
@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);
|
|
|
|
/**
|
|
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.
|
|
|
|
@a method affects behaviour of Convert() in case input character
|
|
cannot be converted because it does not exist in output encoding:
|
|
|
|
@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);
|
|
};
|
|
|