<QtNumeric> - Qt Numeric Functions

Function Documentation

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.

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

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

int qFpClassify(double val)

int qFpClassify(float val)

[constexpr] 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] 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] 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] 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).

Example:

 double valueA = 42949672960.3;
 double valueB = 42949672960.7;

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

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

Example:

 float valueA = 42949672960.3;
 float valueB = 42949672960.7;

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

[constexpr] int qRound(double d)

Rounds d to the nearest integer.

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

Example:

 double valueA = 2.3;
 double valueB = 2.7;

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

[constexpr] int qRound(float d)

Rounds d to the nearest integer.

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

Example:

 float valueA = 2.3;
 float valueB = 2.7;

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

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.