qmath.qdoc

Go to the documentation of this file.

// 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 (x, 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.
 
    This function participates in overload resolution if and only if
    \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.
*/