[libc][stdbit] implement stdc_first_trailing_zero (C23) (#81526)

libc/config/linux/x86_64/entrypoints.txt

@@ -122,6 +122,11 @@ set(TARGET_LIBC_ENTRYPOINTS
     libc.src.stdbit.stdc_first_leading_one_ui
     libc.src.stdbit.stdc_first_leading_one_ul
     libc.src.stdbit.stdc_first_leading_one_ull
+    libc.src.stdbit.stdc_first_trailing_zero_uc
+    libc.src.stdbit.stdc_first_trailing_zero_us
+    libc.src.stdbit.stdc_first_trailing_zero_ui
+    libc.src.stdbit.stdc_first_trailing_zero_ul
+    libc.src.stdbit.stdc_first_trailing_zero_ull
 
     # stdlib.h entrypoints
     libc.src.stdlib.abs

libc/docs/stdbit.rst

@@ -61,11 +61,11 @@ stdc_first_leading_one_us    |check|
 stdc_first_leading_one_ui    |check|
 stdc_first_leading_one_ul    |check|
 stdc_first_leading_one_ull   |check|
-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
+stdc_first_trailing_zero_uc  |check|
+stdc_first_trailing_zero_us  |check|
+stdc_first_trailing_zero_ui  |check|
+stdc_first_trailing_zero_ul  |check|
+stdc_first_trailing_zero_ull |check|
 stdc_first_trailing_one_uc
 stdc_first_trailing_one_us
 stdc_first_trailing_one_ui
@@ -120,7 +120,7 @@ stdc_trailing_zeros        |check|
 stdc_trailing_ones         |check|
 stdc_first_leading_zero    |check|
 stdc_first_leading_one     |check|
-stdc_first_trailing_zero
+stdc_first_trailing_zero   |check|
 stdc_first_trailing_one
 stdc_count_zeros
 stdc_count_ones

libc/include/llvm-libc-macros/stdbit-macros.h

@@ -101,6 +101,21 @@ inline unsigned stdc_first_leading_one(unsigned long x) {
 inline unsigned stdc_first_leading_one(unsigned long long x) {
   return stdc_first_leading_one_ull(x);
 }
+inline unsigned stdc_first_trailing_zero(unsigned char x) {
+  return stdc_first_trailing_zero_uc(x);
+}
+inline unsigned stdc_first_trailing_zero(unsigned short x) {
+  return stdc_first_trailing_zero_us(x);
+}
+inline unsigned stdc_first_trailing_zero(unsigned x) {
+  return stdc_first_trailing_zero_ui(x);
+}
+inline unsigned stdc_first_trailing_zero(unsigned long x) {
+  return stdc_first_trailing_zero_ul(x);
+}
+inline unsigned stdc_first_trailing_zero(unsigned long long x) {
+  return stdc_first_trailing_zero_ull(x);
+}
 #else
 #define stdc_leading_zeros(x)                                                  \
   _Generic((x),                                                                \
@@ -144,6 +159,13 @@ inline unsigned stdc_first_leading_one(unsigned long long x) {
       unsigned: stdc_first_leading_one_ui,                                     \
       unsigned long: stdc_first_leading_one_ul,                                \
       unsigned long long: stdc_first_leading_one_ull)(x)
+#define stdc_first_trailing_zero(x)                                            \
+  _Generic((x),                                                                \
+      unsigned char: stdc_first_trailing_zero_uc,                              \
+      unsigned short: stdc_first_trailing_zero_us,                             \
+      unsigned: stdc_first_trailing_zero_ui,                                   \
+      unsigned long: stdc_first_trailing_zero_ul,                              \
+      unsigned long long: stdc_first_trailing_zero_ull)(x)
 #endif // __cplusplus
 
 #endif // __LLVM_LIBC_MACROS_STDBIT_MACROS_H

libc/spec/stdc.td

@@ -782,7 +782,8 @@ def StdC : StandardSpec<"stdc"> {
         Macro<"stdc_trailing_zeros">,
         Macro<"stdc_trailing_ones">,
         Macro<"stdc_first_leading_zero">,
-        Macro<"stdc_first_leading_one">
+        Macro<"stdc_first_leading_one">,
+        Macro<"stdc_first_trailing_zero">
       ], // Macros
       [], // Types
       [], // Enumerations
@@ -816,7 +817,12 @@ def StdC : StandardSpec<"stdc"> {
           FunctionSpec<"stdc_first_leading_one_us", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedShortType>]>,
           FunctionSpec<"stdc_first_leading_one_ui", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedIntType>]>,
           FunctionSpec<"stdc_first_leading_one_ul", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedLongType>]>,
-          FunctionSpec<"stdc_first_leading_one_ull", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedLongLongType>]>
+          FunctionSpec<"stdc_first_leading_one_ull", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedLongLongType>]>,
+          FunctionSpec<"stdc_first_trailing_zero_uc", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedCharType>]>,
+          FunctionSpec<"stdc_first_trailing_zero_us", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedShortType>]>,
+          FunctionSpec<"stdc_first_trailing_zero_ui", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedIntType>]>,
+          FunctionSpec<"stdc_first_trailing_zero_ul", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedLongType>]>,
+          FunctionSpec<"stdc_first_trailing_zero_ull", RetValSpec<UnsignedIntType>, [ArgSpec<UnsignedLongLongType>]>,
       ] // Functions
   >;
 

libc/src/__support/CPP/bit.h

@@ -236,6 +236,13 @@ template <typename T, typename = cpp::enable_if_t<cpp::is_unsigned_v<T>>>
   return first_leading_zero(static_cast<T>(~value));
 }
 
+template <typename T, typename = cpp::enable_if_t<cpp::is_unsigned_v<T>>>
+[[nodiscard]] LIBC_INLINE constexpr int first_trailing_zero(T value) {
+  return value == cpp::numeric_limits<T>::max()
+             ? 0
+             : countr_zero(static_cast<T>(~value)) + 1;
+}
+
 } // namespace LIBC_NAMESPACE::cpp
 
 #endif // LLVM_LIBC_SRC___SUPPORT_CPP_BIT_H

libc/src/stdbit/CMakeLists.txt

@@ -5,6 +5,7 @@ set(prefixes
   trailing_ones
   first_leading_zero
   first_leading_one
+  first_trailing_zero
 )
 set(suffixes c s i l ll)
 foreach(prefix IN LISTS prefixes)

libc/src/stdbit/stdc_first_trailing_zero_uc.cpp

@@ -0,0 +1,21 @@
+//===-- Implementation of stdc_first_trailing_zero_uc ---------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/stdbit/stdc_first_trailing_zero_uc.h"
+
+#include "src/__support/CPP/bit.h"
+#include "src/__support/common.h"
+
+namespace LIBC_NAMESPACE {
+
+LLVM_LIBC_FUNCTION(unsigned, stdc_first_trailing_zero_uc,
+                   (unsigned char value)) {
+  return static_cast<unsigned>(cpp::first_trailing_zero(value));
+}
+
+} // namespace LIBC_NAMESPACE

libc/src/stdbit/stdc_first_trailing_zero_uc.h

@@ -0,0 +1,18 @@
+//===-- Implementation header for stdc_first_trailing_zero_uc ---*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UC_H
+#define LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UC_H
+
+namespace LIBC_NAMESPACE {
+
+unsigned stdc_first_trailing_zero_uc(unsigned char value);
+
+} // namespace LIBC_NAMESPACE
+
+#endif // LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UC_H

libc/src/stdbit/stdc_first_trailing_zero_ui.cpp

@@ -0,0 +1,20 @@
+//===-- Implementation of stdc_first_trailing_zero_ui ---------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/stdbit/stdc_first_trailing_zero_ui.h"
+
+#include "src/__support/CPP/bit.h"
+#include "src/__support/common.h"
+
+namespace LIBC_NAMESPACE {
+
+LLVM_LIBC_FUNCTION(unsigned, stdc_first_trailing_zero_ui, (unsigned value)) {
+  return static_cast<unsigned>(cpp::first_trailing_zero(value));
+}
+
+} // namespace LIBC_NAMESPACE

libc/src/stdbit/stdc_first_trailing_zero_ui.h

@@ -0,0 +1,18 @@
+//===-- Implementation header for stdc_first_trailing_zero_ui ---*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UI_H
+#define LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UI_H
+
+namespace LIBC_NAMESPACE {
+
+unsigned stdc_first_trailing_zero_ui(unsigned value);
+
+} // namespace LIBC_NAMESPACE
+
+#endif // LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UI_H

libc/src/stdbit/stdc_first_trailing_zero_ul.cpp

@@ -0,0 +1,21 @@
+//===-- Implementation of stdc_first_trailing_zero_ul ---------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/stdbit/stdc_first_trailing_zero_ul.h"
+
+#include "src/__support/CPP/bit.h"
+#include "src/__support/common.h"
+
+namespace LIBC_NAMESPACE {
+
+LLVM_LIBC_FUNCTION(unsigned, stdc_first_trailing_zero_ul,
+                   (unsigned long value)) {
+  return static_cast<unsigned>(cpp::first_trailing_zero(value));
+}
+
+} // namespace LIBC_NAMESPACE

libc/src/stdbit/stdc_first_trailing_zero_ul.h

@@ -0,0 +1,18 @@
+//===-- Implementation header for stdc_first_trailing_zero_ul ---*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UL_H
+#define LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UL_H
+
+namespace LIBC_NAMESPACE {
+
+unsigned stdc_first_trailing_zero_ul(unsigned long value);
+
+} // namespace LIBC_NAMESPACE
+
+#endif // LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_UL_H

libc/src/stdbit/stdc_first_trailing_zero_ull.cpp

@@ -0,0 +1,21 @@
+//===-- Implementation of stdc_first_trailing_zero_ull --------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/stdbit/stdc_first_trailing_zero_ull.h"
+
+#include "src/__support/CPP/bit.h"
+#include "src/__support/common.h"
+
+namespace LIBC_NAMESPACE {
+
+LLVM_LIBC_FUNCTION(unsigned, stdc_first_trailing_zero_ull,
+                   (unsigned long long value)) {
+  return static_cast<unsigned>(cpp::first_trailing_zero(value));
+}
+
+} // namespace LIBC_NAMESPACE

libc/src/stdbit/stdc_first_trailing_zero_ull.h

@@ -0,0 +1,18 @@
+//===-- Implementation header for stdc_first_trailing_zero_ull --*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_ULL_H
+#define LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_ULL_H
+
+namespace LIBC_NAMESPACE {
+
+unsigned stdc_first_trailing_zero_ull(unsigned long long value);
+
+} // namespace LIBC_NAMESPACE
+
+#endif // LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_ULL_H

libc/src/stdbit/stdc_first_trailing_zero_us.cpp

@@ -0,0 +1,21 @@
+//===-- Implementation of stdc_first_trailing_zero_us ---------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/stdbit/stdc_first_trailing_zero_us.h"
+
+#include "src/__support/CPP/bit.h"
+#include "src/__support/common.h"
+
+namespace LIBC_NAMESPACE {
+
+LLVM_LIBC_FUNCTION(unsigned, stdc_first_trailing_zero_us,
+                   (unsigned short value)) {
+  return static_cast<unsigned>(cpp::first_trailing_zero(value));
+}
+
+} // namespace LIBC_NAMESPACE

libc/src/stdbit/stdc_first_trailing_zero_us.h

@@ -0,0 +1,18 @@
+//===-- Implementation header for stdc_first_trailing_zero_us ---*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_US_H
+#define LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_US_H
+
+namespace LIBC_NAMESPACE {
+
+unsigned stdc_first_trailing_zero_us(unsigned short value);
+
+} // namespace LIBC_NAMESPACE
+
+#endif // LLVM_LIBC_SRC_STDBIT_STDC_FIRST_TRAILING_ZERO_US_H

libc/test/include/stdbit_test.cpp

@@ -57,6 +57,13 @@ unsigned stdc_first_leading_one_ul(unsigned long) noexcept { return 0xFDU; }
 unsigned stdc_first_leading_one_ull(unsigned long long) noexcept {
   return 0xFFU;
 }
+unsigned stdc_first_trailing_zero_uc(unsigned char) noexcept { return 0x0AU; }
+unsigned stdc_first_trailing_zero_us(unsigned short) noexcept { return 0x0BU; }
+unsigned stdc_first_trailing_zero_ui(unsigned) noexcept { return 0x0CU; }
+unsigned stdc_first_trailing_zero_ul(unsigned long) noexcept { return 0x0DU; }
+unsigned stdc_first_trailing_zero_ull(unsigned long long) noexcept {
+  return 0x0FU;
+}
 }
 
 #include "include/llvm-libc-macros/stdbit-macros.h"
@@ -108,3 +115,11 @@ TEST(LlvmLibcStdbitTest, TypeGenericMacroFirstLeadingOne) {
   EXPECT_EQ(stdc_first_leading_one(0UL), 0xFDU);
   EXPECT_EQ(stdc_first_leading_one(0ULL), 0xFFU);
 }
+
+TEST(LlvmLibcStdbitTest, TypeGenericMacroFirstTrailingZero) {
+  EXPECT_EQ(stdc_first_trailing_zero(static_cast<unsigned char>(0U)), 0x0AU);
+  EXPECT_EQ(stdc_first_trailing_zero(static_cast<unsigned short>(0U)), 0x0BU);
+  EXPECT_EQ(stdc_first_trailing_zero(0U), 0x0CU);
+  EXPECT_EQ(stdc_first_trailing_zero(0UL), 0x0DU);
+  EXPECT_EQ(stdc_first_trailing_zero(0ULL), 0x0FU);
+}

libc/test/src/__support/CPP/bit_test.cpp

@@ -220,4 +220,10 @@ TYPED_TEST(LlvmLibcBitTest, FirstLeadingOne, UnsignedTypes) {
               cpp::numeric_limits<T>::digits - i);
 }
 
+TYPED_TEST(LlvmLibcBitTest, FirstTrailingZero, UnsignedTypes) {
+  EXPECT_EQ(first_trailing_zero<T>(cpp::numeric_limits<T>::max()), 0);
+  for (int i = 0U; i != cpp::numeric_limits<T>::digits; ++i)
+    EXPECT_EQ(first_trailing_zero<T>(~(T(1) << i)), i + 1);
+}
+
 } // namespace LIBC_NAMESPACE::cpp

libc/test/src/stdbit/CMakeLists.txt

@@ -7,6 +7,7 @@ set(prefixes
   trailing_ones
   first_leading_zero
   first_leading_one
+  first_trailing_zero
 )
 set(suffixes c s i l ll)
 foreach(prefix IN LISTS prefixes)

libc/test/src/stdbit/stdc_first_trailing_zero_uc_test.cpp

@@ -0,0 +1,20 @@
+//===-- Unittests for stdc_first_trailing_zero_uc -------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/__support/CPP/limits.h"
+#include "src/stdbit/stdc_first_trailing_zero_uc.h"
+#include "test/UnitTest/Test.h"
+
+TEST(LlvmLibcStdcFirstTrailingZeroUcTest, ALL) {
+  EXPECT_EQ(LIBC_NAMESPACE::stdc_first_trailing_zero_uc(UCHAR_MAX), 0U);
+}
+
+TEST(LlvmLibcStdcFirstTrailingZeroUcTest, ZeroHot) {
+  for (unsigned i = 0U; i != UCHAR_WIDTH; ++i)
+    EXPECT_EQ(LIBC_NAMESPACE::stdc_first_trailing_zero_uc(~(1U << i)), i + 1);
+}