xref: /illumos-gate/usr/src/man/man3c/stdc_first_leading_zero.3c (revision aaceae985c2e78cadef76bf0b7b50ed887ccb3a6)
1*aaceae98SRobert Mustacchi.\"
2*aaceae98SRobert Mustacchi.\" This file and its contents are supplied under the terms of the
3*aaceae98SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0.
4*aaceae98SRobert Mustacchi.\" You may only use this file in accordance with the terms of version
5*aaceae98SRobert Mustacchi.\" 1.0 of the CDDL.
6*aaceae98SRobert Mustacchi.\"
7*aaceae98SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this
8*aaceae98SRobert Mustacchi.\" source.  A copy of the CDDL is also available via the Internet at
9*aaceae98SRobert Mustacchi.\" http://www.illumos.org/license/CDDL.
10*aaceae98SRobert Mustacchi.\"
11*aaceae98SRobert Mustacchi.\"
12*aaceae98SRobert Mustacchi.\" Copyright 2024 Oxide Computer Company
13*aaceae98SRobert Mustacchi.\"
14*aaceae98SRobert Mustacchi.Dd October 27, 2024
15*aaceae98SRobert Mustacchi.Dt STDC_FIRST_LEADING_ZERO 3C
16*aaceae98SRobert Mustacchi.Os
17*aaceae98SRobert Mustacchi.Sh NAME
18*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero ,
19*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_uc ,
20*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_us ,
21*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_ui ,
22*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_ul ,
23*aaceae98SRobert Mustacchi.Nm stdc_first_leading_zero_ull
24*aaceae98SRobert Mustacchi.Nd find index of most significant zero bit
25*aaceae98SRobert Mustacchi.Sh LIBRARY
26*aaceae98SRobert Mustacchi.Lb libc
27*aaceae98SRobert Mustacchi.Sh SYNOPSIS
28*aaceae98SRobert Mustacchi.In stdbit.h
29*aaceae98SRobert Mustacchi.Ft "unsigned int"
30*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero
31*aaceae98SRobert Mustacchi.Fa "generic_value_type value"
32*aaceae98SRobert Mustacchi.Fc
33*aaceae98SRobert Mustacchi.Ft "unsigned int"
34*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_uc
35*aaceae98SRobert Mustacchi.Fa "unsigned char value"
36*aaceae98SRobert Mustacchi.Fc
37*aaceae98SRobert Mustacchi.Ft "unsigned int"
38*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_us
39*aaceae98SRobert Mustacchi.Fa "unsigned short value"
40*aaceae98SRobert Mustacchi.Fc
41*aaceae98SRobert Mustacchi.Ft "unsigned int"
42*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_ui
43*aaceae98SRobert Mustacchi.Fa "unsigned int value"
44*aaceae98SRobert Mustacchi.Fc
45*aaceae98SRobert Mustacchi.Ft "unsigned int"
46*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_ul
47*aaceae98SRobert Mustacchi.Fa "unsigned long value"
48*aaceae98SRobert Mustacchi.Fc
49*aaceae98SRobert Mustacchi.Ft "unsigned int"
50*aaceae98SRobert Mustacchi.Fo stdc_first_leading_zero_ull
51*aaceae98SRobert Mustacchi.Fa "unsigned long long value"
52*aaceae98SRobert Mustacchi.Fc
53*aaceae98SRobert Mustacchi.Sh DESCRIPTION
54*aaceae98SRobert MustacchiThe
55*aaceae98SRobert Mustacchi.Fn stdc_first_leading_zero
56*aaceae98SRobert Mustacchifamily of functions returns the 1s-based index of the first zero bit in
57*aaceae98SRobert Mustacchi.Fa value
58*aaceae98SRobert Mustacchistarting at the most significant bit.
59*aaceae98SRobert MustacchiIf there is no zero bit in
60*aaceae98SRobert Mustacchi.Fa value
61*aaceae98SRobert Mustacchithen zero is returned.
62*aaceae98SRobert Mustacchi.Pp
63*aaceae98SRobert MustacchiThe
64*aaceae98SRobert Mustacchi.Fn stdc_first_leading_zero
65*aaceae98SRobert Mustacchifunction is generic and will operate on all 8, 16, 32, and 64-bit
66*aaceae98SRobert Mustacchiunsigned integers; however, it is only available in C23.
67*aaceae98SRobert MustacchiThe other functions all operate on a specific integer type, but
68*aaceae98SRobert Mustacchiotherwise behave the same and are available regardless of the C language
69*aaceae98SRobert Mustacchiversion.
70*aaceae98SRobert Mustacchi.Pp
71*aaceae98SRobert MustacchiThe way that the index is constructed is not necessarily intuitive.
72*aaceae98SRobert MustacchiThe C standard counts the most significant index starting with the most
73*aaceae98SRobert Mustacchisignificant bit as index value 0.
74*aaceae98SRobert MustacchiConsider the 16-bit value 0x952b.
75*aaceae98SRobert MustacchiGenerally we would consider the value
76*aaceae98SRobert Mustacchi.Sq b
77*aaceae98SRobert Mustacchias bits 0 to 3 while the value
78*aaceae98SRobert Mustacchi.Sq 9
79*aaceae98SRobert Mustacchias bits 12 to 15.
80*aaceae98SRobert MustacchiBit 15 is actually most significant index 0.
81*aaceae98SRobert MustacchiBit 14, most significant index 1.
82*aaceae98SRobert MustacchiBit 0, most significant index 15.
83*aaceae98SRobert MustacchiThis example, 0x952b, would return the value 2
84*aaceae98SRobert Mustacchi.Po
85*aaceae98SRobert Mustacchiwhen using the generic or
86*aaceae98SRobert Mustacchi.Vt unsigned short
87*aaceae98SRobert Mustacchiform
88*aaceae98SRobert Mustacchi.Pc
89*aaceae98SRobert Mustacchias the function is defined to return this particular index
90*aaceae98SRobert Mustacchi.Em plus one .
91*aaceae98SRobert MustacchiZero is reserved for when there is no leading zero bit at all.
92*aaceae98SRobert Mustacchi.Pp
93*aaceae98SRobert MustacchiNote that if an unsigned integer is promoted, it will always be filled
94*aaceae98SRobert Mustacchiwith leading zeros which will cause the function to return 1.
95*aaceae98SRobert Mustacchi.Sh RETURN VALUES
96*aaceae98SRobert MustacchiThe functions in the
97*aaceae98SRobert Mustacchi.Fn stdc_first_leading_zero
98*aaceae98SRobert Mustacchifamily always return the most significant index of the first leading
99*aaceae98SRobert Mustacchizero bit in
100*aaceae98SRobert Mustacchi.Fa value ,
101*aaceae98SRobert Mustacchi.Em plus one .
102*aaceae98SRobert MustacchiOtherwise, if there are no zero bits in
103*aaceae98SRobert Mustacchi.Fa value ,
104*aaceae98SRobert Mustacchi0 will be returned.
105*aaceae98SRobert MustacchiThese functions cannot fail.
106*aaceae98SRobert Mustacchi.Sh EXAMPLES
107*aaceae98SRobert Mustacchi.Sy Example 1
108*aaceae98SRobert MustacchiPrinting the index of the first leading zero
109*aaceae98SRobert Mustacchi.Pq plus one .
110*aaceae98SRobert Mustacchi.Bd -literal
111*aaceae98SRobert Mustacchi#include <stdbit.h>
112*aaceae98SRobert Mustacchi#include <stdio.h>
113*aaceae98SRobert Mustacchi#include <limits.h>
114*aaceae98SRobert Mustacchi
115*aaceae98SRobert Mustacchiint
116*aaceae98SRobert Mustacchimain(void)
117*aaceae98SRobert Mustacchi{
118*aaceae98SRobert Mustacchi	printf("0x%x 0x%x 0x%x 0x%x\en",
119*aaceae98SRobert Mustacchi	    stdc_first_leading_zero_uc(0xf0),
120*aaceae98SRobert Mustacchi	    stdc_first_leading_zero_us(0xfabc),
121*aaceae98SRobert Mustacchi	    stdc_first_leading_zero_ui(UINT32_MAX),
122*aaceae98SRobert Mustacchi	    stdc_first_leading_zero_ull(0));
123*aaceae98SRobert Mustacchi	return (0);
124*aaceae98SRobert Mustacchi}
125*aaceae98SRobert Mustacchi.Ed
126*aaceae98SRobert Mustacchi.Pp
127*aaceae98SRobert MustacchiWhen compiled and run, this produces:
128*aaceae98SRobert Mustacchi.Bd -literal -offset indent
129*aaceae98SRobert Mustacchi$ ./a.out
130*aaceae98SRobert Mustacchi0x5 0x6 0x0 0x1
131*aaceae98SRobert Mustacchi.Ed
132*aaceae98SRobert Mustacchi.Sh INTERFACE STABILITY
133*aaceae98SRobert Mustacchi.Sy Committed
134*aaceae98SRobert Mustacchi.Sh MT-LEVEL
135*aaceae98SRobert Mustacchi.Sy Async-Signal-Safe
136*aaceae98SRobert Mustacchi.Sh SEE ALSO
137*aaceae98SRobert Mustacchi.Xr stdc_bit_ceil 3C ,
138*aaceae98SRobert Mustacchi.Xr stdc_bit_floor 3C ,
139*aaceae98SRobert Mustacchi.Xr stdc_bit_width 3C ,
140*aaceae98SRobert Mustacchi.Xr stdc_count_ones 3C ,
141*aaceae98SRobert Mustacchi.Xr stdc_count_zeros 3C ,
142*aaceae98SRobert Mustacchi.Xr stdc_first_leading_one 3C ,
143*aaceae98SRobert Mustacchi.Xr stdc_first_trailing_one 3C ,
144*aaceae98SRobert Mustacchi.Xr stdc_first_trailing_zero 3C ,
145*aaceae98SRobert Mustacchi.Xr stdc_has_single_bit 3C ,
146*aaceae98SRobert Mustacchi.Xr stdc_leading_ones 3C ,
147*aaceae98SRobert Mustacchi.Xr stdc_leading_zeros 3C ,
148*aaceae98SRobert Mustacchi.Xr stdc_trailing_ones 3C ,
149*aaceae98SRobert Mustacchi.Xr stdc_trailing_zeros 3C ,
150*aaceae98SRobert Mustacchi.Xr stdbit.h 3HEAD
151