Round
Defined in header <cmath>
.
Description
Computes the nearest integer value to num
(in floating-point format), rounding halfway cases away from zero, regardless of the current rounding mode.
The library provides overloads of std::round
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 Computes the nearest integer value to num
(in integer format),
rounding halfway cases away from zero, regardless of the current rounding mode.
The library provides overloads of std::lround
and std::llround
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)
constexpr /* floating-point-type */
round ( /* floating-point-type */ num );
// 2)
constexpr float roundf( float num );
// 3)
constexpr long double roundl( long double num );
// 4)
constexpr long lround( /* floating-point-type */ num );
// 5)
constexpr long lroundf( float num );
// 6)
constexpr long lroundl( long double num );
// 7)
constexpr long long llround( /* floating-point-type */ num );
// 8)
constexpr long long llroundf( float num );
// 9)
constexpr long long llroundl( long double num );
// 10)
template< class Integer >
constexpr double round( Integer num );
// 11)
template< class Integer >
constexpr long lround( Integer num );
// 12)
template< class Integer >
constexpr long long llround( Integer num );
// 1)
float round ( float num );
// 2)
double round ( double num );
// 3)
long double round ( long double num );
// 4)
float roundf( float num );
// 5)
long double roundl( long double num );
// 6)
long lround ( float num );
// 7)
long lround ( double num );
// 8)
long lround ( long double num );
// 9)
long lroundf( float num );
// 10)
long lroundl( long double num );
// 11)
long long llround ( float num );
// 12)
long long llround ( double num );
// 13)
long long llround ( long double num );
// 14)
long long llroundf( float num );
// 15)
long long llroundl( long double num );
// 16)
template< class Integer >
double round( Integer num );
// 17)
template< class Integer >
long lround( Integer num );
// 18)
template< class Integer >
long long llround( Integer num );
Parameters
num
- floating-point or integer value
Return value
If no errors occur, the nearest integer value to num
, rounding halfway cases away from zero, is returned.
If a domain error occurs, an implementation-defined value is returned.
Error handling
Errors are reported as specified in math_errhandling.
If the result of std::lround
or std::llround
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::round
function:
The current rounding mode has no effect.
If num
is ±∞
, it is returned, unmodified
If num
is ±0
, it is returned, unmodified
If num
is NaN, NaN is returned
For std::lround
and std::llround
functions:
FE_INEXACT is never raised
The current rounding mode has no effect.
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
FE_INEXACT may be (but is not required to be) raised by std::round
when rounding a non-integer finite value.
The largest representable floating-point values are exact integers in all standard floating-point formats, so std::round
never overflows on its own;
however the result may overflow any integer type (including std::intmax_t
), when stored in an integer variable.
POSIX
specifies that all cases where std::lround
or std::llround
raise FE_INEXACT are domain errors.
The double version of std::round
behaves as if implemented as follows:
#include <cfenv>
#include <cmath>
#pragma STDC FENV_ACCESS ON
double round(double x)
{
std::fenv_t save_env;
std::feholdexcept(&save_env);
double result = std::rint(x);
if (std::fetestexcept(FE_INEXACT))
{
auto const save_round = std::fegetround();
std::fesetround(FE_TOWARDZERO);
result = std::rint(std::copysign(0.5 + std::fabs(x), x));
std::fesetround(save_round);
}
std::feupdateenv(&save_env);
return result;
}
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::round(num)
has the same effect as std::round(static_cast<double>(num))
std::lround(num)
has the same effect as std::lround(static_cast<double>(num))
std::llround(num)
has the same effect as std::llround(static_cast<double>(num))
Examples
#include <cfenv>
#include <climits>
#include <cmath>
#include <iostream>
// #pragma STDC FENV_ACCESS ON
int main()
{
// round
std::cout
<< "round(+2.3) = "<< std::round(2.3) <<'\n'
<< "round(+2.5) = " << std::round(2.5) <<'\n'
<< "round(+2.7) = "<< std::round(2.7) <<'\n'
<< "round(-2.3) = "<< std::round(-2.3) <<'\n'
<< "round(-2.5) = " << std::round(-2.5) <<'\n'
<< "round(-2.7) = "<< std::round(-2.7) <<'\n';
std::cout
<< "round(-0.0) = "
<< std::round(-0.0) << '\n'
<< "round(-Inf) = "
<< std::round(-INFINITY) << '\n';
// lround
std::cout
<< "lround(+2.3) = "<< std::lround(2.3) <<'\n'
<< "lround(+2.5) = "<< std::lround(2.5) <<'\n'
<< "lround(+2.7) = "<< std::lround(2.7) <<'\n'
<< "lround(-2.3) = "<< std::lround(-2.3) <<'\n'
<< "lround(-2.5) = "<< std::lround(-2.5) <<'\n'
<< "lround(-2.7) = "<< std::lround(-2.7) <<'\n';
std::cout
<< "lround(-0.0) = "
<< std::lround(-0.0) << '\n'
<< "lround(-Inf) = "
<< std::lround(-INFINITY) << '\n';
// error handling
std::feclearexcept(FE_ALL_EXCEPT);
std::cout
<< "std::lround(LONG_MAX+1.5) = "
<< std::lround(LONG_MAX + 1.5) << '\n';
if (std::fetestexcept(FE_INVALID))
std::cout
<< "FE_INVALID was raised\n";
}
round(+2.3) = 2
round(+2.5) = 3
round(+2.7) = 3
round(-2.3) = -2
round(-2.5) = -3
round(-2.7) = -3
round(-0.0) = -0
round(-Inf) = -inf
lround(+2.3) = 2
lround(+2.5) = 3
lround(+2.7) = 3
lround(-2.3) = -2
lround(-2.5) = -3
lround(-2.7) = -3
lround(-0.0) = 0
lround(-Inf) = -9223372036854775808
std::lround(LONG_MAX+1.5) = -9223372036854775808
FE_INVALID was raised