std::rint,std::rintf,std::rintl,std::lrint,std::lrintf,std::lrintl,std::llrint, (3) - Linux Man Pages

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,

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)  rint(+2.5)  rint(+3.5) 4
 rint(-2.3) -2  rint(-2.5) -2  rint(-3.5) -4
 rounding down:
 rint(+2.3)  rint(+2.5)  rint(+3.5) 3
 rint(-2.3) -3  rint(-2.5) -3  rint(-3.5) -4
 rounding down with lrint
 lrint(+2.3)  lrint(+2.5)  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)