Revision control
Copy as Markdown
// Copyright (C) 2020 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\headerfile <QtMath>
\inmodule QtCore
\title Generic Math Functions
\ingroup funclists
\brief The <QtMath> header file provides various math functions.
These functions are partly convenience definitions for basic math operations
not available in the C or Standard Template Libraries.
The header also ensures some constants specified in POSIX, but not present
in C++ standards (so absent from <math.h> on some platforms), are defined:
\value M_E The base of the natural logarithms, e = exp(1)
\value M_LOG2E The base-two logarithm of e
\value M_LOG10E The base-ten logarithm of e
\value M_LN2 The natural logarithm of two
\value M_LN10 The natural logarithm of ten
\value M_PI The ratio of a circle's circumference to diameter, \unicode{0x3C0}
\value M_PI_2 Half M_PI, \unicode{0x3C0} / 2
\value M_PI_4 Quarter M_PI, \unicode{0x3C0} / 4
\value M_1_PI The inverse of M_PI, 1 / \unicode{0x3C0}
\value M_2_PI Twice the inverse of M_PI, 2 / \unicode{0x3C0}
\value M_2_SQRTPI Two divided by the square root of pi, 2 / \unicode{0x221A}\unicode{0x3C0}
\value M_SQRT2 The square root of two, \unicode{0x221A}2
\value M_SQRT1_2 The square roof of half, 1 / \unicode{0x221A}2
*/
/*!
\fn template <typename T> int qCeil(T v)
Returns the ceiling of the value \a v.
The ceiling is the smallest integer that is not less than \a v.
For example, if \a v is 41.2, then the ceiling is 42.
\relates <QtMath>
\sa qFloor()
*/
/*!
\fn template <typename T> int qFloor(T v)
Returns the floor of the value \a v.
The floor is the largest integer that is not greater than \a v.
For example, if \a v is 41.2, then the floor is 41.
\relates <QtMath>
\sa qCeil()
*/
/*!
\fn template <typename T> auto qFabs(T v)
Returns the absolute value of \a v.
\relates <QtMath>
*/
/*!
\fn template <typename T> auto qSin(T v)
Returns the sine of the angle \a v in radians.
\relates <QtMath>
\sa qCos(), qTan()
*/
/*!
\fn template <typename T> auto qCos(T v)
Returns the cosine of an angle \a v in radians.
\relates <QtMath>
\sa qSin(), qTan()
*/
/*!
\fn template <typename T> auto qTan(T v)
Returns the tangent of an angle \a v in radians.
\relates <QtMath>
\sa qSin(), qCos()
*/
/*!
\fn template <typename T> auto qAcos(T v)
Returns the arccosine of \a v as an angle in radians.
Arccosine is the inverse operation of cosine.
\relates <QtMath>
\sa qAtan(), qAsin(), qCos()
*/
/*!
\fn template <typename T> auto qAsin(T v)
Returns the arcsine of \a v as an angle in radians.
Arcsine is the inverse operation of sine.
\relates <QtMath>
\sa qSin(), qAtan(), qAcos()
*/
/*!
\fn template <typename T> auto qAtan(T v)
Returns the arctangent of \a v as an angle in radians.
Arctangent is the inverse operation of tangent.
\relates <QtMath>
\sa qTan(), qAcos(), qAsin()
*/
/*!
\fn template <typename T1, typename T2> auto qAtan2(T1 y, T2 x)
Returns the arctangent of a point specified by the coordinates \a y and \a x.
This function will return the angle (argument) of that point.
\relates <QtMath>
\sa qAtan(), qHypot()
*/
/*!
\fn template <typename T> auto qSqrt(T v)
Returns the square root of \a v.
This function returns a NaN if \a v is a negative number.
\relates <QtMath>
\sa qPow(), qHypot()
*/
/*!
\since 6.1
\overload
\fn template <typename Tx, typename Ty> auto qHypot(Tx x, Ty y)
Returns the distance of a point (\a x, \a y) from the origin (0, 0).
This is qSqrt(x * x + y * y), optimized.
In particular, underflow and overflow may be avoided.
Accepts any mix of numeric types, returning the same
floating-point type as std::hypot(). If either parameter is
infinite, so is the result; otherwise, if either is a NaN, so is
the result.
\relates <QtMath>
\sa qSqrt(), qAtan2()
*/
/*!
\since 6.1
\overload
\fn template <typename Tx, typename Ty, typename Tz> auto qHypot(Tx x, Ty y, Tz z)
Returns the distance of a point (x, y, z) from the origin (0, 0, 0).
This is qSqrt(x * x + y * y + z * z), optimized where supported.
In particular, underflow and overflow may be avoided.
Accepts any mix of numeric types, returning the same
floating-point type as std::hypot(). If any parameter is infinite,
so is the result; otherwise, if any is NaN, so is the result.
\relates <QtMath>
\sa qSqrt()
*/
/*!
\since 6.1
\fn template<typename F, typename ...Fs> auto qHypot(F first, Fs... rest)
Returns the distance from origin in arbitrarily many dimensions
This is as for the two-argument and three-argument forms, supported by
std::hypot(), but with as many numeric parameters as you care to pass to
it. Uses \a first and each of the \a rest as coordinates, performing a
calculation equivalent to squaring each, summing and returning the square
root, save that underflow and overflow are avoided as far as possible.
\relates <QtMath>
\sa qSqrt()
*/
/*!
\fn template <typename T> auto qLn(T v)
Returns the natural logarithm of \a v. Natural logarithm uses base e.
\relates <QtMath>
\sa qExp()
*/
/*!
\fn template <typename T> auto qExp(T v)
Returns the exponential function of \c e to the power of \a v.
\relates <QtMath>
\sa qLn()
*/
/*!
\fn template <typename T1, typename T2> auto qPow(T1 x, T2 y)
Returns the value of \a x raised to the power of \a y.
That is, \a x is the base and \a y is the exponent.
\relates <QtMath>
\sa qSqrt()
*/
/*!
\fn float qDegreesToRadians(float degrees)
\relates <QtMath>
\since 5.1
This function converts the \a degrees in float to radians.
Example:
\snippet code/src_corelib_kernel_qmath.cpp 0
\sa qRadiansToDegrees()
*/
/*!
\fn double qDegreesToRadians(double degrees)
\relates <QtMath>
\since 5.1
This function converts the \a degrees in double to radians.
Example:
\snippet code/src_corelib_kernel_qmath.cpp 1
\sa qRadiansToDegrees()
*/
/*!
\fn long double qDegreesToRadians(long double degrees)
\relates <QtMath>
\since 6.0
This function converts the \a degrees in double to radians.
\sa qRadiansToDegrees()
*/
/*!
\fn template <typename Integral> double qDegreesToRadians(Integral degrees)
\relates <QtMath>
\since 6.0
This function converts the \a degrees in double to radians;
the angle is casted to a double before the conversion.
\constraints \c Integral is an integral type.
\sa qRadiansToDegrees()
*/
/*!
\fn float qRadiansToDegrees(float radians)
\relates <QtMath>
\since 5.1
This function converts the \a radians in float to degrees.
Example:
\snippet code/src_corelib_kernel_qmath.cpp 2
\sa qDegreesToRadians()
*/
/*!
\fn double qRadiansToDegrees(double radians)
\relates <QtMath>
\since 5.1
This function converts the \a radians in double to degrees.
Example:
\snippet code/src_corelib_kernel_qmath.cpp 3
\sa qDegreesToRadians()
*/
/*!
\fn long double qRadiansToDegrees(long double radians)
\relates <QtMath>
\since 6.0
This function converts the \a radians in double to degrees.
\sa qDegreesToRadians()
*/
/*!
\fn quint32 qNextPowerOfTwo(quint32 value)
\relates <QtMath>
\since 5.4
This function returns the nearest power of two greater than \a value. For 0 it returns 1, and for values larger than or equal to 2^31 the result is undefined.
*/
/*!
\fn quint32 qNextPowerOfTwo(qint32 value)
\relates <QtMath>
\since 5.4
\overload
This function returns the nearest power of two greater than \a value. For negative values the result is undefined.
*/
/*!
\fn quint64 qNextPowerOfTwo(quint64 value)
\relates <QtMath>
\since 5.4
This function returns the nearest power of two greater than \a value. For 0 it returns 1, and for values larger than or equal to 2^63 the result is undefined.
*/
/*!
\fn quint64 qNextPowerOfTwo(qint64 value)
\relates <QtMath>
\since 5.4
\overload
This function returns the nearest power of two greater than \a value. For negative values the result is undefined.
*/