File indexing completed on 2024-11-10 12:18:18
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;) 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