# std::bit_ceil

From cppreference.com
< cpp‎ | numeric

Defined in header `<bit>` |  |
template< class T > constexpr T bit_ceil( T x ); |  | (since C++20)

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

If that value is not representable in `T`, the behavior is undefined. Call to this function is permitted in constant evaluation only if the undefined behavior does not occur.

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).

### Parameters

x | - | value of unsigned integer type

### Return value

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

### Exceptions

Throws nothing.

### Notes

Prior to P1956R1, the proposed name for this function template was `ceil2`.

Feature-test macro | Value | Std | Feature
--- | --- | --- | ---
`__cpp_lib_int_pow2` | `202002L` | (C++20) | Integral power-of-2 operations

### Possible implementation

See possible implementations in libstdc++ (gcc) and libc++ (clang).

    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);
        }
    }

### Example

Run this code

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

    int main()
    {
        using bin = std::bitset<8>;
        for (auto x{0U}; 0XA != x; ++x)
            std::cout << "bit_ceil( " << bin(x) << " ) = "
                      << bin(std::bit_ceil(x)) << '\n';
    }

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

### See also

bit_floor (C++20) | finds the largest integral power of 2 not greater than the given value (function template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/numeric/bit_ceil&oldid=178983"