Rint
Defined in header <cmath>
.
Description
Rounds the floating-point argument num
to an integer value (in floating-point format), using the current rounding mode.
The library provides overloads of std::rint
for all cv-unqualified floating-point types as the type of the parameter num
(od C++23).
Rounding to long and Rounding to long long Rounds the floating-point argument num to an integer value, using the current rounding mode.
The library provides overloads of std::lrint
and std::llrint
for all cv-unqualified floating-point types as the type of the parameter num
(od C++23)
Additional Overloads are provided for all integer types, which are treated as double.
Declarations
- C++23
- C++11
// 1)
/* floating-point-type */
rint ( /* floating-point-type */ num );
// 2)
float rintf( float num );
// 3)
long double rintl( long double num );
// 4)
long lrint( /* floating-point-type */ num );
// 5)
long lrintf( float num );
// 6)
long lrintl( long double num );
// 7)
long long llrint( /* floating-point-type */ num );
// 8)
long long llrintf( float num );
// 9)
long long llrintl( long double num );
// 10)
template< class Integer >
double rint( Integer num );
// 11)
template< class Integer >
long lrint( Integer num );
// 12)
template< class Integer >
long long llrint( Integer num );
// 1)
float rint ( float num );
// 2)
double rint ( double num );
// 3)
long double rint ( long double num );
// 4)
float rintf( float num );
// 5)
long double rintl( long double num );
// 6)
long lrint ( float num );
// 7)
long lrint ( double num );
// 8)
long lrint ( long double num );
// 9)
long lrintf( float num );
// 10)
long lrintl( long double num );
// 11)
long long llrint ( float num );
// 12)
long long llrint ( double num );
// 13)
long long llrint ( long double num );
// 14)
long long llrintf( float num );
// 15)
long long llrintl( long double num );
// 16)
template< class Integer >
double rint( Integer num );
// 17)
template< class Integer >
long lrint( Integer num );
// 18)
template< class Integer >
long long llrint( Integer num );
Parameters
num
- floating-point or integer value
Return value
If no errors occur, the nearest integer value to num
, according to the current rounding mode, is returned
Error handling
Errors are reported as specified in math_errhandling.
If the result of std::lrint
or std::llrint
is outside the range representable by the return type, a domain error or a range error may occur.
If the implementation supports IEEE floating-point arithmetic (IEC 60559):
For the std::rint
function:
If num
is ±∞
, it is returned, unmodified
If num
is ±0
, it is returned, unmodified
If num
is NaN, NaN is returned
For std::lrint
and std::llrint
functions:
If num
is ±∞
, FE_INVALID is raised and an implementation-defined value is returned
If the result of the rounding is outside the range of the return type, FE_INVALID is raised and an implementation-defined value is returned
If num
is NaN, FE_INVALID is raised and an implementation-defined value is returned
Notes
POSIX
specifies that all cases where std::lrint
or std::llrint
raise FE_INEXACT are domain errors.
as specified in math_errhandling, FE_INEXACT may be (but isn't required to be on non-IEEE floating-point platforms) raised by std::rint
when rounding a non-integer finite value.
The only difference between std::rint
and std::nearbyint
is that std::nearbyint
never raises FE_INEXACT.
The largest representable floating-point values are exact integers in all standard floating-point formats, so std::rint never overflows on its own; however the result may overflow any integer type (including std::intmax_t), when stored in an integer variable.
If the current rounding mode is:
FE_DOWNWARD, then std::rint
is equivalent to std::floor
.
FE_UPWARD, then std::rint
is equivalent to std::ceil
.
FE_TOWARDZERO, then std::rint
is equivalent to std::trunc
FE_TONEAREST, then std::rint
differs from std::round
in that halfway cases are rounded to even rather than away from zero.
The additional overloads are not required to be provided exactly as Additional Overloads. They only need to be sufficient to ensure that for their argument num
of integer type:
std::rint(num)
has the same effect as std::rint(static_cast<double>(num))
.
std::lrint(num)
has the same effect as std::lrint(static_cast<double>(num))
.
std::llrint(num)
has the same effect as std::llrint(static_cast<double>(num))
.
Examples
#include <cfenv>
#include <climits>
#include <cmath>
#include <iostream>
#pragma STDC FENV_ACCESS ON
int main()
{
std::fesetround(FE_TONEAREST);
std::cout
<< "rounding to nearest (halfway cases to even):\n\n"
<< "rint(+2.3) = "
<< std::rint(2.3) << '\n'
<< " rint(+2.5) = "
<< std::rint(2.5) << '\n'
<< " rint(+3.5) = "
<< std::rint(3.5) << '\n'
<< "rint(-2.3) = "
<< std::rint(-2.3) << '\n'
<< " rint(-2.5) = "
<< std::rint(-2.5) << '\n'
<< " rint(-3.5) = "
<< std::rint(-3.5) << '\n\n';
std::fesetround(FE_DOWNWARD);
std::cout
<< "rounding down:\n\n"
<< "rint(+2.3) = "
<< std::rint(2.3) << '\n'
<< " rint(+2.5) = "
<< std::rint(2.5) << '\n'
<< " rint(+3.5) = "
<< std::rint(3.5) << '\n'
<< "rint(-2.3) = "
<< std::rint(-2.3) << '\n'
<< " rint(-2.5) = "
<< std::rint(-2.5) << '\n'
<< " rint(-3.5) = "
<< std::rint(-3.5) << '\n\n'
<< "rounding down with lrint:\n\n"
<< "lrint(+2.3) = "
<< std::lrint(2.3) << '\n'
<< " lrint(+2.5) = "
<< std::lrint(2.5) << '\n'
<< " lrint(+3.5) = "
<< std::lrint(3.5) << '\n'
<< "lrint(-2.3) = "
<< std::lrint(-2.3) << '\n'
<< " lrint(-2.5) = "
<< std::lrint(-2.5) << '\n'
<< " lrint(-3.5) = "
<< std::lrint(-3.5) << '\n';
std::cout
<< "lrint(-0.0) = "
<< std::lrint(-0.0) << '\n'
<< "lrint(-Inf) = "
<< std::lrint(-INFINITY) << '\n';
// error handling
std::feclearexcept(FE_ALL_EXCEPT);
std::cout
<< "std::rint(0.1) = "
<< std::rint(.1) << '\n';
if (std::fetestexcept(FE_INEXACT))
std::cout
<< "FE_INEXACT was raised\n";
std::feclearexcept(FE_ALL_EXCEPT);
std::cout
<< "std::lrint(LONG_MIN-2048.0) = "
<< std::lrint(LONG_MIN - 2048.0) << '\n';
if (std::fetestexcept(FE_INVALID))
std::cout
<< "FE_INVALID was raised\n";
}
rounding to nearest (halfway cases to even):
rint(+2.3) = 2
rint(+2.5) = 2
rint(+3.5) = 4
rint(-2.3) = -2
rint(-2.5) = -2
rint(-3.5) = -4
rounding down:
rint(+2.3) = 2
rint(+2.5) = 2
rint(+3.5) = 3
rint(-2.3) = -3
rint(-2.5) = -3
rint(-3.5) = -4
rounding down with lrint:
lrint(+2.3) = 2
lrint(+2.5) = 2
lrint(+3.5) = 3
lrint(-2.3) = -3
lrint(-2.5) = -3
lrint(-3.5) = -4
lrint(-0.0) = 0
lrint(-Inf) = -9223372036854775808
std::rint(0.1) = 0
FE_INEXACT was raised
std::lrint(LONG_MIN-2048.0) = -9223372036854775808
FE_INVALID was raised