File indexing completed on 2024-12-08 03:38:25

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 KCharsetsPrivate;
0020 
0021 class QChar;
0022 class QString;
0023 
0024 /**
0025  * @class KCharsets kcharsets.h KCharsets
0026  *
0027  * Charset font and encoder/decoder handling.
0028  *
0029  * This is needed, because Qt's encoding name matching in
0030  * QTextCodec::codecForName matches only closely-related encoded names
0031  * but not alternate names, e.g. found in the reality of the Internet.
0032  */
0033 class KCODECS_EXPORT KCharsets final
0034 {
0035     Q_DECLARE_TR_FUNCTIONS(KCharsets)
0036 
0037 protected:
0038     /** Protected constructor. If you need the kcharsets object, use
0039         KCharsets::charsets() instead.
0040     */
0041     KCharsets();
0042 
0043 public:
0044     /**
0045      * Destructor.
0046      */
0047     ~KCharsets();
0048 
0049     /**
0050      * The global charset manager.
0051      * @return the global charset manager
0052      */
0053     static KCharsets *charsets();
0054 
0055     /**
0056      * @brief Converts an entity to a character.
0057      *
0058      * The string must contain only the
0059      * entity without the trailing ';'.
0060      * @param str the entity
0061      * @return QChar::Null if the entity could not be decoded.
0062      */
0063     static QChar fromEntity(QStringView str);
0064 
0065     /**
0066      * Overloaded member function. Tries to find an entity in the
0067      * QString str.
0068      * @param str the string containing entified
0069      * @param len is a return value, that gives the length of the decoded
0070      * entity.
0071      * @return a decoded entity if one could be found, QChar::null
0072      * otherwise
0073      */
0074     static QChar fromEntity(QStringView str, int &len);
0075 
0076     /**
0077      * Converts a QChar to an entity. The returned string does already
0078      * contain the leading '&' and the trailing ';'.
0079      * @param ch the char to convert
0080      * @return the entity
0081      */
0082     static QString toEntity(const QChar &ch);
0083 
0084     /**
0085      * Scans the given string for entities (like &amp;amp;) and resolves them
0086      * using fromEntity.
0087      * @param text the string containing the entities
0088      * @return the clean string
0089      */
0090     static QString resolveEntities(const QString &text);
0091 
0092     /**
0093      * Lists all available encodings as names.
0094      * @return the list of all encodings
0095      */
0096     QStringList availableEncodingNames() const;
0097 
0098     /**
0099      * Lists the available encoding names together with a more descriptive language.
0100      * @return the list of descriptive encoding names
0101      */
0102     QStringList descriptiveEncodingNames() const;
0103 
0104     /**
0105      * Lists the available encoding names grouped by script (or language that uses them).
0106      * @returns the list of lists consisting of description followed by encoding names (i.e. encodingsByScript().at(i).at(0) is a description for
0107      * encodingsByScript().at(i).at(k), k>0)
0108      */
0109     QList<QStringList> encodingsByScript() const;
0110 
0111     /**
0112      * @brief Returns a long description for an encoding name.
0113      * @param encoding the encoding for the language
0114      * @return the long description for the encoding
0115      */
0116     QString descriptionForEncoding(QStringView encoding) const;
0117 
0118     /**
0119      * Returns the encoding for a string obtained with descriptiveEncodingNames().
0120      * @param descriptiveName the descriptive name for the encoding
0121      * @return the name of the encoding
0122      */
0123     QString encodingForName(const QString &descriptiveName) const;
0124 
0125 private:
0126     std::unique_ptr<KCharsetsPrivate> const d;
0127     friend struct KCharsetsSingletonPrivate;
0128 };
0129 
0130 #endif