manual/stdbit.texi

   1 @node Bit Manipulation, Date and Time, Arithmetic, Top
   2 @c %MENU% Bit manipulation
   3 @chapter Bit Manipulation
   4
   5 This chapter contains information about functions and macros for
   6 determining the endianness of integer types and manipulating the bits
   7 of unsigned integers.  These functions and macros are from ISO C23 and
   8 are declared in the header file @file{stdbit.h}.
   9
  10 The following macros describe the endianness of integer types.  They
  11 have values that are integer constant expressions.
  12
  13 @defmac __STDC_ENDIAN_LITTLE__
  14 This macro represents little-endian storage.
  15 @end defmac
  16
  17 @defmac __STDC_ENDIAN_BIG__
  18 This macro represents big-endian storage.
  19 @end defmac
  20
  21 @defmac __STDC_ENDIAN_NATIVE__
  22 This macro equals @code{__STDC_ENDIAN_LITTLE__} if integer types are
  23 stored in memory in little-endian format, and equals
  24 @code{__STDC_ENDIAN_BIG__} if integer types are stored in memory in
  25 big-endian format.
  26 @end defmac
  27
  28 The following functions manipulate the bits of unsigned integers.
  29 Each function family has functions for the types @code{unsigned char},
  30 @code{unsigned short}, @code{unsigned int}, @code{unsigned long int}
  31 and @code{unsigned long long int}.  In addition, there is a
  32 corresponding type-generic macro (not listed below), named the same as
  33 the functions but without any suffix such as @samp{_uc}.  The
  34 type-generic macro can only be used with an argument of an unsigned
  35 integer type with a width of 8, 16, 32 or 64 bits, or when using
  36 a compiler with support for
  37 @uref{https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html@code{__builtin_stdc_bit_ceil}},
  38 etc.@:, built-in functions such as GCC 14.1 or later
  39 any unsigned integer type those built-in functions support.
  40 In GCC 14.1 that includes support for @code{unsigned __int128} and
  41 @code{unsigned _BitInt(@var{n})} if supported by the target.
  42
  43 @deftypefun {unsigned int} stdc_leading_zeros_uc (unsigned char @var{x})
  44 @deftypefunx {unsigned int} stdc_leading_zeros_us (unsigned short @var{x})
  45 @deftypefunx {unsigned int} stdc_leading_zeros_ui (unsigned int @var{x})
  46 @deftypefunx {unsigned int} stdc_leading_zeros_ul (unsigned long int @var{x})
  47 @deftypefunx {unsigned int} stdc_leading_zeros_ull (unsigned long long int @var{x})
  48 @standards{C23, stdbit.h}
  49 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  50 The @code{stdc_leading_zeros} functions count the number of leading
  51 (most significant) zero bits in @var{x}, starting from the most
  52 significant bit of the argument type.  If @var{x} is zero, they return
  53 the width of @var{x} in bits.
  54 @end deftypefun
  55
  56 @deftypefun {unsigned int} stdc_leading_ones_uc (unsigned char @var{x})
  57 @deftypefunx {unsigned int} stdc_leading_ones_us (unsigned short @var{x})
  58 @deftypefunx {unsigned int} stdc_leading_ones_ui (unsigned int @var{x})
  59 @deftypefunx {unsigned int} stdc_leading_ones_ul (unsigned long int @var{x})
  60 @deftypefunx {unsigned int} stdc_leading_ones_ull (unsigned long long int @var{x})
  61 @standards{C23, stdbit.h}
  62 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  63 The @code{stdc_leading_ones} functions count the number of leading
  64 (most significant) one bits in @var{x}, starting from the most
  65 significant bit of the argument type.
  66 @end deftypefun
  67
  68 @deftypefun {unsigned int} stdc_trailing_zeros_uc (unsigned char @var{x})
  69 @deftypefunx {unsigned int} stdc_trailing_zeros_us (unsigned short @var{x})
  70 @deftypefunx {unsigned int} stdc_trailing_zeros_ui (unsigned int @var{x})
  71 @deftypefunx {unsigned int} stdc_trailing_zeros_ul (unsigned long int @var{x})
  72 @deftypefunx {unsigned int} stdc_trailing_zeros_ull (unsigned long long int @var{x})
  73 @standards{C23, stdbit.h}
  74 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  75 The @code{stdc_trailing_zeros} functions count the number of trailing
  76 (least significant) zero bits in @var{x}, starting from the least
  77 significant bit of the argument type.  If @var{x} is zero, they return
  78 the width of @var{x} in bits.
  79 @end deftypefun
  80
  81 @deftypefun {unsigned int} stdc_trailing_ones_uc (unsigned char @var{x})
  82 @deftypefunx {unsigned int} stdc_trailing_ones_us (unsigned short @var{x})
  83 @deftypefunx {unsigned int} stdc_trailing_ones_ui (unsigned int @var{x})
  84 @deftypefunx {unsigned int} stdc_trailing_ones_ul (unsigned long int @var{x})
  85 @deftypefunx {unsigned int} stdc_trailing_ones_ull (unsigned long long int @var{x})
  86 @standards{C23, stdbit.h}
  87 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  88 The @code{stdc_trailing_ones} functions count the number of trailing
  89 (least significant) one bits in @var{x}, starting from the least
  90 significant bit of the argument type.
  91 @end deftypefun
  92
  93 @deftypefun {unsigned int} stdc_first_leading_zero_uc (unsigned char @var{x})
  94 @deftypefunx {unsigned int} stdc_first_leading_zero_us (unsigned short @var{x})
  95 @deftypefunx {unsigned int} stdc_first_leading_zero_ui (unsigned int @var{x})
  96 @deftypefunx {unsigned int} stdc_first_leading_zero_ul (unsigned long int @var{x})
  97 @deftypefunx {unsigned int} stdc_first_leading_zero_ull (unsigned long long int @var{x})
  98 @standards{C23, stdbit.h}
  99 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 100 The @code{stdc_first_leading_zero} functions return the position of
 101 the most significant zero bit in @var{x}, counting from the most
 102 significant bit of @var{x} as 1, or zero if there is no zero bit in
 103 @var{x}.
 104 @end deftypefun
 105
 106 @deftypefun {unsigned int} stdc_first_leading_one_uc (unsigned char @var{x})
 107 @deftypefunx {unsigned int} stdc_first_leading_one_us (unsigned short @var{x})
 108 @deftypefunx {unsigned int} stdc_first_leading_one_ui (unsigned int @var{x})
 109 @deftypefunx {unsigned int} stdc_first_leading_one_ul (unsigned long int @var{x})
 110 @deftypefunx {unsigned int} stdc_first_leading_one_ull (unsigned long long int @var{x})
 111 @standards{C23, stdbit.h}
 112 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 113 The @code{stdc_first_leading_one} functions return the position of the
 114 most significant one bit in @var{x}, counting from the most
 115 significant bit of @var{x} as 1, or zero if there is no one bit in
 116 @var{x}.
 117 @end deftypefun
 118
 119 @deftypefun {unsigned int} stdc_first_trailing_zero_uc (unsigned char @var{x})
 120 @deftypefunx {unsigned int} stdc_first_trailing_zero_us (unsigned short @var{x})
 121 @deftypefunx {unsigned int} stdc_first_trailing_zero_ui (unsigned int @var{x})
 122 @deftypefunx {unsigned int} stdc_first_trailing_zero_ul (unsigned long int @var{x})
 123 @deftypefunx {unsigned int} stdc_first_trailing_zero_ull (unsigned long long int @var{x})
 124 @standards{C23, stdbit.h}
 125 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 126 The @code{stdc_first_trailing_zero} functions return the position of
 127 the least significant zero bit in @var{x}, counting from the least
 128 significant bit of @var{x} as 1, or zero if there is no zero bit in
 129 @var{x}.
 130 @end deftypefun
 131
 132 @deftypefun {unsigned int} stdc_first_trailing_one_uc (unsigned char @var{x})
 133 @deftypefunx {unsigned int} stdc_first_trailing_one_us (unsigned short @var{x})
 134 @deftypefunx {unsigned int} stdc_first_trailing_one_ui (unsigned int @var{x})
 135 @deftypefunx {unsigned int} stdc_first_trailing_one_ul (unsigned long int @var{x})
 136 @deftypefunx {unsigned int} stdc_first_trailing_one_ull (unsigned long long int @var{x})
 137 @standards{C23, stdbit.h}
 138 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 139 The @code{stdc_first_trailing_one} functions return the position of
 140 the least significant one bit in @var{x}, counting from the least
 141 significant bit of @var{x} as 1, or zero if there is no one bit in
 142 @var{x}.
 143 @end deftypefun
 144
 145 @deftypefun {unsigned int} stdc_count_zeros_uc (unsigned char @var{x})
 146 @deftypefunx {unsigned int} stdc_count_zeros_us (unsigned short @var{x})
 147 @deftypefunx {unsigned int} stdc_count_zeros_ui (unsigned int @var{x})
 148 @deftypefunx {unsigned int} stdc_count_zeros_ul (unsigned long int @var{x})
 149 @deftypefunx {unsigned int} stdc_count_zeros_ull (unsigned long long int @var{x})
 150 @standards{C23, stdbit.h}
 151 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 152 The @code{stdc_count_zeros} functions count the number of zero bits in
 153 @var{x}.
 154 @end deftypefun
 155
 156 @deftypefun {unsigned int} stdc_count_ones_uc (unsigned char @var{x})
 157 @deftypefunx {unsigned int} stdc_count_ones_us (unsigned short @var{x})
 158 @deftypefunx {unsigned int} stdc_count_ones_ui (unsigned int @var{x})
 159 @deftypefunx {unsigned int} stdc_count_ones_ul (unsigned long int @var{x})
 160 @deftypefunx {unsigned int} stdc_count_ones_ull (unsigned long long int @var{x})
 161 @standards{C23, stdbit.h}
 162 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 163 The @code{stdc_count_ones} functions count the number of one bits in
 164 @var{x}.
 165 @end deftypefun
 166
 167 @deftypefun {_Bool} stdc_has_single_bit_uc (unsigned char @var{x})
 168 @deftypefunx {_Bool} stdc_has_single_bit_us (unsigned short @var{x})
 169 @deftypefunx {_Bool} stdc_has_single_bit_ui (unsigned int @var{x})
 170 @deftypefunx {_Bool} stdc_has_single_bit_ul (unsigned long int @var{x})
 171 @deftypefunx {_Bool} stdc_has_single_bit_ull (unsigned long long int @var{x})
 172 @standards{C23, stdbit.h}
 173 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 174 The @code{stdc_has_single_bit} functions return whether @var{x} has
 175 exactly one bit set to one.
 176 @end deftypefun
 177
 178 @deftypefun {unsigned int} stdc_bit_width_uc (unsigned char @var{x})
 179 @deftypefunx {unsigned int} stdc_bit_width_us (unsigned short @var{x})
 180 @deftypefunx {unsigned int} stdc_bit_width_ui (unsigned int @var{x})
 181 @deftypefunx {unsigned int} stdc_bit_width_ul (unsigned long int @var{x})
 182 @deftypefunx {unsigned int} stdc_bit_width_ull (unsigned long long int @var{x})
 183 @standards{C23, stdbit.h}
 184 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 185 The @code{stdc_bit_width} functions return the minimum number of bits
 186 needed to store @var{x}, not counting leading zero bits.  If @var{x}
 187 is zero, they return zero.
 188 @end deftypefun
 189
 190 @deftypefun {unsigned char} stdc_bit_floor_uc (unsigned char @var{x})
 191 @deftypefunx {unsigned short} stdc_bit_floor_us (unsigned short @var{x})
 192 @deftypefunx {unsigned int} stdc_bit_floor_ui (unsigned int @var{x})
 193 @deftypefunx {unsigned long int} stdc_bit_floor_ul (unsigned long int @var{x})
 194 @deftypefunx {unsigned long long int} stdc_bit_floor_ull (unsigned long long int @var{x})
 195 @standards{C23, stdbit.h}
 196 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 197 The @code{stdc_bit_floor} functions return the largest integer power
 198 of two that is less than or equal to @var{x}.  If @var{x} is zero,
 199 they return zero.
 200 @end deftypefun
 201
 202 @deftypefun {unsigned char} stdc_bit_ceil_uc (unsigned char @var{x})
 203 @deftypefunx {unsigned short} stdc_bit_ceil_us (unsigned short @var{x})
 204 @deftypefunx {unsigned int} stdc_bit_ceil_ui (unsigned int @var{x})
 205 @deftypefunx {unsigned long int} stdc_bit_ceil_ul (unsigned long int @var{x})
 206 @deftypefunx {unsigned long long int} stdc_bit_ceil_ull (unsigned long long int @var{x})
 207 @standards{C23, stdbit.h}
 208 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 209 The @code{stdc_bit_ceil} functions return the smallest integer power
 210 of two that is greater than or equal to @var{x}.  If this cannot be
 211 represented in the return type, they return zero.
 212 @end deftypefun