| Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | |
The QTextCodec class provides conversion between text encodings. More...
#include <qtextcodec.h>
Inherited by QEucJpCodec, QEucKrCodec, QGb18030Codec, QJisCodec, QHebrewCodec, QSjisCodec and QTsciiCodec.
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 ISO2022, while Russian users often have their documents in KOI8-R or CP1251.
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 (see later).
The supported encodings are:
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 this is:
QCString locallyEncoded = "..."; // text to convert
QTextCodec *codec = QTextCodec::codecForName("KOI8-R"); // get the codec for KOI8-R
QString unicodeString = codec->toUnicode( locallyEncoded );
After this, unicodeString holds the text converted to Unicode. Converting a string from Unicode to the local encoding is just as easy:
QString unicodeString = "..."; // any Unicode text
QTextCodec *codec = QTextCodec::codecForName("KOI8-R"); // get the codec for KOI8-R
QCString locallyEncoded = codec->fromUnicode( unicodeString );
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 *c = QTextCodec::codecForName( "Shift-JIS" );
QTextDecoder *decoder = c->makeDecoder();
QString unicodeString;
while( receiving_data ) {
QByteArray chunk = new_data;
unicodeString += decoder->toUnicode( chunk.data(), chunk.length() );
}
The QTextDecoder object maintains state between chunks and therefore works correctly even if a multi-byte character is split between chunks.
By making objects of subclasses of QTextCodec, support for new text encodings can be added to Qt.
More recently created QTextCodec objects take precedence over earlier ones.
You may find it more convenient to make your codec class available as a plugin; see the plugin documentation for more details.
The abstract 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 8-bit encoding to Qt, make a subclass of QTextCodec and implement at least the following methods:
const char* name() constReturn the official name for the encoding.
int mibEnum() constReturn the MIB enum for the encoding if it is listed in the IANA character-sets encoding file.
If the encoding is multi-byte then it will have "state"; that is, the interpretation of some bytes will be dependent on some preceding bytes. For such encodings, you must implement:
QTextDecoder* makeDecoder() constReturn a QTextDecoder that remembers incomplete multi-byte sequence prefixes or other required state.
If the encoding does not require state, you should implement:
QString toUnicode(const char* chars, int len) constConverts len characters from chars to Unicode.
The base QTextCodec class has default implementations of the above two functions, but they are mutually recursive, so you must re-implement at least one of them, or both for improved efficiency.
For conversion from Unicode to 8-bit encodings, it is rarely necessary to maintain state. However, two functions similar to the two above are used for encoding:
QTextEncoder* makeEncoder() constReturn a QTextDecoder.
QCString fromUnicode(const QString& uc, int& lenInOut ) constConverts lenInOut characters (of type QChar) from the start of the string uc, returning a QCString result, and also returning the length of the result in lenInOut.
Again, these are mutually recursive so only one needs to be implemented, or both if greater efficiency is possible.
Finally, you must implement:
int heuristicContentMatch(const char* chars, int len) constGives a value indicating how likely it is that len characters from chars are in the encoding.
A good model for this function is the QWindowsLocalCodec::heuristicContentMatch function found in the Qt sources.
A QTextCodec subclass might have improved performance if you also re-implement:
bool canEncode( QChar ) constTest if a Unicode character can be encoded.
bool canEncode( const QString& ) constTest if a string of Unicode characters can be encoded.
int heuristicNameMatch(const char* hint) constTest if a possibly non-standard name is referring to the codec.
Codecs can also be created as plugins.
See also Internationalization with Qt.
s contains the string being tested for encode-ability.
Note that this is often a poor choice, since character encodings often use most of the available character sequences, and so only by linguistic analysis could a true match be made.
chars contains the string to check, and len contains the number of characters in the string to use.
See also heuristicContentMatch().
Example: qwerty/qwerty.cpp.
Example: qwerty/qwerty.cpp.
Example: qwerty/qwerty.cpp.
See also heuristicNameMatch().
Warning: Do not call this function.
QApplication calls this just before exiting, to delete any QTextCodec objects that may be lying around. Since various other classes hold pointers to QTextCodec objects, it is not safe to call this function earlier.
If you are using the utility classes (like QString) but not using QApplication, calling this function at the very end of your application can be helpful to chase down memory leaks, as QTextCodec objects will not show up.
The value returned is owned by the caller, which is responsible for deleting it with delete []. The length of the resulting Unicode character sequence is returned in lenInOut.
The default implementation makes an encoder with makeEncoder() and converts the input with that. Note that the default makeEncoder() implementation makes an encoder that simply calls this function, hence subclasses must reimplement one function or the other to avoid infinite recursion.
Reimplemented in QHebrewCodec.
uc is the unicode source string.
Subclasses of QTextCodec must reimplement this function. It examines the first len bytes of chars and returns a value indicating how likely it is that the string is a prefix of text encoded in the encoding of the subclass. A negative return value indicates that the text is detectably not in the encoding (e.g. it contains characters undefined in the encoding). A return value of 0 indicates that the text should be decoded with this codec rather than as ASCII, but there is no particular evidence. The value should range up to len. Thus, most decoders will return -1, 0, or -len.
The characters are not null terminated.
See also codecForContent().
A good match returns a positive number around the length of the string. A bad match is negative.
The default implementation calls simpleHeuristicNameMatch() with the name of the codec.
<code_set_name> name <escape_char> character % alias alias CHARMAP <token> /xhexbyte <Uunicode> ... <token> /ddecbyte <Uunicode> ... <token> /octbyte <Uunicode> ... <token> /any/any... <Uunicode> ... END CHARMAP
The resulting QTextCodec is returned (and also added to the global list of codecs). The name() of the result is taken from the code_set_name.
Note that a codec constructed in this way uses much more memory and is slower than a hand-written QTextCodec subclass, since tables in code are in memory shared by all applications simultaneously using Qt.
See also loadCharmapFile().
Example: qwerty/qwerty.cpp.
Example: i18n/main.cpp.
The caller is responsible for deleting the returned object.
The caller is responsible for deleting the returned object.
Subclasses of QTextCodec must reimplement this function. It returns the MIBenum (see the IANA character-sets encoding file for more information). It is important that each QTextCodec subclass returns the correct unique value for this function.
Reimplemented in QEucJpCodec.
Reimplemented in QEucJpCodec, QEucKrCodec, QGbkCodec, QJisCodec, QHebrewCodec and QSjisCodec.
Subclasses of QTextCodec must reimplement this function. It returns the name of the encoding supported by the subclass. When choosing a name for an encoding, consider these points:
Example: qwerty/qwerty.cpp.
See also codecForLocale().
The default implementation makes a decoder with makeDecoder() and converts the input with that. Note that the default makeDecoder() implementation makes a decoder that simply calls this function, hence subclasses must reimplement one function or the other to avoid infinite recursion.
a contains the source characters; len contains the number of characters in a to use.
a contains the source characters.
a contains the source characters; len contains the number of characters in a to use.
a contains the source characters.
chars contains the source characters.
This file is part of the Qt toolkit. Copyright © 1995-2002 Trolltech. All Rights Reserved.
| Copyright © 2002 Trolltech | Trademarks | Qt version 3.0.4
|