std::nearbyint,std::nearbyintf,std::nearbyintl (3) - Linux Manuals

std::nearbyint,std::nearbyintf,std::nearbyintl: std::nearbyint,std::nearbyintf,std::nearbyintl

NAME

std::nearbyint,std::nearbyintf,std::nearbyintl - std::nearbyint,std::nearbyintf,std::nearbyintl

Synopsis

Defined in header <cmath>
float nearbyint ( float arg ); (1) (since C++11)
float nearbyintf( float arg );
double nearbyint ( double arg ); (2) (since C++11)
long double nearbyint ( long double arg ); (3) (since C++11)
long double nearbyintl( long double arg );
double nearbyint ( IntegralType arg ); (4) (since C++11)

1-3) Rounds the floating-point argument arg to an integer value in floating-point format, using the current_rounding_mode.
4) A set of overloads or a function template accepting an argument of any integral_type. Equivalent to (2) (the argument is cast to double).

Parameters

arg - floating point value

Return value

The nearest integer value to arg, according to the current_rounding_mode, is returned.

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 arg is ±∞, it is returned, unmodified
* If arg is ±0, it is returned, unmodified
* If arg is NaN, NaN is returned

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 rint, but unlike round).

Example

// Run this code

  #include <iostream>
  #include <cmath>
  #include <cfenv>

  int main()
  {
  #pragma STDC FENV_ACCESS ON
      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:

  rounding to nearest:
  nearbyint(+2.3) = 2 nearbyint(+2.5) = 2 nearbyint(+3.5) = 4
  nearbyint(-2.3) = -2 nearbyint(-2.5) = -2 nearbyint(-3.5) = -4
  rounding down:
  nearbyint(+2.3) = 2 nearbyint(+2.5) = 2 nearbyint(+3.5) = 3
  nearbyint(-2.3) = -3 nearbyint(-2.5) = -3 nearbyint(-3.5) = -4
  nearbyint(-0.0) = -0
  nearbyint(-Inf) = -inf