std::bit_ceil(3)

💅 std::bit_ceil 💅

ok so bestie, welcome to std::bit_ceil(3) — that's section 3 of the manual, and the manual is the C++ Standard Libary (yes that's how it's spelled on the page, no I will not be fixing it, it's iconic in its own way 🫶).

---

✨ NAME ✨

std::bit_ceil — literally std::bit_ceil. that's it. that's the name. slay.

---

🌸 SYNOPSIS 🌸

ok so it lives in the <bit> header, and it's been around since C++20. here's the whole vibe:

template< class T >           (since C++20)
constexpr T bit_ceil( T x );

what it does: it calculates the smallest integral power of two that is not smaller than x. so like… round up to the next power of two, but if you're already a power of two you stay exactly where you are. lowkey the politest rounding function ever.

⚠️ bestie listen to me. if that value is not representable in T, the behavior is undefined. and a call to this function is permitted in constant evaluation only if the undefined behavior does not occur. so like, don't do that. no cap.

this overload participates in overload resolution only if T is an unsigned integer type (that is, unsigned char, unsigned short, unsigned int, unsigned long, unsigned long long, or an extended unsigned integer type). so check your types before you come for her 💅

---

🎀 PARAMETERS 🎀

• x — a value of unsigned integer type. that's the whole parameter list. one (1) bestie. we love a low-maintenance signature.

---

🌈 RETURN VALUE 🌈

the smallest integral power of two that is not smaller than x. periodt.

---

🦋 EXCEPTIONS 🦋

throws nothing. she is unbothered. she is at peace. she does not throw. ✨

---

💜 NOTES 💜

there's a feature-test macro and she has receipts:

• __cpp_lib_int_pow2 — value 202002L — Std (C++20) — feature: Integral power-of-2 operations

---

👑 POSSIBLE IMPLEMENTATION 👑

ok so you don't have to do it this way, but the page says: see possible implementations in libstdc++ (gcc) and libc++ (clang). and here's the actual code, verbatim, do not touch her:

template<std::unsigned_integral T>
    requires !std::same_as<T, bool> && !std::same_as<T, char> &&
             !std::same_as<T, char8_t> && !std::same_as<T, char16_t> &&
             !std::same_as<T, char32_t> && !std::same_as<T, wchar_t>
constexpr T bit_ceil(T x) noexcept
{
    if (x <= 1u)
        return T(1);
    if constexpr (std::same_as<T, decltype(+x)>)
        return T(1) << std::bit_width(T(x - 1));
    else
    {   // for types subject to integral promotion
        constexpr int offset_for_ub =
            std::numeric_limits<unsigned>::digits - std::numeric_limits<T>::digits;
        return T(1u << (std::bit_width(T(x - 1)) + offset_for_ub) >> offset_for_ub);
    }
}

like the way that requires clause just lists every char type it doesn't want?? the way that offset_for_ub is literally named after undefined behavior?? main character energy honestly 💀

---

🔥 EXAMPLE 🔥

the page says "Run this code" so like… run it bestie:

#include <bit>
#include <bitset>
#include <iostream>

int main()
{
    using bin = std::bitset<8>;

    for (unsigned x{0}; x != 10; ++x)
    {
        unsigned const z = std::bit_ceil(x); // `ceil2` before P1956R1
        std::cout << "bit_ceil( " << bin(x) << " ) = " << bin(z) << '\n';
    }
}

(also shoutout to that little comment — it was called ceil2 before P1956R1. lore.)

⭐ Output: ⭐

bit_ceil( 00000000 ) = 00000001
bit_ceil( 00000001 ) = 00000001
bit_ceil( 00000010 ) = 00000010
bit_ceil( 00000011 ) = 00000100
bit_ceil( 00000100 ) = 00000100
bit_ceil( 00000101 ) = 00001000
bit_ceil( 00000110 ) = 00001000
bit_ceil( 00000111 ) = 00001000
bit_ceil( 00001000 ) = 00001000
bit_ceil( 00001001 ) = 00010000

look at 00000011 becoming 00000100 — she said round up bestie. and 00001001 becoming 00010000?? ate. 🔥

---

🍓 SEE ALSO 🍓

• bit_floor — finds the largest integral power of two not greater than the given value — (C++20) (function template) — the other half of the duo, the down-bad counterpart, iykyk 🌸

---

that's the whole page bestie, go forth and round up responsibly 💖

— with love, from http://cppreference.com, dated 2024.06.10, filed under std::bit_ceil(3) 🎀✨🦋