std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint,std::llrintf (3) - Linux Manuals

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

NAME

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

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
           (function)
(C++11)
(C++11)
(C++11)


nearbyint
nearbyintf
nearbyintl nearest integer using current rounding mode
           (function)
(C++11)
(C++11)
(C++11)


fegetround
fesetround gets or sets rounding direction
           (function)
(C++11)
(C++11)