Tribblix: manual page: stdc_first_trailing

STDC_FIRST_TRAILING_ZERO(3C) Standard C Library Functions

NAME

stdc_first_trailing_zero, stdc_first_trailing_zero_uc,
stdc_first_trailing_zero_us, stdc_first_trailing_zero_ui,
stdc_first_trailing_zero_ul, stdc_first_trailing_zero_ull - find index
of least significant zero bit

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <stdbit.h>

unsigned int
stdc_first_trailing_zero(generic_value_type value);

unsigned int
stdc_first_trailing_zero_uc(unsigned char value);

unsigned int
stdc_first_trailing_zero_us(unsigned short value);

unsigned int
stdc_first_trailing_zero_ui(unsigned int value);

unsigned int
stdc_first_trailing_zero_ul(unsigned long value);

unsigned int
stdc_first_trailing_zero_ull(unsigned long long value);

DESCRIPTION

The stdc_first_trailing_zero() family of functions returns the 1s-based
index of the first zero bit in value starting at the least significant
bit. If there is no zero bit in value then zero is returned.

The stdc_first_trailing_zero() function is generic and will operate on
all 8, 16, 32, and 64-bit unsigned integers; however, it is only
available in C23. The other functions all operate on a specific
integer type, but otherwise behave the same and are available
regardless of the C language version.

RETURN VALUES

The functions in the stdc_first_trailing_zero() family always return
the index of the first trailing zero bit in value plus one. Otherwise,
if there are no zero bits in value, 0 will be returned. These
functions cannot fail.

EXAMPLES

Example 1 Printing the index of the first trailing zero.

#include <stdbit.h>
#include <stdio.h>
#include <limits.h>

int
main(void)
{
printf("0x%x 0x%x 0x%x 0x%x\n",
stdc_first_trailing_zero_uc(0xef),
stdc_first_trailing_zero_us(0x07ff),
stdc_first_trailing_zero_ui(UINT32_MAX),
stdc_first_trailing_zero_ull(0x7777777777777777));
return (0);
}

When compiled and run, this produces:

$ ./a.out
0x5 0xc 0x0 0x4

INTERFACE STABILITY

Committed

MT-LEVEL
Async-Signal-Safe