std::nearby...:nearbyintl(3)

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

okay bestie, welcome to the C++ Standard Library corner of the manual 💅 this page is literally about std::nearbyint and its two glamorous siblings, and it's shorter than you'd think. iykyk.

---

🌸 Synopsis 🌸

Bestie. The whole vibe is "round a float to an integer, but do it in floating-point format, and use whatever rounding mode you've got set." That's it. That's the function.

Defined in header <cmath>:

float       nearbyint ( float num );

double      nearbyint ( double num );
(until C++23)

long double nearbyint ( long double num );
/* floating-point-type */
(since C++23)
                nearbyint ( /* floating-point-type */ num ); (1)
float       nearbyintf( float num );                         (2)
(since C++11)
long double nearbyintl( long double num );                   (3)
(since C++11)

Additional overloads (since C++11) — Defined in header <cmath>:

template< class Integer >                                    (A)
double      nearbyint ( Integer num );

so like, here's the tea on each numbered thing 🫖

1. 1-3) — these round the floating-point argument num to an integer value in floating-point format, using the current rounding mode. no cap.
2. since C++23 — the library provides overloads of std::nearbyint for all cv-unqualified floating-point types as the type of the parameter. slay ✨
3. A) — since C++11, additional overloads are provided for all integer types, which are treated as double. cute.

---

🎀 Parameters 🎀

• num — floating-point or integer value. that's the whole parameter list. go off, king 👑

---

💖 Return value 💖

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

like it just... gives you the nearest integer. in floating point. obsessed.

---

🦋 Error handling 🦋

This function is not subject to any of the errors specified in math_errhandling. so she's low-maintenance like that 💅

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

• FE_INEXACT is never raised. never ever. not once.
• If num is ±∞, it is returned, unmodified. she's coming back exactly as she left, periodt.
• If num is ±0, it is returned, unmodified. iconic.
• If num is NaN, NaN is returned. can't fix that, bestie 😭

---

🧚 Notes 🧚

The only difference between std::nearbyint and std::rint is that std::nearbyint never raises FE_INEXACT. like, that's literally the single distinguishing feature. that's the whole personality trait.

The largest representable floating-point values are exact integers in all standard floating-point formats, so std::nearbyint never overflows on its own. however — and this is important, bestie, don't skip this — the result may overflow any integer type (including std::intmax_t) when stored in an integer variable. so like, be careful.

If the current rounding mode is FE_TONEAREST, this function rounds to even in halfway cases (like std::rint, but unlike std::round). yes this is the "banker's rounding" thing. yes it surprises everyone. no you're not the only one who got got by it 🙈

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)). i.e. nobody's grading the implementation, just the vibes 🫶

---

⭐ Example ⭐

// Run this code

#include <cfenv>
#include <cmath>
#include <iostream>
#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

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

see how 2.5 → 2 and 3.5 → 4? that's the round-to-even thing doing its little dance 💃 and see how -0.0 stays -0? she refuses to lose her sign. respect.

---

🔥 See also 🔥

• rint, rintf, rintl, lrint, lrintf, lrintl, llrint, llrintf, llrintl (since C++11) — nearest integer using current rounding mode with exception if the result differs (function)
• round, roundf, roundl, lround, lroundf, lroundl, llround, llroundf, llroundl (since C++11) — nearest integer, rounding away from zero in halfway cases (function)
• fegetround, fesetround (since C++11) — gets or sets rounding direction (function)
• C documentation for nearbyint

---

okay that's the whole page, bestie, you're officially educated 💜 go forth and round responsibly. periodt. 🎀✨

this gem was served fresh from cppreference.com, dated 2024.06.10, and lives under the manual entry std::nearby...:nearbyintl(3) — mwah, bye! 💅