File indexing completed on 2024-07-07 14:14:13

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 1999 Lars Knoll <knoll@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 #ifndef KCHARSETS_H
0008 #define KCHARSETS_H
0009 
0010 #include <kcodecs_export.h>
0011 
0012 #include <QCoreApplication>
0013 #include <QList>
0014 #include <QStringList>
0015 #include <memory>
0016 
0017 #include "kcodecs.h"
0018 
0019 class KCharsets;
0020 class KCharsetsPrivate;
0021 
0022 class QChar;
0023 class QString;
0024 class QTextCodec;
0025 
0026 namespace KCodecs
0027 {
0028 bool parseEncodedWord(const char *&, const char *, QString *, QByteArray *, QByteArray *, const QByteArray &, CharsetOption);
0029 QByteArray encodeRFC2047String(const QString &src, const QByteArray &charset);
0030 };
0031 
0032 /**
0033  * @class KCharsets kcharsets.h KCharsets
0034  *
0035  * Charset font and encoder/decoder handling.
0036  *
0037  * This is needed, because Qt's encoding name matching in
0038  * QTextCodec::codecForName matches only closely-related encoded names
0039  * but not alternate names, e.g. found in the reality of the Internet.
0040  */
0041 class KCODECS_EXPORT KCharsets
0042 {
0043     Q_DECLARE_TR_FUNCTIONS(KCharsets)
0044 
0045 protected:
0046     /** Protected constructor. If you need the kcharsets object, use
0047         KCharsets::charsets() instead.
0048     */
0049     KCharsets();
0050 
0051 public:
0052     /**
0053      * Destructor.
0054      */
0055     virtual ~KCharsets();
0056 
0057 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 101)
0058     /**
0059      * Provided for compatibility.
0060      * @param name the name of the codec
0061      * @return the QTextCodec. If the desired codec could not be found,
0062      *         it returns a default (ISO 8859-1) codec
0063      * @deprecated since 5.101 apps should use QTextCodec::codecForName in Qt5 or Qt5Compat in Qt6 or
0064      * port to QStringEncoder
0065      */
0066     KCODECS_DEPRECATED_VERSION(5, 101, "use QTextCodec codecForName or QStringEncoder")
0067     QTextCodec *codecForName(const QString &name) const;
0068 #endif
0069 
0070 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 101)
0071     /**
0072      * Tries to find a QTextCodec to convert the given encoding from and to
0073      * Unicode.
0074      *
0075      * If no codec could be found, the ISO 8859-1 codec will be returned an
0076      * and @p ok will be set to false.
0077      * @deprecated apps should use QTextCodec::codecForName in Qt5 or Qt5Compat in Qt6 or 
0078      * port to QStringEncoder
0079      *
0080      * @param n the name of the codec
0081      * @param ok true if a matching codec has been found, false if not
0082      * @return the QTextCodec. If the desired codec could not be found,
0083      *         it returns a default (ISO 8859-1) codec
0084      */
0085     KCODECS_DEPRECATED_VERSION(5, 101, "use QTextCodec codecForName or QStringEncoder")
0086     QTextCodec *codecForName(const QString &n, bool &ok) const;
0087 #endif
0088 
0089     /**
0090      * The global charset manager.
0091      * @return the global charset manager
0092      */
0093     static KCharsets *charsets();
0094 
0095     /**
0096      * @brief Converts an entity to a character.
0097      *
0098      * The string must contain only the
0099      * entity without the trailing ';'.
0100      * @param str the entity
0101      * @return QChar::Null if the entity could not be decoded.
0102      */
0103     static QChar fromEntity(const QString &str);
0104 
0105     /**
0106      * Overloaded member function. Tries to find an entity in the
0107      * QString str.
0108      * @param str the string containing entified
0109      * @param len is a return value, that gives the length of the decoded
0110      * entity.
0111      * @return a decoded entity if one could be found, QChar::null
0112      * otherwise
0113      */
0114     static QChar fromEntity(const QString &str, int &len);
0115 
0116     /**
0117      * Converts a QChar to an entity. The returned string does already
0118      * contain the leading '&' and the trailing ';'.
0119      * @param ch the char to convert
0120      * @return the entity
0121      */
0122     static QString toEntity(const QChar &ch);
0123 
0124     /**
0125      * Scans the given string for entities (like &amp;amp;) and resolves them
0126      * using fromEntity.
0127      * @param text the string containing the entities
0128      * @return the clean string
0129      */
0130     static QString resolveEntities(const QString &text);
0131 
0132     /**
0133      * Lists all available encodings as names.
0134      * @return the list of all encodings
0135      */
0136     QStringList availableEncodingNames() const;
0137 
0138     /**
0139      * Lists the available encoding names together with a more descriptive language.
0140      * @return the list of descriptive encoding names
0141      */
0142     QStringList descriptiveEncodingNames() const;
0143 
0144     /**
0145      * Lists the available encoding names grouped by script (or language that uses them).
0146      * @returns the list of lists consisting of description followed by encoding names (i.e. encodingsByScript().at(i).at(0) is a description for
0147      * encodingsByScript().at(i).at(k), k>0)
0148      */
0149     QList<QStringList> encodingsByScript() const;
0150 
0151     /**
0152      * @brief Returns a long description for an encoding name.
0153      * @param encoding the encoding for the language
0154      * @return the long description for the encoding
0155      */
0156     QString descriptionForEncoding(const QString &encoding) const;
0157 
0158     /**
0159      * Returns the encoding for a string obtained with descriptiveEncodingNames().
0160      * @param descriptiveName the descriptive name for the encoding
0161      * @return the name of the encoding
0162      */
0163     QString encodingForName(const QString &descriptiveName) const;
0164 
0165 private:
0166 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 101)
0167     /**
0168      * @brief Get the QTextCodec for the name or return NULL
0169      *
0170      * This function is similar to KCharsets::codecForName except that it
0171      * can return a NULL value when the name was not found.
0172      * @deprecated apps should use QTextCodec::codecForName in Qt5 or Qt5Compat in Qt6 or
0173      * port to QStringEncoder
0174      *
0175      * @param n name of the text codec
0176      * @return pointer to the QTextCodec or NULL
0177      * @todo Make this function public when it is clear what API is needed.
0178      */
0179     KCODECS_DEPRECATED_VERSION(5, 101, "use QTextCodec codecForName or QStringEncoder")
0180     QTextCodec *codecForNameOrNull(const QByteArray &n) const;
0181 #endif
0182 
0183 private:
0184     std::unique_ptr<KCharsetsPrivate> const d;
0185     friend struct KCharsetsSingletonPrivate;
0186     friend bool KCodecs::parseEncodedWord(const char *&, const char *, QString *, QByteArray *, QByteArray *, const QByteArray &, KCodecs::CharsetOption);
0187     friend QByteArray KCodecs::encodeRFC2047String(const QString &src, const QByteArray &charset);
0188     friend class KCharsetsTest;
0189 };
0190 
0191 #endif