diff options
author | Sona Kurazyan <sona.kurazyan@qt.io> | 2022-09-16 16:35:54 +0200 |
---|---|---|
committer | Sona Kurazyan <sona.kurazyan@qt.io> | 2022-09-21 14:00:44 +0200 |
commit | 8b9c7fa53a5c35dfc42f9aa2de9311ac40268dd2 (patch) | |
tree | c54adec0ff9f39496be37b7c09db4a155302c3cf | |
parent | bee606b0916e58de4a6783d2c96a0ed70fe914ed (diff) |
Improve docs for QtNumeric header
- Move the docs for functions from qnumeric.h from qglobal.cpp to
qnumeric.cpp.
- Update the '\relates' commands to refer to QtNumeric
instead of QtGlobal.
- Add overview page.
Task-number: QTBUG-106154
Change-Id: Id39f2508415995a4c7a9dcc0a323447dbe348978
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
-rw-r--r-- | src/corelib/global/qglobal.cpp | 119 | ||||
-rw-r--r-- | src/corelib/global/qnumeric.cpp | 160 |
2 files changed, 145 insertions, 134 deletions
diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index 1661702f16..ca01ea0659 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -229,74 +229,6 @@ using namespace Qt::StringLiterals; \sa quint64, Q_INT64_C() */ -/*! \fn template <typename T> T qAbs(const T &t) - \relates <QtNumeric> - - Compares \a t to the 0 of type T and returns the absolute - value. Thus if T is \e {double}, then \a t is compared to - \e{(double) 0}. - - Example: - - \snippet code/src_corelib_global_qglobal.cpp 10 -*/ - -/*! \fn int qRound(double d) - \relates <QtNumeric> - - Rounds \a 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: - - \snippet code/src_corelib_global_qglobal.cpp 11A -*/ - -/*! \fn int qRound(float d) - \relates <QtNumeric> - - Rounds \a 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: - - \snippet code/src_corelib_global_qglobal.cpp 11B -*/ - -/*! \fn qint64 qRound64(double d) - \relates <QtNumeric> - - Rounds \a 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: - - \snippet code/src_corelib_global_qglobal.cpp 12A -*/ - -/*! \fn qint64 qRound64(float d) - \relates <QtNumeric> - - Rounds \a 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: - - \snippet code/src_corelib_global_qglobal.cpp 12B -*/ - /*! \macro QT_VERSION_STR \relates <QtGlobal> @@ -2650,57 +2582,6 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) */ /*! - \fn bool qFuzzyCompare(double p1, double p2) - \relates <QtNumeric> - \since 4.4 - \threadsafe - - Compares the floating point value \a p1 and \a p2 and - returns \c true if they are considered equal, otherwise \c false. - - Note that comparing values where either \a p1 or \a 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. - - \snippet code/src_corelib_global_qglobal.cpp 46 - - The two numbers are compared in a relative way, where the - exactness is stronger the smaller the numbers are. -*/ - -/*! - \fn bool qFuzzyCompare(float p1, float p2) - \relates <QtNumeric> - \since 4.4 - \threadsafe - - Compares the floating point value \a p1 and \a p2 and - returns \c true if they are considered equal, otherwise \c false. - - The two numbers are compared in a relative way, where the - exactness is stronger the smaller the numbers are. -*/ - -/*! - \fn bool qFuzzyIsNull(double d) - \relates <QtNumeric> - \since 4.4 - \threadsafe - - Returns true if the absolute value of \a d is within 0.000000000001 of 0.0. -*/ - -/*! - \fn bool qFuzzyIsNull(float f) - \relates <QtNumeric> - \since 4.4 - \threadsafe - - Returns true if the absolute value of \a f is within 0.00001f of 0.0. -*/ - -/*! \macro QT_REQUIRE_VERSION(int argc, char **argv, const char *version) \relates <QtGlobal> diff --git a/src/corelib/global/qnumeric.cpp b/src/corelib/global/qnumeric.cpp index 544d3e17b8..b846325964 100644 --- a/src/corelib/global/qnumeric.cpp +++ b/src/corelib/global/qnumeric.cpp @@ -8,61 +8,72 @@ QT_BEGIN_NAMESPACE /*! + \headerfile <QtNumeric> + \inmodule QtCore + \title Qt Numeric Functions + + \brief The <QtNumeric> header file provides common numeric functions. + + The <QtNumeric> header file contains various numeric functions + for comparing and adjusting a numeric value. +*/ + +/*! Returns \c true if the double \a {d} is equivalent to infinity. - \relates <QtGlobal> + \relates <QtNumeric> \sa qInf() */ Q_CORE_EXPORT bool qIsInf(double d) { return qt_is_inf(d); } /*! Returns \c true if the double \a {d} is not a number (NaN). - \relates <QtGlobal> + \relates <QtNumeric> */ Q_CORE_EXPORT bool qIsNaN(double d) { return qt_is_nan(d); } /*! Returns \c true if the double \a {d} is a finite number. - \relates <QtGlobal> + \relates <QtNumeric> */ Q_CORE_EXPORT bool qIsFinite(double d) { return qt_is_finite(d); } /*! Returns \c true if the float \a {f} is equivalent to infinity. - \relates <QtGlobal> + \relates <QtNumeric> \sa qInf() */ Q_CORE_EXPORT bool qIsInf(float f) { return qt_is_inf(f); } /*! Returns \c true if the float \a {f} is not a number (NaN). - \relates <QtGlobal> + \relates <QtNumeric> */ Q_CORE_EXPORT bool qIsNaN(float f) { return qt_is_nan(f); } /*! Returns \c true if the float \a {f} is a finite number. - \relates <QtGlobal> + \relates <QtNumeric> */ Q_CORE_EXPORT bool qIsFinite(float f) { return qt_is_finite(f); } #if QT_CONFIG(signaling_nan) /*! Returns the bit pattern of a signalling NaN as a double. - \relates <QtGlobal> + \relates <QtNumeric> */ Q_CORE_EXPORT double qSNaN() { return qt_snan(); } #endif /*! Returns the bit pattern of a quiet NaN as a double. - \relates <QtGlobal> + \relates <QtNumeric> \sa qIsNaN() */ Q_CORE_EXPORT double qQNaN() { return qt_qnan(); } /*! Returns the bit pattern for an infinite number as a double. - \relates <QtGlobal> + \relates <QtNumeric> \sa qIsInf() */ Q_CORE_EXPORT double qInf() { return qt_inf(); } @@ -71,7 +82,7 @@ Q_CORE_EXPORT double qInf() { return qt_inf(); } \fn int qFpClassify(double val) \fn int qFpClassify(float val) - \relates <QtGlobal> + \relates <QtNumeric> Classifies a floating-point value. The return values are defined in \c{<cmath>}: returns one of the following, @@ -123,7 +134,7 @@ static inline quint32 f2i(float f) \sa qFuzzyCompare() \since 5.2 - \relates <QtGlobal> + \relates <QtNumeric> */ Q_CORE_EXPORT quint32 qFloatDistance(float a, float b) { @@ -181,7 +192,7 @@ static inline quint64 d2i(double d) \sa qFuzzyCompare() \since 5.2 - \relates <QtGlobal> + \relates <QtNumeric> */ Q_CORE_EXPORT quint64 qFloatDistance(double a, double b) { @@ -220,7 +231,7 @@ Q_CORE_EXPORT quint64 qFloatDistance(double a, double b) /*! \fn template<typename T> bool qAddOverflow(T v1, T v2, T *result) - \relates <QtGlobal> + \relates <QtNumeric> \since 6.1 Adds two values \a v1 and \a v2, of a numeric type \c T and records the @@ -252,7 +263,7 @@ Q_CORE_EXPORT quint64 qFloatDistance(double a, double b) /*! \fn template<typename T> bool qSubOverflow(T v1, T v2, T *result) - \relates <QtGlobal> + \relates <QtNumeric> \since 6.1 Subtracts \a v2 from \a v1 and records the resulting value in \a result. If @@ -284,7 +295,7 @@ Q_CORE_EXPORT quint64 qFloatDistance(double a, double b) /*! \fn template<typename T> bool qMulOverflow(T v1, T v2, T *result) - \relates <QtGlobal> + \relates <QtNumeric> \since 6.1 Multiplies \a v1 and \a v2, and records the resulting value in \a result. If @@ -316,4 +327,123 @@ Q_CORE_EXPORT quint64 qFloatDistance(double a, double b) This can be faster than calling the version with only variable arguments. */ +/*! \fn template <typename T> T qAbs(const T &t) + \relates <QtNumeric> + + Compares \a t to the 0 of type T and returns the absolute + value. Thus if T is \e {double}, then \a t is compared to + \e{(double) 0}. + + Example: + + \snippet code/src_corelib_global_qglobal.cpp 10 +*/ + +/*! \fn int qRound(double d) + \relates <QtNumeric> + + Rounds \a 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: + + \snippet code/src_corelib_global_qglobal.cpp 11A +*/ + +/*! \fn int qRound(float d) + \relates <QtNumeric> + + Rounds \a 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: + + \snippet code/src_corelib_global_qglobal.cpp 11B +*/ + +/*! \fn qint64 qRound64(double d) + \relates <QtNumeric> + + Rounds \a 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: + + \snippet code/src_corelib_global_qglobal.cpp 12A +*/ + +/*! \fn qint64 qRound64(float d) + \relates <QtNumeric> + + Rounds \a 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: + + \snippet code/src_corelib_global_qglobal.cpp 12B +*/ + +/*! + \fn bool qFuzzyCompare(double p1, double p2) + \relates <QtNumeric> + \since 4.4 + \threadsafe + + Compares the floating point value \a p1 and \a p2 and + returns \c true if they are considered equal, otherwise \c false. + + Note that comparing values where either \a p1 or \a 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. + + \snippet code/src_corelib_global_qglobal.cpp 46 + + The two numbers are compared in a relative way, where the + exactness is stronger the smaller the numbers are. +*/ + +/*! + \fn bool qFuzzyCompare(float p1, float p2) + \relates <QtNumeric> + \since 4.4 + \threadsafe + + Compares the floating point value \a p1 and \a p2 and + returns \c true if they are considered equal, otherwise \c false. + + The two numbers are compared in a relative way, where the + exactness is stronger the smaller the numbers are. +*/ + +/*! + \fn bool qFuzzyIsNull(double d) + \relates <QtNumeric> + \since 4.4 + \threadsafe + + Returns true if the absolute value of \a d is within 0.000000000001 of 0.0. +*/ + +/*! + \fn bool qFuzzyIsNull(float f) + \relates <QtNumeric> + \since 4.4 + \threadsafe + + Returns true if the absolute value of \a f is within 0.00001f of 0.0. +*/ + QT_END_NAMESPACE |