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

From cppreference.com
< cpp‎ | numeric‎ | math

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).

### 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 (C++11) | nearest integer not greater in magnitude than the given value (function)
nearbyint (C++11) | nearest integer using current rounding mode (function)
fegetround fesetround (C++11)(C++11) | gets or sets rounding direction (function)
C documentation for rint

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/numeric/math/rint&oldid=86481"