MuldeR's Utilities for Qt MUtilities

Namespaces | Classes | Typedefs | Functions | Variables
MUtils Namespace Reference

Global MUtils namespace. More...

## Namespaces
| CPUFetaures
| This namespace contains functions and constants for detecting CPU information.
| OS
| MUtils OS-specific functions namespace.

## Classes
struct | _fp_parts_t
| This struct containes the parts (integral and fractional part) of a floating-point number. More...
class | IPCChannel
class | JobObject
| This class represents a job object. More...
class | Lazy
| Lazy initialization template class. More...
class | Taskbar7
class | UpdateChecker
class | UpdateCheckerInfo
class | Version

## Typedefs
typedef struct MUtils::_fp_parts_t | fp_parts_t
| This struct containes the parts (integral and fractional part) of a floating-point number.

## Functions
MUTILS_API const QString & | temp_folder (void)
| Rerieves the full path of the application's Temp folder. More...
MUTILS_API void | init_process (QProcess &process, const QString &wokringDir, const bool bReplaceTempDir=true, const QStringList *const extraPaths=NULL, const QHash< QString, QString > *const extraEnv=NULL)
| Initialize a given QProcess object. More...
MUTILS_API quint32 | next_rand_u32 (void)
| Generates a random unsigned 32-Bit value. More...
MUTILS_API quint32 | next_rand_u32 (const quint32 max)
MUTILS_API quint64 | next_rand_u64 (void)
| Generates a random unsigned 64-Bit value. More...
MUTILS_API QString | next_rand_str (const bool &bLong=false)
| Generates a random string. More...
MUTILS_API QString | make_temp_file (const QString &basePath, const QString &extension, const bool placeholder=false)
| Generates a temporary file name. More...
MUTILS_API QString | make_temp_file (const QDir &basePath, const QString &extension, const bool placeholder=false)
MUTILS_API QString | make_unique_file (const QString &basePath, const QString &baseName, const QString &extension, const bool fancy=false, const bool placeholder=false)
| Generates a unique file name. More...
MUTILS_API QString | make_unique_file (const QDir &basePath, const QString &baseName, const QString &extension, const bool fancy=false, const bool placeholder=false)
MUTILS_API bool | parity (quint32 value)
| Computes the parity of the given unsigned 32-Bit value. More...
MUTILS_API bool | remove_file (const QString &fileName)
| Deletes the specified file. More...
MUTILS_API bool | remove_directory (const QString &folderPath, const bool &recursive)
| Recursively deletes the specified directory. More...
MUTILS_API QString & | trim_right (QString &str)
| Remove trailing white-space characters. More...
MUTILS_API QString & | trim_left (QString &str)
| Remove leading white-space characters. More...
MUTILS_API QString | trim_right (const QString &str)
| Remove trailing white-space characters. More...
MUTILS_API QString | trim_left (const QString &str)
| Remove trailing white-space characters. More...
MUTILS_API void | natural_string_sort (QStringList &list, const bool bIgnoreCase)
| Sort a list of strings using "natural ordering" algorithm. More...
MUTILS_API QString | clean_file_name (const QString &name, const bool &pretty)
| Clean up a file name string. More...
MUTILS_API QString | clean_file_path (const QString &path, const bool &pretty)
| Clean up a file path string. More...
MUTILS_API bool | regexp_parse_uint32 (const QRegExp &regexp, quint32 &value)
| Parse regular expression results. More...
MUTILS_API bool | regexp_parse_int32 (const QRegExp &regexp, qint32 &value)
MUTILS_API bool | regexp_parse_uint32 (const QRegExp &regexp, quint32 &value, const size_t &offset)
MUTILS_API bool | regexp_parse_int32 (const QRegExp &regexp, qint32 &value, const size_t &offset)
MUTILS_API QString | parent_path (const QString &path)
| Get parent path. More...
MUTILS_API bool | regexp_parse_uint32 (const QRegExp &regexp, quint32 *values, const size_t &count)
| Parse regular expression results. More...
MUTILS_API bool | regexp_parse_int32 (const QRegExp &regexp, qint32 *values, const size_t &count)
MUTILS_API bool | regexp_parse_uint32 (const QRegExp &regexp, quint32 *values, const size_t &offset, const size_t &count)
MUTILS_API bool | regexp_parse_int32 (const QRegExp &regexp, qint32 *values, const size_t &offset, const size_t &count)
MUTILS_API QStringList | available_codepages (const bool &noAliases=true)
| Retrieve a list of all available codepages. More...
MUTILS_API fp_parts_t | break_fp (const double value)
| Break floating-point number into fractional and integral parts. More...

## Variables
class MUTILS_API | IPCChannel_Private
class MUTILS_API | Taskbar7_Private

## Detailed Description

Global MUtils namespace.

INTERNAL

## Function Documentation

## § available_codepages()

MUTILS_API QStringList MUtils::available_codepages | ( | const bool & | noAliases = `true` | ) |

Retrieve a list of all available codepages.

The function generates a list of all codepages that are available on the system. Each codepage name returned by this function may be passed to the `QTextCodec::codecForName()` function in order to obtain a corresponding QTextCodec object.

Parameters

  noAliases | If set to `true`, only distinct codepages are returned, i.e. any codepage aliases are discarded from the list; if set to `false`, the returned list may (and usually will) also contain codepage aliases.

Returns
  If the function succeeds, it returns a QStringList holding the names of all codepages available on the system; otherwise it returns a default-constructed QStringList.

## § break_fp()

MUTILS_API fp_parts_t MUtils::break_fp | ( | const double | value | ) |

Break floating-point number into fractional and integral parts.

The function returns a struct containing the fractional and the integral part of a given floating-point values as two separate values. This is a convenience warapper for the `modf()` function.

Parameters

  value | The original floating-point value

Returns
  Returns a struct containing the fractional and integral parts.

## § clean_file_name()

MUTILS_API QString MUtils::clean_file_name | ( | const QString & | name,
|  | const bool & | pretty
| ) |  |

Clean up a file name string.

This function ensures that the given string is a valid file (or directory) name. It does so by replacing any illegal characters, i.e. any characters not allowed in file names (which explicitly includes directory separators). Furthermore, the function will trim/remove specific characters that are not allowed directly at the beginning or end of a file name. Finally, the function takes care of special "reserved" file names that are forbidden by the file system. You can use this function to convert user inputs into a valid file name.

Parameters

  name | A read-only reference to the QString holding the original, potentially invalid file name.
  pretty | If set to `true`, the function tries to generate a "pretty" file name from the given file name. Otherwise, the function simply replaces each forbidden file name character by an underscore character.

Returns
  The function returns a QString holding a valid file name. If, however, the input string was empty or contained only white-space characters, the returned sting can be empty.

## § clean_file_path()

MUTILS_API QString MUtils::clean_file_path | ( | const QString & | path,
|  | const bool & | pretty
| ) |  |

Clean up a file path string.

This function ensures that the given string is a valid file (or directory) path. It does so by replacing any illegal characters, i.e. any characters not allowed in file paths. Directory separators are preserved, but they will be "canonicalized". Furthermore, in each path component, the function will trim/remove specific characters that are not allowed directly at the beginning or end of a path component. Finally, the function takes care of special "reserved" file names that are forbidden by the file system. You can use this function to convert user inputs into a valid file path.

Parameters

  path | A read-only reference to the QString holding the original, potentially invalid file path.
  pretty | If set to `true`, the function tries to generate "pretty" file names from the given file names. Otherwise, the function simply replaces each forbidden file name character by an underscore character.

Returns
  The function returns a QString holding a valid file path. If, however, the input string was empty or contained only white-space characters, the returned sting can be empty.

## § init_process()

MUTILS_API void MUtils::init_process | ( | QProcess & | process,
|  | const QString & | wokringDir,
|  | const bool | bReplaceTempDir = `true`,
|  | const QStringList *const | extraPaths = `NULL`,
|  | const QHash< QString, QString > *const | extraEnv = `NULL`
| ) |  |

Initialize a given QProcess object.

This function prepares a given QProcess object for sub-process creation. It does so by setting up combined stdout and stderr redirection for the sub-process, cleaning up the sub-process' environment variables, as well as setting up the sub-process' working directory. Optionally, the Temp directory for the sub-process can be set to the application-specific Temp directory, which is achieved by overwriting the corresponding environment variables (e.g. `TMP` and `TEMP`). Furthermore, additional paths can be added to the `PATH` environment variable of the sub-process.

Parameters

  process | A reference to the QProcess object to be initialized. The QProcess object must be initialized before calling the `QProcess::start()` method.
  process | A read-only reference to a QString holding the path of the working directory for the sub-process.
  bReplaceTempDir | If set to `true`, the Temp directory for the sub-process is set to the application-specific Temp directory; if set to `false`, the default Temp directory is retained.
  extraPaths | A read-only pointer to a QStringList object containing additional paths that will be added (prepended) to the sub-process' `PATH` environment variable. This parameter can be `NULL`, in which case no additional paths are added.

## § make_temp_file()

MUTILS_API QString MUtils::make_temp_file | ( | const QString & | basePath,
|  | const QString & | extension,
|  | const bool | placeholder = `false`
| ) |  |

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.

Parameters

  basePath | Specifies the "base" directory where the temporary file is supposed to be created. This must be a valid existing directory.
  extension | Specifies the desired file extensions of the temporary file. Do not include a leading dot (`.`) character.
  placeholder | If set to `true`, the function creates an empty "placeholder" file under the returned file name; if set to `false`, it does not.

Returns
  If the function succeeds, it returns a QString holding the full path of the temporary file; otherwise it returns a default-constructed QString.

## § make_unique_file()

MUTILS_API QString MUtils::make_unique_file | ( | const QString & | basePath,
|  | const QString & | baseName,
|  | const QString & | extension,
|  | const bool | fancy = `false`,
|  | const bool | placeholder = `false`
| ) |  |

Generates a unique file name.

The function generates a unique file name in the specified directory. The function guarantees that the returned file name does not exist yet. If necessary, a counter will be included in the file name in order to ensure its uniqueness.

Parameters

  basePath | Specifies the "base" directory where the unique file is supposed to be created. This must be a valid existing directory.
  baseName | Specifies the desired "base" file name of the unique file. Do not include a file extension.
  extension | Specifies the desired file extensions of the unique file. Do not include a leading dot (`.`) character.
  fancy | If set to `true`, the unique file name is generated according to the `"<basedir>/<basename> (N).<ext>"` pattern; if set to `false`, it is generated according to the `"<basedir>/<basename>.XXXX.<ext>"` pattern. Also, if set to `true`, a counter is only included in the file name, if the file name without counter already exists; if set to `false`, a counter is always included. Finally, if set to `true`, the counter starts at 2 and is printed in decimal format; if set to `false`, the counter starts at 0 and is printed in zero-padded hexadecimal format.

Returns
  If the function succeeds, it returns a QString holding the full path of the unique file; otherwise it returns a default-constructed QString.

## § natural_string_sort()

MUTILS_API void MUtils::natural_string_sort | ( | QStringList & | list,
|  | const bool | bIgnoreCase
| ) |  |

Sort a list of strings using "natural ordering" algorithm.

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

  list | A reference to the QStringList object to be sorted. The list will be sorted "in place".
  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.

## § next_rand_str()

MUTILS_API QString MUtils::next_rand_str | ( | const bool & | bLong = `false` | ) |

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.

Parameters

  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.

Returns
  The function returns a QString holding a random hexadecimal string

## § next_rand_u32()

MUTILS_API quint32 MUtils::next_rand_u32 | ( | void |  | ) |

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 returns a random unsigned 32-Bit value.

## § next_rand_u64()

MUTILS_API quint64 MUtils::next_rand_u64 | ( | void |  | ) |

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 returns a random unsigned 64-Bit value.

## § parent_path()

MUTILS_API QString MUtils::parent_path | ( | const QString & | path | ) |

Get parent path.

This function determines the "parent" path, by removing the last path component (file name or directory) form the given original path.

Parameters

  path | A read-only reference to the original path string.

Returns
  The remaining path string (i.e. "parent" path); an empty string if the original path only consited of a single component.

## § parity()

MUTILS_API bool MUtils::parity | ( | quint32 | value | ) |

Computes the parity of the given unsigned 32-Bit value.

Parameters

  value | The 32-Bit unsigned value from which the parity is to be computed.

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

## § regexp_parse_uint32() [1/2]

MUTILS_API bool MUtils::regexp_parse_uint32 | ( | const QRegExp & | regexp,
|  | quint32 & | value
| ) |  |

Parse regular expression results.

This function tries to parses the result (capture) of a regular expression as an unsigned 32-Bit value. The given regular expression must contain at least one capture. Only the first capture is considered, additional captures are ignored.

Parameters

  regexp | A read-only reference to the QRegExp object whose result (capture) will be parsed. This QRegExp must already have been successfully matched against the respective input string, e.g. via `QRegExp::indexIn()`, prior to calling this function.
  value | A reference to a variable of type `quint32`, where the unsigned 32-Bit representation of the result will be stored. The contents of this variable are undefined, if the function failed.

Returns
  The function returns `true`, if the regular expression's capture could be parsed successfully; it returns `false`, if the capture contains an invalid string or if there are insufficient captures in given the QRegExp object.

## § regexp_parse_uint32() [2/2]

MUTILS_API bool MUtils::regexp_parse_uint32 | ( | const QRegExp & | regexp,
|  | quint32 * | values,
|  | const size_t & | count
| ) |  |

Parse regular expression results.

This function tries to parses the results (captures) of a regular expression as unsigned 32-Bit values. The given regular expression must contain at least `count` captures. Only the first `count` captures are considered, additional captures are ignored.

Parameters

  regexp | A read-only reference to the QRegExp object whose results (captures) will be parsed. This QRegExp must already have been successfully matched against the respective input string, e.g. via `QRegExp::indexIn()`, prior to calling this function.
  value | A pointer to an array of type `quint32`, where the unsigned 32-Bit representations of the results will be stored (the `n`-th result is stored at `value[n-1]`). The array must be at least `count` elements in length. The contents of this array are undefined, if the function failed.
  count | Specifies the number of results (captures) in the given QRegExp object. The function tries to parse the first `count` captures and ignores any additional captures that may exist. This parameter also determines the required (minimum) length of the `value` array.

Returns
  The function returns `true`, if all of the regular expression's captures could be parsed successfully; it returns `false`, if any of the captures contain an invalid string or if there are insufficient captures in given the QRegExp object.

## § remove_directory()

MUTILS_API bool MUtils::remove_directory | ( | const QString & | folderPath,
|  | const bool & | recursive
| ) |  |

Recursively deletes the specified directory.

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

  folderPath | The path to the directory to be deleted. This should be a full path.
  recursive | If set to `true` the function removes all files and sub-directories in the specified directory; if set to `false`, the function will not try to delete any files or sub-directories, which means that it will fail on non-empty directories.

Returns
  The function returns `true`, if the directory was deleted successfully or if the directory doesn't exist; it returns `false`, if the directory could not be deleted.

## § remove_file()

MUTILS_API bool MUtils::remove_file | ( | const QString & | fileName | ) |

Deletes the specified file.

The function deletes the specified file, even if it has the "read only" flag set. If the file is currently locked (e.g. by another process), the function retries multiple times to delete the file before it fails.

Parameters

  fileName | The path to the file to be deleted. This should be a full path.

Returns
  The function returns `true`, if the file was deleted successfully or if the file doesn't exist; it returns `false`, if the file could not be deleted.

## § temp_folder()

MUTILS_API const QString& MUtils::temp_folder | ( | void |  | ) |

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

## § trim_left() [1/2]

MUTILS_API QString& MUtils::trim_left | ( | QString & | str | ) |

Remove leading white-space characters.

The function removes all leading white-space characters from the specified string. Trailing white-space characters are not removed. White-space characters are defined by the `\s` character class.

Parameters

  str | A reference to the QString object to be trimmed. This QString object will be modified directly.

Returns
  A reference to the trimmed QString object. This is the same QString object that was specified in the `str` parameter.

## § trim_left() [2/2]

MUTILS_API QString MUtils::trim_left | ( | const QString & | str | ) |

Remove trailing white-space characters.

The function removes all leading white-space characters from the specified string. Trailing white-space characters are not removed. White-space characters are defined by the `\s` character class.

Parameters

  str | A read-only reference to the QString object to be trimmed. The original QString object is not modified.

Returns
  A new QString object that equals the original QString object, except that it has all leading white-space characters removed.

## § trim_right() [1/2]

MUTILS_API QString& MUtils::trim_right | ( | QString & | str | ) |

Remove trailing white-space characters.

The function removes all trailing white-space characters from the specified string. Leading white-space characters are not removed. White-space characters are defined by the `\s` character class.

Parameters

  str | A reference to the QString object to be trimmed. This QString object will be modified directly.

Returns
  A reference to the trimmed QString object. This is the same QString object that was specified in the `str` parameter.

## § trim_right() [2/2]

MUTILS_API QString MUtils::trim_right | ( | const QString & | str | ) |

Remove trailing white-space characters.

The function removes all trailing white-space characters from the specified string. Leading white-space characters are not removed. White-space characters are defined by the `\s` character class.

Parameters

  str | A read-only reference to the QString object to be trimmed. The original QString object is not modified.

Returns
  A new QString object that equals the original QString object, except that it has all trailing white-space characters removed.