std::nearbyint, std::nearbyintf, std::nearbyintl - cppreference.com (original) (raw)

Defined in header
(1)
float nearbyint ( float num ); double nearbyint ( double num ); long double nearbyint ( long double num );		(until C++23)
/floating-point-type/ nearbyint ( /floating-point-type/ num );		(since C++23)
float nearbyintf( float num );	(2)	(since C++11)
long double nearbyintl( long double num );	(3)	(since C++11)
SIMD overload (since C++26)
Defined in header
template< /math-floating-point/ V > constexpr /deduced-simd-t/<V> nearbyint ( const V& v_num );	(S)	(since C++26)
Additional overloads (since C++11)
Defined in header
template< class Integer > double nearbyint ( Integer num );	(A)

1-3) Rounds the floating-point argument num to an integer value in floating-point format, using the current rounding mode. The library provides overloads of std::nearbyint for all cv-unqualified floating-point types as the type of the parameter.(since C++23)

A) Additional overloads are provided for all integer types, which are treated as double.	(since C++11)

[edit] Parameters

num	-	floating-point or integer value

[edit] Return value

The nearest integer value to num, according to the current rounding mode, is returned.

[edit] Error handling

This function is not subject to any of the errors specified in math_errhandling.

If the implementation supports IEEE floating-point arithmetic (IEC 60559),

FE_INEXACT is never raised.
If num is ±∞, it is returned, unmodified.
If num is ±0, it is returned, unmodified.
If num is NaN, NaN is returned.

[edit] Notes

The only difference between std::nearbyint and std::rint 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::nearbyint 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_TONEAREST, this function rounds to even in halfway cases (like std::rint, but unlike std::round).

The additional overloads are not required to be provided exactly as (A). They only need to be sufficient to ensure that for their argument num of integer type, std::nearbyint(num) has the same effect as std::nearbyint(static_cast<double>(num)).

[edit] Example

#include #include #include #pragma STDC FENV_ACCESS ON int main() { std::fesetround(FE_TONEAREST); std::cout << "rounding to nearest: \n" << "nearbyint(+2.3) = " << std::nearbyint(2.3) << " nearbyint(+2.5) = " << std::nearbyint(2.5) << " nearbyint(+3.5) = " << std::nearbyint(3.5) << '\n' << "nearbyint(-2.3) = " << std::nearbyint(-2.3) << " nearbyint(-2.5) = " << std::nearbyint(-2.5) << " nearbyint(-3.5) = " << std::nearbyint(-3.5) << '\n'; std::fesetround(FE_DOWNWARD); std::cout << "rounding down:\n" << "nearbyint(+2.3) = " << std::nearbyint(2.3) << " nearbyint(+2.5) = " << std::nearbyint(2.5) << " nearbyint(+3.5) = " << std::nearbyint(3.5) << '\n' << "nearbyint(-2.3) = " << std::nearbyint(-2.3) << " nearbyint(-2.5) = " << std::nearbyint(-2.5) << " nearbyint(-3.5) = " << std::nearbyint(-3.5) << '\n'; std::cout << "nearbyint(-0.0) = " << std::nearbyint(-0.0) << '\n' << "nearbyint(-Inf) = " << std::nearbyint(-INFINITY) << '\n'; }

Output: