- Qt 6.8
- Qt Core
- <QtNumeric> - Qt Numeric Functions
- Qt 6.8.3 Reference Documentation

# <QtNumeric> - Qt Numeric Functions

The <QtNumeric> header file provides common numeric functions. More...

Header: | `#include <QtNumeric>`

## Functions

T | qAbs(const T &t)
`(since 6.1)` typename std::enable_if_t<std::is_unsigned_v<T> || std::is_signed_v<T>, bool> | qAddOverflow(T v1, T v2, T *result)
quint64 | qFloatDistance(double a, double b)
quint32 | qFloatDistance(float a, float b)
int | qFpClassify(double val)
int | qFpClassify(float val)
bool | qFuzzyCompare(double p1, double p2)
bool | qFuzzyCompare(float p1, float p2)
bool | qFuzzyIsNull(double d)
bool | qFuzzyIsNull(float f)
double | qInf()
bool | qIsFinite(double d)
bool | qIsFinite(float f)
bool | qIsInf(double d)
bool | qIsInf(float f)
bool | qIsNaN(double d)
bool | qIsNaN(float f)
`(since 6.1)` typename std::enable_if_t<std::is_unsigned_v<T> || std::is_signed_v<T>, bool> | qMulOverflow(T v1, T v2, T *result)
double | qQNaN()
qint64 | qRound64(double d)
qint64 | qRound64(float d)
int | qRound(double d)
int | qRound(float d)
double | qSNaN()
`(since 6.1)` typename std::enable_if_t<std::is_unsigned_v<T> || std::is_signed_v<T>, bool> | qSubOverflow(T v1, T v2, T *result)

## Detailed Description

The <QtNumeric> header file contains various numeric functions for comparing and adjusting a numeric value.

## Function Documentation

### int qFpClassify(double val)

### int qFpClassify(float val)

Classifies a floating-point value.

The return values are defined in `<cmath>`: returns one of the following, determined by the floating-point class of val:

- FP_NAN not a number
- FP_INFINITE infinities (positive or negative)
- FP_ZERO zero (positive or negative)
- FP_NORMAL finite with a full mantissa
- FP_SUBNORMAL finite with a reduced mantissa

### `[constexpr]` template <typename T> T qAbs(const T &t)

Compares t to the 0 of type T and returns the absolute value. Thus if T is double, then t is compared to (double) 0.

Example:

     int absoluteValue;
     int myValue = -4;

     absoluteValue = qAbs(myValue);
     // absoluteValue == 4

### `[since 6.1]` template <typename T> typename std::enable_if_t<std::is_unsigned_v<T> || std::is_signed_v<T>, bool> qAddOverflow(T v1, T v2, T *result)

Adds two values v1 and v2, of a numeric type `T` and records the value in result. If the addition overflows the valid range for type `T`, returns `true`, otherwise returns `false`.

An implementation is guaranteed to be available for 8-, 16-, and 32-bit integer types, as well as integer types of the size of a pointer. Overflow math for other types, if available, is considered private API.

This function was introduced in Qt 6.1.

### quint64 qFloatDistance(double a, double b)

Returns the number of representable floating-point numbers between a and b.

This function serves the same purpose as `qFloatDistance(float, float)`, but returns the distance between two `double` numbers. Since the range is larger than for two `float` numbers (`[-DBL_MAX,DBL_MAX]`), the return type is quint64.

See also qFuzzyCompare().

### quint32 qFloatDistance(float a, float b)

Returns the number of representable floating-point numbers between a and b.

This function provides an alternative way of doing approximated comparisons of floating-point numbers similar to qFuzzyCompare(). However, it returns the distance between two numbers, which gives the caller a possibility to choose the accepted error. Errors are relative, so for instance the distance between 1.0E-5 and 1.00001E-5 will give 110, while the distance between 1.0E36 and 1.00001E36 will give 127.

This function is useful if a floating point comparison requires a certain precision. Therefore, if a and b are equal it will return 0. The maximum value it will return for 32-bit floating point numbers is 4,278,190,078. This is the distance between `-FLT_MAX` and `+FLT_MAX`.

The function does not give meaningful results if any of the arguments are `Infinite` or `NaN`. You can check for this by calling qIsFinite().

The return value can be considered as the "error", so if you for instance want to compare two 32-bit floating point numbers and all you need is an approximated 24-bit precision, you can use this function like this:

         if (qFloatDistance(a, b) < (1 << 7)) {   // The last 7 bits are not
                                                 // significant
             // precise enough
         }

See also qFuzzyCompare().

### `[constexpr noexcept]` bool qFuzzyCompare(double p1, double p2)

Compares the floating point value p1 and p2 and returns `true` if they are considered equal, otherwise `false`.

Note that comparing values where either p1 or p2 is 0.0 will not work, nor does comparing values where one of the values is NaN or infinity. If one of the values is always 0.0, use qFuzzyIsNull instead. If one of the values is likely to be 0.0, one solution is to add 1.0 to both values.

     // Instead of comparing with 0.0
     qFuzzyCompare(0.0, 1.0e-200); // This will return false
     // Compare adding 1 to both values will fix the problem
     qFuzzyCompare(1 + 0.0, 1 + 1.0e-200); // This will return true

The two numbers are compared in a relative way, where the exactness is stronger the smaller the numbers are.

Note: This function is thread-safe.

### `[constexpr noexcept]` bool qFuzzyCompare(float p1, float p2)

Compares the floating point value p1 and p2 and returns `true` if they are considered equal, otherwise `false`.

The two numbers are compared in a relative way, where the exactness is stronger the smaller the numbers are.

Note: This function is thread-safe.

### `[constexpr noexcept]` bool qFuzzyIsNull(double d)

Returns true if the absolute value of d is within 0.000000000001 of 0.0.

Note: This function is thread-safe.

### `[constexpr noexcept]` bool qFuzzyIsNull(float f)

Returns true if the absolute value of f is within 0.00001f of 0.0.

Note: This function is thread-safe.

### double qInf()

Returns the bit pattern for an infinite number as a double.

See also qIsInf().

### bool qIsFinite(double d)

Returns `true` if the double d is a finite number.

### bool qIsFinite(float f)

Returns `true` if the float f is a finite number.

### bool qIsInf(double d)

Returns `true` if the double d is equivalent to infinity.

See also qInf().

### bool qIsInf(float f)

Returns `true` if the float f is equivalent to infinity.

See also qInf().

### bool qIsNaN(double d)

Returns `true` if the double d is not a number (NaN).

### bool qIsNaN(float f)

Returns `true` if the float f is not a number (NaN).

### `[since 6.1]` template <typename T> typename std::enable_if_t<std::is_unsigned_v<T> || std::is_signed_v<T>, bool> qMulOverflow(T v1, T v2, T *result)

Multiplies v1 and v2, and records the resulting value in result. If the multiplication overflows the valid range for type `T`, returns `true`, otherwise returns `false`.

An implementation is guaranteed to be available for 8-, 16-, and 32-bit integer types, as well as integer types of the size of a pointer. Overflow math for other types, if available, is considered private API.

This function was introduced in Qt 6.1.

### double qQNaN()

Returns the bit pattern of a quiet NaN as a double.

See also qIsNaN().

### `[constexpr]` qint64 qRound64(double d)

Rounds d to the nearest 64-bit integer.

Rounds half away from zero (e.g. 0.5 -> 1, -0.5 -> -1).

Note: This function does not guarantee correctness for high precisions.

Example:

     double valueA = 42949672960.3;
     double valueB = 42949672960.7;

     qint64 roundedValueA = qRound64(valueA);
     // roundedValueA = 42949672960
     qint64 roundedValueB = qRound64(valueB);
     // roundedValueB = 42949672961

Note: If the value d is outside the range of `qint64`, the behavior is undefined.

### `[constexpr]` qint64 qRound64(float d)

Rounds d to the nearest 64-bit integer.

Rounds half away from zero (e.g. 0.5f -> 1, -0.5f -> -1).

Note: This function does not guarantee correctness for high precisions.

Example:

     float valueA = 42949672960.3;
     float valueB = 42949672960.7;

     qint64 roundedValueA = qRound64(valueA);
     // roundedValueA = 42949672960
     qint64 roundedValueB = qRound64(valueB);
     // roundedValueB = 42949672961

Note: If the value d is outside the range of `qint64`, the behavior is undefined.

### `[constexpr]` int qRound(double d)

Rounds d to the nearest integer.

Rounds half away from zero (e.g. 0.5 -> 1, -0.5 -> -1).

Note: This function does not guarantee correctness for high precisions.

Example:

     double valueA = 2.3;
     double valueB = 2.7;

     int roundedValueA = qRound(valueA);
     // roundedValueA = 2
     int roundedValueB = qRound(valueB);
     // roundedValueB = 3

Note: If the value d is outside the range of `int`, the behavior is undefined.

### `[constexpr]` int qRound(float d)

Rounds d to the nearest integer.

Rounds half away from zero (e.g. 0.5f -> 1, -0.5f -> -1).

Note: This function does not guarantee correctness for high precisions.

Example:

     float valueA = 2.3;
     float valueB = 2.7;

     int roundedValueA = qRound(valueA);
     // roundedValueA = 2
     int roundedValueB = qRound(valueB);
     // roundedValueB = 3

Note: If the value d is outside the range of `int`, the behavior is undefined.

### double qSNaN()

Returns the bit pattern of a signalling NaN as a double.

### `[since 6.1]` template <typename T> typename std::enable_if_t<std::is_unsigned_v<T> || std::is_signed_v<T>, bool> qSubOverflow(T v1, T v2, T *result)

Subtracts v2 from v1 and records the resulting value in result. If the subtraction overflows the valid range for type `T`, returns `true`, otherwise returns `false`.

An implementation is guaranteed to be available for 8-, 16-, and 32-bit integer types, as well as integer types of the size of a pointer. Overflow math for other types, if available, is considered private API.

This function was introduced in Qt 6.1.