diff options
Diffstat (limited to 'src/corelib/kernel/qmath.qdoc')
| -rw-r--r-- | src/corelib/kernel/qmath.qdoc | 133 |
1 files changed, 97 insertions, 36 deletions
diff --git a/src/corelib/kernel/qmath.qdoc b/src/corelib/kernel/qmath.qdoc index 82a4ae85a5..bc365f26fa 100644 --- a/src/corelib/kernel/qmath.qdoc +++ b/src/corelib/kernel/qmath.qdoc @@ -1,32 +1,9 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// 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 @@ -54,8 +31,8 @@ */ /*! - \fn int qCeil(qreal v) - Return the ceiling of the value \a v. + \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. @@ -65,8 +42,8 @@ */ /*! - \fn int qFloor(qreal v) - Return the floor of the value \a v. + \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. @@ -139,7 +116,7 @@ This function will return the angle (argument) of that point. \relates <QtMath> - \sa qAtan() + \sa qAtan(), qHypot() */ /*! @@ -148,7 +125,57 @@ This function returns a NaN if \a v is a negative number. \relates <QtMath> - \sa qPow() + \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() */ /*! @@ -205,6 +232,30 @@ */ /*! + \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 @@ -233,11 +284,21 @@ */ /*! + \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 it returns 0. + 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. */ /*! @@ -246,7 +307,7 @@ \since 5.4 \overload - This function returns the nearest power of two greater than \a value. For negative values it returns 0. + This function returns the nearest power of two greater than \a value. For negative values the result is undefined. */ /*! @@ -254,7 +315,7 @@ \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 it returns 0. + 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. */ /*! @@ -263,5 +324,5 @@ \since 5.4 \overload - This function returns the nearest power of two greater than \a value. For negative values it returns 0. + This function returns the nearest power of two greater than \a value. For negative values the result is undefined. */ |