Tribblix: manual page: stdc_first_leading

STDC_FIRST_LEADING_ONE(3C) Standard C Library Functions

NAME

stdc_first_leading_one, stdc_first_leading_one_uc,
stdc_first_leading_one_us, stdc_first_leading_one_ui,
stdc_first_leading_one_ul, stdc_first_leading_one_ull - find index of
most significant one bit

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <stdbit.h>

unsigned int
stdc_first_leading_one(generic_value_type value);

unsigned int
stdc_first_leading_one_uc(unsigned char value);

unsigned int
stdc_first_leading_one_us(unsigned short value);

unsigned int
stdc_first_leading_one_ui(unsigned int value);

unsigned int
stdc_first_leading_one_ul(unsigned long value);

unsigned int
stdc_first_leading_one_ull(unsigned long long value);

DESCRIPTION

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

The stdc_first_leading_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.

The way that the index is constructed is not necessarily intuitive.
The C standard counts the most significant index starting with the most
significant bit as index value 0. Consider the 16-bit value 0x952b.
Generally we would consider the value `b' as bits 0 to 3 while the
value `9' as bits 12 to 15. Bit 15 is actually most significant index
0. Bit 14, most significant index 1. Bit 0, most significant index
15. This example, 0x952b, would return the value 1 (when using the
generic or unsigned short form) as the function is defined to return
this particular index plus one. Zero is reserved for when there is no
leading zero bit at all.

Note that if a non-zero unsigned integer is promoted, it will always be
filled with leading zeros which will cause the returned value to
increase as the first one bit is further away from the most significant
bit.

While this is similar in function to the fls(3C) functions which find
the last set value and identify the same bits, the fls(3C) functions
determine the index starting from the least significant bit, instead of
the most significant bit.

RETURN VALUES

The functions in the stdc_first_leading_one() family always return the
most significant index of the first leading 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 leading one (plus one).

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

int
main(void)
{
printf("0x%x 0x%x 0x%x 0x%x\n",
stdc_first_leading_one_uc(0x7f),
stdc_first_leading_one_us(0x0000),
stdc_first_leading_one_ui(UINT32_MAX),
stdc_first_leading_one_ull(0x000fedcba9abcdef));
return (0);
}

When compiled and run, this produces:

$ ./a.out
0x2 0x0 0x1 0xd

INTERFACE STABILITY

Committed

MT-LEVEL
Async-Signal-Safe