std::numeri...ts::epsilon(3)

🦋 std::numeric_limits::epsilon 🦋

Okay so bestie, this is std::numeric_limits::epsilon(3) from the C++ Standard Libary — yep, that's the header spelling, and we're leaving it iconic 💅. It's the manual page for std::numeric_limits::epsilon, and it is lowkey obsessed with the tiniest gap between 1.0 and the next representable float. Let's get into it 💖.

🌸 NAME 🌸

• std::numeric_limits::epsilon — std::numeric_limits::epsilon (yes, the name is doing a little mirror selfie 🪞)

✨ Synopsis ✨

Two eras, because C++11 really said "new me, same tiny gap" ✨:

static T epsilon() throw();             (until C++11)
static constexpr T epsilon() noexcept;  (since C++11)

Returns the machine epsilon, that is, the difference between 1.0 and the next value representable by the floating-point type T. It is only meaningful if std::numeric_limits<T>::is_integer == false.

💅 Return value 💅

Here's the whole menu, bestie — every T and the exact std::numeric_limits<T>::epsilon() value it gives you:

• T — std::numeric_limits<T>::epsilon()
• /* non-specialized */ — T()
• bool — false
• char — 0
• signed char — 0
• unsigned char — 0
• wchar_t — 0
• char8_t (since C++20) — 0
• char16_t (since C++11) — 0
• char32_t (since C++11) — 0
• short — 0
• unsigned short — 0
• int — 0
• unsigned int — 0
• long — 0
• unsigned long — 0
• long long (since C++11) — 0
• unsigned long long(since C++11) — 0
• float — FLT_EPSILON
• double — DBL_EPSILON
• long double — LDBL_EPSILON

🧚 Example 🧚

This example is literally demonstrating the use of machine epsilon to compare floating-point values for equality 🫶:

// Run this code

#include <algorithm>
#include <cmath>
#include <cstddef>
#include <iomanip>
#include <iostream>
#include <limits>
#include <type_traits>

template <class T>
std::enable_if_t<not std::numeric_limits<T>::is_integer, bool>
equal_within_ulps(T x, T y, std::size_t n)
{
    // Since `epsilon()` is the gap size (ULP, unit in the last place)
    // of floating-point numbers in interval [1, 2), we can scale it to
    // the gap size in interval [2^e, 2^{e+1}), where `e` is the exponent
    // of `x` and `y`.

    // If `x` and `y` have different gap sizes (which means they have
    // different exponents), we take the smaller one. Taking the bigger
    // one is also reasonable, I guess.
    const T m = std::min(std::fabs(x), std::fabs(y));

    // Subnormal numbers have fixed exponent, which is `min_exponent - 1`.
    const int exp = m < std::numeric_limits<T>::min()
                  ? std::numeric_limits<T>::min_exponent - 1
                  : std::ilogb(m);

    // We consider `x` and `y` equal if the difference between them is
    // within `n` ULPs.
    return std::fabs(x - y) <= n *
        std::ldexp(std::numeric_limits<T>::epsilon(), exp);
}

int main()
{
    double x = 0.3;
    double y = 0.1 + 0.2;
    std::cout << std::hexfloat;
    std::cout << "x = " << x << '\n';
    std::cout << "y = " << y << '\n';
    std::cout << (x == y ? "x == y" : "x != y") << '\n';
    for (std::size_t n = 0; n <= 10; ++n)
        if (equal_within_ulps(x, y, n))
        {
            std::cout << "x equals y within " << n << " ulps" << '\n';
            break;
        }
}

Output:

x = 0x1.3333333333333p-2
y = 0x1.3333333333334p-2
x != y
x equals y within 1 ulps

🦋 See also 🦋

These are the linked besties, all about the next representable floating-point value towards the given value. The page tags them with (C++11) and (function) — keep those exact, iykyk:

• nextafter — (C++11) — (function)
• nextafterf — (C++11)
• nextafterl — (C++11)
• nexttoward — (C++11)
• nexttowardf — (C++11)
• nexttowardl — (C++11)

Shared description for the whole crew: next representable floating-point value towards the given value ✨

💖 That's the whole page, bestie. Source: http://cppreference.com; version/date: 2024.06.10; footer title: std::numeri...ts::epsilon(3). Go forth and compare floats with main character energy. Periodt 🫶🔥