Edit

Share via


<bit> functions

The <bit> header includes the following non-member template functions:

Non-member functions Description
bit_cast Reinterpret the object representation from one type to another.
bit_ceil Find the smallest power of two greater than or equal to a value.
bit_floor Find the largest power of two not greater than a value.
bit_width Find the smallest number of bits needed to represent a value.
countl_zero Count the number of consecutive bits set to zero, starting from the most significant bit.
countl_one Count the number of consecutive bits set to one, starting from the most significant bit.
countr_zero Count the number of consecutive bits set to zero, starting from the least significant bit.
countr_one Count the number of consecutive bits set to one, starting from the least significant bit.
has_single_bit Check if a value has only a single bit set to one. This is the same as testing whether a value is a power of two.
popcount Count the number of bits set to one.
rotl Compute the result of a bitwise left rotation.
rotr Compute the result of a bitwise right rotation.

bit_cast

Copy a bit pattern from an object of type From to a new object of type To.

template <class To, class From>
[[nodiscard]] constexpr To bit_cast(const From& from) noexcept;

Parameters

To
The type of the output.

From
The type of the value to convert.

from
The value to convert.

Return value

An object of type To.

Each bit in the result matches the corresponding bit in from unless there are padding bits in To, in which case those bits in the result are unspecified.

Example

#include <bit>
#include <iostream>

int main()
{
    float f = std::numeric_limits<float>::infinity();
    int i = std::bit_cast<int>(f);
    std::cout << "float f = " << std::hex << f
              << "\nstd::bit_cast<int>(f) = " << std::hex << i << '\n';
    return 0;
}
float f = inf
std::bit_cast<int>(f) = 7f800000

Remarks

Low-level code often needs to interpret an object of one type as another type. The reinterpreted object has the same bit representation as the original, but is a different type.

Instead of using reinterpret_cast, or memcpy(), bit_cast() is a better way to make these conversions. It's better because:

  • bit_cast() is constexpr
  • bit_cast() requires the types to be trivially copyable and the same size. This prevents potential problems that you could encounter using reinterpret_cast and memcpy because they could be used to inadvertently, and incorrectly, convert non-trivially-copyable types. Also, memcpy() could be used to inadvertently copy between types that aren't the same size. For example, a double (8 bytes) into an unsigned int (4 bytes), or the other way around.

This overload only participates in overload resolution if:

This function template is constexpr if and only if To, From, and the types of their subobjects are:

  • Not a union or pointer type
  • Not a pointer to member type
  • Not volatile-qualified
  • Have no non-static data member that is a reference type

bit_ceil

Find the smallest power of two greater than or equal to a value. For example, given 3, returns 4.

template<class T>
[[nodiscard]] constexpr T bit_ceil(T value);

Parameters

value
The unsigned integer value to test.

Return value

The smallest power of two greater than or equal to value.

Example

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

int main()
{
    for (auto i = 0u; i < 6u; ++i) // bit_ceil() takes an unsigned integer type
    {
        auto nextClosestPowerOf2 = std::bit_ceil(i);
        std::cout << "\nbit_ceil(0b" << std::bitset<4>(i) << ") = "
                  << "0b" << std::bitset<4>(nextClosestPowerOf2);
    }
    return 0;
}
bit_ceil(0b0000) = 0b0001
bit_ceil(0b0001) = 0b0001
bit_ceil(0b0010) = 0b0010
bit_ceil(0b0011) = 0b0100
bit_ceil(0b0100) = 0b0100
bit_ceil(0b0101) = 0b1000

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

bit_floor

Find the largest power of two not greater than a value. For example, given 5, returns 4.

template< class T >
[[nodiscard]] constexpr T bit_floor(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

The largest power of two that isn't greater than value.
If value is zero, returns zero.

Example

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

int main()
{
    for (auto i = 0u; i < 6u; ++i) // bit_floor() takes an unsigned integer type
    {
        auto previousPowerOf2 = std::bit_floor(i);
        std::cout << "\nbit_floor(0b" << std::bitset<4>(i) << ") = 0b"
                  << std::bitset<4>(previousPowerOf2);
    }
    return 0;
}
bit_floor(0b0000) = 0b0000
bit_floor(0b0001) = 0b0001
bit_floor(0b0010) = 0b0010
bit_floor(0b0011) = 0b0010
bit_floor(0b0100) = 0b0100
bit_floor(0b0101) = 0b0100

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

bit_width

Find the smallest number of bits needed to represent a value.

For example, given 5 (0b101), returns 3 because it takes 3 binary bits to express the value 5.

template<class T>
[[nodiscard]] constexpr T bit_width(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

The number of bits needed to represent value.
If value is zero, returns zero.

Example

#include <bit>
#include <iostream>

int main()
{
    for (unsigned i=0u; i <= 8u; ++i)
    {
        std::cout << "\nbit_width(" << i << ") = "
                  << std::bit_width(i);
    }
    return 0;
}
bit_width(0) = 0
bit_width(1) = 1
bit_width(2) = 2
bit_width(3) = 2
bit_width(4) = 3
bit_width(5) = 3
bit_width(6) = 3
bit_width(7) = 3
bit_width(8) = 4

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

countl_zero

Count the number of consecutive bits set to zero, starting from the most significant bit.

template<class T>
[[nodiscard]] constexpr int countl_zero(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

The number of consecutive zero bits, starting from the most significant bit.
If value is zero, the number of bits in the type of value.

Example

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

int main()
{
    for (unsigned char result = 0, i = 0; i < 9; i++)
    {
        std::cout << "\ncountl_zero(0b" << std::bitset<8>(result) << ") = " << std::countl_zero(result);
        result = result == 0 ? 1 : result * 2;
    }
    return 0;
}
countl_zero(0b00000000) = 8
countl_zero(0b00000001) = 7
countl_zero(0b00000010) = 6
countl_zero(0b00000100) = 5
countl_zero(0b00001000) = 4
countl_zero(0b00010000) = 3
countl_zero(0b00100000) = 2
countl_zero(0b01000000) = 1
countl_zero(0b10000000) = 0

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

countl_one

Count the number of consecutive bits set to one, starting from the most significant bit.

template<class T>
[[nodiscard]] constexpr int countl_one(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

The number of consecutive bits set to one, starting from the most significant bit.

Example

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

int main()
{
    unsigned char value = 0;
    for (unsigned char bit = 128; bit > 0; bit /= 2)
    {
        value |= bit;
        std::cout << "\ncountl_one(0b" << std::bitset<8>(value) << ") = "
                  << std::countl_one(value);
    }
    return 0;
}
countl_one(0b10000000) = 1
countl_one(0b11000000) = 2
countl_one(0b11100000) = 3
countl_one(0b11110000) = 4
countl_one(0b11111000) = 5
countl_one(0b11111100) = 6
countl_one(0b11111110) = 7
countl_one(0b11111111) = 8

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

countr_zero

Count the number of consecutive bits set to zero, starting from the least significant bit.

template<class T>
[[nodiscard]] constexpr int countr_zero(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

The number of consecutive zero bits, starting from the least significant bit.
If value is zero, the number of bits in the type of value.

Example

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

int main()
{
    for (unsigned char result = 0, i = 0; i < 9; i++)
    {
        std::cout << "\ncountr_zero(0b" << std::bitset<8>(result) << ") = "
                  << std::countr_zero(result);
        result = result == 0 ? 1 : result * 2;
    }
    return 0;
}
countr_zero(0b00000000) = 8
countr_zero(0b00000001) = 0
countr_zero(0b00000010) = 1
countr_zero(0b00000100) = 2
countr_zero(0b00001000) = 3
countr_zero(0b00010000) = 4
countr_zero(0b00100000) = 5
countr_zero(0b01000000) = 6
countr_zero(0b10000000) = 7

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

countr_one

Count the number of consecutive bits set to one, starting from the least significant bit.

template<class T>
[[nodiscard]] constexpr int countr_one(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

The number of consecutive bits set to one, starting from the least significant bit.

Example

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

int main()
{
    unsigned char value = 0;
    for (int bit = 1; bit <= 128; bit *= 2)
    {
        value |= bit;
        std::cout << "\ncountr_one(0b" << std::bitset<8>(value) << ") = "
                  << std::countr_one(value);
    }
    return 0;
}
countr_one(0b00000001) = 1
countr_one(0b00000011) = 2
countr_one(0b00000111) = 3
countr_one(0b00001111) = 4
countr_one(0b00011111) = 5
countr_one(0b00111111) = 6
countr_one(0b01111111) = 7
countr_one(0b11111111) = 8

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

has_single_bit

Check if a value has only one bit set.This is the same as testing whether a value is a power of two.

template <class T>
[[nodiscard]] constexpr bool has_single_bit(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

true if value has only one bit set, which also means that value is a power of two. Otherwise, false.

Example

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

int main()
{
    for (auto i = 0u; i < 10u; ++i)
    {
        std::cout << "has_single_bit(0b" << std::bitset<4>(i) << ") = "
                  << std::boolalpha << std::has_single_bit(i) << '\n';
    }
    return 0;
}
has_single_bit(0b0000) = false
has_single_bit(0b0001) = true
has_single_bit(0b0010) = true
has_single_bit(0b0011) = false
has_single_bit(0b0100) = true
has_single_bit(0b0101) = false
has_single_bit(0b0110) = false
has_single_bit(0b0111) = false
has_single_bit(0b1000) = true
has_single_bit(0b1001) = false

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

popcount

Count the number of bits set to one in an unsigned integer value.

template<class T>
[[nodiscard]] constexpr int popcount(T value) noexcept;

Parameters

value
The unsigned integer value to test.

Return value

The number bits set to one in value.

Example

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

int main()
{
   for (unsigned char value = 0; value < 16; value++)
    {
        std::cout << "\npopcount(0b" << std::bitset<4>(value) << ") = "
                  << std::popcount(value);
    }
    return 0;
}
popcount(0b0000) = 0
popcount(0b0001) = 1
popcount(0b0010) = 1
popcount(0b0011) = 2
popcount(0b0100) = 1
popcount(0b0101) = 2
popcount(0b0110) = 2
popcount(0b0111) = 3
popcount(0b1000) = 1
popcount(0b1001) = 2
popcount(0b1010) = 2
popcount(0b1011) = 3
popcount(0b1100) = 2
popcount(0b1101) = 3
popcount(0b1110) = 3
popcount(0b1111) = 4

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

rotl

Rotates the bits of an unsigned integer value left the specified number of times. Bits that "fall out" of the leftmost bit are rotated into the rightmost bit.

template<class T>
[[nodiscard]] constexpr T rotl(T value, int s) noexcept;

Parameters

value
The unsigned integer value to rotate.

s
The number of left rotations to perform.

Return value

The result of rotating value left, s times.
If s is zero, returns value.
If s is negative, does rotr(value, -s). Bits that 'fall out' of the rightmost bit are rotated into the leftmost bit.

Example

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

int main()
{
    unsigned char bits = 1;
    for (int i = 0; i < 8; ++i)
    {
        std::cout << "rotl(0b" << std::bitset<8>(bits) << ", 1) = ";
        bits = std::rotl(bits, 1);
        std::cout << "0b" << std::bitset<8>(bits) << '\n';
    }
    std::cout << "rotl(0b" << std::bitset<8>(bits) << ",-1) = ";
    bits = std::rotl(bits, -1);
    std::cout << "0b" << std::bitset<8>(bits);
    return 0;
}
rotl(0b00000001, 1) = 0b00000010
rotl(0b00000010, 1) = 0b00000100
rotl(0b00000100, 1) = 0b00001000
rotl(0b00001000, 1) = 0b00010000
rotl(0b00010000, 1) = 0b00100000
rotl(0b00100000, 1) = 0b01000000
rotl(0b01000000, 1) = 0b10000000
rotl(0b10000000, 1) = 0b00000001
rotl(0b00000001,-1) = 0b10000000

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

rotr

Rotates the bits of value right the specified number of times. Bits that 'fall out' of the rightmost bit are rotated back into the leftmost bit.

template<class T>
[[nodiscard]] constexpr T rotr(T value, int s) noexcept;

Parameters

value
The unsigned integer value to rotate.

s
The number of right rotations to perform.

Return value

The result of rotating value right, s times.
If s is zero, returns value.
If s is negative, does rotl(value, -s). Bits that 'fall out' of the leftmost bit are rotated back into the rightmost bit.

Example

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

int main()
{
    unsigned char bits = 128;
    for (int i = 0; i < 8; ++i)
    {
        std::cout << "rotr(0b" << std::bitset<8>(bits) << ", 1) = ";
        bits = std::rotr(bits, 1);
        std::cout << "0b" << std::bitset<8>(bits) << '\n';
    }
    std::cout << "rotr(0b" << std::bitset<8>(bits) << ",-1) = ";
    bits = std::rotr(bits, -1);
    std::cout << "0b" << std::bitset<8>(bits);
    return 0;
}
rotr(0b10000000, 1) = 0b01000000
rotr(0b01000000, 1) = 0b00100000
rotr(0b00100000, 1) = 0b00010000
rotr(0b00010000, 1) = 0b00001000
rotr(0b00001000, 1) = 0b00000100
rotr(0b00000100, 1) = 0b00000010
rotr(0b00000010, 1) = 0b00000001
rotr(0b00000001, 1) = 0b10000000
rotr(0b10000000,-1) = 0b00000001

Remarks

This template function only participates in overload resolution if T is an unsigned integer type. For example: unsigned int, unsigned long, unsigned short, unsigned char, and so on.

Requirements

Header: <bit>

Namespace: std

/std:c++20 or later is required.

See also

<bit>