File indexing completed on 2024-12-08 09:43:25

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 1999 Waldo Bastian <bastian@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-only
0006 */
0007 
0008 #ifndef KSYCOCADICT_H
0009 #define KSYCOCADICT_H
0010 
0011 #include "ksycocaentry.h"
0012 #include <kservice_export.h>
0013 
0014 #include <QList>
0015 
0016 #include <memory>
0017 
0018 class KSycocaDictPrivate;
0019 
0020 class QString;
0021 class QDataStream;
0022 
0023 /**
0024  * @internal
0025  * Hash table implementation for the sycoca database file
0026  *
0027  * Only exported for the unit test
0028  */
0029 class KSERVICE_EXPORT KSycocaDict // krazy:exclude=dpointer (not const because it gets deleted by clear())
0030 {
0031 public:
0032     /**
0033      * Create an empty dict, for building the database
0034      */
0035     KSycocaDict();
0036     /**
0037      * Create a dict from an existing database
0038      */
0039     KSycocaDict(QDataStream *str, int offset);
0040 
0041     ~KSycocaDict();
0042 
0043     /**
0044      * Adds a 'payload' to the dictionary with key 'key'.
0045      *
0046      * 'payload' should have a valid offset by the time
0047      * the dictionary gets saved.
0048      **/
0049     void add(const QString &key, const KSycocaEntry::Ptr &payload);
0050 
0051     /**
0052      * Removes the 'payload' from the dictionary with key 'key'.
0053      *
0054      * Not very fast, use with care O(N)
0055      **/
0056     void remove(const QString &key);
0057 
0058     /**
0059      * Looks up an entry identified by 'key'.
0060      *
0061      * If 0 is returned, no matching entry exists.
0062      * Otherwise, the offset of the entry is returned.
0063      *
0064      * NOTE: It is not guaranteed that this entry is
0065      * indeed the one you were looking for.
0066      * After loading the entry you should check that it
0067      * indeed matches the search key. If it doesn't
0068      * then no matching entry exists.
0069      */
0070     int find_string(const QString &key) const;
0071 
0072     /**
0073      * Looks up all entries identified by 'key'.
0074      * This is useful when the dict is used as a multi-hash.
0075      *
0076      * If an empty list is returned, no matching entry exists.
0077      * Otherwise, the offset of the matching entries are returned.
0078      *
0079      * NOTE: It is not guaranteed that each entry is
0080      * indeed among the ones you were looking for.
0081      * After loading each entry you should check that it
0082      * indeed matches the search key.
0083      */
0084     QList<int> findMultiString(const QString &key) const;
0085 
0086     /**
0087      * The number of entries in the dictionary.
0088      *
0089      * Only valid when building the database.
0090      */
0091     uint count() const;
0092 
0093     /**
0094      * Reset the dictionary.
0095      *
0096      * Only valid when building the database.
0097      */
0098     void clear();
0099 
0100     /**
0101      * Save the dictionary to the stream
0102      * A reasonable fast hash algorithm will be created.
0103      *
0104      * Typically this will find 90% of the entries directly.
0105      * Average hash table size: nrOfItems * 20 bytes.
0106      * Average duplicate list size: nrOfItms * avgKeyLength / 5.
0107      *
0108      * Unknown keys have an average 20% chance to give a false hit.
0109      * (That's why your program should check the result)
0110      *
0111      * Example:
0112      *   Assume 1000 items with an average key length of 60 bytes.
0113      *
0114      *   Approx. 900 items will hash directly to the right entry.
0115      *   Approx. 100 items require a lookup in the duplicate list.
0116      *
0117      *   The hash table size will be approx. 20Kb.
0118      *   The duplicate list size will be approx. 12Kb.
0119      **/
0120     void save(QDataStream &str);
0121 
0122 private:
0123     Q_DISABLE_COPY(KSycocaDict)
0124     std::unique_ptr<KSycocaDictPrivate> d;
0125 };
0126 
0127 #endif