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 C2X 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.
  36
  37 @deftypefun {unsigned int} stdc_leading_zeros_uc (unsigned char @var{x})
  38 @deftypefunx {unsigned int} stdc_leading_zeros_us (unsigned short @var{x})
  39 @deftypefunx {unsigned int} stdc_leading_zeros_ui (unsigned int @var{x})
  40 @deftypefunx {unsigned int} stdc_leading_zeros_ul (unsigned long int @var{x})
  41 @deftypefunx {unsigned int} stdc_leading_zeros_ull (unsigned long long int @var{x})
  42 @standards{C2X, stdbit.h}
  43 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  44 The @code{stdc_leading_zeros} functions count the number of leading
  45 (most significant) zero bits in @var{x}, starting from the most
  46 significant bit of the argument type.  If @var{x} is zero, they return
  47 the width of @var{x} in bits.
  48 @end deftypefun
  49
  50 @deftypefun {unsigned int} stdc_leading_ones_uc (unsigned char @var{x})
  51 @deftypefunx {unsigned int} stdc_leading_ones_us (unsigned short @var{x})
  52 @deftypefunx {unsigned int} stdc_leading_ones_ui (unsigned int @var{x})
  53 @deftypefunx {unsigned int} stdc_leading_ones_ul (unsigned long int @var{x})
  54 @deftypefunx {unsigned int} stdc_leading_ones_ull (unsigned long long int @var{x})
  55 @standards{C2X, stdbit.h}
  56 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  57 The @code{stdc_leading_ones} functions count the number of leading
  58 (most significant) one bits in @var{x}, starting from the most
  59 significant bit of the argument type.
  60 @end deftypefun
  61
  62 @deftypefun {unsigned int} stdc_trailing_zeros_uc (unsigned char @var{x})
  63 @deftypefunx {unsigned int} stdc_trailing_zeros_us (unsigned short @var{x})
  64 @deftypefunx {unsigned int} stdc_trailing_zeros_ui (unsigned int @var{x})
  65 @deftypefunx {unsigned int} stdc_trailing_zeros_ul (unsigned long int @var{x})
  66 @deftypefunx {unsigned int} stdc_trailing_zeros_ull (unsigned long long int @var{x})
  67 @standards{C2X, stdbit.h}
  68 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  69 The @code{stdc_trailing_zeros} functions count the number of trailing
  70 (least significant) zero bits in @var{x}, starting from the least
  71 significant bit of the argument type.  If @var{x} is zero, they return
  72 the width of @var{x} in bits.
  73 @end deftypefun
  74
  75 @deftypefun {unsigned int} stdc_trailing_ones_uc (unsigned char @var{x})
  76 @deftypefunx {unsigned int} stdc_trailing_ones_us (unsigned short @var{x})
  77 @deftypefunx {unsigned int} stdc_trailing_ones_ui (unsigned int @var{x})
  78 @deftypefunx {unsigned int} stdc_trailing_ones_ul (unsigned long int @var{x})
  79 @deftypefunx {unsigned int} stdc_trailing_ones_ull (unsigned long long int @var{x})
  80 @standards{C2X, stdbit.h}
  81 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  82 The @code{stdc_trailing_ones} functions count the number of trailing
  83 (least significant) one bits in @var{x}, starting from the least
  84 significant bit of the argument type.
  85 @end deftypefun
  86
  87 @deftypefun {unsigned int} stdc_first_leading_zero_uc (unsigned char @var{x})
  88 @deftypefunx {unsigned int} stdc_first_leading_zero_us (unsigned short @var{x})
  89 @deftypefunx {unsigned int} stdc_first_leading_zero_ui (unsigned int @var{x})
  90 @deftypefunx {unsigned int} stdc_first_leading_zero_ul (unsigned long int @var{x})
  91 @deftypefunx {unsigned int} stdc_first_leading_zero_ull (unsigned long long int @var{x})
  92 @standards{C2X, stdbit.h}
  93 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
  94 The @code{stdc_first_leading_zero} functions return the position of
  95 the most significant zero bit in @var{x}, counting from the most
  96 significant bit of @var{x} as 1, or zero if there is no zero bit in
  97 @var{x}.
  98 @end deftypefun
  99
 100 @deftypefun {unsigned int} stdc_first_leading_one_uc (unsigned char @var{x})
 101 @deftypefunx {unsigned int} stdc_first_leading_one_us (unsigned short @var{x})
 102 @deftypefunx {unsigned int} stdc_first_leading_one_ui (unsigned int @var{x})
 103 @deftypefunx {unsigned int} stdc_first_leading_one_ul (unsigned long int @var{x})
 104 @deftypefunx {unsigned int} stdc_first_leading_one_ull (unsigned long long int @var{x})
 105 @standards{C2X, stdbit.h}
 106 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 107 The @code{stdc_first_leading_one} functions return the position of the
 108 most significant one bit in @var{x}, counting from the most
 109 significant bit of @var{x} as 1, or zero if there is no one bit in
 110 @var{x}.
 111 @end deftypefun
 112
 113 @deftypefun {unsigned int} stdc_first_trailing_zero_uc (unsigned char @var{x})
 114 @deftypefunx {unsigned int} stdc_first_trailing_zero_us (unsigned short @var{x})
 115 @deftypefunx {unsigned int} stdc_first_trailing_zero_ui (unsigned int @var{x})
 116 @deftypefunx {unsigned int} stdc_first_trailing_zero_ul (unsigned long int @var{x})
 117 @deftypefunx {unsigned int} stdc_first_trailing_zero_ull (unsigned long long int @var{x})
 118 @standards{C2X, stdbit.h}
 119 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 120 The @code{stdc_first_trailing_zero} functions return the position of
 121 the least significant zero bit in @var{x}, counting from the least
 122 significant bit of @var{x} as 1, or zero if there is no zero bit in
 123 @var{x}.
 124 @end deftypefun
 125
 126 @deftypefun {unsigned int} stdc_first_trailing_one_uc (unsigned char @var{x})
 127 @deftypefunx {unsigned int} stdc_first_trailing_one_us (unsigned short @var{x})
 128 @deftypefunx {unsigned int} stdc_first_trailing_one_ui (unsigned int @var{x})
 129 @deftypefunx {unsigned int} stdc_first_trailing_one_ul (unsigned long int @var{x})
 130 @deftypefunx {unsigned int} stdc_first_trailing_one_ull (unsigned long long int @var{x})
 131 @standards{C2X, stdbit.h}
 132 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 133 The @code{stdc_first_trailing_one} functions return the position of
 134 the least significant one bit in @var{x}, counting from the least
 135 significant bit of @var{x} as 1, or zero if there is no one bit in
 136 @var{x}.
 137 @end deftypefun
 138
 139 @deftypefun {unsigned int} stdc_count_zeros_uc (unsigned char @var{x})
 140 @deftypefunx {unsigned int} stdc_count_zeros_us (unsigned short @var{x})
 141 @deftypefunx {unsigned int} stdc_count_zeros_ui (unsigned int @var{x})
 142 @deftypefunx {unsigned int} stdc_count_zeros_ul (unsigned long int @var{x})
 143 @deftypefunx {unsigned int} stdc_count_zeros_ull (unsigned long long int @var{x})
 144 @standards{C2X, stdbit.h}
 145 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 146 The @code{stdc_count_zeros} functions count the number of zero bits in
 147 @var{x}.
 148 @end deftypefun
 149
 150 @deftypefun {unsigned int} stdc_count_ones_uc (unsigned char @var{x})
 151 @deftypefunx {unsigned int} stdc_count_ones_us (unsigned short @var{x})
 152 @deftypefunx {unsigned int} stdc_count_ones_ui (unsigned int @var{x})
 153 @deftypefunx {unsigned int} stdc_count_ones_ul (unsigned long int @var{x})
 154 @deftypefunx {unsigned int} stdc_count_ones_ull (unsigned long long int @var{x})
 155 @standards{C2X, stdbit.h}
 156 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 157 The @code{stdc_count_ones} functions count the number of one bits in
 158 @var{x}.
 159 @end deftypefun
 160
 161 @deftypefun {_Bool} stdc_has_single_bit_uc (unsigned char @var{x})
 162 @deftypefunx {_Bool} stdc_has_single_bit_us (unsigned short @var{x})
 163 @deftypefunx {_Bool} stdc_has_single_bit_ui (unsigned int @var{x})
 164 @deftypefunx {_Bool} stdc_has_single_bit_ul (unsigned long int @var{x})
 165 @deftypefunx {_Bool} stdc_has_single_bit_ull (unsigned long long int @var{x})
 166 @standards{C2X, stdbit.h}
 167 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 168 The @code{stdc_has_single_bit} functions return whether @var{x} has
 169 exactly one bit set to one.
 170 @end deftypefun
 171
 172 @deftypefun {unsigned int} stdc_bit_width_uc (unsigned char @var{x})
 173 @deftypefunx {unsigned int} stdc_bit_width_us (unsigned short @var{x})
 174 @deftypefunx {unsigned int} stdc_bit_width_ui (unsigned int @var{x})
 175 @deftypefunx {unsigned int} stdc_bit_width_ul (unsigned long int @var{x})
 176 @deftypefunx {unsigned int} stdc_bit_width_ull (unsigned long long int @var{x})
 177 @standards{C2X, stdbit.h}
 178 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 179 The @code{stdc_bit_width} functions return the minimum number of bits
 180 needed to store @var{x}, not counting leading zero bits.  If @var{x}
 181 is zero, they return zero.
 182 @end deftypefun
 183
 184 @deftypefun {unsigned char} stdc_bit_floor_uc (unsigned char @var{x})
 185 @deftypefunx {unsigned short} stdc_bit_floor_us (unsigned short @var{x})
 186 @deftypefunx {unsigned int} stdc_bit_floor_ui (unsigned int @var{x})
 187 @deftypefunx {unsigned long int} stdc_bit_floor_ul (unsigned long int @var{x})
 188 @deftypefunx {unsigned long long int} stdc_bit_floor_ull (unsigned long long int @var{x})
 189 @standards{C2X, stdbit.h}
 190 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 191 The @code{stdc_bit_floor} functions return the largest integer power
 192 of two that is less than or equal to @var{x}.  If @var{x} is zero,
 193 they return zero.
 194 @end deftypefun
 195
 196 @deftypefun {unsigned char} stdc_bit_ceil_uc (unsigned char @var{x})
 197 @deftypefunx {unsigned short} stdc_bit_ceil_us (unsigned short @var{x})
 198 @deftypefunx {unsigned int} stdc_bit_ceil_ui (unsigned int @var{x})
 199 @deftypefunx {unsigned long int} stdc_bit_ceil_ul (unsigned long int @var{x})
 200 @deftypefunx {unsigned long long int} stdc_bit_ceil_ull (unsigned long long int @var{x})
 201 @standards{C2X, stdbit.h}
 202 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 203 The @code{stdc_bit_ceil} functions return the smallest integer power
 204 of two that is greater than or equal to @var{x}.  If this cannot be
 205 represented in the return type, they return zero.
 206 @end deftypefun