1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \headerfile <QtMath>
30    \title Generic Math Functions
31    \ingroup funclists
32
33    \brief The <QtMath> header file provides various math functions.
34
35    These functions are partly convenience definitions for basic math operations
36    not available in the C or Standard Template Libraries.
37
38    The header also ensures some constants specified in POSIX, but not present
39    in C++ standards (so absent from <math.h> on some platforms), are defined:
40
41    \value M_E The base of the natural logarithms, e = exp(1)
42    \value M_LOG2E The base-two logarithm of e
43    \value M_LOG10E The base-ten logarithm of e
44    \value M_LN2 The natural logarithm of two
45    \value M_LN10 The natural logarithm of ten
46    \value M_PI The ratio of a circle's circumference to diameter, \unicode{0x3C0}
47    \value M_PI_2 Half M_PI, \unicode{0x3C0} / 2
48    \value M_PI_4 Quarter M_PI, \unicode{0x3C0} / 4
49    \value M_1_PI The inverse of M_PI, 1 / \unicode{0x3C0}
50    \value M_2_PI Twice the inverse of M_PI, 2 / \unicode{0x3C0}
51    \value M_2_SQRTPI Two divided by the square root of pi, 2 / \unicode{0x221A}\unicode{0x3C0}
52    \value M_SQRT2 The square root of two, \unicode{0x221A}2
53    \value M_SQRT1_2 The square roof of half, 1 / \unicode{0x221A}2
54*/
55
56/*!
57    \fn int qCeil(qreal v)
58    Return the ceiling of the value \a v.
59
60    The ceiling is the smallest integer that is not less than \a v.
61    For example, if \a v is 41.2, then the ceiling is 42.
62
63    \relates <QtMath>
64    \sa qFloor()
65*/
66
67/*!
68    \fn int qFloor(qreal v)
69    Return the floor of the value \a v.
70
71    The floor is the largest integer that is not greater than \a v.
72    For example, if \a v is 41.2, then the floor is 41.
73
74    \relates <QtMath>
75    \sa qCeil()
76*/
77
78/*!
79    \fn qreal qFabs(qreal v)
80    Returns the absolute value of \a v as a qreal.
81
82    \relates <QtMath>
83*/
84
85/*!
86    \fn qreal qSin(qreal v)
87    Returns the sine of the angle \a v in radians.
88
89    \relates <QtMath>
90    \sa qCos(), qTan()
91*/
92
93/*!
94    \fn  qreal qCos(qreal v)
95    Returns the cosine of an angle \a v in radians.
96
97    \relates <QtMath>
98    \sa qSin(), qTan()
99*/
100
101/*!
102    \fn qreal qTan(qreal v)
103    Returns the tangent of an angle \a v in radians.
104
105    \relates <QtMath>
106    \sa qSin(), qCos()
107*/
108
109/*!
110    \fn qreal qAcos(qreal v)
111    Returns the arccosine of \a v as an angle in radians.
112    Arccosine is the inverse operation of cosine.
113
114    \relates <QtMath>
115    \sa qAtan(), qAsin(), qCos()
116*/
117
118/*!
119    \fn qreal qAsin(qreal v)
120    Returns the arcsine of \a v as an angle in radians.
121    Arcsine is the inverse operation of sine.
122
123    \relates <QtMath>
124    \sa qSin(), qAtan(), qAcos()
125*/
126
127/*!
128    \fn qreal qAtan(qreal v)
129    Returns the arctangent of \a v as an angle in radians.
130    Arctangent is the inverse operation of tangent.
131
132    \relates <QtMath>
133    \sa qTan(), qAcos(), qAsin()
134*/
135
136/*!
137    \fn qreal qAtan2(qreal y, qreal x)
138    Returns the arctangent of a point specified by the coordinates \a y and \a x.
139    This function will return the angle (argument) of that point.
140
141    \relates <QtMath>
142    \sa qAtan()
143*/
144
145/*!
146    \fn qreal qSqrt(qreal v)
147    Returns the square root of \a v.
148    This function returns a NaN if \a v is a negative number.
149
150    \relates <QtMath>
151    \sa qPow()
152*/
153
154/*!
155    \fn qreal qLn(qreal v)
156    Returns the natural logarithm of \a v. Natural logarithm uses base e.
157
158    \relates <QtMath>
159    \sa qExp()
160*/
161
162/*!
163    \fn qreal qExp(qreal v)
164    Returns the exponential function of \c e to the power of \a v.
165
166    \relates <QtMath>
167    \sa qLn()
168*/
169
170/*!
171    \fn qreal qPow(qreal x, qreal y)
172    Returns the value of \a x raised to the power of \a y.
173    That is, \a x is the base and \a y is the exponent.
174
175    \relates <QtMath>
176    \sa qSqrt()
177*/
178
179/*!
180    \fn float qDegreesToRadians(float degrees)
181    \relates <QtMath>
182    \since 5.1
183
184    This function converts the \a degrees in float to radians.
185
186    Example:
187
188    \snippet code/src_corelib_kernel_qmath.cpp 0
189
190    \sa qRadiansToDegrees()
191*/
192
193/*!
194    \fn double qDegreesToRadians(double degrees)
195    \relates <QtMath>
196    \since 5.1
197
198    This function converts the \a degrees in double to radians.
199
200    Example:
201
202    \snippet code/src_corelib_kernel_qmath.cpp 1
203
204    \sa qRadiansToDegrees()
205*/
206
207/*!
208    \fn float qRadiansToDegrees(float radians)
209    \relates <QtMath>
210    \since 5.1
211
212    This function converts the \a radians in float to degrees.
213
214    Example:
215
216    \snippet code/src_corelib_kernel_qmath.cpp 2
217
218    \sa qDegreesToRadians()
219*/
220
221/*!
222    \fn double qRadiansToDegrees(double radians)
223    \relates <QtMath>
224    \since 5.1
225
226    This function converts the \a radians in double to degrees.
227
228    Example:
229
230    \snippet code/src_corelib_kernel_qmath.cpp 3
231
232    \sa qDegreesToRadians()
233*/
234
235/*!
236    \fn quint32 qNextPowerOfTwo(quint32 value)
237    \relates <QtMath>
238    \since 5.4
239
240    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.
241*/
242
243/*!
244    \fn quint32 qNextPowerOfTwo(qint32 value)
245    \relates <QtMath>
246    \since 5.4
247    \overload
248
249    This function returns the nearest power of two greater than \a value. For negative values it returns 0.
250*/
251
252/*!
253    \fn quint64 qNextPowerOfTwo(quint64 value)
254    \relates <QtMath>
255    \since 5.4
256
257    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.
258*/
259
260/*!
261    \fn quint64 qNextPowerOfTwo(qint64 value)
262    \relates <QtMath>
263    \since 5.4
264    \overload
265
266    This function returns the nearest power of two greater than \a value. For negative values it returns 0.
267*/
268