table of contents
std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint,(3) | C++ Standard Libary | std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint,(3) |
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
See also¶
trunc
truncf
truncl nearest integer not greater in magnitude than the given value
(C++11) (function)
(C++11)
(C++11)
nearbyint
nearbyintf
nearbyintl nearest integer using current rounding mode
(C++11) (function)
(C++11)
(C++11)
fegetround
fesetround gets or sets rounding direction
(C++11) (function)
(C++11)
2022.07.31 | http://cppreference.com |