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.
43namespace __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 */
53template<typename _Tp>
54inline unsigned int
55stdc_leading_zeros(_Tp __value)
56{
57 static_assert(std::__unsigned_integer<_Tp>);
58 return std::countl_zero(__value);
59}
60
61inline unsigned int
62stdc_leading_zeros_uc(unsigned char __value)
63{ return stdc_leading_zeros(__value); }
64
65inline unsigned int
66stdc_leading_zeros_us(unsigned short __value)
67{ return stdc_leading_zeros(__value); }
68
69inline unsigned int
70stdc_leading_zeros_ui(unsigned int __value)
71{ return stdc_leading_zeros(__value); }
72
73inline unsigned int
74stdc_leading_zeros_ul(unsigned long int __value)
75{ return stdc_leading_zeros(__value); }
76
77inline unsigned int
78stdc_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 */
88template<typename _Tp>
89inline unsigned int
90stdc_leading_ones(_Tp __value)
91{
92 static_assert(std::__unsigned_integer<_Tp>);
93 return std::countl_one(__value);
94}
95
96inline unsigned int
97stdc_leading_ones_uc(unsigned char __value)
98{ return stdc_leading_ones(__value); }
99
100inline unsigned int
101stdc_leading_ones_us(unsigned short __value)
102{ return stdc_leading_ones(__value); }
103
104inline unsigned int
105stdc_leading_ones_ui(unsigned int __value)
106{ return stdc_leading_ones(__value); }
107
108inline unsigned int
109stdc_leading_ones_ul(unsigned long int __value)
110{ return stdc_leading_ones(__value); }
111
112inline unsigned int
113stdc_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 */
123template<typename _Tp>
124inline unsigned int
125stdc_trailing_zeros(_Tp __value)
126{
127 static_assert(std::__unsigned_integer<_Tp>);
128 return std::countr_zero(__value);
129}
130
131inline unsigned int
132stdc_trailing_zeros_uc(unsigned char __value)
133{ return stdc_trailing_zeros(__value); }
134
135inline unsigned int
136stdc_trailing_zeros_us(unsigned short __value)
137{ return stdc_trailing_zeros(__value); }
138
139inline unsigned int
140stdc_trailing_zeros_ui(unsigned int __value)
141{ return stdc_trailing_zeros(__value); }
142
143inline unsigned int
144stdc_trailing_zeros_ul(unsigned long int __value)
145{ return stdc_trailing_zeros(__value); }
146
147inline unsigned int
148stdc_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 */
158template<typename _Tp>
159inline unsigned int
160stdc_trailing_ones(_Tp __value)
161{
162 static_assert(std::__unsigned_integer<_Tp>);
163 return std::countr_one(__value);
164}
165
166inline unsigned int
167stdc_trailing_ones_uc(unsigned char __value)
168{ return stdc_trailing_ones(__value); }
169
170inline unsigned int
171stdc_trailing_ones_us(unsigned short __value)
172{ return stdc_trailing_ones(__value); }
173
174inline unsigned int
175stdc_trailing_ones_ui(unsigned int __value)
176{ return stdc_trailing_ones(__value); }
177
178inline unsigned int
179stdc_trailing_ones_ul(unsigned long int __value)
180{ return stdc_trailing_ones(__value); }
181
182inline unsigned int
183stdc_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 */
195template<typename _Tp>
196inline unsigned int
197stdc_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
203inline unsigned int
204stdc_first_leading_zero_uc(unsigned char __value)
205{ return stdc_first_leading_zero(__value); }
206
207inline unsigned int
208stdc_first_leading_zero_us(unsigned short __value)
209{ return stdc_first_leading_zero(__value); }
210
211inline unsigned int
212stdc_first_leading_zero_ui(unsigned int __value)
213{ return stdc_first_leading_zero(__value); }
214
215inline unsigned int
216stdc_first_leading_zero_ul(unsigned long int __value)
217{ return stdc_first_leading_zero(__value); }
218
219inline unsigned int
220stdc_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 */
232template<typename _Tp>
233inline unsigned int
234stdc_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
240inline unsigned int
241stdc_first_leading_one_uc(unsigned char __value)
242{ return stdc_first_leading_one(__value); }
243
244inline unsigned int
245stdc_first_leading_one_us(unsigned short __value)
246{ return stdc_first_leading_one(__value); }
247
248inline unsigned int
249stdc_first_leading_one_ui(unsigned int __value)
250{ return stdc_first_leading_one(__value); }
251
252inline unsigned int
253stdc_first_leading_one_ul(unsigned long int __value)
254{ return stdc_first_leading_one(__value); }
255
256inline unsigned int
257stdc_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 */
269template<typename _Tp>
270inline unsigned int
271stdc_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
277inline unsigned int
278stdc_first_trailing_zero_uc(unsigned char __value)
279{ return stdc_first_trailing_zero(__value); }
280
281inline unsigned int
282stdc_first_trailing_zero_us(unsigned short __value)
283{ return stdc_first_trailing_zero(__value); }
284
285inline unsigned int
286stdc_first_trailing_zero_ui(unsigned int __value)
287{ return stdc_first_trailing_zero(__value); }
288
289inline unsigned int
290stdc_first_trailing_zero_ul(unsigned long int __value)
291{ return stdc_first_trailing_zero(__value); }
292
293inline unsigned int
294stdc_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 */
306template<typename _Tp>
307inline unsigned int
308stdc_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
314inline unsigned int
315stdc_first_trailing_one_uc(unsigned char __value)
316{ return stdc_first_trailing_one(__value); }
317
318inline unsigned int
319stdc_first_trailing_one_us(unsigned short __value)
320{ return stdc_first_trailing_one(__value); }
321
322inline unsigned int
323stdc_first_trailing_one_ui(unsigned int __value)
324{ return stdc_first_trailing_one(__value); }
325
326inline unsigned int
327stdc_first_trailing_one_ul(unsigned long int __value)
328{ return stdc_first_trailing_one(__value); }
329
330inline unsigned int
331stdc_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 */
342template<typename _Tp>
343inline unsigned int
344stdc_count_zeros(_Tp __value)
345{
346 static_assert(std::__unsigned_integer<_Tp>);
347 return std::popcount(_Tp(~__value));
348}
349
350inline unsigned int
351stdc_count_zeros_uc(unsigned char __value)
352{ return stdc_count_zeros(__value); }
353
354inline unsigned int
355stdc_count_zeros_us(unsigned short __value)
356{ return stdc_count_zeros(__value); }
357
358inline unsigned int
359stdc_count_zeros_ui(unsigned int __value)
360{ return stdc_count_zeros(__value); }
361
362inline unsigned int
363stdc_count_zeros_ul(unsigned long int __value)
364{ return stdc_count_zeros(__value); }
365
366inline unsigned int
367stdc_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 */
378template<typename _Tp>
379inline unsigned int
380stdc_count_ones(_Tp __value)
381{
382 static_assert(std::__unsigned_integer<_Tp>);
383 return std::popcount(__value);
384}
385
386inline unsigned int
387stdc_count_ones_uc(unsigned char __value)
388{ return stdc_count_ones(__value); }
389
390inline unsigned int
391stdc_count_ones_us(unsigned short __value)
392{ return stdc_count_ones(__value); }
393
394inline unsigned int
395stdc_count_ones_ui(unsigned int __value)
396{ return stdc_count_ones(__value); }
397
398inline unsigned int
399stdc_count_ones_ul(unsigned long int __value)
400{ return stdc_count_ones(__value); }
401
402inline unsigned int
403stdc_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 */
414template<typename _Tp>
415inline bool
416stdc_has_single_bit(_Tp __value)
417{
418 static_assert(std::__unsigned_integer<_Tp>);
419 return std::has_single_bit(__value);
420}
421
422inline bool
423stdc_has_single_bit_uc(unsigned char __value)
424{ return stdc_has_single_bit(__value); }
425
426inline bool
427stdc_has_single_bit_us(unsigned short __value)
428{ return stdc_has_single_bit(__value); }
429
430inline bool
431stdc_has_single_bit_ui(unsigned int __value)
432{ return stdc_has_single_bit(__value); }
433
434inline bool
435stdc_has_single_bit_ul(unsigned long int __value)
436{ return stdc_has_single_bit(__value); }
437
438inline bool
439stdc_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 */
450template<typename _Tp>
451inline unsigned int
452stdc_bit_width(_Tp __value)
453{
454 static_assert(std::__unsigned_integer<_Tp>);
455 return std::bit_width(__value);
456}
457
458inline unsigned int
459stdc_bit_width_uc(unsigned char __value)
460{ return stdc_bit_width(__value); }
461
462inline unsigned int
463stdc_bit_width_us(unsigned short __value)
464{ return stdc_bit_width(__value); }
465
466inline unsigned int
467stdc_bit_width_ui(unsigned int __value)
468{ return stdc_bit_width(__value); }
469
470inline unsigned int
471stdc_bit_width_ul(unsigned long int __value)
472{ return stdc_bit_width(__value); }
473
474inline unsigned int
475stdc_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 */
486template<typename _Tp>
487inline _Tp
488stdc_bit_floor(_Tp __value)
489{
490 static_assert(std::__unsigned_integer<_Tp>);
491 return std::bit_floor(__value);
492}
493
494inline unsigned char
495stdc_bit_floor_uc(unsigned char __value)
496{ return stdc_bit_floor(__value); }
497
498inline unsigned short
499stdc_bit_floor_us(unsigned short __value)
500{ return stdc_bit_floor(__value); }
501
502inline unsigned int
503stdc_bit_floor_ui(unsigned int __value)
504{ return stdc_bit_floor(__value); }
505
506inline unsigned long int
507stdc_bit_floor_ul(unsigned long int __value)
508{ return stdc_bit_floor(__value); }
509
510inline unsigned long long int
511stdc_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 */
525template<typename _Tp>
526inline _Tp
527stdc_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
534inline unsigned char
535stdc_bit_ceil_uc(unsigned char __value)
536{ return stdc_bit_ceil(__value); }
537
538inline unsigned short
539stdc_bit_ceil_us(unsigned short __value)
540{ return stdc_bit_ceil(__value); }
541
542inline unsigned int
543stdc_bit_ceil_ui(unsigned int __value)
544{ return stdc_bit_ceil(__value); }
545
546inline unsigned long int
547stdc_bit_ceil_ul(unsigned long int __value)
548{ return stdc_bit_ceil(__value); }
549
550inline unsigned long long int
551stdc_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_cxx
GNU extensions for public use.