From ad051347b86a5334261a15239f65105fdb4eaa25 Mon Sep 17 00:00:00 2001 From: LoRd_MuldeR Date: Mon, 19 Dec 2016 17:46:05 +0100 Subject: [PATCH] Fixed some typos + moved "main" page to a separate .dox file. --- README.html | 4 +- README.md | 4 +- docs/d5/d3b/_global_8h.html | 17 +++--- docs/d5/d3b/_global_8h_source.html | 2 +- docs/index.html | 67 ++++++++++++++++++++--- docs/search/all_7.js | 1 - docs/search/pages_0.html | 26 --------- docs/search/pages_0.js | 4 -- docs/search/searchdata.js | 9 ++-- include/MUtils/Global.h | 53 ++++-------------- include/MUtilsInfo.dox | 87 ++++++++++++++++++++++++++++++ 11 files changed, 172 insertions(+), 102 deletions(-) delete mode 100644 docs/search/pages_0.html delete mode 100644 docs/search/pages_0.js create mode 100644 include/MUtilsInfo.dox diff --git a/README.html b/README.html index f379771..3deda24 100644 --- a/README.html +++ b/README.html @@ -60,7 +60,7 @@ document.write(''+e+'<\
  • etc/ – miscellaneous files, everything that doesn't fit in anywhere else
  • include/ – public header files, include this directory in projects that use the MUtilities library
  • obj/ – object code files, intermediate files generated during the build process
    • -
  • res/ – resouce files, required for building the MUtilities library
    • +
  • res/ – resource files, required for building the MUtilities library
  • src/ – source code files, required for building the MUtilities library (third-party code in src/3rd_party/)
  • test/ – unit tests, based on Google Test framework
  • tmp/ – temporary files, automatically generated during the build process
    • @@ -78,7 +78,7 @@ int main(int argc, char **argv)

    4 API Documentation

    diff --git a/README.md b/README.md index 50b8267..bd3dd48 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ The *MUtilities* project directory is organized as follows: * `etc/` – miscellaneous files, everything that doesn't fit in anywhere else * `include/` – public header files, include this directory in projects that use the MUtilities library * `obj/` – object code files, intermediate files generated during the build process -* `res/` – resouce files, required for building the MUtilities library +* `res/` – resource files, required for building the MUtilities library * `src/` – source code files, required for building the MUtilities library (third-party code in `src/3rd_party/`) * `test/` – unit tests, based on Google Test framework * `tmp/` – temporary files, automatically generated during the build process @@ -37,7 +37,7 @@ Here is a minimal example on how to use the *MUtilities* library in your project * In order to use the *MUtilities* library in your project, your build environment must have already been set up for building Qt-based projects. Setting up Qt is *not* covered by this document. * Additionally, make sure that *MUtilities'* `include/` directory is contained in your "Additional Include Directories" and that the *MUtilities'* `bin/` directory is contained in your "Additional Library Directories". -* Finally, make sure that your project links against the `MUtils32-1.lib` library file. For each build configuration you have to pick the proper **.lib** file from the correspnding `bin///` directory! +* Finally, make sure that your project links against the `MUtils32-1.lib` library file. For each build configuration, pick the proper **.lib** file from the corresponding `bin///` directory! * If your projects intends to use the *MUtilities* library as a **static** library, then the macro `MUTILS_STATIC_LIB` *must* be added to your project's "Preprocessor Definitions". diff --git a/docs/d5/d3b/_global_8h.html b/docs/d5/d3b/_global_8h.html index b2e01ff..a1337ff 100644 --- a/docs/d5/d3b/_global_8h.html +++ b/docs/d5/d3b/_global_8h.html @@ -299,8 +299,8 @@ QString MUtils::clean_file
    Parameters
    - - + +
    basePathSpecifies the "base" directory where the unique file is supposed to be created. This must be a valid existing directory.
    baseNameSpecifies the desired "base" file name of the unqiue file. Do not include a file extension.
    extensionSpecifies the desired file extensions of the unqiue file. Do not include a leading dot (.) character.
    baseNameSpecifies the desired "base" file name of the unique file. Do not include a file extension.
    extensionSpecifies the desired file extensions of the unique file. Do not include a leading dot (.) character.
    fancyIf set to true, the file name is generated according to the "<basedir>/<basename> (N).<ext>" pattern; if set to false, the file name is generated according to the "<basedir>/<basename>.XXXX.<ext>" pattern.
    @@ -339,7 +339,8 @@ QString MUtils::clean_file

    This function implements a sort algorithm that orders alphanumeric strings in the way a human being would. See Natural Order String Comparison for details!

    Parameters
    - + +
    listA reference to the QStringList object to be sorted. The list will be sorted "in place".
    listA reference to the QStringList object to be sorted. The list will be sorted "in place".
    bIgnoreCaseIf set to true, the list will be sorted disregarding the character case, i.e. upper-case and lower-case characters (of the same letter) are treated the same; if set to false, the character case is taken into account.
    @@ -370,7 +371,7 @@ QString MUtils::clean_file
    -
    Returns
    The function retruns a QString holding a random hexadecimal string
    +
    Returns
    The function returns a QString holding a random hexadecimal string
    @@ -392,7 +393,7 @@ QString MUtils::clean_file

    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.

    -
    Returns
    The function retruns a random unsigned 32-Bit value.
    +
    Returns
    The function returns a random unsigned 32-Bit value.
    @@ -414,7 +415,7 @@ QString MUtils::clean_file

    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.

    -
    Returns
    The function retruns a random unsigned 64-Bit value.
    +
    Returns
    The function returns a random unsigned 64-Bit value.
    @@ -557,7 +558,7 @@ QString MUtils::clean_file

    Recursively deletes the specified directory.

    -

    The function deletes the specified directory. In recusive mode, the directory will be removed including all of its files and sub-directories. Files are deleted using the remove_file() function.

    +

    The function deletes the specified directory. In recursive mode, the directory will be removed including all of its files and sub-directories. Files are deleted using the remove_file() function.

    Parameters
    @@ -614,7 +615,7 @@ QString 
    folderPathThe path to the directory to be deleted. This should be a full path.
    MUtils::clean_file

    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!

    +

    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 terminates normally, the application's Temp folder and all files or sub-directories thereof will be removed automatically!

    Returns
    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.
    diff --git a/docs/d5/d3b/_global_8h_source.html b/docs/d5/d3b/_global_8h_source.html index 4d1e872..2484d61 100644 --- a/docs/d5/d3b/_global_8h_source.html +++ b/docs/d5/d3b/_global_8h_source.html @@ -67,7 +67,7 @@ $(function() {
    Global.h
    -Go to the documentation of this file.
    1 // MuldeR's Utilities for Qt
    3 // Copyright (C) 2004-2016 LoRd_MuldeR <MuldeR2@GMX.de>
    4 //
    5 // This library is free software; you can redistribute it and/or
    6 // modify it under the terms of the GNU Lesser General Public
    7 // License as published by the Free Software Foundation; either
    8 // version 2.1 of the License, or (at your option) any later version.
    9 //
    10 // This library is distributed in the hope that it will be useful,
    11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
    12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    13 // Lesser General Public License for more details.
    14 //
    15 // You should have received a copy of the GNU Lesser General Public
    16 // License along with this library; if not, write to the Free Software
    17 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
    18 //
    19 // http://www.gnu.org/licenses/lgpl-2.1.txt
    21 
    27 #pragma once
    28 
    29 #include <QString>
    30 
    31 //Forward Declarations
    32 class QProcess;
    33 
    35 
    36 //MUtils API
    37 #ifdef _MSC_VER
    38 # ifdef MUTILS_DLL_EXPORT
    39 # define MUTILS_API __declspec(dllexport)
    40 # else
    41 # ifndef MUTILS_STATIC_LIB
    42 # define MUTILS_API __declspec(dllimport)
    43 # else
    44 # define MUTILS_API /*static lib*/
    45 # endif
    46 # endif
    47 #else
    48 # define MUTILS_API
    49 #endif
    50 
    51 //Helper Macros
    52 #define MUTILS_MAKE_STRING_HELPER(X) #X
    53 #define MUTILS_MAKE_STRING(X) MUTILS_MAKE_STRING_HELPER(X)
    54 #define MUTILS_COMPILER_WARNING(TXT) __pragma(message(__FILE__ "(" MUTILS_MAKE_STRING(__LINE__) ") : warning: " TXT))
    55 
    56 //Check Debug Flags
    57 #if defined(_DEBUG) || defined(DEBUG) || (!defined(NDEBUG))
    58 # define MUTILS_DEBUG (1)
    59 # if defined(NDEBUG) || defined(QT_NO_DEBUG) || (!defined(QT_DEBUG))
    60 # error Inconsistent DEBUG flags have been detected!
    61 # endif
    62 #else
    63 # define MUTILS_DEBUG (0)
    64 # if (!defined(NDEBUG)) || (!defined(QT_NO_DEBUG)) || defined(QT_DEBUG)
    65 # error Inconsistent DEBUG flags have been detected!
    66 # endif
    67 #endif
    68 
    69 //Check CPU options
    70 #if defined(_MSC_VER) && (!defined(__INTELLISENSE__)) && (!defined(_M_X64)) && defined(_M_IX86_FP)
    71  #if (_M_IX86_FP != 0)
    72  #error We should not enabled SSE or SSE2 in release builds!
    73  #endif
    74 #endif
    75 
    77 
    114 namespace MUtils
    115 {
    123  MUTILS_API const QString& temp_folder(void);
    124 
    125  //Process Utils
    126  MUTILS_API void init_process(QProcess &process, const QString &wokringDir, const bool bReplaceTempDir = true, const QStringList *const extraPaths = NULL);
    127 
    135  MUTILS_API quint32 next_rand_u32(void);
    136 
    144  MUTILS_API quint64 next_rand_u64(void);
    145 
    155  MUTILS_API QString next_rand_str(const bool &bLong = false);
    156 
    170  MUTILS_API QString make_temp_file(const QString &basePath, const QString &extension, const bool placeholder = false);
    171 
    187  MUTILS_API QString make_unique_file(const QString &basePath, const QString &baseName, const QString &extension, const bool fancy = false);
    188 
    196  MUTILS_API bool parity(quint32 value);
    197 
    207  MUTILS_API bool remove_file(const QString &fileName);
    208 
    220  MUTILS_API bool remove_directory(const QString &folderPath, const bool &recursive);
    221 
    231  MUTILS_API QString& trim_right(QString &str);
    232 
    242  MUTILS_API QString& trim_left(QString &str);
    243 
    253  MUTILS_API QString trim_right(const QString &str);
    254 
    264  MUTILS_API QString trim_left(const QString &str);
    265 
    273  MUTILS_API void natural_string_sort(QStringList &list, const bool bIgnoreCase);
    274 
    275 
    276  MUTILS_API QString clean_file_name(const QString &name);
    277  MUTILS_API QString clean_file_path(const QString &path);
    278 
    290  MUTILS_API bool regexp_parse_uint32(const QRegExp &regexp, quint32 &value);
    291 
    305  MUTILS_API bool regexp_parse_uint32(const QRegExp &regexp, quint32 *values, const size_t &count);
    306 
    316  MUTILS_API QStringList available_codepages(const bool &noAliases = true);
    317 
    318  //Internal
    319  namespace Internal
    320  {
    321  MUTILS_API int selfTest(const char *const buildKey, const bool debug);
    322  static const int s_selfTest = selfTest(__DATE__ "@" __TIME__, MUTILS_DEBUG);
    323  }
    324 }
    325 
    327 
    328 //Delete helper
    329 #define MUTILS_DELETE(PTR) do { if((PTR)) { delete (PTR); (PTR) = NULL; } } while(0)
    330 #define MUTILS_DELETE_ARRAY(PTR) do { if((PTR)) { delete [] (PTR); (PTR) = NULL; } } while(0)
    331 
    332 //Zero memory
    333 #define MUTILS_ZERO_MEMORY(PTR) memset(&(PTR), 0, sizeof((PTR)))
    334 
    335 //String conversion macros
    336 #define MUTILS_WCHR(STR) (reinterpret_cast<const wchar_t*>((STR).utf16()))
    337 #define MUTILS_UTF8(STR) ((STR).toUtf8().constData())
    338 #define MUTILS_QSTR(STR) (QString::fromUtf16(reinterpret_cast<const unsigned short*>((STR))))
    339 
    340 //Boolean helper
    341 #define MUTILS_BOOL2STR(X) ((X) ? "1" : "0")
    MUtils::remove_file
    bool remove_file(const QString &fileName)
    Deletes the specified file.
    +Go to the documentation of this file.
    1 // MuldeR's Utilities for Qt
    3 // Copyright (C) 2004-2016 LoRd_MuldeR <MuldeR2@GMX.de>
    4 //
    5 // This library is free software; you can redistribute it and/or
    6 // modify it under the terms of the GNU Lesser General Public
    7 // License as published by the Free Software Foundation; either
    8 // version 2.1 of the License, or (at your option) any later version.
    9 //
    10 // This library is distributed in the hope that it will be useful,
    11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
    12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    13 // Lesser General Public License for more details.
    14 //
    15 // You should have received a copy of the GNU Lesser General Public
    16 // License along with this library; if not, write to the Free Software
    17 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
    18 //
    19 // http://www.gnu.org/licenses/lgpl-2.1.txt
    21 
    27 #pragma once
    28 
    29 #include <QString>
    30 
    31 //Forward Declarations
    32 class QProcess;
    33 
    35 
    36 //MUtils API
    37 #ifdef _MSC_VER
    38 # ifdef MUTILS_DLL_EXPORT
    39 # define MUTILS_API __declspec(dllexport)
    40 # else
    41 # ifndef MUTILS_STATIC_LIB
    42 # define MUTILS_API __declspec(dllimport)
    43 # else
    44 # define MUTILS_API /*static lib*/
    45 # endif
    46 # endif
    47 #else
    48 # define MUTILS_API
    49 #endif
    50 
    51 //Helper Macros
    52 #define MUTILS_MAKE_STRING_HELPER(X) #X
    53 #define MUTILS_MAKE_STRING(X) MUTILS_MAKE_STRING_HELPER(X)
    54 #define MUTILS_COMPILER_WARNING(TXT) __pragma(message(__FILE__ "(" MUTILS_MAKE_STRING(__LINE__) ") : warning: " TXT))
    55 
    56 //Check Debug Flags
    57 #if defined(_DEBUG) || defined(DEBUG) || (!defined(NDEBUG))
    58 # define MUTILS_DEBUG (1)
    59 # if defined(NDEBUG) || defined(QT_NO_DEBUG) || (!defined(QT_DEBUG))
    60 # error Inconsistent DEBUG flags have been detected!
    61 # endif
    62 #else
    63 # define MUTILS_DEBUG (0)
    64 # if (!defined(NDEBUG)) || (!defined(QT_NO_DEBUG)) || defined(QT_DEBUG)
    65 # error Inconsistent DEBUG flags have been detected!
    66 # endif
    67 #endif
    68 
    69 //Check CPU options
    70 #if defined(_MSC_VER) && (!defined(__INTELLISENSE__)) && (!defined(_M_X64)) && defined(_M_IX86_FP)
    71  #if (_M_IX86_FP != 0)
    72  #error We should not enabled SSE or SSE2 in release builds!
    73  #endif
    74 #endif
    75 
    77 
    78 namespace MUtils
    79 {
    87  MUTILS_API const QString& temp_folder(void);
    88 
    89  //Process Utils
    90  MUTILS_API void init_process(QProcess &process, const QString &wokringDir, const bool bReplaceTempDir = true, const QStringList *const extraPaths = NULL);
    91 
    99  MUTILS_API quint32 next_rand_u32(void);
    100 
    108  MUTILS_API quint64 next_rand_u64(void);
    109 
    119  MUTILS_API QString next_rand_str(const bool &bLong = false);
    120 
    134  MUTILS_API QString make_temp_file(const QString &basePath, const QString &extension, const bool placeholder = false);
    135 
    151  MUTILS_API QString make_unique_file(const QString &basePath, const QString &baseName, const QString &extension, const bool fancy = false);
    152 
    160  MUTILS_API bool parity(quint32 value);
    161 
    171  MUTILS_API bool remove_file(const QString &fileName);
    172 
    184  MUTILS_API bool remove_directory(const QString &folderPath, const bool &recursive);
    185 
    195  MUTILS_API QString& trim_right(QString &str);
    196 
    206  MUTILS_API QString& trim_left(QString &str);
    207 
    217  MUTILS_API QString trim_right(const QString &str);
    218 
    228  MUTILS_API QString trim_left(const QString &str);
    229 
    239  MUTILS_API void natural_string_sort(QStringList &list, const bool bIgnoreCase);
    240 
    241  MUTILS_API QString clean_file_name(const QString &name);
    242  MUTILS_API QString clean_file_path(const QString &path);
    243 
    255  MUTILS_API bool regexp_parse_uint32(const QRegExp &regexp, quint32 &value);
    256 
    270  MUTILS_API bool regexp_parse_uint32(const QRegExp &regexp, quint32 *values, const size_t &count);
    271 
    281  MUTILS_API QStringList available_codepages(const bool &noAliases = true);
    282 
    283  //Internal
    284  namespace Internal
    285  {
    286  MUTILS_API int selfTest(const char *const buildKey, const bool debug);
    287  static const int s_selfTest = selfTest(__DATE__ "@" __TIME__, MUTILS_DEBUG);
    288  }
    289 }
    290 
    292 
    293 //Delete helper
    294 #define MUTILS_DELETE(PTR) do { if((PTR)) { delete (PTR); (PTR) = NULL; } } while(0)
    295 #define MUTILS_DELETE_ARRAY(PTR) do { if((PTR)) { delete [] (PTR); (PTR) = NULL; } } while(0)
    296 
    297 //Zero memory
    298 #define MUTILS_ZERO_MEMORY(PTR) memset(&(PTR), 0, sizeof((PTR)))
    299 
    300 //String conversion macros
    301 #define MUTILS_WCHR(STR) (reinterpret_cast<const wchar_t*>((STR).utf16()))
    302 #define MUTILS_UTF8(STR) ((STR).toUtf8().constData())
    303 #define MUTILS_QSTR(STR) (QString::fromUtf16(reinterpret_cast<const unsigned short*>((STR))))
    304 
    305 //Boolean helper
    306 #define MUTILS_BOOL2STR(X) ((X) ? "1" : "0")
    MUtils::remove_file
    bool remove_file(const QString &fileName)
    Deletes the specified file.
    MUtils::next_rand_u32
    quint32 next_rand_u32(void)
    Generates a random unsigned 32-Bit value.
    MUtils::parity
    bool parity(quint32 value)
    Computes the parity of the given unsigned 32-Bit value.
    MUtils::make_unique_file
    QString make_unique_file(const QString &basePath, const QString &baseName, const QString &extension, const bool fancy=false)
    Generates a unique file name.
    diff --git a/docs/index.html b/docs/index.html index f37c015..565e796 100644 --- a/docs/index.html +++ b/docs/index.html @@ -5,7 +5,7 @@ -MuldeR's Utilities for Qt: MuldeR's Utilities for Qt +MuldeR's Utilities for Qt: Main Page @@ -60,17 +60,68 @@ $(function() {
    -
    MuldeR's Utilities for Qt
    +
    MuldeR's Utilities for Qt Documentation
    -

    The MUtilities library is a collection of routines and classes to extend the Qt cross-platform framework. 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 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.

    -

    API-Documentation

    -

    The public API of the MUtilities library is defined in the following header files:

      +

      Introduction

      +

      The MUtilities library is a collection of routines and classes to extend the Qt cross-platform framework. 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 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.

      +

      Project Structure

      +

      The MUtilities project directory is organized as follows:

      +
        +
      • bin/ – compiled library files (static or shared), link those files in projects that use the MUtilities library
        • +
      • docs/ – programming interface documentation, generated with Doxygen tool
        • +
      • etc/ – miscellaneous files, everything that doesn't fit in anywhere else
        • +
      • include/ – public header files, include this directory in projects that use the MUtilities library
        • +
      • obj/ – object code files, intermediate files generated during the build process
        • +
      • res/ – resource files, required for building the MUtilities library
        • +
      • src/ – source code files, required for building the MUtilities library (third-party code in src/3rd_party/)
        • +
      • test/ – unit tests, based on Google Test framework
        • +
      • tmp/ – temporary files, automatically generated during the build process
        • +
      +

      API Documentation

      +

      The public API of the MUtilities library is defined in the following header files (select file for details):

      • 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.

      -
      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.
    +

    Example

    +

    Here is a minimal example on how to use the MUtilities library in your project: 

    //MUtils
+#include <MUtils/Global.h>
+
+int main(int argc, char **argv)
+{
+    qDebug("Random number: %u\n", MUtils::next_rand_u32());
+}
+

    Build Notes

    +
      +
    • In order to use the MUtilities library in your project, your build environment must have already been set up for building Qt-based projects. Setting up Qt is not covered by this document.
      • +
    • Additionally, make sure that MUtilities' include/ directory is contained in your "Additional Include Directories" and that the MUtilities' bin/ directory is contained in your "Additional Library Directories".
      • +
    • Finally, make sure that your project links against the MUtils32-1.lib library file. For each build configuration, pick the proper **.lib** file from the corresponding bin/<platform>/<config>/ directory!
      • +
    • If your projects intends to use the MUtilities library as a static library, then the macro MUTILS_STATIC_LIB must be added to your project's "Preprocessor Definitions".
      • +
    +

    License

    +

    This library is free software. It is released under the terms of the GNU Lesser General Public License (LGPL), Version 2.1. 

    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.
+

    Acknowledgement

    +

    The following third-party code is used in the MUtilities library:

    +
      +
    • Keccak/SHA-3 Reference Implementation Implementation by the Keccak, Keyak and Ketje Teams, namely, Guido Bertoni, Joan Daemen, Michaël Peeters, Gilles Van Assche and Ronny Van Keer No Copyright / Dedicated to the Public Domain
      • +
    • Natural Order String Comparison Copyright (C) 2000, 2004 by Martin Pool mbp@s.nosp@m.ourc.nosp@m.efrog.nosp@m..net Released under the zlib License
      • +
    • Adler-32 Checksum Algorithm (from zlib) Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler Released under the zlib License
      • +
    +
    Generated by   diff --git a/docs/search/all_7.js b/docs/search/all_7.js index c56547f..3281d97 100644 --- a/docs/search/all_7.js +++ b/docs/search/all_7.js @@ -1,6 +1,5 @@ var searchData= [ - ['mulder_27s_20utilities_20for_20qt',['MuldeR's Utilities for Qt',['../index.html',1,'']]], ['make_5ftemp_5ffile',['make_temp_file',['../d5/d3b/_global_8h.html#a67cb16c62b213da5135a6fa076f3f005',1,'MUtils']]], ['make_5funique_5ffile',['make_unique_file',['../d5/d3b/_global_8h.html#a390e56e35eb9329d2e67fa9741d07536',1,'MUtils']]] ]; diff --git a/docs/search/pages_0.html b/docs/search/pages_0.html deleted file mode 100644 index d0102ff..0000000 --- a/docs/search/pages_0.html +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - -
    -
    Loading...
    -
    - -
    Searching...
    -
    No Matches
    - -
    - - diff --git a/docs/search/pages_0.js b/docs/search/pages_0.js deleted file mode 100644 index 08022ce..0000000 --- a/docs/search/pages_0.js +++ /dev/null @@ -1,4 +0,0 @@ -var searchData= -[ - ['mulder_27s_20utilities_20for_20qt',['MuldeR's Utilities for Qt',['../index.html',1,'']]] -]; diff --git a/docs/search/searchdata.js b/docs/search/searchdata.js index 8da7011..6c81df2 100644 --- a/docs/search/searchdata.js +++ b/docs/search/searchdata.js @@ -3,8 +3,7 @@ var indexSectionsWithContent = 0: "_abgijkmnprstuv", 1: "_bijkrstuv", 2: "g", - 3: "amnprt", - 4: "m" + 3: "amnprt" }; var indexSectionNames = @@ -12,8 +11,7 @@ var indexSectionNames = 0: "all", 1: "classes", 2: "files", - 3: "functions", - 4: "pages" + 3: "functions" }; var indexSectionLabels = @@ -21,7 +19,6 @@ var indexSectionLabels = 0: "All", 1: "Classes", 2: "Files", - 3: "Functions", - 4: "Pages" + 3: "Functions" }; diff --git a/include/MUtils/Global.h b/include/MUtils/Global.h index 4229f8a..4a577c8 100644 --- a/include/MUtils/Global.h +++ b/include/MUtils/Global.h @@ -75,48 +75,12 @@ class QProcess; /////////////////////////////////////////////////////////////////////////////// -/** -* \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 . 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 { /** * \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! + * 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 terminates normally, 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. */ @@ -130,7 +94,7 @@ namespace MUtils * * 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. + * \return The function returns a *random* unsigned 32-Bit value. */ MUTILS_API quint32 next_rand_u32(void); @@ -139,7 +103,7 @@ namespace MUtils * * 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. + * \return The function returns a *random* unsigned 64-Bit value. */ MUTILS_API quint64 next_rand_u64(void); @@ -150,7 +114,7 @@ namespace MUtils * * \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 + * \return The function returns a QString holding a *random* hexadecimal string */ MUTILS_API QString next_rand_str(const bool &bLong = false); @@ -176,9 +140,9 @@ namespace MUtils * * \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 baseName Specifies the desired "base" file name of the unique 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 extension Specifies the desired file extensions of the unique file. Do **not** include a leading dot (`.`) character. * * \param fancy If set to `true`, the file name is generated according to the `"/ (N)."` pattern; if set to `false`, the file name is generated according to the `"/.XXXX."` pattern. * @@ -209,7 +173,7 @@ namespace MUtils /** * \brief Recursively deletes the specified directory * - * The function deletes the specified directory. In *recusive* mode, the directory will be removed including all of its files and sub-directories. Files are deleted using the `remove_file()` function. + * The function deletes the specified directory. In *recursive* mode, the directory will be removed including all of its files and sub-directories. Files are deleted using the `remove_file()` function. * * \param folderPath The path to the directory to be deleted. This should be a full path. * @@ -269,10 +233,11 @@ namespace MUtils * This function implements a sort algorithm that orders alphanumeric strings in the way a human being would. See [*Natural Order String Comparison*](http://sourcefrog.net/projects/natsort/) for details! * * \param list A reference to the QStringList object to be sorted. The list will be sorted "in place". + * + * \param bIgnoreCase If set to `true`, the list will be sorted disregarding the character case, i.e. upper-case and lower-case characters (of the same letter) are treated the same; if set to `false`, the character case *is* taken into account. */ MUTILS_API void natural_string_sort(QStringList &list, const bool bIgnoreCase); - MUTILS_API QString clean_file_name(const QString &name); MUTILS_API QString clean_file_path(const QString &path); diff --git a/include/MUtilsInfo.dox b/include/MUtilsInfo.dox new file mode 100644 index 0000000..7bd871c --- /dev/null +++ b/include/MUtilsInfo.dox @@ -0,0 +1,87 @@ +/** + * @mainpage + * + * # Introduction # + * + * 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). + * + * + * # Project Structure + * + * The *MUtilities* project directory is organized as follows: + * + * - `bin/` – compiled library files (static or shared), link those files in projects that use the MUtilities library + * - `docs/` – programming interface documentation, generated with Doxygen tool + * - `etc/` – miscellaneous files, everything that doesn't fit in anywhere else + * - `include/` – public header files, include this directory in projects that use the MUtilities library + * - `obj/` – object code files, intermediate files generated during the build process + * - `res/` – resource files, required for building the MUtilities library + * - `src/` – source code files, required for building the MUtilities library (third-party code in `src/3rd_party/`) + * - `test/` – unit tests, based on Google Test framework + * - `tmp/` – temporary files, automatically generated during the build process + * + * + * # API Documentation + * + * The public API of the *MUtilities* library is defined in the following header files (select file for details): + * - **Global.h** – miscellaneous useful functions + * + * + * # Example + * + * Here is a minimal example on how to use the *MUtilities* library in your project: + * + * //MUtils + * #include + * + * int main(int argc, char **argv) + * { + * qDebug("Random number: %u\n", MUtils::next_rand_u32()); + * } + * + * ## Build Notes + * + * - In order to use the *MUtilities* library in your project, your build environment must have already been set up for building Qt-based projects. Setting up Qt is *not* covered by this document. + * - Additionally, make sure that *MUtilities'* `include/` directory is contained in your "Additional Include Directories" and that the *MUtilities'* `bin/` directory is contained in your "Additional Library Directories". + * - Finally, make sure that your project links against the `MUtils32-1.lib` library file. For each build configuration, pick the proper **.lib** file from the corresponding `bin///` directory! + * - If your projects intends to use the *MUtilities* library as a **static** library, then the macro `MUTILS_STATIC_LIB` *must* be added to your project's "Preprocessor Definitions". + * + * + * # 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 . 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. + * + * + * # Acknowledgement + * + * The following third-party code is used in the MUtilities library: + * + * - **Keccak/SHA-3 Reference Implementation** + * Implementation by the Keccak, Keyak and Ketje Teams, namely, Guido Bertoni, Joan Daemen, Michaël Peeters, Gilles Van Assche and Ronny Van Keer + * No Copyright / Dedicated to the Public Domain + * + * - **Natural Order String Comparison** + * Copyright (C) 2000, 2004 by Martin Pool + * Released under the zlib License + * + * - **Adler-32 Checksum Algorithm (from zlib)** + * Copyright (C) 1995-2013 Jean-loup Gailly and Mark Adler + * Released under the zlib License + */ \ No newline at end of file