1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Lars Knoll <knoll@kde.org>
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
19class KCharsetsPrivate;
20
21class QChar;
22class QString;
23
24/*!
25 * \class KCharsets
26 * \inmodule KCodecs
27 *
28 * \brief Charset font and encoder/decoder handling.
29 *
30 * This is needed, because Qt's encoding name matching in
31 * QTextCodec::codecForName() matches only closely-related encoded names
32 * but not alternate names, e.g. found in the reality of the Internet.
33 */
34class KCODECS_EXPORT KCharsets final
35{
36 Q_DECLARE_TR_FUNCTIONS(KCharsets)
37
38protected:
39 /*
40 * Protected constructor. If you need the kcharsets object, use
41 * KCharsets::charsets() instead.
42 */
43 KCharsets();
44
45public:
46 ~KCharsets();
47
48 /*!
49 * The global charset manager.
50 */
51 static KCharsets *charsets();
52
53 /*!
54 * Converts an entity to a character.
55 *
56 * The string must contain only the
57 * entity without the trailing ';'.
58 *
59 * \a str the entity
60 *
61 * Returns QChar::Null if the entity could not be decoded.
62 */
63 static QChar fromEntity(QStringView str);
64
65 /*!
66 * Tries to find an entity in the
67 * QString str.
68 *
69 * \a str the string containing entified
70 *
71 * \a len is a return value, that gives the length of the decoded
72 * entity.
73 *
74 * Returns a decoded entity if one could be found, QChar::null
75 * otherwise
76 *
77 * \overload fromEntity(QStringView)
78 */
79 static QChar fromEntity(QStringView str, int &len);
80
81 /*!
82 * Converts a QChar to an entity. The returned string does already
83 * contain the leading '&' and the trailing ';'.
84 *
85 * \a ch the char to convert
86 *
87 * Returns the entity
88 */
89 static QString toEntity(const QChar &ch);
90
91 /*!
92 * Scans the given string for entities (like &amp;amp;) and resolves them
93 * using fromEntity.
94 *
95 * \a text the string containing the entities
96 *
97 * Returns the clean string
98 */
99 static QString resolveEntities(const QString &text);
100
101 /*!
102 * Lists all available encodings as names
103 */
104 QStringList availableEncodingNames() const;
105
106 /*!
107 * Lists the available encoding names together with a more descriptive language
108 */
109 QStringList descriptiveEncodingNames() const;
110
111 /*!
112 * Lists the available encoding names grouped by script (or language that uses them).
113 *
114 * Returns the list of lists consisting of description followed by encoding names (i.e. encodingsByScript().at(i).at(0) is a description for
115 * encodingsByScript().at(i).at(k), k>0)
116 */
117 QList<QStringList> encodingsByScript() const;
118
119 /*!
120 * Returns a long description for an encoding name.
121 *
122 * \a encoding the encoding for the language
123 *
124 */
125 QString descriptionForEncoding(QStringView encoding) const;
126
127 /*!
128 * Returns the encoding for a string obtained with descriptiveEncodingNames().
129 *
130 * \a descriptiveName the descriptive name for the encoding
131 */
132 QString encodingForName(const QString &descriptiveName) const;
133
134private:
135 std::unique_ptr<KCharsetsPrivate> const d;
136 friend struct KCharsetsSingletonPrivate;
137};
138
139#endif
140

source code of kcodecs/src/kcharsets.h