libstdc++
stdbit.h
Go to the documentation of this file.
1 // C compatibility header <stdbit.h> -*- C++ -*-
2 
3 // Copyright The GNU Toolchain Authors.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /** @file include/stdbit.h
26  * This is a Standard C++ Library header.
27  */
28 
29 #ifndef _GLIBCXX_STDBIT_H
30 #define _GLIBCXX_STDBIT_H
31 
32 #if __cplusplus > 202302L
33 #include <bit>
34 
35 #define __STDC_VERSION_STDBIT_H__ 202311L
36 
37 #define __STDC_ENDIAN_BIG__ __ORDER_BIG_ENDIAN__
38 #define __STDC_ENDIAN_LITTLE__ __ORDER_LITTLE_ENDIAN__
39 #define __STDC_ENDIAN_NATIVE__ __BYTE_ORDER__
40 
41 #ifndef _GLIBCXX_DOXYGEN
42 // We define these in our own namespace, but let Doxygen think otherwise.
43 namespace __gnu_cxx _GLIBCXX_VISIBILITY(default)
44 {
45 #endif
46 
47 /** Count the number of leading zero bits
48  *
49  * @param __value An unsigned integer.
50  * @since C++26
51  * @{
52  */
53 template<typename _Tp>
54 inline unsigned int
55 stdc_leading_zeros(_Tp __value)
56 {
57  static_assert(std::__unsigned_integer<_Tp>);
58  return std::countl_zero(__value);
59 }
60 
61 inline unsigned int
62 stdc_leading_zeros_uc(unsigned char __value)
63 { return stdc_leading_zeros(__value); }
64 
65 inline unsigned int
66 stdc_leading_zeros_us(unsigned short __value)
67 { return stdc_leading_zeros(__value); }
68 
69 inline unsigned int
70 stdc_leading_zeros_ui(unsigned int __value)
71 { return stdc_leading_zeros(__value); }
72 
73 inline unsigned int
74 stdc_leading_zeros_ul(unsigned long int __value)
75 { return stdc_leading_zeros(__value); }
76 
77 inline unsigned int
78 stdc_leading_zeros_ull(unsigned long long int __value)
79 { return stdc_leading_zeros(__value); }
80 /// @}
81 
82 /** Count the number of leading one bits
83  *
84  * @param __value An unsigned integer.
85  * @since C++26
86  * @{
87  */
88 template<typename _Tp>
89 inline unsigned int
90 stdc_leading_ones(_Tp __value)
91 {
92  static_assert(std::__unsigned_integer<_Tp>);
93  return std::countl_one(__value);
94 }
95 
96 inline unsigned int
97 stdc_leading_ones_uc(unsigned char __value)
98 { return stdc_leading_ones(__value); }
99 
100 inline unsigned int
101 stdc_leading_ones_us(unsigned short __value)
102 { return stdc_leading_ones(__value); }
103 
104 inline unsigned int
105 stdc_leading_ones_ui(unsigned int __value)
106 { return stdc_leading_ones(__value); }
107 
108 inline unsigned int
109 stdc_leading_ones_ul(unsigned long int __value)
110 { return stdc_leading_ones(__value); }
111 
112 inline unsigned int
113 stdc_leading_ones_ull(unsigned long long int __value)
114 { return stdc_leading_ones(__value); }
115 /// @}
116 
117 /** Count the number of trailing zero bits
118  *
119  * @param __value An unsigned integer.
120  * @since C++26
121  * @{
122  */
123 template<typename _Tp>
124 inline unsigned int
125 stdc_trailing_zeros(_Tp __value)
126 {
127  static_assert(std::__unsigned_integer<_Tp>);
128  return std::countr_zero(__value);
129 }
130 
131 inline unsigned int
132 stdc_trailing_zeros_uc(unsigned char __value)
133 { return stdc_trailing_zeros(__value); }
134 
135 inline unsigned int
136 stdc_trailing_zeros_us(unsigned short __value)
137 { return stdc_trailing_zeros(__value); }
138 
139 inline unsigned int
140 stdc_trailing_zeros_ui(unsigned int __value)
141 { return stdc_trailing_zeros(__value); }
142 
143 inline unsigned int
144 stdc_trailing_zeros_ul(unsigned long int __value)
145 { return stdc_trailing_zeros(__value); }
146 
147 inline unsigned int
148 stdc_trailing_zeros_ull(unsigned long long int __value)
149 { return stdc_trailing_zeros(__value); }
150 /// @}
151 
152 /** Count the number of trailing one bits
153  *
154  * @param __value An unsigned integer.
155  * @since C++26
156  * @{
157  */
158 template<typename _Tp>
159 inline unsigned int
160 stdc_trailing_ones(_Tp __value)
161 {
162  static_assert(std::__unsigned_integer<_Tp>);
163  return std::countr_one(__value);
164 }
165 
166 inline unsigned int
167 stdc_trailing_ones_uc(unsigned char __value)
168 { return stdc_trailing_ones(__value); }
169 
170 inline unsigned int
171 stdc_trailing_ones_us(unsigned short __value)
172 { return stdc_trailing_ones(__value); }
173 
174 inline unsigned int
175 stdc_trailing_ones_ui(unsigned int __value)
176 { return stdc_trailing_ones(__value); }
177 
178 inline unsigned int
179 stdc_trailing_ones_ul(unsigned long int __value)
180 { return stdc_trailing_ones(__value); }
181 
182 inline unsigned int
183 stdc_trailing_ones_ull(unsigned long long int __value)
184 { return stdc_trailing_ones(__value); }
185 /// @}
186 
187 /** Find the leftmost (i.e. most significant) zero bit
188  *
189  * @param __value An unsigned integer.
190  * @return The one-based index of the first zero bit counting from the left,
191  * or zero if there are no zero bits.
192  * @since C++26
193  * @{
194  */
195 template<typename _Tp>
196 inline unsigned int
197 stdc_first_leading_zero(_Tp __value)
198 {
199  static_assert(std::__unsigned_integer<_Tp>);
200  return __value == _Tp(-1) ? 0 : 1 + std::countl_one(__value);
201 }
202 
203 inline unsigned int
204 stdc_first_leading_zero_uc(unsigned char __value)
205 { return stdc_first_leading_zero(__value); }
206 
207 inline unsigned int
208 stdc_first_leading_zero_us(unsigned short __value)
209 { return stdc_first_leading_zero(__value); }
210 
211 inline unsigned int
212 stdc_first_leading_zero_ui(unsigned int __value)
213 { return stdc_first_leading_zero(__value); }
214 
215 inline unsigned int
216 stdc_first_leading_zero_ul(unsigned long int __value)
217 { return stdc_first_leading_zero(__value); }
218 
219 inline unsigned int
220 stdc_first_leading_zero_ull(unsigned long long int __value)
221 { return stdc_first_leading_zero(__value); }
222 /// @}
223 
224 /** Find the leftmost (i.e. most significant) one bit
225  *
226  * @param __value An unsigned integer.
227  * @return The one-based index of the first one bit counting from the left,
228  * or zero if there are no one bits.
229  * @since C++26
230  * @{
231  */
232 template<typename _Tp>
233 inline unsigned int
234 stdc_first_leading_one(_Tp __value)
235 {
236  static_assert(std::__unsigned_integer<_Tp>);
237  return __value == 0 ? 0 : 1 + std::countl_zero(__value);
238 }
239 
240 inline unsigned int
241 stdc_first_leading_one_uc(unsigned char __value)
242 { return stdc_first_leading_one(__value); }
243 
244 inline unsigned int
245 stdc_first_leading_one_us(unsigned short __value)
246 { return stdc_first_leading_one(__value); }
247 
248 inline unsigned int
249 stdc_first_leading_one_ui(unsigned int __value)
250 { return stdc_first_leading_one(__value); }
251 
252 inline unsigned int
253 stdc_first_leading_one_ul(unsigned long int __value)
254 { return stdc_first_leading_one(__value); }
255 
256 inline unsigned int
257 stdc_first_leading_one_ull(unsigned long long int __value)
258 { return stdc_first_leading_one(__value); }
259 /// @}
260 
261 /** Find the rightmost (i.e. least significant) zero bit
262  *
263  * @param __value An unsigned integer.
264  * @return The one-based index of the first zero bit counting from the right,
265  * or zero if there are no zero bits.
266  * @since C++26
267  * @{
268  */
269 template<typename _Tp>
270 inline unsigned int
271 stdc_first_trailing_zero(_Tp __value)
272 {
273  static_assert(std::__unsigned_integer<_Tp>);
274  return __value == _Tp(-1) ? 0 : 1 + std::countr_one(__value);
275 }
276 
277 inline unsigned int
278 stdc_first_trailing_zero_uc(unsigned char __value)
279 { return stdc_first_trailing_zero(__value); }
280 
281 inline unsigned int
282 stdc_first_trailing_zero_us(unsigned short __value)
283 { return stdc_first_trailing_zero(__value); }
284 
285 inline unsigned int
286 stdc_first_trailing_zero_ui(unsigned int __value)
287 { return stdc_first_trailing_zero(__value); }
288 
289 inline unsigned int
290 stdc_first_trailing_zero_ul(unsigned long int __value)
291 { return stdc_first_trailing_zero(__value); }
292 
293 inline unsigned int
294 stdc_first_trailing_zero_ull(unsigned long long int __value)
295 { return stdc_first_trailing_zero(__value); }
296 /// @}
297 
298 /** Find the rightmost (i.e. least significant) one bit
299  *
300  * @param __value An unsigned integer.
301  * @return The one-based index of the first one bit counting from the right,
302  * or zero if there are no one bits.
303  * @since C++26
304  * @{
305  */
306 template<typename _Tp>
307 inline unsigned int
308 stdc_first_trailing_one(_Tp __value)
309 {
310  static_assert(std::__unsigned_integer<_Tp>);
311  return __value == 0 ? 0 : 1 + std::countr_zero(__value);
312 }
313 
314 inline unsigned int
315 stdc_first_trailing_one_uc(unsigned char __value)
316 { return stdc_first_trailing_one(__value); }
317 
318 inline unsigned int
319 stdc_first_trailing_one_us(unsigned short __value)
320 { return stdc_first_trailing_one(__value); }
321 
322 inline unsigned int
323 stdc_first_trailing_one_ui(unsigned int __value)
324 { return stdc_first_trailing_one(__value); }
325 
326 inline unsigned int
327 stdc_first_trailing_one_ul(unsigned long int __value)
328 { return stdc_first_trailing_one(__value); }
329 
330 inline unsigned int
331 stdc_first_trailing_one_ull(unsigned long long int __value)
332 { return stdc_first_trailing_one(__value); }
333 /// @}
334 
335 /** Count zeros
336  *
337  * @param __value An unsigned integer.
338  * @return The total number of zero bits in `__value`.
339  * @since C++26
340  * @{
341  */
342 template<typename _Tp>
343 inline unsigned int
344 stdc_count_zeros(_Tp __value)
345 {
346  static_assert(std::__unsigned_integer<_Tp>);
347  return std::popcount(_Tp(~__value));
348 }
349 
350 inline unsigned int
351 stdc_count_zeros_uc(unsigned char __value)
352 { return stdc_count_zeros(__value); }
353 
354 inline unsigned int
355 stdc_count_zeros_us(unsigned short __value)
356 { return stdc_count_zeros(__value); }
357 
358 inline unsigned int
359 stdc_count_zeros_ui(unsigned int __value)
360 { return stdc_count_zeros(__value); }
361 
362 inline unsigned int
363 stdc_count_zeros_ul(unsigned long int __value)
364 { return stdc_count_zeros(__value); }
365 
366 inline unsigned int
367 stdc_count_zeros_ull(unsigned long long int __value)
368 { return stdc_count_zeros(__value); }
369 /// @}
370 
371 /** Count ones
372  *
373  * @param __value An unsigned integer.
374  * @return The total number of one bits in `__value`.
375  * @since C++26
376  * @{
377  */
378 template<typename _Tp>
379 inline unsigned int
380 stdc_count_ones(_Tp __value)
381 {
382  static_assert(std::__unsigned_integer<_Tp>);
383  return std::popcount(__value);
384 }
385 
386 inline unsigned int
387 stdc_count_ones_uc(unsigned char __value)
388 { return stdc_count_ones(__value); }
389 
390 inline unsigned int
391 stdc_count_ones_us(unsigned short __value)
392 { return stdc_count_ones(__value); }
393 
394 inline unsigned int
395 stdc_count_ones_ui(unsigned int __value)
396 { return stdc_count_ones(__value); }
397 
398 inline unsigned int
399 stdc_count_ones_ul(unsigned long int __value)
400 { return stdc_count_ones(__value); }
401 
402 inline unsigned int
403 stdc_count_ones_ull(unsigned long long int __value)
404 { return stdc_count_ones(__value); }
405 /// @}
406 
407 /** Power of two check
408  *
409  * @param __value An unsigned integer.
410  * @return True if the value has a single bit set, false otherwise.
411  * @since C++26
412  * @{
413  */
414 template<typename _Tp>
415 inline bool
416 stdc_has_single_bit(_Tp __value)
417 {
418  static_assert(std::__unsigned_integer<_Tp>);
419  return std::has_single_bit(__value);
420 }
421 
422 inline bool
423 stdc_has_single_bit_uc(unsigned char __value)
424 { return stdc_has_single_bit(__value); }
425 
426 inline bool
427 stdc_has_single_bit_us(unsigned short __value)
428 { return stdc_has_single_bit(__value); }
429 
430 inline bool
431 stdc_has_single_bit_ui(unsigned int __value)
432 { return stdc_has_single_bit(__value); }
433 
434 inline bool
435 stdc_has_single_bit_ul(unsigned long int __value)
436 { return stdc_has_single_bit(__value); }
437 
438 inline bool
439 stdc_has_single_bit_ull(unsigned long long int __value)
440 { return stdc_has_single_bit(__value); }
441 /// @}
442 
443 /** Bit width
444  *
445  * @param __value An unsigned integer.
446  * @return The minimum number of bits needed to represent `__value`.
447  * @since C++26
448  * @{
449  */
450 template<typename _Tp>
451 inline unsigned int
452 stdc_bit_width(_Tp __value)
453 {
454  static_assert(std::__unsigned_integer<_Tp>);
455  return std::bit_width(__value);
456 }
457 
458 inline unsigned int
459 stdc_bit_width_uc(unsigned char __value)
460 { return stdc_bit_width(__value); }
461 
462 inline unsigned int
463 stdc_bit_width_us(unsigned short __value)
464 { return stdc_bit_width(__value); }
465 
466 inline unsigned int
467 stdc_bit_width_ui(unsigned int __value)
468 { return stdc_bit_width(__value); }
469 
470 inline unsigned int
471 stdc_bit_width_ul(unsigned long int __value)
472 { return stdc_bit_width(__value); }
473 
474 inline unsigned int
475 stdc_bit_width_ull(unsigned long long int __value)
476 { return stdc_bit_width(__value); }
477 /// @}
478 
479 /** Bit floor
480  *
481  * @param __value An unsigned integer.
482  * @return The largest power of two that is not greater than `__value`.
483  * @since C++26
484  * @{
485  */
486 template<typename _Tp>
487 inline _Tp
488 stdc_bit_floor(_Tp __value)
489 {
490  static_assert(std::__unsigned_integer<_Tp>);
491  return std::bit_floor(__value);
492 }
493 
494 inline unsigned char
495 stdc_bit_floor_uc(unsigned char __value)
496 { return stdc_bit_floor(__value); }
497 
498 inline unsigned short
499 stdc_bit_floor_us(unsigned short __value)
500 { return stdc_bit_floor(__value); }
501 
502 inline unsigned int
503 stdc_bit_floor_ui(unsigned int __value)
504 { return stdc_bit_floor(__value); }
505 
506 inline unsigned long int
507 stdc_bit_floor_ul(unsigned long int __value)
508 { return stdc_bit_floor(__value); }
509 
510 inline unsigned long long int
511 stdc_bit_floor_ull(unsigned long long int __value)
512 { return stdc_bit_floor(__value); }
513 /// @}
514 
515 /** Bit ceiling
516  *
517  * Unlike `std::bit_ceil`, this is defined to return zero for values which
518  * are not representable in the return type.
519  *
520  * @param __value An unsigned integer.
521  * @return The smallest power of two that is not less than `__value`.
522  * @since C++26
523  * @{
524  */
525 template<typename _Tp>
526 inline _Tp
527 stdc_bit_ceil(_Tp __value)
528 {
529  static_assert(std::__unsigned_integer<_Tp>);
530  constexpr _Tp __msb = _Tp(1) << (__gnu_cxx::__int_traits<_Tp>::__digits - 1);
531  return (__value & __msb) ? 0 : std::bit_ceil(__value);
532 }
533 
534 inline unsigned char
535 stdc_bit_ceil_uc(unsigned char __value)
536 { return stdc_bit_ceil(__value); }
537 
538 inline unsigned short
539 stdc_bit_ceil_us(unsigned short __value)
540 { return stdc_bit_ceil(__value); }
541 
542 inline unsigned int
543 stdc_bit_ceil_ui(unsigned int __value)
544 { return stdc_bit_ceil(__value); }
545 
546 inline unsigned long int
547 stdc_bit_ceil_ul(unsigned long int __value)
548 { return stdc_bit_ceil(__value); }
549 
550 inline unsigned long long int
551 stdc_bit_ceil_ull(unsigned long long int __value)
552 { return stdc_bit_ceil(__value); }
553 /// @}
554 
555 #ifndef _GLIBCXX_DOXYGEN
556 } // namespace __gnu_cxx
557 #define _GLIBCXX_STDBIT_FUNC(F) \
558  using __gnu_cxx::F ## _uc; \
559  using __gnu_cxx::F ## _us; \
560  using __gnu_cxx::F ## _ui; \
561  using __gnu_cxx::F ## _ul; \
562  using __gnu_cxx::F ## _ull; \
563  using __gnu_cxx::F
564 _GLIBCXX_STDBIT_FUNC(stdc_leading_zeros);
565 _GLIBCXX_STDBIT_FUNC(stdc_leading_ones);
566 _GLIBCXX_STDBIT_FUNC(stdc_trailing_zeros);
567 _GLIBCXX_STDBIT_FUNC(stdc_trailing_ones);
568 _GLIBCXX_STDBIT_FUNC(stdc_first_leading_zero);
569 _GLIBCXX_STDBIT_FUNC(stdc_first_leading_one);
570 _GLIBCXX_STDBIT_FUNC(stdc_first_trailing_zero);
571 _GLIBCXX_STDBIT_FUNC(stdc_first_trailing_one);
572 _GLIBCXX_STDBIT_FUNC(stdc_count_zeros);
573 _GLIBCXX_STDBIT_FUNC(stdc_count_ones);
574 _GLIBCXX_STDBIT_FUNC(stdc_has_single_bit);
575 _GLIBCXX_STDBIT_FUNC(stdc_bit_width);
576 _GLIBCXX_STDBIT_FUNC(stdc_bit_floor);
577 _GLIBCXX_STDBIT_FUNC(stdc_bit_ceil);
578 #undef _GLIBCXX_STDBIT_FUNC
579 #endif // !DOXYGEN
580 #endif // C++26
581 
582 #endif // _GLIBCXX_STDBIT_H
GNU extensions for public use.
__numeric_traits_integer< _Tp > __int_traits
Convenience alias for __numeric_traits<integer-type>.