Namespaces
Variants
Views
Actions

std::rint, std::lrint, std::llrint

From cppreference.com
< cpp‎ | numeric‎ | math
 
 
 
Common mathematical functions
Functions
Basic operations
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)
Exponential functions
(C++11)
(C++11)
(C++11)
(C++11)
Power functions
(C++11)
(C++11)
Trigonometric and hyperbolic functions
(C++11)
(C++11)
(C++11)
Error and gamma functions
(C++11)
(C++11)
(C++11)
(C++11)
Nearest integer floating point operations
(C++11)(C++11)(C++11)
(C++11)
(C++11)
rintlrintllrint
(C++11)(C++11)(C++11)
Floating point manipulation functions
(C++11)(C++11)
(C++11)
(C++11)
(C++11)(C++11)
(C++11)
Classification/Comparison
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Macro constants
(C++11)(C++11)(C++11)(C++11)(C++11)
 
Defined in header <cmath>
float rint( float arg );
(1) (since C++11)
double rint( double arg );
(2) (since C++11)
long double rint( long double arg );
(3) (since C++11)
double rint( Integral arg );
(4) (since C++11)
long lrint( float arg );
(5) (since C++11)
long lrint( double arg );
(6) (since C++11)
long lrint( long double arg );
(7) (since C++11)
long lrint( Integral arg );
(8) (since C++11)
long long llrint( float arg );
(9) (since C++11)
long long llrint( double arg );
(10) (since C++11)
long long llrint( long double arg );
(11) (since C++11)
long long llrint( Integral 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).

Contents

[edit] Parameters

arg - floating point value

[edit] Return value

If no errors occur, the nearest integer value to arg, according to the current rounding mode, is returned.

[edit] 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

[edit] 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.

[edit] Example

#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

[edit] See also

(C++11)
nearest integer not greater in magnitude than the given value
(function) [edit]
(C++11)
nearest integer using current rounding mode
(function) [edit]
(C++11)(C++11)
gets or sets rounding direction
(function) [edit]