QTextCodec - Provides conversion between text encodings

       #include <qtextcodec.h>

       Inherited by QEucJpCodec, QEucKrCodec, QGbkCodec,
       QJisCodec, QSjisCodec and QTsciiCodec.

   Public Members
       virtual ~QTextCodec ()
       virtual const char* name () const
       virtual int mibEnum () const
       virtual QTextDecoder* makeDecoder () const
       virtual QTextEncoder* makeEncoder () const
       virtual QString toUnicode ( const char * chars, int len )
           const
       virtual QCString fromUnicode ( const QString & uc, int &
           lenInOut ) const
       QCString fromUnicode ( const QString & uc ) const
       QString toUnicode ( const QByteArray &, int len ) const
       QString toUnicode ( const QByteArray & ) const
       QString toUnicode ( const char * chars ) const
       virtual bool canEncode ( QChar ) const
       virtual bool canEncode ( const QString & ) const
       virtual int heuristicContentMatch ( const char * chars,
           int len ) const
       virtual int heuristicNameMatch ( const char * hint ) const

   Static Public Members
       QTextCodec* loadCharmap ( QIODevice * )
       QTextCodec* loadCharmapFile ( QString filename )
       QTextCodec* codecForMib ( int mib )
       QTextCodec* codecForName ( const char * hint, int
           accuracy=0 )
       QTextCodec* codecForContent ( const char * chars, int len
           )
       QTextCodec* codecForIndex ( int i )
       QTextCodec* codecForLocale ()
       void deleteAllCodecs ()
       const char* locale ()

   Protected Members
       QTextCodec ()

   Static Protected Members
       int simpleHeuristicNameMatch ( const char * name, const
           char * hint )


DESCRIPTION

       Provides conversion between text encodings.

       By making objects of subclasses of QTextCodec, support for
       new text encodings can be added to Qt.

       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


       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]

       Destructs 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]

       Returns TRUE if the unicode string s can be fully encoded
       with this codec. The default implementation tests if the
       result of toUnicode(fromUnicode(s)) is the original s.



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.

       See also heuristicContentMatch().


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.


QTextCodec* QTextCodec::codecForLocale () [static]

       Returns a pointer to the codec most suitable for this
       locale.


QTextCodec* QTextCodec::codecForMib ( int mib ) [static]

       Returns the QTextCodec which matches the MIBenum mib.


QTextCodec* QTextCodec::codecForName ( const char * hint, int

       accuracy=0 ) [static]
       Searches all installed QTextCodec objects, returning the
       one which best matches given name. Returns NULL if no
       codec has a match closeness above accuracy.

       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

       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 QEucJpCodec, QGbkCodec, QEucKrCodec,
       QSjisCodec, QJisCodec and QTsciiCodec.


QCString QTextCodec::fromUnicode ( const QString & uc ) const

       This is an overloaded member function, provided for
       convenience. It differs from the above function only in
       what argument(s) it accepts.


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

       Reimplemented in QEucJpCodec, QJisCodec, QGbkCodec,
       QEucKrCodec, QSjisCodec and QTsciiCodec.


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.

       A good match returns a positive number around the length
       of the string. A bad match is negative.

       The default implementation calls


       Reimplemented in QGbkCodec, QJisCodec, QEucKrCodec,
       QSjisCodec, QEucJpCodec and QTsciiCodec.


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


QTextCodec* QTextCodec::loadCharmapFile ( QString filename )

       [static]
       A convenience function for loadCharmap().


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.

       Reimplemented in QEucKrCodec, QEucJpCodec, QJisCodec,
       QSjisCodec and QGbkCodec.


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

       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.


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.

       Reimplemented in QJisCodec, QEucJpCodec, QEucKrCodec,
       QGbkCodec, QTsciiCodec and QSjisCodec.


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.


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.

       Reimplemented in QEucJpCodec, QEucKrCodec, QJisCodec,
       QSjisCodec, QGbkCodec and QTsciiCodec.

       This is an overloaded member function, provided for
       convenience. It differs from the above function only in
       what argument(s) it accepts.


QString QTextCodec::toUnicode ( const QByteArray & a, int len )

       const
       This is an overloaded member function, provided for
       convenience. It differs from the above function only in
       what argument(s) it accepts.


QString QTextCodec::toUnicode ( const char * chars ) const

       This is an overloaded member function, provided for
       convenience.  It differs from the above function only in
       what argument(s) it accepts.


SEE ALSO

       http://doc.trolltech.com/qtextcodec.html
       http://www.trolltech.com/faq/tech.html


COPYRIGHT

       Copyright 1992-2001 Trolltech AS,
       http://www.trolltech.com.  See the license file included
       in the distribution for a complete license statement.


AUTHOR

       Generated automatically from the source code.


BUGS

       If you find a bug in Qt, please report it as described in
       http://doc.trolltech.com/bughowto.html.  Good bug reports
       make our job much simpler. Thank you.

       In case of content or formattting problems with this
       manual page, please report them to qt-bugs@trolltech.com.
       Please include the name of the manual page
       (qtextcodec.3qt) and the Qt version (2.3.1).


Man(1) output converted with man2html