File indexing completed on 2024-12-08 10:15:15

 /* This file is part of the KDE project
    Copyright (C) 2003-2019 Jarosław Staniek <staniek@kde.org>
 
    Portions of kstandarddirs.cpp:
    Copyright (C) 1999 Sirtaj Singh Kang <taj@kde.org>
    Copyright (C) 1999,2007 Stephan Kulow <coolo@kde.org>
    Copyright (C) 1999 Waldo Bastian <bastian@kde.org>
    Copyright (C) 2009 David Faure <faure@kde.org>
 
    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.
 
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.
 
    You should have received a copy of the GNU Library General Public License
    along with this program; see the file COPYING.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA 02110-1301, USA.
 */
 
 #ifndef KDB_TOOLS_UTILS_H
 #define KDB_TOOLS_UTILS_H
 
 #include "kdb_export.h"
 #include "config-kdb.h"
 
 #include <QObject>
 #include <QDateTime>
 #include <QMetaMethod>
 #include <QDebug>
 
 namespace KDbUtils
 {
 
 //! @return true if @a o has parent @a par (checks recursively)
 KDB_EXPORT bool hasParent(QObject* par, QObject* o);
 
 //! @return parent object of @a o that is of type @a type or @c nullptr if no such parent
 template<class type>
 inline type findParent(QObject* o, const char* className = nullptr)
 {
     if (!o)
         return nullptr;
     while ((o = o->parent())) {
         if (::qobject_cast< type >(o) && (!className || o->inherits(className)))
             return ::qobject_cast< type >(o);
     }
     return nullptr;
 }
 
 /**
  * Returns the time as a string using Qt::ISODateWithMs format
  *
  * If milliseconds is zero then they are not appended.
  * Works also for Qt < 5.8 which does not offer QTime::toString(Qt::ISODateWithMs).
  *
  * @since 3.2
  */
 KDB_EXPORT QString toISODateStringWithMs(const QTime &time);
 
 /**
  * Returns the date/time as a string using Qt::ISODateWithMs format
  *
  * If milliseconds in time is zero then they are not appended.
  * Works also for Qt < 5.8 which does not offer QDateTime::toString(Qt::ISODateWithMs).
  *
  * @since 3.2
  */
 KDB_EXPORT QString toISODateStringWithMs(const QDateTime &dateTime);
 
 /**
  * Returns the time represented by the string using the Qt::ISODateWithMs format
  *
  * Milliseconds are optional.
  * Works also for Qt < 5.8 which does not offer QTime::fromString(QString, Qt::ISODateWithMs).
  *
  * @note Equal to QTime::fromString(string, Qt::ISODate) since the Qt::ISODate mode already
  * supports milliseconds in case of fromString().
  *
  * @since 3.2
  */
 KDB_EXPORT QTime timeFromISODateStringWithMs(const QString &string);
 
 /**
  * Returns the date/time represented by the string using the Qt::ISODateWithMs format
  *
  * Milliseconds of time are optional.
  * Works also for Qt < 5.8 which does not offer QDateTime::fromString(QString, Qt::ISODateWithMs).
  *
  * @note Equal to QDateTime::fromString(string, Qt::ISODate) since the Qt::ISODate mode already
  * supports milliseconds in case of fromString().
  *
  * @since 3.2
  */
 KDB_EXPORT QDateTime dateTimeFromISODateStringWithMs(const QString &string);
 
 //! QDateTime - a hack needed because QVariant(QTime) has broken isNull()
 KDB_EXPORT QDateTime stringToHackedQTime(const QString& s);
 
 /*! Serializes @a map to the array pointed by @a array.
  KDbUtils::deserializeMap() can be used to deserialize this array back to map.
  Does nothing if @a array is @c nullptr. */
 KDB_EXPORT void serializeMap(const QMap<QString, QString>& map, QByteArray *array);
 
 /*! Serializes @a map to the string pointed by @a string.
  KDbUtils::deserializeMap() can be used to deserialize this array back to map.
  Does nothing if @a string is @c nullptr. */
 KDB_EXPORT void serializeMap(const QMap<QString, QString>& map, QString *string);
 
 /*! @return a map deserialized from a byte array @a array.
  @a array need to contain data previously serialized using KexiUtils::serializeMap(). */
 KDB_EXPORT QMap<QString, QString> deserializeMap(const QByteArray& array);
 
 /*! @return a map deserialized from @a string.
  @a string need to contain data previously serialized using KexiUtils::serializeMap(). */
 KDB_EXPORT QMap<QString, QString> deserializeMap(const QString& string);
 
 /**
  * Returns a valid filename converted from given string
  *
  * Following steps are performed:
  * - replace \\, /, :, *, ?, ", <, >, |, \n \\t characters with a space,
  * - simplify whitespace by removing redundant space characters using QString::simplified().
  * - prepend '_' character if the first character is '.', so the file will not be considered hidden
  *   (since 3.2.0).
  *
  * @note Do not pass full paths here but only filename strings.
  */
 KDB_EXPORT QString stringToFileName(const QString& string);
 
 /*! Performs a simple @a string encryption using rot47-like algorithm.
  Each character's unicode value is increased by 47 + i (where i is index of the character).
  The resulting string still contains readable characters but some of them can be non-ASCII.
  Does nothing if @a string is @c nullptr.
  @note Do not use this for data that can be accessed by attackers! */
 KDB_EXPORT void simpleCrypt(QString *string);
 
 /*! Performs a simple @a string decryption using rot47-like algorithm,
  using opposite operations to KexiUtils::simpleCrypt().
  @return true on success and false on failure. Failue means that one or more characters have unicode
  numbers smaller than value of 47 + i. On failure @a string is not altered.
  Does nothing and returns @c false if @a string is @c nullptr.
 */
 KDB_EXPORT bool simpleDecrypt(QString *string);
 
 //! @internal
 KDB_EXPORT QString pointerToStringInternal(void* pointer, int size);
 //! @internal
 KDB_EXPORT void* stringToPointerInternal(const QString& string, int size);
 
 //! @return a pointer @a pointer safely serialized to string
 template<class type>
 QString pointerToString(type *pointer)
 {
     return pointerToStringInternal(pointer, sizeof(type*));
 }
 
 //! @return a pointer of type @a type safely deserialized from @a string
 template<class type>
 type* stringToPointer(const QString& string)
 {
     return static_cast<type*>(stringToPointerInternal(string, sizeof(type*)));
 }
 
 //! @return value converted to text, squeezed to reasonable length, useful for debugging
 //! If the value is not a byte array or string, or if it's not longer than 1024 characters,
 //! @a value is returned.
 //! @since 3.1
 KDB_EXPORT QVariant squeezedValue(const QVariant &value);
 
 //! @short Autodeleting hash
 template <class Key, class T>
 class AutodeletedHash : public QHash<Key, T>
 {
 public:
     //! Creates autodeleting hash as a copy of @a other.
     //! Auto-deletion is not enabled as it would cause double deletion for items.
     //! If you enable auto-deletion on here, make sure you disable it in the @a other hash.
     AutodeletedHash(const AutodeletedHash& other) : QHash<Key, T>(other), m_autoDelete(false) {}
 
     //! Creates empty autodeleting hash.
     //! Auto-deletion is enabled by default.
     AutodeletedHash(bool autoDelete = true) : QHash<Key, T>(), m_autoDelete(autoDelete) {}
 
     ~AutodeletedHash() {
         if (m_autoDelete) {
             qDeleteAll(*this);
         }
     }
     void setAutoDelete(bool set) {
         m_autoDelete = set;
     }
     bool autoDelete() const {
         return m_autoDelete;
     }
     void clear() {
         if (m_autoDelete) {
             qDeleteAll(*this);
         }
         QHash<Key, T>::clear();
     }
     typename QHash<Key, T>::iterator erase(typename QHash<Key, T>::iterator pos) {
         typename QHash<Key, T>::iterator it = QHash<Key, T>::erase(pos);
         if (m_autoDelete) {
             delete it.value();
             it.value() = 0;
             return it;
         }
     }
     typename QHash<Key, T>::iterator insert(const Key &key, const T &value) {
         if (m_autoDelete) {
             T &oldValue = QHash<Key, T>::operator[](key);
             if (oldValue && oldValue != value) { // only delete if differs
                 delete oldValue;
             }
         }
         return QHash<Key, T>::insert(key, value);
     }
     int remove(const Key &key) {
         if (m_autoDelete) {
             const QList<T> values(QHash<Key, T>::values(key));
             const int result = QHash<Key, T>::remove(key);
             for (T item : values) {
                 delete item;
             }
             return result;
         } else {
             return QHash<Key, T>::remove(key);
         }
     }
     // note: no need to override insertMulti(), unite(), take(), they do not replace items
 
 private:
     bool m_autoDelete;
 };
 
 //! @short Autodeleting list
 template <typename T>
 class AutodeletedList : public QList<T>
 {
 public:
     //! Creates autodeleting list as a copy of @a other.
     //! Auto-deletion is not enabled as it would cause double deletion for items.
     //! If you enable auto-deletion on here, make sure you disable it in the @a other list.
     AutodeletedList(const AutodeletedList& other)
             : QList<T>(other), m_autoDelete(false) {}
 
     //! Creates empty autodeleting list.
     //! Auto-deletion is enabled by default.
     AutodeletedList(bool autoDelete = true) : QList<T>(), m_autoDelete(autoDelete) {}
 
     ~AutodeletedList() {
         if (m_autoDelete) qDeleteAll(*this);
     }
     void setAutoDelete(bool set) {
         m_autoDelete = set;
     }
     bool autoDelete() const {
         return m_autoDelete;
     }
     void removeAt(int i) {
         T item = QList<T>::takeAt(i); if (m_autoDelete) delete item;
     }
     void removeFirst() {
         T item = QList<T>::takeFirst(); if (m_autoDelete) delete item;
     }
     void removeLast() {
         T item = QList<T>::takeLast(); if (m_autoDelete) delete item;
     }
     void replace(int i, const T& value) {
         T item = QList<T>::takeAt(i); insert(i, value); if (m_autoDelete) delete item;
     }
     void insert(int i, const T& value) {
         QList<T>::insert(i, value);
     }
     typename QList<T>::iterator erase(typename QList<T>::iterator pos) {
         T item = *pos;
         typename QList<T>::iterator res = QList<T>::erase(pos);
         if (m_autoDelete)
             delete item;
         return res;
     }
     typename QList<T>::iterator erase(
         typename QList<T>::iterator afirst,
         typename QList<T>::iterator alast) {
         if (!m_autoDelete)
             return QList<T>::erase(afirst, alast);
         while (afirst != alast) {
             T item = *afirst;
             afirst = QList<T>::erase(afirst);
             delete item;
         }
         return alast;
     }
     void pop_back() {
         removeLast();
     }
     void pop_front() {
         removeFirst();
     }
     int removeAll(const T& value) {
         if (!m_autoDelete)
             return QList<T>::removeAll(value);
         typename QList<T>::iterator it(QList<T>::begin());
         int removedCount = 0;
         while (it != QList<T>::end()) {
             if (*it == value) {
                 T item = *it;
                 it = QList<T>::erase(it);
                 delete item;
                 removedCount++;
             } else
                 ++it;
         }
         return removedCount;
     }
     void clear() {
         if (!m_autoDelete)
             return QList<T>::clear();
         while (!QList<T>::isEmpty()) {
             T item = QList<T>::takeFirst();
             delete item;
         }
     }
 
 private:
     bool m_autoDelete;
 };
 
 //! @short Case insensitive hash container supporting QString or QByteArray keys.
 //! Keys are turned to lowercase before inserting.
 template <typename Key, typename T>
 class CaseInsensitiveHash : public QHash<Key, T>
 {
 public:
     CaseInsensitiveHash() : QHash<Key, T>() {}
     typename QHash<Key, T>::iterator find(const Key& key) const {
         return QHash<Key, T>::find(key.toLower());
     }
     typename QHash<Key, T>::const_iterator constFind(const Key& key) const {
         return QHash<Key, T>::constFind(key.toLower());
     }
     bool contains(const Key& key) const {
         return QHash<Key, T>::contains(key.toLower());
     }
     int count(const Key& key) const {
         return QHash<Key, T>::count(key.toLower());
     }
     typename QHash<Key, T>::iterator insert(const Key& key, const T& value) {
         return QHash<Key, T>::insert(key.toLower(), value);
     }
     typename QHash<Key, T>::iterator insertMulti(const Key& key, const T& value) {
         return QHash<Key, T>::insertMulti(key.toLower(), value);
     }
     const Key key(const T& value, const Key& defaultKey) const {
         return QHash<Key, T>::key(value, defaultKey.toLower());
     }
     int remove(const Key& key) {
         return QHash<Key, T>::remove(key.toLower());
     }
     const T take(const Key& key) {
         return QHash<Key, T>::take(key.toLower());
     }
     const T value(const Key& key) const {
         return QHash<Key, T>::value(key.toLower());
     }
     const T value(const Key& key, const T& defaultValue) const {
         return QHash<Key, T>::value(key.toLower(), defaultValue);
     }
     QList<T> values(const Key& key) const {
         return QHash<Key, T>::values(key.toLower());
     }
     T& operator[](const Key& key) {
         return QHash<Key, T>::operator[](key.toLower());
     }
     const T operator[](const Key& key) const {
         return QHash<Key, T>::operator[](key.toLower());
     }
 };
 
 //! A set created from static (0-terminated) array of raw null-terminated strings.
 class KDB_EXPORT StaticSetOfStrings
 {
 public:
     StaticSetOfStrings();
     explicit StaticSetOfStrings(const char* const array[]);
     ~StaticSetOfStrings();
     void setStrings(const char* const array[]);
     bool isEmpty() const;
 
     //! @return true if @a string can be found within set, comparison is case sensitive
     bool contains(const QByteArray& string) const;
 private:
     class Private;
     Private * const d;
     Q_DISABLE_COPY(StaticSetOfStrings)
 };
 
 /*! @return debugging string for object @a object of type @a T */
 template <typename T>
 QString debugString(const T& object)
 {
     QString result;
     QDebug dbg(&result);
     dbg << object;
     return result;
 }
 
 //! Used by findExe().
 enum class FindExeOption {
     //! No options
     None = 0,
     //! If set, the path returned may not have the executable bit set.
     IgnoreExecBit = 1
 };
 Q_DECLARE_FLAGS(FindExeOptions, FindExeOption)
 
 /**
  * Finds the executable in the system path.
  *
  * A valid executable must be a file and have its executable bit set.
  *
  * @param appname The name of the executable file for which to search.
  *                if this contains a path separator, it will be resolved
  *                according to the current working directory
  *                (shell-like behavior).
  * @param path    The path which will be searched. If this is
  *                null (default), the @c $PATH environment variable will
  *                be searched.
  * @param options Options, see FindExeOption.
  *
  * @return The path of the executable. If it was not found, returns QString().
  */
 QString findExe(const QString& appname,
                 const QString& path = QString(),
                 FindExeOptions options = FindExeOption::None);
 
 //! A single property
 //! @note This property is general-purpose and not related to Qt Properties.
 //! @see KDbUtils::PropertySet
 class KDB_EXPORT Property {
 public:
     //! Constructs a null property
     Property();
 
     Property(const QVariant &aValue, const QString &aCaption);
 
     Property(const Property &other);
 
     ~Property();
 
     bool operator==(const Property &other) const;
 
     bool operator!=(const Property &other) const { return !operator==(other); }
 
     bool isNull() const;
 
     QVariant value() const;
 
     void setValue(const QVariant &value);
 
     QString caption() const;
 
     void setCaption(const QString &caption);
 
 private:
     class Private;
     Private * const d;
 };
 
 //! A set of properties.
 //! @note These properties are general-purpose and not related to Qt Properties.
 //! @see KDbUtils::Property
 class KDB_EXPORT PropertySet
 {
 public:
     PropertySet();
 
     PropertySet(const PropertySet &other);
 
     ~PropertySet();
 
     //! Assigns @a other to this property set and returns a reference to this property set.
     PropertySet& operator=(const PropertySet &other);
 
     //! @return true if this property set has exactly the same properties as @a other
     //! @since 3.1
     bool operator==(const PropertySet &other) const;
 
     //! @return true if this property differs in at least one property from @a other
     //! @since 3.1
     bool operator!=(const PropertySet &other) const { return !operator==(other); }
 
     //! Inserts property with a given @a name, @a value and @a caption.
     //! If @a caption is empty, caption from existing property is reused.
     //! @a name must be a valid identifier (see KDb::isIdentifier()).
     void insert(const QByteArray &name, const QVariant &value, const QString &caption = QString());
 
     //! Sets caption for property @a name to @a caption.
     //! If such property does not exist, does nothing.
     //! @since 3.1
     void setCaption(const QByteArray &name, const QString &caption);
 
     //! Sets value for property @a name to @a value.
     //! If such property does not exist, does nothing.
     //! @since 3.1
     void setValue(const QByteArray &name, const QVariant &value);
 
     //! Removes property with a given @a name.
     void remove(const QByteArray &name);
 
     //! @return property with a given @a name.
     //! If not found, a null Property is returned (Property::isNull).
     Property property(const QByteArray &name) const;
 
     //! @return a list of property names.
     QList<QByteArray> names() const;
 
 private:
     class Private;
     Private * const d;
 };
 
 } // KDbUtils
 
 #endif //KDB_TOOLS_UTILS_H