26 Numerics library [numerics]

26.5 Bit manipulation [bit]

26.5.1 General [bit.general]

1
#
The header <bit> provides components to access, manipulate and process both individual bits and bit sequences.

26.5.2 Header <bit> synopsis [bit.syn]

namespace std {
  // [bit.cast], bit_­cast
  template<class To, class From>
    constexpr To bit_cast(const From& from) noexcept;

  // [bit.pow.two], integral powers of 2
  template<class T>
    constexpr bool has_single_bit(T x) noexcept;
  template<class T>
    constexpr T bit_ceil(T x);
  template<class T>
    constexpr T bit_floor(T x) noexcept;
  template<class T>
    constexpr T bit_width(T x) noexcept;

  // [bit.rotate], rotating
  template<class T>
    [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
  template<class T>
    [[nodiscard]] constexpr T rotr(T x, int s) noexcept;

  // [bit.count], counting
  template<class T>
    constexpr int countl_zero(T x) noexcept;
  template<class T>
    constexpr int countl_one(T x) noexcept;
  template<class T>
    constexpr int countr_zero(T x) noexcept;
  template<class T>
    constexpr int countr_one(T x) noexcept;
  template<class T>
    constexpr int popcount(T x) noexcept;

  // [bit.endian], endian
  enum class endian {
    little = see below,
    big    = see below,
    native = see below
  };
}

26.5.3 Function template bit_­cast [bit.cast]

🔗
template<class To, class From> constexpr To bit_cast(const From& from) noexcept;
1
#
Constraints:
  • (1.1)
    sizeof(To) == sizeof(From) is true;
  • (1.2)
    is_­trivially_­copyable_­v<To> is true; and
  • (1.3)
    is_­trivially_­copyable_­v<From> is true.
2
#
Returns: An object of type To.
Implicitly creates objects nested within the result ([intro.object]).
Each bit of the value representation of the result is equal to the corresponding bit in the object representation of from.
Padding bits of the result are unspecified.
For the result and each object created within it, if there is no value of the object's type corresponding to the value representation produced, the behavior is undefined.
If there are multiple such values, which value is produced is unspecified.
3
#
Remarks: This function is constexpr if and only if To, From, and the types of all subobjects of To and From are types T such that:
  • (3.1)
    is_­union_­v<T> is false;
  • (3.2)
    is_­pointer_­v<T> is false;
  • (3.3)
    is_­member_­pointer_­v<T> is false;
  • (3.4)
    is_­volatile_­v<T> is false; and
  • (3.5)
    T has no non-static data members of reference type.

26.5.4 Integral powers of 2 [bit.pow.two]

🔗
template<class T> constexpr bool has_single_bit(T x) noexcept;
1
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
2
#
Returns: true if x is an integral power of two; false otherwise.
🔗
template<class T> constexpr T bit_ceil(T x);
3
#
Let N be the smallest power of 2 greater than or equal to x.
4
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
5
#
Preconditions: N is representable as a value of type T.
6
#
Returns: N.
7
#
Throws: Nothing.
8
#
Remarks: A function call expression that violates the precondition in the Preconditions: element is not a core constant expression ([expr.const]).
🔗
template<class T> constexpr T bit_floor(T x) noexcept;
9
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
10
#
Returns: If x == 0, 0; otherwise the maximal value y such that has_­single_­bit(y) is true and y <= x.
🔗
template<class T> constexpr T bit_width(T x) noexcept;
11
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
12
#
Returns: If x == 0, 0; otherwise one plus the base-2 logarithm of x, with any fractional part discarded.

26.5.5 Rotating [bit.rotate]

In the following descriptions, let N denote numeric_­limits<T>​::​digits.
🔗
template<class T> [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
1
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
2
#
Let r be s % N.
3
#
Returns: If r is 0, x; if r is positive, (x << r) | (x >> (N - r)); if r is negative, rotr(x, -r).
🔗
template<class T> [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
4
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
5
#
Let r be s % N.
6
#
Returns: If r is 0, x; if r is positive, (x >> r) | (x << (N - r)); if r is negative, rotl(x, -r).

26.5.6 Counting [bit.count]

In the following descriptions, let N denote numeric_­limits<T>​::​digits.
🔗
template<class T> constexpr int countl_zero(T x) noexcept;
1
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
2
#
Returns: The number of consecutive 0 bits in the value of x, starting from the most significant bit.
[Note
:
Returns N if x == 0.
— end note
]
🔗
template<class T> constexpr int countl_one(T x) noexcept;
3
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
4
#
Returns: The number of consecutive 1 bits in the value of x, starting from the most significant bit.
[Note
:
Returns N if x == numeric_­limits<T>​::​max().
— end note
]
🔗
template<class T> constexpr int countr_zero(T x) noexcept;
5
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
6
#
Returns: The number of consecutive 0 bits in the value of x, starting from the least significant bit.
[Note
:
Returns N if x == 0.
— end note
]
🔗
template<class T> constexpr int countr_one(T x) noexcept;
7
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
8
#
Returns: The number of consecutive 1 bits in the value of x, starting from the least significant bit.
[Note
:
Returns N if x == numeric_­limits<T>​::​max().
— end note
]
🔗
template<class T> constexpr int popcount(T x) noexcept;
9
#
Constraints: T is an unsigned integer type ([basic.fundamental]).
10
#
Returns: The number of 1 bits in the value of x.

26.5.7 Endian [bit.endian]

1
#
Two common methods of byte ordering in multibyte scalar types are big-endian and little-endian in the execution environment.
Big-endian is a format for storage of binary data in which the most significant byte is placed first, with the rest in descending order.
Little-endian is a format for storage of binary data in which the least significant byte is placed first, with the rest in ascending order.
This subclause describes the endianness of the scalar types of the execution environment.
🔗
enum class endian { little = see below, big = see below, native = see below };
2
#
If all scalar types have size 1 byte, then all of endian​::​little, endian​::​big, and endian​::​native have the same value.
Otherwise, endian​::​little is not equal to endian​::​big.
If all scalar types are big-endian, endian​::​native is equal to endian​::​big.
If all scalar types are little-endian, endian​::​native is equal to endian​::​little.
Otherwise, endian​::​native is not equal to either endian​::​big or endian​::​little.