KCodecs

kcharsets.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 1999 Lars Knoll <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 #ifndef KCHARSETS_H
8 #define KCHARSETS_H
9 
10 #include <kcodecs_export.h>
11 
12 #include <QCoreApplication>
13 #include <QList>
14 #include <QStringList>
15 #include <memory>
16 
17 #include "kcodecs.h"
18 
19 class KCharsets;
20 class KCharsetsPrivate;
21 
22 class QChar;
23 class QString;
24 class QTextCodec;
25 
26 namespace KCodecs
27 {
28 bool parseEncodedWord(const char *&, const char *, QString *, QByteArray *, QByteArray *, const QByteArray &, CharsetOption);
29 QByteArray encodeRFC2047String(const QString &src, const QByteArray &charset);
30 };
31 
32 /**
33  * @class KCharsets kcharsets.h KCharsets
34  *
35  * Charset font and encoder/decoder handling.
36  *
37  * This is needed, because Qt's encoding name matching in
38  * QTextCodec::codecForName matches only closely-related encoded names
39  * but not alternate names, e.g. found in the reality of the Internet.
40  */
41 class KCODECS_EXPORT KCharsets
42 {
43  Q_DECLARE_TR_FUNCTIONS(KCharsets)
44 
45 protected:
46  /** Protected constructor. If you need the kcharsets object, use
47  KCharsets::charsets() instead.
48  */
49  KCharsets();
50 
51 public:
52  /**
53  * Destructor.
54  */
55  virtual ~KCharsets();
56 
57 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 101)
58  /**
59  * Provided for compatibility.
60  * @param name the name of the codec
61  * @return the QTextCodec. If the desired codec could not be found,
62  * it returns a default (ISO 8859-1) codec
63  * @deprecated since 5.101 apps should use QTextCodec::codecForName in Qt5 or Qt5Compat in Qt6 or
64  * port to QStringEncoder
65  */
66  KCODECS_DEPRECATED_VERSION(5, 101, "use QTextCodec codecForName or QStringEncoder")
67  QTextCodec *codecForName(const QString &name) const;
68 #endif
69 
70 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 101)
71  /**
72  * Tries to find a QTextCodec to convert the given encoding from and to
73  * Unicode.
74  *
75  * If no codec could be found, the ISO 8859-1 codec will be returned an
76  * and @p ok will be set to false.
77  * @deprecated apps should use QTextCodec::codecForName in Qt5 or Qt5Compat in Qt6 or
78  * port to QStringEncoder
79  *
80  * @param n the name of the codec
81  * @param ok true if a matching codec has been found, false if not
82  * @return the QTextCodec. If the desired codec could not be found,
83  * it returns a default (ISO 8859-1) codec
84  */
85  KCODECS_DEPRECATED_VERSION(5, 101, "use QTextCodec codecForName or QStringEncoder")
86  QTextCodec *codecForName(const QString &n, bool &ok) const;
87 #endif
88 
89  /**
90  * The global charset manager.
91  * @return the global charset manager
92  */
93  static KCharsets *charsets();
94 
95  /**
96  * @brief Converts an entity to a character.
97  *
98  * The string must contain only the
99  * entity without the trailing ';'.
100  * @param str the entity
101  * @return QChar::Null if the entity could not be decoded.
102  */
103  static QChar fromEntity(const QString &str);
104 
105  /**
106  * Overloaded member function. Tries to find an entity in the
107  * QString str.
108  * @param str the string containing entified
109  * @param len is a return value, that gives the length of the decoded
110  * entity.
111  * @return a decoded entity if one could be found, QChar::null
112  * otherwise
113  */
114  static QChar fromEntity(const QString &str, int &len);
115 
116  /**
117  * Converts a QChar to an entity. The returned string does already
118  * contain the leading '&' and the trailing ';'.
119  * @param ch the char to convert
120  * @return the entity
121  */
122  static QString toEntity(const QChar &ch);
123 
124  /**
125  * Scans the given string for entities (like &amp;amp;) and resolves them
126  * using fromEntity.
127  * @param text the string containing the entities
128  * @return the clean string
129  */
130  static QString resolveEntities(const QString &text);
131 
132  /**
133  * Lists all available encodings as names.
134  * @return the list of all encodings
135  */
136  QStringList availableEncodingNames() const;
137 
138  /**
139  * Lists the available encoding names together with a more descriptive language.
140  * @return the list of descriptive encoding names
141  */
142  QStringList descriptiveEncodingNames() const;
143 
144  /**
145  * Lists the available encoding names grouped by script (or language that uses them).
146  * @returns the list of lists consisting of description followed by encoding names (i.e. encodingsByScript().at(i).at(0) is a description for
147  * encodingsByScript().at(i).at(k), k>0)
148  */
149  QList<QStringList> encodingsByScript() const;
150 
151  /**
152  * @brief Returns a long description for an encoding name.
153  * @param encoding the encoding for the language
154  * @return the long description for the encoding
155  */
156  QString descriptionForEncoding(const QString &encoding) const;
157 
158  /**
159  * Returns the encoding for a string obtained with descriptiveEncodingNames().
160  * @param descriptiveName the descriptive name for the encoding
161  * @return the name of the encoding
162  */
163  QString encodingForName(const QString &descriptiveName) const;
164 
165 private:
166 #if KCODECS_ENABLE_DEPRECATED_SINCE(5, 101)
167  /**
168  * @brief Get the QTextCodec for the name or return NULL
169  *
170  * This function is similar to KCharsets::codecForName except that it
171  * can return a NULL value when the name was not found.
172  * @deprecated apps should use QTextCodec::codecForName in Qt5 or Qt5Compat in Qt6 or
173  * port to QStringEncoder
174  *
175  * @param n name of the text codec
176  * @return pointer to the QTextCodec or NULL
177  * @todo Make this function public when it is clear what API is needed.
178  */
179  KCODECS_DEPRECATED_VERSION(5, 101, "use QTextCodec codecForName or QStringEncoder")
180  QTextCodec *codecForNameOrNull(const QByteArray &n) const;
181 #endif
182 
183 private:
184  std::unique_ptr<KCharsetsPrivate> const d;
185  friend struct KCharsetsSingletonPrivate;
186  friend bool KCodecs::parseEncodedWord(const char *&, const char *, QString *, QByteArray *, QByteArray *, const QByteArray &, KCodecs::CharsetOption);
187  friend QByteArray KCodecs::encodeRFC2047String(const QString &src, const QByteArray &charset);
188  friend class KCharsetsTest;
189 };
190 
191 #endif
CharsetOption
Charset options for RFC2047 encoder.
Definition: kcodecs.h:291
KIMAP_EXPORT QTextCodec * codecForName(const QString &name)
A wrapper class for the most commonly used encoding and decoding algorithms.
Definition: kcharsets.h:26
QByteArray encodeRFC2047String(const QString &src, const QByteArray &charset)
Encodes string src according to RFC2047 using charset charset.
Definition: kcodecs.cpp:441
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Feb 7 2023 04:06:47 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.