|  | Home · Overviews · Examples |

# QTextCodec Class Reference
[com.trolltech.qt.core module]

The `QTextCodec` class provides conversions between text encodings. More...

## Detailed Description

The `QTextCodec` class provides conversions between text encodings.

Qt uses Unicode to store, draw and manipulate strings. In many situations you may wish to deal with data that uses a different encoding. For example, most Japanese documents are still stored in Shift-JIS or ISO 2022-JP, while Russian users often have their documents in KOI8-R or Windows-1251.

Qt provides a set of `QTextCodec` classes to help with converting non-Unicode formats to and from Unicode. You can also create your own codec classes.

The supported encodings are:

- Apple Roman
- `Big5`
- `Big5-HKSCS`
- EUC-JP
- EUC-KR
- GB18030-0
- IBM 850
- IBM 866
- IBM 874
- ISO 2022-JP
- ISO 8859-1 to 10
- ISO 8859-13 to 16
- Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml
- JIS X 0201
- JIS X 0208
- KOI8-R
- KOI8-U
- MuleLao-1
- ROMAN8
- Shift-JIS
- TIS-620
- TSCII
- UTF-8
- UTF-16
- UTF-16BE
- UTF-16LE
- Windows-1250 to 1258
- WINSAMI2

QTextCodecs can be used as follows to convert some locally encoded string to Unicode. Suppose you have some string encoded in Russian KOI8-R encoding, and want to convert it to Unicode. The simple way to do it is like this:

        QByteArray encodedString = "...";
        QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
        QString string = codec->toUnicode(encodedString);

After this, `string` holds the text converted to Unicode. Converting a string from Unicode to the local encoding is just as easy:

        QString string = "...";
        QTextCodec *codec = QTextCodec::codecForName("KOI8-R");
        QByteArray encodedString = codec->fromUnicode(string);

To read or write files in various encodings, use `QTextStream` and its setCodec() function. See the Codecs example for an application of `QTextCodec` to file I/O.

Some care must be taken when trying to convert the data in chunks, for example, when receiving it over a network. In such cases it is possible that a multi-byte character will be split over two chunks. At best this might result in the loss of a character and at worst cause the entire conversion to fail.

The approach to use in these situations is to create a `QTextDecoder` object for the codec and use this `QTextDecoder` for the whole decoding process, as shown below:

        QTextCodec *codec = QTextCodec::codecForName("Shift-JIS");
        QTextDecoder *decoder = codec->makeDecoder();

        QString string;
        while (new_data_available()) {
            QByteArray chunk = get_new_data();
            string += decoder->toUnicode(chunk);
        }

The `QTextDecoder` object maintains state between chunks and therefore works correctly even if a multi-byte character is split between chunks.

### Creating Your Own Codec Class

Support for new text encodings can be added to Qt by creating `QTextCodec` subclasses.

The pure virtual functions describe the encoder to the system and the coder is used as required in the different text file formats supported by `QTextStream`, and under X11, for the locale-specific character input and output.

To add support for another encoding to Qt, make a subclass of `QTextCodec` and implement the functions listed in the table below.

Function | Description
--- | ---
`name` | Returns the official name for the encoding. If the ncoding is listed in the IANA character-sets encoding file, the name should be the preferred MIME name for the encoding.
`aliases` | Returns a list of alternative names for the encoding. `QTextCodec` provides a default implementation that returns an empty list. For example, "ISO-8859-1" has "latin1", "CP819", "IBM819", and "iso-ir-100" as aliases.
`mibEnum` | Return the MIB enum for the encoding if it is listed in the IANA character-sets encoding file.
`convertToUnicode` | Converts an 8-bit character string to Unicode.
`convertFromUnicode` | Converts a Unicode string to an 8-bit character string.

You may find it more convenient to make your codec class available as a plugin; see How to Create Qt Plugins for details.

See also `QTextStream`, `QTextDecoder`, `QTextEncoder`, and Codecs Example.