QTextCodec Class Reference
The QTextCodec class provides conversion between text encodings.
More...
#include <qtextcodec.h>
Inherited by QEucJpCodec, QEucKrCodec, QGbkCodec, QJisCodec, QHebrewCodec, QSjisCodec and QTsciiCodec.
List of all member functions.
Public Members
virtual const char *
name () const
virtual QString
toUnicode ( const char * chars, int len ) const
virtual QCString
fromUnicode ( const QString & uc, int & lenInOut ) const
QString
toUnicode ( const QByteArray & a, int len ) const
QString
toUnicode ( const QByteArray & a ) const
QString
toUnicode ( const QCString & a, int len ) const
QString
toUnicode ( const QCString & a ) const
QString
toUnicode ( const char * chars ) const
virtual bool
canEncode ( const QString & s ) const
Static Public Members
QTextCodec *
codecForName ( const char * name, int accuracy = 0 )
Protected Members
Static Protected Members
Detailed Description
The QTextCodec class provides conversion between text encodings.
By making objects of subclasses of QTextCodec, support for
new text encodings can be added to Qt.
The abstract virtual functions describe the encoder to the
system and the coder is used as required in the different
text file formats supported QTextStream and, under X11 for the
locale-specific character input and output (under Windows NT
codecs are not needed for GUI I/O since the system works
with Unicode already, and Windows 95/98 has built-in convertors
for the 8-bit local encoding).
More recently created QTextCodec objects take precedence
over earlier ones.
To add support for another 8-bit encoding to Qt, make a subclass
or QTextCodec and implement at least the following methods:
- const char* name() const
- Return the official name for the encoding.
- int mibEnum() const
- Return 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 an encoding, you will need to implement
- QTextDecoder* makeDecoder() const
- Return a QTextDecoder that remembers incomplete multibyte
sequence prefixes or other required state.
If the encoding does not require state, you should implement:
- QString toUnicode(const char* chars, int len) const
- Converts 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() const
- Return a QTextDecoder.
- QCString fromUnicode(const QString& uc, int& lenInOut ) const;
- Converts 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 better efficiency is possible.
Finally, you must implement:
- int heuristicContentMatch(const char* chars, int len) const
- Gives 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 ) const
- Test if a Unicode character can be encoded.
- bool canEncode( const QString& ) const
- Test if a string of Unicode characters can be encoded.
- int heuristicNameMatch(const char* hint) const
- Test if a possibly non-standard name is referring to the codec.
Member Function Documentation
QTextCodec::QTextCodec () [protected]
Constructs a QTextCodec, making it of highest precedence.
The QTextCodec should always be constructed on the heap
(with new), and once constructed it becomes the responsibility
of Qt to delete it (which is done at QApplication destruction).
QTextCodec::~QTextCodec () [virtual]
Destroys the QTextCodec. Note that you should not delete
codecs yourself - once created they become the responsibility
of Qt to delete.
bool QTextCodec::canEncode ( QChar ch ) const [virtual]
Returns TRUE if the unicode character ch can be fully encoded
with this codec. The default implementation tests if the result of
toUnicode(fromUnicode(ch)) is the original ch. Subclasses may be
able to improve the efficiency.
bool QTextCodec::canEncode ( const QString & s ) const [virtual]
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
s contains the string that we are testing for encode-ability.
QTextCodec * QTextCodec::codecForContent ( const char * chars, int len ) [static]
Searches all installed QTextCodec objects, returning the one
which most recognizes the given content. May return 0.
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 characters to check, and len contans the
number of characters.
See also heuristicContentMatch().
Example: qwerty/qwerty.cpp.
QTextCodec * QTextCodec::codecForIndex ( int i ) [static]
Returns the QTextCodec i places from the more recently
inserted, or NULL if there is no such QTextCodec. Thus,
codecForIndex(0) returns the most recently created QTextCodec.
Example: qwerty/qwerty.cpp.
QTextCodec * QTextCodec::codecForLocale () [static]
Returns a pointer to the codec most suitable for this locale.
Example: qwerty/qwerty.cpp.
QTextCodec * QTextCodec::codecForMib ( int mib ) [static]
Returns the QTextCodec which matches the
MIBenum mib.
QTextCodec * QTextCodec::codecForName ( const char * name, int accuracy = 0 ) [static]
Searches all installed QTextCodec objects and returns the one
which best matches name. Returns a null pointer if no codec's
heuristicNameMatch() reports a match better than accuracy, or
if name is a null string.
See also heuristicNameMatch().
void QTextCodec::deleteAllCodecs () [static]
Deletes all the created codecs.
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 chasing down memory leaks, as
QTextCodec objects will not show up.
QCString QTextCodec::fromUnicode ( const QString & uc, int & lenInOut ) const [virtual]
Subclasses of QTextCodec must reimplement either this function or
makeEncoder(). It converts the first lenInOut characters of uc from Unicode to the encoding of the subclass. If lenInOut
is negative or too large, the length of uc is used instead.
The value returned is the property of 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.
QCString QTextCodec::fromUnicode ( const QString & uc ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
uc is the unicode source string.
int QTextCodec::heuristicContentMatch ( const char * chars, int len ) const [virtual]
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. Any negative return value indicates that the text
is detectably not in the encoding (eg. it contains undefined characters).
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().
int QTextCodec::heuristicNameMatch ( const char * hint ) const [virtual]
Returns a value indicating how likely this decoder is
for decoding some format that has the given name. The name is
compared with the hint.
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.
QTextCodec * QTextCodec::loadCharmap ( QIODevice * iod ) [static]
Reads a POSIX2 charmap definition from iod.
The parser recognizes the following lines:
<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.
QTextCodec * QTextCodec::loadCharmapFile ( QString filename ) [static]
A convenience function for loadCharmap() that loads the charmap
definition from the file filename.
const char * QTextCodec::locale () [static]
Returns a string representing the current language.
QTextDecoder * QTextCodec::makeDecoder () const [virtual]
Creates a QTextDecoder which stores enough state to decode chunks
of char* data to create chunks of Unicode data. The default implementation
creates a stateless decoder, which is sufficient for only the simplest
encodings where each byte corresponds to exactly one Unicode character.
The caller is responsible for deleting the returned object.
QTextEncoder * QTextCodec::makeEncoder () const [virtual]
Creates a QTextEncoder which stores enough state to encode chunks
of Unicode data as char* data. The default implementation
creates a stateless encoder, which is sufficient for only the simplest
encodings where each Unicode character corresponds to exactly one char.
The caller is responsible for deleting the returned object.
int QTextCodec::mibEnum () const [virtual]
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 return the correct unique
value for this function.
Reimplemented in QEucJpCodec.
const char * QTextCodec::name () const [virtual]
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:
- On X11, heuristicNameMatch( const char * hint )
is used to test if a the QTextCodec
can convert between Unicode and the encoding of a font
with encoding hint, such as "iso8859-1" for Latin-1 fonts,
"koi8-r" for Russian KOI8 fonts.
The default algorithm of heuristicNameMatch() uses name().
- Some applications may use this function to present
encodings to the end user.
Example: qwerty/qwerty.cpp.
void QTextCodec::setCodecForLocale ( QTextCodec * c ) [static]
Set the codec to c; this will be returned by See also codecForLocale, This, might, be, needed, for, some, applications, that, want, to, use, their, own, mechanism, for, setting, the and locale.
int QTextCodec::simpleHeuristicNameMatch ( const char * name, const char * hint ) [static protected]
A simple utility function for heuristicNameMatch() - it
does some very minor character-skipping
so that almost-exact matches score high.
name is the text we're matching and hint is used for the
comparison.
QString QTextCodec::toUnicode ( const char * chars, int len ) const [virtual]
Subclasses of QTextCodec must reimplement this function or
makeDecoder(). It converts the first len characters of chars
to Unicode.
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.
QString QTextCodec::toUnicode ( const QByteArray & a, int len ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
a contains the source characters; len contains the number of
characters in a to use.
QString QTextCodec::toUnicode ( const QByteArray & a ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
a contains the source characters.
QString QTextCodec::toUnicode ( const QCString & a, int len ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
a contains the source characters; len contains the number of
characters in a to use.
QString QTextCodec::toUnicode ( const QCString & a ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
a contains the source characters.
QString QTextCodec::toUnicode ( const char * chars ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
chars contains the source characters.
Search the documentation, FAQ, qt-interest archive and more (uses
www.trolltech.com):
This file is part of the Qt toolkit,
copyright © 1995-2001
Trolltech, all rights reserved.
Copyright © 2001 Trolltech | Trademarks
| Qt version 3.0.0-beta2
|