| <large>libXpertMassCore and libXpertMassGui Developer Documentation</large>

- libXpertMassCore
- Utils

# MsXpS::libXpertMassCore::Utils Class

class MsXpS::libXpertMassCore::Utils

The Utils class provides a number of utilitary features that may be of use anywhere in the XpertMass source code tree. More...

Header: | `#include <MsXpS/libXpertMassCore/Utils.hpp>`
Inherits: | QObject

- List of all members, including inherited members
- Utils is part of libXpertMassCore Utilities.

## Public Functions

| Utils(QObject *parent = nullptr)
virtual | ~Utils()
void | configureDebugMessagesFormat()
QTextStream & | qStdOut()

## Static Public Members

double | addPpm(double value, double ppm)
double | addRes(double value, double res)
bool | almostEqual(double value1, double value2, int decimal_places = 10)
QString | binaryRepresentation(int value)
QString | configSettingsFilePath
int | countZeroDecimals(double value)
void | doubleListStatistics(QList<double> list, double &sum, double &average, double &variance, double &std_dev, double &smallest_non_zero, double &smallest, double &smallest_median, double &greatest)
void | doubleVectorStatistics(std::vector<double> &vector, double &sum, double &average, double &variance, double &std_dev, double &smallest_non_zero, double &smallest, double &smallest_median, double &greatest)
QString | elideText(const QString &text, int chars_left = 4, int chars_right = 4, const QString &delimiter = "...")
QRegularExpression | endOfLineRegExp
void | initializeConfigSettingsFilePath(const QString &config_settings_file_path)
QString | joinErrorList(const MsXpS::libXpertMassCore::ErrorList &error_list, const QString &separator = "\n")
void | messageOutputFormat(QtMsgType type, const QMessageLogContext &context, const QString &msg)
QString | pointerAsString(T *ptr)
double | ppm(double value, double ppm)
double | removePpm(double value, double ppm)
double | removeRes(double value, double res)
double | res(double value, double res)
double | roundValueToDecimalPlaces(double value, int decimal_places, bool round_up = true)
QString | stanzify(const QString &text, int width)
QString | stanzifyOld(const QString &text, int width)
QString | stanzifyParagraphs(const QString &text, int width)
T * | stringAsPointer(const QString &str)
QRegularExpression | subFormulaRegExp
int | testDiffBetweenTwoTextFiles(const QString &file_path_1, const QString &file_path_2)
QString | unspacify(const QString &text)
QString | xmlIndentationToken
QRegularExpression | xyFormatMassDataRegExp

## Detailed Description

## Member Function Documentation

### `[explicit invokable]` Utils::Utils(QObject *parent = nullptr)

Constructs a Utils instance setting parent to parent.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[virtual noexcept]` Utils::~Utils()

Destructs a Utils instance.

### `[static invokable]` double Utils::addPpm(double value, double ppm)

Returns value incremented by the matching ppm part.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` double Utils::addRes(double value, double res)

Returns value incremented by the matching res part.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` bool Utils::almostEqual(double value1, double value2, int decimal_places = 10)

Returns true if both double values value1 and value2, are equal within the double representation capabilities of the platform, false otherwise.

In the comparison, the decimal_places are taken into account.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` QString Utils::binaryRepresentation(int value)

Returns a string with a binary representation of the value integer.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void Utils::configureDebugMessagesFormat()

Installs the message handler.

See also Utils::messageOutputFormat().

### `[static invokable]` int Utils::countZeroDecimals(double value)

Returns the number of zero decimals in value that are found between the decimal point and the first non-zero decimal.

For example, 0.11 would return 0 (no empty decimal)

2.001 would return 2

1000.0001254 would return 3

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` void Utils::doubleListStatistics(QList<double> list, double &sum, double &average, double &variance, double &std_dev, double &smallest_non_zero, double &smallest, double &smallest_median, double &greatest)

Returns the average of the list of `double` values.

All the values in list are process in order to compute the following:

- sum
- average
- variance
- std_dev
- smallest_non_zero
- smallest
- smallest_median
- greatest

statistical values if the corresponding parameters are non-nullptr.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also doubleVectorStatistics().

### `[static]` void Utils::doubleVectorStatistics(std::vector<double> &vector, double &sum, double &average, double &variance, double &std_dev, double &smallest_non_zero, double &smallest, double &smallest_median, double &greatest)

Returns the average of the vector of `double` values.

All the values in the container are processed in order to compute the following:

- sum
- average
- variance
- std_dev
- smallest_non_zero
- smallest
- smallest_median
- greatest

statistical values if the corresponding parameters are non-nullptr.

See also doubleListStatistics().

### `[static invokable]` QString Utils::elideText(const QString &text, int chars_left = 4, int chars_right = 4, const QString &delimiter = "...")

Returns a shortened (elided) version of the text string.

It is sometimes necessary to display, in a graphical user interface a very long string, that cannot fit in the provided widget. This function returns a shortened version of the input string.

For example, "Interesting bits of information are often lost where there are too many details", becomes "Interes...details".

chars_left: Count of characters to be kept on the left side of the string.

chars_right: Count of characters to be kept on the right side of the string.

delimiter string to use as the elision delimiter (in the above example, that is '.').

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static]` void Utils::initializeConfigSettingsFilePath(const QString &config_settings_file_path)

Sets the configuration settings file path to config_settings_file_path

This initialization function needs to be called by the program that links to this library.

The static Utils::configSettingsFilePath will then be available throughout the library code.

### `[static invokable]` QString Utils::joinErrorList(const MsXpS::libXpertMassCore::ErrorList &error_list, const QString &separator = "\n")

Returns a string obtained by concatenating all the strings in the error_list container. Each string is separated from the other with separator.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static]` void Utils::messageOutputFormat(QtMsgType type, const QMessageLogContext &context, const QString &msg)

Configures the format of all the messages that are output using qDebug(), qDebug(), qDebug(), qFatal() and qDebug() using a number of parameters.

- type The kind of message
- context The context of the message
- msg The message to output.

### `[static]` template <typename T> QString Utils::pointerAsString(T *ptr)

Returns a string representing the ptr address location.

See also stringAsPointer.

### `[static invokable]` double Utils::ppm(double value, double ppm)

Returns the delta value corresponding to value and ppm part-per-million.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### QTextStream &Utils::qStdOut()

Provides a text stream handle to the standard output.

Use:

    qStdOut() << __FILE__ << __LINE__
    << "text to the standard output,"
    << "not the error standard output."

Returns a reference to a static QTextStream that directs to the standard output.

### `[static invokable]` double Utils::removePpm(double value, double ppm)

Returns value decremented by the matching ppm part.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` double Utils::removeRes(double value, double res)

Returns value decremented by the matching res part.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` double Utils::res(double value, double res)

Return the delta corresponding to value and resolution res.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` double Utils::roundValueToDecimalPlaces(double value, int decimal_places, bool round_up = true)

Return the value double value as rounded to decimal_places.

If round_up is true then the std::ceil() is used to round up, otherwise std::round() is used.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static invokable]` QString Utils::stanzify(const QString &text, int width)

Returns a string containing a paragraph-based version of the very long single-line text.

When a text string is too long to be displayed in a line of reasonable length, inserts newline characters at positions calculated to yield a paragraph of the given width.

Newline characters can be forced in the output stanza if they appear as ""{[\n]}" in the initial text.

This function is typically used to stanzify tooltip text strings.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also stanzifyParagraphs().

### `[static invokable]` QString Utils::stanzifyOld(const QString &text, int width)

Returns a string containing a paragraph-based version of the very long single-line text.

When a text string is too long to be displayed in a line of reasonable length, inserts newline characters at positions calculated to yield a paragraph of the given width.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also stanzifyParagraphs().

### `[static invokable]` QString Utils::stanzifyParagraphs(const QString &text, int width)

Returns a string containing a series of paragraph-based versions of the very long single-line-containing paragraphs in text.

text is a string with newline characters that delimit paragraph that thelmselves are made of a very long single line. This function splits text along the `'\n'` character and each obtained very long single-line string is reduced to a set of lines to make a pararagraph (see stanzify). The with of the line in that generated paragraph is width.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also stanzify().

### `[static]` template <typename T> T *Utils::stringAsPointer(const QString &str)

Returns a pointer to type T corresponding the str representation of the pointer.

See also pointerAsString().

### `[static]` int Utils::testDiffBetweenTwoTextFiles(const QString &file_path_1, const QString &file_path_2)

Returns 0 if both files file_path_1 and file_path_2 have the same contents or 1 if theirs contents differ.

Returns -1 if any file could not be opened.

### `[static invokable]` QString Utils::unspacify(const QString &text)

Removes all space characters from a copy of the text string and returns the new string.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

## Member Variable Documentation

### QString Utils::configSettingsFilePath

String holding the QSettings-based configuration file path as set by the caller (the program linking to this library).

### QRegularExpression Utils::endOfLineRegExp

Regular expression that matches the end of line in text files.

### QRegularExpression Utils::subFormulaRegExp

Regular expression used to deconstruct the main action-formula into minus and plus component sub-formulas.

This regular expression does not account for the "<text>" title of the action-formula.

    "([+-]?)([A-Z][a-z]*)(\\d*[\\.]?\\d*)"

See also Formula::splitActionParts().

### QString Utils::xmlIndentationToken

String used to craft the indentation of the XML elements.

### QRegularExpression Utils::xyFormatMassDataRegExp

Regular expression that matches the m/z,i pairs in text files.