[libcxx-commits] [libcxx] 3a8894d - [libc++][numeric] Marked saturation artithmetic functions as `[[nodiscard]]` (#166898)

[via libcxx-commits]

Author: Hristo Hristov
Date: 2025-11-09T05:39:36+02:00
New Revision: 3a8894d7aff1fa4bd2502827c31dad87b5765f4d

URL: https://github.com/llvm/llvm-project/commit/3a8894d7aff1fa4bd2502827c31dad87b5765f4d
DIFF: https://github.com/llvm/llvm-project/commit/3a8894d7aff1fa4bd2502827c31dad87b5765f4d.diff

LOG: [libc++][numeric] Marked saturation artithmetic functions as `[[nodiscard]]` (#166898)

...according to Coding Guidelines: *`[[nodiscard]]` should be applied to
functions where discarding the return value is most likely a correctness
issue.*

# References
-
https://libcxx.llvm.org/CodingGuidelines.html#apply-nodiscard-where-relevant
-
https://github.com/llvm/llvm-project/pull/166524#issuecomment-3495567876

Co-authored-by: Hristo Hristov <zingam at outlook.com>

Added: 
    libcxx/test/libcxx/numerics/nodiscard.verify.cpp

Modified: 
    libcxx/include/__numeric/saturation_arithmetic.h

Removed: 
    libcxx/test/std/numerics/bit/bitops.rot/nodiscard.verify.cpp


################################################################################
diff  --git a/libcxx/include/__numeric/saturation_arithmetic.h b/libcxx/include/__numeric/saturation_arithmetic.h
index 7a7410b5dea08..4491bab2b1479 100644
--- a/libcxx/include/__numeric/saturation_arithmetic.h
+++ b/libcxx/include/__numeric/saturation_arithmetic.h
@@ -121,27 +121,27 @@ _LIBCPP_HIDE_FROM_ABI constexpr _Rp __saturate_cast(_Tp __x) noexcept {
 #if _LIBCPP_STD_VER >= 26
 
 template <__signed_or_unsigned_integer _Tp>
-_LIBCPP_HIDE_FROM_ABI constexpr _Tp add_sat(_Tp __x, _Tp __y) noexcept {
+[[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr _Tp add_sat(_Tp __x, _Tp __y) noexcept {
   return std::__add_sat(__x, __y);
 }
 
 template <__signed_or_unsigned_integer _Tp>
-_LIBCPP_HIDE_FROM_ABI constexpr _Tp sub_sat(_Tp __x, _Tp __y) noexcept {
+[[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr _Tp sub_sat(_Tp __x, _Tp __y) noexcept {
   return std::__sub_sat(__x, __y);
 }
 
 template <__signed_or_unsigned_integer _Tp>
-_LIBCPP_HIDE_FROM_ABI constexpr _Tp mul_sat(_Tp __x, _Tp __y) noexcept {
+[[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr _Tp mul_sat(_Tp __x, _Tp __y) noexcept {
   return std::__mul_sat(__x, __y);
 }
 
 template <__signed_or_unsigned_integer _Tp>
-_LIBCPP_HIDE_FROM_ABI constexpr _Tp div_sat(_Tp __x, _Tp __y) noexcept {
+[[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr _Tp div_sat(_Tp __x, _Tp __y) noexcept {
   return std::__div_sat(__x, __y);
 }
 
 template <__signed_or_unsigned_integer _Rp, __signed_or_unsigned_integer _Tp>
-_LIBCPP_HIDE_FROM_ABI constexpr _Rp saturate_cast(_Tp __x) noexcept {
+[[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr _Rp saturate_cast(_Tp __x) noexcept {
   return std::__saturate_cast<_Rp>(__x);
 }
 

diff  --git a/libcxx/test/libcxx/numerics/nodiscard.verify.cpp b/libcxx/test/libcxx/numerics/nodiscard.verify.cpp
new file mode 100644
index 0000000000000..10da62feca7c0
--- /dev/null
+++ b/libcxx/test/libcxx/numerics/nodiscard.verify.cpp
@@ -0,0 +1,35 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+// REQUIRES: std-at-least-c++20
+
+// <numeric>
+
+// Check that functions are marked [[nodiscard]]
+
+#include <bit>
+#include <numeric>
+
+#include "test_macros.h"
+
+void test() {
+  // [bit.rotate]
+  std::rotl(0u, 0); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::rotr(0u, 0); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+
+  // clang-format off
+#if TEST_STD_VER >= 26
+  // [numeric.sat]
+  std::add_sat(94, 82);               // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::sub_sat(94, 82);               // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::mul_sat(94, 82);               // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::div_sat(94, 82);               // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+  std::saturate_cast<signed int>(49); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
+#endif // TEST_STD_VER >= 26
+  // clang-format on
+}

diff  --git a/libcxx/test/std/numerics/bit/bitops.rot/nodiscard.verify.cpp b/libcxx/test/std/numerics/bit/bitops.rot/nodiscard.verify.cpp
deleted file mode 100644
index 885534a85c3cb..0000000000000
--- a/libcxx/test/std/numerics/bit/bitops.rot/nodiscard.verify.cpp
+++ /dev/null
@@ -1,18 +0,0 @@
-//===----------------------------------------------------------------------===//
-//
-// 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
-//
-//===----------------------------------------------------------------------===//
-
-// UNSUPPORTED: c++03, c++11, c++14, c++17
-
-// Check that std::rotl and std::rotr are marked [[nodiscard]]
-
-#include <bit>
-
-void func() {
-  std::rotl(0u, 0); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
-  std::rotr(0u, 0); // expected-warning {{ignoring return value of function declared with 'nodiscard' attribute}}
-}