// http://www.gnu.org/licenses/lgpl-2.1.txt
//////////////////////////////////////////////////////////////////////////////////
+/**
+* @file
+* @brief This file contains miscellaneous functions that are generally useful for Qt-based applications
+*/
+
#pragma once
#include <QString>
///////////////////////////////////////////////////////////////////////////////
+/**
+* \mainpage MuldeR's Utilities for Qt
+*
+* The **MUtilities** library is a collection of routines and classes to extend the [*Qt cross-platform framework*](http://qt-project.org/). It contains various convenience and utility functions as well as wrappers for OS-specific functionalities. The library was originally created as a "side product" of the [**LameXP**](http://lamexp.sourceforge.net/) application: Over the years, a lot of code, **not** really specific to *LameXP*, had accumulated in the *LameXP* code base. Some of that code even had been used in other projects too, in a "copy & paste" fashion – which had lead to redundancy and much complicated maintenance. In order to clean-up the LameXP code base, to eliminate the ugly redundancy and to simplify maintenance, the code in question has finally been refactored into the **MUtilities** (aka "MuldeR's Utilities for Qt") library. This library now forms the foundation of *LameXP* and [*other OpenSource projects*](https://github.com/lordmulder).
+*
+*
+* ### API-Documentation
+*
+* The public API of the *MUtilities* library is defined in the following header files:
+* - **Global.h** – miscellaneous useful functions
+*
+*
+* ### License
+*
+* This library is free software. It is released under the terms of the [GNU Lesser General Public License (LGPL), Version 2.1](https://www.gnu.org/licenses/lgpl-2.1.html).
+*
+* ```
+* MUtilities - MuldeR's Utilities for Qt
+* Copyright (C) 2004-2016 LoRd_MuldeR <MuldeR2@GMX.de>. Some rights reserved.
+*
+* This library is free software; you can redistribute it and/or
+* modify it under the terms of the GNU Lesser General Public
+* License as published by the Free Software Foundation; either
+* version 2.1 of the License, or (at your option) any later version.
+*
+* This library 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
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this library; if not, write to the Free Software
+* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+* ```
+*/
+
namespace MUtils
{
- //Temp Folder
+ /**
+ * \brief Rerieves the full path of the application's *Temp* folder.
+ *
+ * The application's *Temp* folder is a unique application-specific folder, intended to store any temporary files that the application may need. It will be created when this function is called for the first time (lazy initialization); subsequent calls are guaranteed to return the same path. Usually the application's *Temp* folder will be created as a sub-folder of the system's global *Temp* folder, as indicated by the `TMP` or `TEMP` environment variables. However, it may be created at a different place(e.g. in the users *Profile* directory), if those environment variables don't point to a usable directory. In any case, this function makes sure that the application's *Temp* folder exists for the whole lifetime of the application and that it is writable. When the application is about to terminate, the application's *Temp* folder and all files or sub-directories thereof will be *removed* automatically!
+ *
+ * \return If the function succeeds, it returns a read-only reference to a QString holding the full path of the application's *Temp* folder; otherwise a read-only reference to a default-constructed QString is returned.
+ */
MUTILS_API const QString& temp_folder(void);
//Process Utils
MUTILS_API void init_process(QProcess &process, const QString &wokringDir, const bool bReplaceTempDir = true, const QStringList *const extraPaths = NULL);
- //Random
- MUTILS_API void seed_rand(void);
- MUTILS_API QString next_rand_str(const bool &bLong = false);
+ /**
+ * \brief Generates a *random* unsigned 32-Bit value.
+ *
+ * The *random* value is created using a "strong" PRNG of the underlying system, if possible. Otherwise a fallback PRNG is used. It is **not** required or useful to call `srand()` or `qsrand()` prior to using this function. If necessary, the seeding of the PRNG happen *automatically* on the first call.
+ *
+ * \return The function retruns a *random* unsigned 32-Bit value.
+ */
MUTILS_API quint32 next_rand_u32(void);
+
+ /**
+ * \brief Generates a *random* unsigned 64-Bit value.
+ *
+ * The *random* value is created using a "strong" PRNG of the underlying system, if possible. Otherwise a fallback PRNG is used. It is **not** required or useful to call `srand()` or `qsrand()` prior to using this function. If necessary, the seeding of the PRNG happen *automatically* on the first call.
+ *
+ * \return The function retruns a *random* unsigned 64-Bit value.
+ */
MUTILS_API quint64 next_rand_u64(void);
+
+ /**
+ * \brief Generates a *random* string.
+ *
+ * The random string is generated using the same PRNG as the `next_rand_u64()` function. The *random* bytes are converted to a hexadecimal string and, if necessary, zero-padded to a toal length of 16 or 32 characters. There is **no** `0x`-prefix included in the result.
+ *
+ * \param bLong If set to `true`, a "long" random string (32 characters) will be generated; if set to `false`, a "short" random string (16 characters) is generated.
+ *
+ * \return The function retruns a QString holding a *random* hexadecimal string
+ */
+ MUTILS_API QString next_rand_str(const bool &bLong = false);
- //File Name
+ /**
+ * \brief Generates a temporary file name.
+ *
+ * The function generates a file name that contains a *random* component and that is guaranteed to **not** exist yet. The generated file name follows a `"<basedir>/<random>.<ext>"` pattern. This is useful (not only) for creating temporary files.
+ *
+ * \param basePath Specifies the "base" directory where the temporary file is supposed to be created. This must be a valid *existing* directory.
+ *
+ * \param extension Specifies the desired file extensions of the temporary file. Do **not** include a leading dot (`.`) character.
+ *
+ * \param placeholder If set to `true`, the function creates an empty "placeholder" file under the returned file name; if set to `false`, it does *not*.
+ *
+ * \return If the function succeeds, it returns a QString holding the full path of the temporary file; otherwise it returns a default-constructed QString.
+ */
MUTILS_API QString make_temp_file(const QString &basePath, const QString &extension, const bool placeholder = false);
+
+ /**
+ * \brief Generates a unique file name.
+ *
+ * The function generates a unique file name in the specified directory. The function guarantees that the return file name does *not* exist yet. If necessary, a *counter* will be included in the file name in order to ensure its uniqueness.
+ *
+ * \param basePath Specifies the "base" directory where the unique file is supposed to be created. This must be a valid *existing* directory.
+ *
+ * \param baseName Specifies the desired "base" file name of the unqiue file. Do **not** include a file extension.
+ *
+ * \param extension Specifies the desired file extensions of the unqiue file. Do **not** include a leading dot (`.`) character.
+ *
+ * \param fancy If set to `true`, the file name is generated according to the `"<basedir>/<basername> (N).<ext>"` pattern; if set to `false`, the file name is generated according to the `"<basedir>/<basername>.XXXX.<ext>"` pattern.
+ *
+ * \return If the function succeeds, it returns a QString holding the full path of the unique file; otherwise it returns a default-constructed QString.
+ */
MUTILS_API QString make_unique_file(const QString &basePath, const QString &baseName, const QString &extension, const bool fancy = false);
- //Parity
+ /**
+ * \brief Computes the *parity* of the given unsigned 32-Bit value
+ *
+ * \param value The 32-Bit unsigned value from which the parity is to be computed.
+ *
+ * \return The function returns `true`, if the number of **1** bits in the given value is *odd*; it returns `false`, if the number of **1** bits in the given value is *even*.
+ */
MUTILS_API bool parity(quint32 value);
//Remove File/Dir
//////////////////////////////////////////////////////////////////////////////////
#if _MSC_VER
-#define _CRT_RAND_S 1
+//#define _CRT_RAND_S 1
#endif
//MUtils
#include <MUtils/Global.h>
#include <MUtils/OSSupport.h>
+#include <MUtils/Version.h>
//Internal
#include "DirLocker.h"
#include <QPair>
#include <QListIterator>
#include <QMutex>
+#include <QThreadStorage>
//CRT
#include <cstdlib>
#define rand_s(X) (true)
#endif
+//Per-thread init flag
+static QThreadStorage<bool> g_srand_flag;
+
//Robert Jenkins' 96 bit Mix Function
-static unsigned int mix_function(const unsigned int x, const unsigned int y, const unsigned int z)
+static quint32 mix_function(const quint32 x, const quint32 y, const quint32 z)
{
- unsigned int a = x;
- unsigned int b = y;
- unsigned int c = z;
+ quint32 a = x;
+ quint32 b = y;
+ quint32 c = z;
a=a-b; a=a-c; a=a^(c >> 13);
- b=b-c; b=b-a; b=b^(a << 8 );
+ b=b-c; b=b-a; b=b^(a << 8);
c=c-a; c=c-b; c=c^(b >> 13);
a=a-b; a=a-c; a=a^(c >> 12);
b=b-c; b=b-a; b=b^(a << 16);
- c=c-a; c=c-b; c=c^(b >> 5 );
- a=a-b; a=a-c; a=a^(c >> 3 );
+ c=c-a; c=c-b; c=c^(b >> 5);
+ a=a-b; a=a-c; a=a^(c >> 3);
b=b-c; b=b-a; b=b^(a << 10);
c=c-a; c=c-b; c=c^(b >> 15);
return a ^ b ^ c;
}
-void MUtils::seed_rand(void)
+static void seed_rand(void)
{
- qsrand(mix_function(clock(), time(NULL), _getpid()));
+ fprintf(stderr, "SEED RAND (TID: %u)\n", MUtils::OS::thread_id());
+ QDateTime build(MUtils::Version::lib_build_date(), MUtils::Version::lib_build_time());
+ const quint32 seed = mix_function(MUtils::OS::process_id(), MUtils::OS::thread_id(), build.toMSecsSinceEpoch());
+ qsrand(mix_function(clock(), time(NULL), seed));
+}
+
+static quint32 rand_fallback(void)
+{
+ Q_ASSERT(RAND_MAX >= 0xFFF);
+ if (!(g_srand_flag.hasLocalData() && g_srand_flag.localData()))
+ {
+ seed_rand();
+ g_srand_flag.setLocalData(true);
+ }
+ quint32 rnd = 0x32288EA3;
+ for (size_t i = 0; i < 3; i++)
+ {
+ rnd = (rnd << 12) ^ qrand();
+ }
+ return rnd;
}
quint32 MUtils::next_rand_u32(void)
quint32 rnd;
if (rand_s(&rnd))
{
- for (size_t i = 0; i < sizeof(quint32); i += 2)
- {
- rnd = (rnd << 16) ^ qrand();
- }
+ return rand_fallback();
}
return rnd;
}
OSDN Git Service
