| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxEncodingConverter Class Reference
Class List by Category » Text Conversion

`#include <wx/encconv.h>`

Inheritance diagram for wxEncodingConverter:
[legend]

## Detailed Description

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: `wxFONTENCODING_ISO8859_1`..15, `wxFONTENCODING_CP1250`..1257 and `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: Text Conversion

See also
  wxFontMapper, wxMBConv, Writing Non-English Applications

## Public Member Functions
| wxEncodingConverter ()
| Constructor. More...
bool | Init (wxFontEncoding input_enc, wxFontEncoding output_enc, int method=wxCONVERT_STRICT)
| Initialize the conversion. More...
Conversion functions
bool | Convert (const char *input, char *output) const
| Convert input string according to settings passed to Init() and writes the result to output. More...
bool | Convert (const wchar_t *input, wchar_t *output) const
| Convert input string according to settings passed to Init() and writes the result to output. More...
bool | Convert (const char *input, wchar_t *output) const
| Convert input string according to settings passed to Init() and writes the result to output. More...
bool | Convert (const wchar_t *input, char *output) const
| Convert input string according to settings passed to Init() and writes the result to output. More...
bool | Convert (char *str) const
| Convert input string according to settings passed to Init() in-place. More...
bool | Convert (wchar_t *str) const
| Convert input string according to settings passed to Init() in-place. More...
wxString | Convert (const wxString &input) const
| Convert a wxString and return a new wxString object. More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to nullptr the internal reference data. More...
| wxObject (const wxObject &other)
| Copy ctor. More...
virtual | ~wxObject ()
| Destructor. More...
virtual wxClassInfo * | GetClassInfo () const
| This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
wxObjectRefData * | GetRefData () const
| Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
bool | IsKindOf (const wxClassInfo *info) const
| Determines whether this class is a subclass of (or the same class as) the given class. More...
bool | IsSameAs (const wxObject &obj) const
| Returns true if this object has the same data pointer as obj. More...
void | Ref (const wxObject &clone)
| Makes this object refer to the data in clone. More...
void | SetRefData (wxObjectRefData *data)
| Sets the wxObject::m_refData pointer. More...
void | UnRef ()
| Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
void | UnShare ()
| This is the same of AllocExclusive() but this method is public. More...
void | operator delete (void *buf)
| The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...
void * | operator new (size_t size, const wxString &filename=nullptr, int lineNum=0)
| The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

## Static Public Member Functions
static bool | CanConvert (wxFontEncoding encIn, wxFontEncoding encOut)
| Return true if (any text in) multibyte encoding encIn can be converted to another one (encOut) losslessly. More...
static wxFontEncodingArray | GetAllEquivalents (wxFontEncoding enc)
| Similar to GetPlatformEquivalents(), but this one will return ALL equivalent encodings, regardless of the platform, and including itself. More...
static wxFontEncodingArray | GetPlatformEquivalents (wxFontEncoding enc, int platform=wxPLATFORM_CURRENT)
| Return equivalents for given font that are used under given platform. More...

## Additional Inherited Members
Protected Member Functions inherited from wxObject
void | AllocExclusive ()
| Ensure that this object's data is not shared with any other object. More...
virtual wxObjectRefData * | CreateRefData () const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
virtual wxObjectRefData * | CloneRefData (const wxObjectRefData *data) const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...
Protected Attributes inherited from wxObject
wxObjectRefData * | m_refData
| Pointer to an object which is the object's reference-counted data. More...

## Constructor & Destructor Documentation

## ◆ wxEncodingConverter()

wxEncodingConverter::wxEncodingConverter | ( |  | ) |

Constructor.

## Member Function Documentation

## ◆ CanConvert()

static bool wxEncodingConverter::CanConvert | ( | wxFontEncoding | encIn,
|  | wxFontEncoding | encOut
| ) |  |
| static

Return true if (any text in) multibyte encoding encIn can be converted to another one (encOut) losslessly.

Do not call this method with `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).

## ◆ Convert() [1/7]

bool wxEncodingConverter::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 char*,char*) const overload for more info.

## ◆ Convert() [2/7]

bool wxEncodingConverter::Convert | ( | const char * | input,
|  | char * | output
| ) |  | const

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 `wxCONVERT_SUBSTITUTE` was passed to Init(), substitution is considered a lossless operation.

Note
  You must call Init() before using this method!

## ◆ Convert() [3/7]

bool wxEncodingConverter::Convert | ( | const char * | input,
|  | wchar_t * | output
| ) |  | const

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 `wxCONVERT_SUBSTITUTE` was passed to Init(), substitution is considered a lossless operation.

Note
  You must call Init() before using this method!

## ◆ Convert() [4/7]

bool wxEncodingConverter::Convert | ( | const wchar_t * | input,
|  | char * | output
| ) |  | const

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 `wxCONVERT_SUBSTITUTE` was passed to Init(), substitution is considered a lossless operation.

Note
  You must call Init() before using this method!

## ◆ Convert() [5/7]

bool wxEncodingConverter::Convert | ( | const wchar_t * | input,
|  | wchar_t * | output
| ) |  | const

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 `wxCONVERT_SUBSTITUTE` was passed to Init(), substitution is considered a lossless operation.

Note
  You must call Init() before using this method!

## ◆ Convert() [6/7]

wxString wxEncodingConverter::Convert | ( | const wxString & | input | ) | const

Convert a wxString and return a new wxString object.

See the Convert(const char*,char*) const overload for more info.

## ◆ Convert() [7/7]

bool wxEncodingConverter::Convert | ( | wchar_t * | 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.

## ◆ GetAllEquivalents()

static wxFontEncodingArray wxEncodingConverter::GetAllEquivalents | ( | wxFontEncoding | enc | ) |
| static

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 enc is in the array, it is the very first item in it.

## ◆ GetPlatformEquivalents()

static wxFontEncodingArray wxEncodingConverter::GetPlatformEquivalents | ( | wxFontEncoding | enc,
|  | int | platform = `wxPLATFORM_CURRENT`
| ) |  |
| static

Return equivalents for given font that are used under given platform.

Supported platforms:

- wxPLATFORM_UNIX
- wxPLATFORM_WINDOWS
- wxPLATFORM_MAC
- wxPLATFORM_CURRENT

wxPLATFORM_CURRENT means the platform this binary was compiled for.

Examples:

    current platform   enc          returned value
    ----------------------------------------------
    unix            CP1250             {ISO8859_2}
    unix         ISO8859_2             {ISO8859_2}
    windows      ISO8859_2                {CP1250}
    unix            CP1252  {ISO8859_1,ISO8859_15}

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 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.
  Convert() is not limited to converting between equivalent encodings, it can convert between two arbitrary encodings.
  If enc is present in the returned array, then it is always the first item of it.
  Please note that the returned array may contain no items at all.

## ◆ Init()

bool wxEncodingConverter::Init | ( | wxFontEncoding | input_enc,
|  | wxFontEncoding | output_enc,
|  | int | method = `wxCONVERT_STRICT`
| ) |  |

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 input_enc encoding and will output string in 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.

method affects behaviour of Convert() in case input character cannot be converted because it does not exist in output encoding:

- 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)
- 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.

Returns
  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).