21 Bit Manipulation

This chapter contains information about functions and macros for determining the endianness of integer types and manipulating the bits of unsigned integers. These functions and macros are from ISO C23 and are declared in the header file stdbit.h.

The following macros describe the endianness of integer types. They have values that are integer constant expressions.

Macro: __STDC_ENDIAN_LITTLE__

This macro represents little-endian storage.

Macro: __STDC_ENDIAN_BIG__

This macro represents big-endian storage.

Macro: __STDC_ENDIAN_NATIVE__

This macro equals __STDC_ENDIAN_LITTLE__ if integer types are stored in memory in little-endian format, and equals __STDC_ENDIAN_BIG__ if integer types are stored in memory in big-endian format.

The following functions manipulate the bits of unsigned integers. Each function family has functions for the types unsigned char, unsigned short, unsigned int, unsigned long int and unsigned long long int. In addition, there is a corresponding type-generic macro (not listed below), named the same as the functions but without any suffix such as ‘_uc’. The type-generic macro can only be used with an argument of an unsigned integer type with a width of 8, 16, 32 or 64 bits, or when using a compiler with support for __builtin_stdc_bit_ceil, etc., built-in functions such as GCC 14.1 or later any unsigned integer type those built-in functions support. In GCC 14.1 that includes support for unsigned __int128 and unsigned _BitInt(n) if supported by the target.

Function: unsigned int stdc_leading_zeros_uc (unsigned char x)

Function: unsigned int stdc_leading_zeros_us (unsigned short x)

Function: unsigned int stdc_leading_zeros_ui (unsigned int x)

Function: unsigned int stdc_leading_zeros_ul (unsigned long int x)

Function: unsigned int stdc_leading_zeros_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_leading_zeros functions count the number of leading (most significant) zero bits in x, starting from the most significant bit of the argument type. If x is zero, they return the width of x in bits.

Function: unsigned int stdc_leading_ones_uc (unsigned char x)

Function: unsigned int stdc_leading_ones_us (unsigned short x)

Function: unsigned int stdc_leading_ones_ui (unsigned int x)

Function: unsigned int stdc_leading_ones_ul (unsigned long int x)

Function: unsigned int stdc_leading_ones_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_leading_ones functions count the number of leading (most significant) one bits in x, starting from the most significant bit of the argument type.

Function: unsigned int stdc_trailing_zeros_uc (unsigned char x)

Function: unsigned int stdc_trailing_zeros_us (unsigned short x)

Function: unsigned int stdc_trailing_zeros_ui (unsigned int x)

Function: unsigned int stdc_trailing_zeros_ul (unsigned long int x)

Function: unsigned int stdc_trailing_zeros_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_trailing_zeros functions count the number of trailing (least significant) zero bits in x, starting from the least significant bit of the argument type. If x is zero, they return the width of x in bits.

Function: unsigned int stdc_trailing_ones_uc (unsigned char x)

Function: unsigned int stdc_trailing_ones_us (unsigned short x)

Function: unsigned int stdc_trailing_ones_ui (unsigned int x)

Function: unsigned int stdc_trailing_ones_ul (unsigned long int x)

Function: unsigned int stdc_trailing_ones_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_trailing_ones functions count the number of trailing (least significant) one bits in x, starting from the least significant bit of the argument type.

Function: unsigned int stdc_first_leading_zero_uc (unsigned char x)

Function: unsigned int stdc_first_leading_zero_us (unsigned short x)

Function: unsigned int stdc_first_leading_zero_ui (unsigned int x)

Function: unsigned int stdc_first_leading_zero_ul (unsigned long int x)

Function: unsigned int stdc_first_leading_zero_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_first_leading_zero functions return the position of the most significant zero bit in x, counting from the most significant bit of x as 1, or zero if there is no zero bit in x.

Function: unsigned int stdc_first_leading_one_uc (unsigned char x)

Function: unsigned int stdc_first_leading_one_us (unsigned short x)

Function: unsigned int stdc_first_leading_one_ui (unsigned int x)

Function: unsigned int stdc_first_leading_one_ul (unsigned long int x)

Function: unsigned int stdc_first_leading_one_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_first_leading_one functions return the position of the most significant one bit in x, counting from the most significant bit of x as 1, or zero if there is no one bit in x.

Function: unsigned int stdc_first_trailing_zero_uc (unsigned char x)

Function: unsigned int stdc_first_trailing_zero_us (unsigned short x)

Function: unsigned int stdc_first_trailing_zero_ui (unsigned int x)

Function: unsigned int stdc_first_trailing_zero_ul (unsigned long int x)

Function: unsigned int stdc_first_trailing_zero_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_first_trailing_zero functions return the position of the least significant zero bit in x, counting from the least significant bit of x as 1, or zero if there is no zero bit in x.

Function: unsigned int stdc_first_trailing_one_uc (unsigned char x)

Function: unsigned int stdc_first_trailing_one_us (unsigned short x)

Function: unsigned int stdc_first_trailing_one_ui (unsigned int x)

Function: unsigned int stdc_first_trailing_one_ul (unsigned long int x)

Function: unsigned int stdc_first_trailing_one_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_first_trailing_one functions return the position of the least significant one bit in x, counting from the least significant bit of x as 1, or zero if there is no one bit in x.

Function: unsigned int stdc_count_zeros_uc (unsigned char x)

Function: unsigned int stdc_count_zeros_us (unsigned short x)

Function: unsigned int stdc_count_zeros_ui (unsigned int x)

Function: unsigned int stdc_count_zeros_ul (unsigned long int x)

Function: unsigned int stdc_count_zeros_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_count_zeros functions count the number of zero bits in x.

Function: unsigned int stdc_count_ones_uc (unsigned char x)

Function: unsigned int stdc_count_ones_us (unsigned short x)

Function: unsigned int stdc_count_ones_ui (unsigned int x)

Function: unsigned int stdc_count_ones_ul (unsigned long int x)

Function: unsigned int stdc_count_ones_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_count_ones functions count the number of one bits in x.

Function: _Bool stdc_has_single_bit_uc (unsigned char x)

Function: _Bool stdc_has_single_bit_us (unsigned short x)

Function: _Bool stdc_has_single_bit_ui (unsigned int x)

Function: _Bool stdc_has_single_bit_ul (unsigned long int x)

Function: _Bool stdc_has_single_bit_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_has_single_bit functions return whether x has exactly one bit set to one.

Function: unsigned int stdc_bit_width_uc (unsigned char x)

Function: unsigned int stdc_bit_width_us (unsigned short x)

Function: unsigned int stdc_bit_width_ui (unsigned int x)

Function: unsigned int stdc_bit_width_ul (unsigned long int x)

Function: unsigned int stdc_bit_width_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_bit_width functions return the minimum number of bits needed to store x, not counting leading zero bits. If x is zero, they return zero.

Function: unsigned char stdc_bit_floor_uc (unsigned char x)

Function: unsigned short stdc_bit_floor_us (unsigned short x)

Function: unsigned int stdc_bit_floor_ui (unsigned int x)

Function: unsigned long int stdc_bit_floor_ul (unsigned long int x)

Function: unsigned long long int stdc_bit_floor_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_bit_floor functions return the largest integer power of two that is less than or equal to x. If x is zero, they return zero.

Function: unsigned char stdc_bit_ceil_uc (unsigned char x)

Function: unsigned short stdc_bit_ceil_us (unsigned short x)

Function: unsigned int stdc_bit_ceil_ui (unsigned int x)

Function: unsigned long int stdc_bit_ceil_ul (unsigned long int x)

Function: unsigned long long int stdc_bit_ceil_ull (unsigned long long int x)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The stdc_bit_ceil functions return the smallest integer power of two that is greater than or equal to x. If this cannot be represented in the return type, they return zero.