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

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Numerics library

Common mathematical functions
Mathematical special functions (C++17)
Mathematical constants (C++20)
Basic linear algebra algorithms (C++26)
Floating-point environment (C++11)
Complex numbers
Numeric array (valarray)
Pseudo-random number generation
Factor operations
gcd (C++17)	lcm (C++17)
Interpolations
midpoint (C++20)	lerp (C++20)
Saturation arithmetic
add_sat (C++26) sub_sat (C++26) saturate_cast (C++26)	mul_sat (C++26) div_sat (C++26)
Generic numeric operations
iota (C++11) ranges::iota (C++23) accumulate inner_product adjacent_difference partial_sum	reduce (C++17) transform_reduce (C++17) inclusive_scan (C++17) exclusive_scan (C++17) transform_inclusive_scan (C++17) transform_exclusive_scan (C++17)
Bit operations
has_single_bit (C++20)     bit_cast (C++20) bit_ceil (C++20) bit_floor (C++20) bit_width (C++20) rotl (C++20) rotr (C++20)	popcount (C++20) countl_zero (C++20) countl_one (C++20) countr_zero (C++20) countr_one (C++20) byteswap (C++23) endian (C++20)

 

Common mathematical functions

Functions
Basic operations
abs(int)labsllabsimaxabs (C++11)   abs(float)fabs divldivlldivimaxdiv (C++11)	fmod remainder (C++11)   remquo (C++11) fma (C++11) fmax (C++11) fmin (C++11) fdim (C++11) nannanfnanl (C++11)(C++11)(C++11)
Exponential functions
exp exp2 (C++11) expm1 (C++11)	log log10 log1p (C++11) log2 (C++11)
Power functions
sqrt cbrt (C++11)	hypot (C++11) pow
Trigonometric and hyperbolic functions
sin cos tan asin acos atan atan2	sinh cosh tanh asinh (C++11) acosh (C++11) atanh (C++11)
Error and gamma functions
erf (C++11) erfc (C++11)	lgamma (C++11) tgamma (C++11)

Nearest integer floating point operations
ceil floor roundlroundllround (C++11)(C++11)(C++11)	trunc (C++11) nearbyint (C++11) rintlrintllrint (C++11)(C++11)(C++11)
Floating point manipulation functions
ldexp scalbnscalbln (C++11)(C++11) ilogb (C++11) logb (C++11)	frexp modf nextafternexttoward (C++11)(C++11) copysign (C++11)
Classification and comparison
fpclassify (C++11) isfinite (C++11) isinf (C++11) isnan (C++11) isnormal (C++11) signbit (C++11)	isgreater (C++11) isgreaterequal (C++11) isless (C++11) islessequal (C++11) islessgreater (C++11) isunordered (C++11)
Types
div_t ldiv_t lldiv_t (C++11)	imaxdiv_t (C++11) float_t (C++11) double_t (C++11)
Macro constants
HUGE_VALFHUGE_VALHUGE_VALL (C++11)(C++11) math_errhandlingMATH_ERRNOMATH_ERREXCEPT (C++11)   INFINITY (C++11) NAN (C++11)	Classification FP_NORMALFP_SUBNORMALFP_ZEROFP_INFINITEFP_NAN (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).

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: \n"
              << "rint(+2.3) = " << std::rint(2.3)
              << "  rint(+2.5) = " << std::rint(2.5)
              << "  rint(+2.7) = " << std::rint(2.7) << '\n'
              << "rint(-2.3) = " << std::rint(-2.3)
              << "  rint(-2.5) = " << std::rint(-2.5)
              << "  rint(-2.7) = " << std::rint(-2.7) << '\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(+2.7) = " << std::rint(2.7) << '\n'
              << "rint(-2.3) = " << std::rint(-2.3)
              << "  rint(-2.5) = " << std::rint(-2.5)
              << "  rint(-2.7) = " << std::rint(-2.7) << '\n'
              << "rounding down with lrint\n" 
              << "lrint(+2.3) = " << std::lrint(2.3)
              << "  lrint(+2.5) = " << std::lrint(2.5)
              << "  lrint(+2.7) = " << std::lrint(2.7) << '\n'
              << "lrint(-2.3) = " << std::lrint(-2.3)
              << "  lrint(-2.5) = " << std::lrint(-2.5)
              << "  lrint(-2.7) = " << std::lrint(-2.7) << '\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: 
rint(+2.3) = 2  rint(+2.5) = 2  rint(+2.7) = 3
rint(-2.3) = -2  rint(-2.5) = -2  rint(-2.7) = -3
rounding down:
rint(+2.3) = 2  rint(+2.5) = 2  rint(+2.7) = 2
rint(-2.3) = -3  rint(-2.5) = -3  rint(-2.7) = -3
rounding down with lrint
lrint(+2.3) = 2  lrint(+2.5) = 2  lrint(+2.7) = 2
lrint(-2.3) = -3  lrint(-2.5) = -3  lrint(-2.7) = -3
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

trunctruncftruncl (C++11)(C++11)(C++11)	nearest integer not greater in magnitude than the given value (function)
nearbyintnearbyintfnearbyintl (C++11)(C++11)(C++11)	nearest integer using current rounding mode (function)
fegetroundfesetround (C++11)(C++11)	gets or sets rounding direction (function)
C documentation for rint