NAME

std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint, - std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint,

Synopsis

Defined in header <cmath>
float rint ( float arg ); (1) (since C++11)
float rintf( float arg );
double rint ( double arg ); (2) (since C++11)
long double rint ( long double arg ); (3) (since C++11)
long double rintl( long double arg );
double rint ( IntegralType arg ); (4) (since C++11)
long lrint ( float arg ); (5) (since C++11)
long lrintf( float arg );
long lrint ( double arg ); (6) (since C++11)
long lrint ( long double arg ); (7) (since C++11)
long lrintl( long double arg );
long lrint ( IntegralType arg ); (8) (since C++11)
long long llrint ( float arg ); (9) (since C++11)
long long llrintf( float arg );
long long llrint ( double arg ); (10) (since C++11)
long long llrint ( long double arg ); (11) (since C++11)
long long llrintl( long double arg );
long long llrint ( IntegralType arg ); (12) (since C++11)

1-3) Rounds the floating-point argument arg to an integer value (in floating-point
format), using the current rounding mode.
5-7, 9-11) Rounds the floating-point argument arg to an integer value, using the
current rounding mode.
4,8,12) A set of overloads or a function template accepting an argument of any
integral type. Equivalent to (2,6,10), respectively (the argument is cast to
double).

Parameters

arg - floating point value

Return value

If no errors occur, the nearest integer value to arg, 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 arg is ±∞, it is returned, unmodified
* If arg is ±0, it is returned, unmodified
* If arg is NaN, NaN is returned

For std::lrint and std::llrint functions:

* If arg 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 arg 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.

Example

// Run this code

#include <iostream>
#include <cmath>
#include <cfenv>
#include <climits>

int main()
{
#pragma STDC FENV_ACCESS ON
std::fesetround(FE_TONEAREST);
std::cout << "rounding to nearest (halfway cases to even):\n"
<< "rint(+2.3) = " << std::rint(2.3)
<< " rint(+2.5) = " << std::rint(2.5)
<< " rint(+3.5) = " << std::rint(3.5) << '\n'
<< "rint(-2.3) = " << std::rint(-2.3)
<< " rint(-2.5) = " << std::rint(-2.5)
<< " rint(-3.5) = " << std::rint(-3.5) << '\n';

std::fesetround(FE_DOWNWARD);
std::cout << "rounding down:\n"
<< "rint(+2.3) = " << std::rint(2.3)
<< " rint(+2.5) = " << std::rint(2.5)
<< " rint(+3.5) = " << std::rint(3.5) << '\n'
<< "rint(-2.3) = " << std::rint(-2.3)
<< " rint(-2.5) = " << std::rint(-2.5)
<< " rint(-3.5) = " << std::rint(-3.5) << '\n'
<< "rounding down with lrint\n"
<< "lrint(+2.3) = " << std::lrint(2.3)
<< " lrint(+2.5) = " << std::lrint(2.5)
<< " lrint(+3.5) = " << std::lrint(3.5) << '\n'
<< "lrint(-2.3) = " << std::lrint(-2.3)
<< " lrint(-2.5) = " << std::lrint(-2.5)
<< " 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";
}

Possible output:

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