1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2024 Oxide Computer Company 13.\" 14.Dd October 27, 2024 15.Dt STDC_FIRST_LEADING_ONE 3C 16.Os 17.Sh NAME 18.Nm stdc_first_leading_one , 19.Nm stdc_first_leading_one_uc , 20.Nm stdc_first_leading_one_us , 21.Nm stdc_first_leading_one_ui , 22.Nm stdc_first_leading_one_ul , 23.Nm stdc_first_leading_one_ull 24.Nd find index of most significant one bit 25.Sh LIBRARY 26.Lb libc 27.Sh SYNOPSIS 28.In stdbit.h 29.Ft "unsigned int" 30.Fo stdc_first_leading_one 31.Fa "generic_value_type value" 32.Fc 33.Ft "unsigned int" 34.Fo stdc_first_leading_one_uc 35.Fa "unsigned char value" 36.Fc 37.Ft "unsigned int" 38.Fo stdc_first_leading_one_us 39.Fa "unsigned short value" 40.Fc 41.Ft "unsigned int" 42.Fo stdc_first_leading_one_ui 43.Fa "unsigned int value" 44.Fc 45.Ft "unsigned int" 46.Fo stdc_first_leading_one_ul 47.Fa "unsigned long value" 48.Fc 49.Ft "unsigned int" 50.Fo stdc_first_leading_one_ull 51.Fa "unsigned long long value" 52.Fc 53.Sh DESCRIPTION 54The 55.Fn stdc_first_leading_one 56family of functions returns the 1s-based index of the first one bit in 57.Fa value 58starting at the most significant bit. 59If there is no one bit in 60.Fa value 61then zero is returned. 62.Pp 63The 64.Fn stdc_first_leading_one 65function is generic and will operate on all 8, 16, 32, and 64-bit 66unsigned integers; however, it is only available in C23. 67The other functions all operate on a specific integer type, but 68otherwise behave the same and are available regardless of the C language 69version. 70.Pp 71The way that the index is constructed is not necessarily intuitive. 72The C standard counts the most significant index starting with the most 73significant bit as index value 0. 74Consider the 16-bit value 0x952b. 75Generally we would consider the value 76.Sq b 77as bits 0 to 3 while the value 78.Sq 9 79as bits 12 to 15. 80Bit 15 is actually most significant index 0. 81Bit 14, most significant index 1. 82Bit 0, most significant index 15. 83This example, 0x952b, would return the value 1 84.Po 85when using the generic or 86.Vt unsigned short 87form 88.Pc 89as the function is defined to return this particular index 90.Em plus one . 91Zero is reserved for when there is no leading zero bit at all. 92.Pp 93Note that if a non-zero unsigned integer is promoted, it will always be filled 94with leading zeros which will cause the returned value to increase as 95the first one bit is further away from the most significant bit. 96.Pp 97While this is similar in function to the 98.Xr fls 3C 99functions which find the last set value and identify the same bits, the 100.Xr fls 3C 101functions determine the index starting from the least significant bit, 102instead of the most significant bit. 103.Sh RETURN VALUES 104The functions in the 105.Fn stdc_first_leading_one 106family always return the most significant index of the first leading 107one bit in 108.Fa value , 109.Em plus one . 110Otherwise, if there are no one bits in 111.Fa value , 1120 will be returned. 113These functions cannot fail. 114.Sh EXAMPLES 115.Sy Example 1 116Printing the index of the first leading one 117.Pq plus one . 118.Bd -literal 119#include <stdbit.h> 120#include <stdio.h> 121#include <limits.h> 122 123int 124main(void) 125{ 126 printf("0x%x 0x%x 0x%x 0x%x\en", 127 stdc_first_leading_one_uc(0x7f), 128 stdc_first_leading_one_us(0x0000), 129 stdc_first_leading_one_ui(UINT32_MAX), 130 stdc_first_leading_one_ull(0x000fedcba9abcdef)); 131 return (0); 132} 133.Ed 134.Pp 135When compiled and run, this produces: 136.Bd -literal -offset indent 137$ ./a.out 1380x2 0x0 0x1 0xd 139.Ed 140.Sh INTERFACE STABILITY 141.Sy Committed 142.Sh MT-LEVEL 143.Sy Async-Signal-Safe 144.Sh SEE ALSO 145.Xr fls 3C , 146.Xr stdc_bit_ceil 3C , 147.Xr stdc_bit_floor 3C , 148.Xr stdc_bit_width 3C , 149.Xr stdc_count_ones 3C , 150.Xr stdc_count_zeros 3C , 151.Xr stdc_first_leading_zero 3C , 152.Xr stdc_first_trailing_one 3C , 153.Xr stdc_first_trailing_zero 3C , 154.Xr stdc_has_single_bit 3C , 155.Xr stdc_leading_ones 3C , 156.Xr stdc_leading_zeros 3C , 157.Xr stdc_trailing_ones 3C , 158.Xr stdc_trailing_zeros 3C , 159.Xr stdbit.h 3HEAD 160