Tribblix: manual page: stdc_first_trailing

STDC_FIRST_TRAILING_ONE(3C) Standard C Library Functions

NAME

stdc_first_trailing_one, stdc_first_trailing_one_uc,
stdc_first_trailing_one_us, stdc_first_trailing_one_ui,
stdc_first_trailing_one_ul, stdc_first_trailing_one_ull - find index of
least significant one bit

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <stdbit.h>

unsigned int
stdc_first_trailing_one(generic_value_type value);

unsigned int
stdc_first_trailing_one_uc(unsigned char value);

unsigned int
stdc_first_trailing_one_us(unsigned short value);

unsigned int
stdc_first_trailing_one_ui(unsigned int value);

unsigned int
stdc_first_trailing_one_ul(unsigned long value);

unsigned int
stdc_first_trailing_one_ull(unsigned long long value);

DESCRIPTION

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

These functions are sometimes called "find first set" and signed
equivalents exist with ffs(3C).

The stdc_first_trailing_one() 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_one() family always return the
index of the first trailing one bit in value plus one. Otherwise, if
there are no one 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_one_uc(0x2b),
stdc_first_trailing_one_us(0x8000),
stdc_first_trailing_one_ui(UINT32_MAX),
stdc_first_trailing_one_ull(0xff60000000000000));
return (0);
}

When compiled and run, this produces:

$ ./a.out
0x1 0x10 0x1 0x36

INTERFACE STABILITY

Committed

MT-LEVEL
Async-Signal-Safe