[libc++][numeric] Marked saturation artithmetic functions as [[nodiscard]]

[H-G-Hristov]

...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
• [libc++] Mark string functions as [[nodiscard]] #166524 (comment)

[llvmbot]

@llvm/pr-subscribers-libcxx

Author: Hristo Hristov (H-G-Hristov)

Changes

...according to Coding Guidelines:

• https://libcxx.llvm.org/CodingGuidelines.html#apply-nodiscard-where-relevant
• [libc++] Mark string functions as [[nodiscard]] #166524 (comment)

---

Full diff: https://github.com/llvm/llvm-project/pull/166898.diff

2 Files Affected:

• (modified) libcxx/include/__numeric/saturation_arithmetic.h (+5-5)
• (added) libcxx/test/libcxx/numerics/numeric.ops/sat.nodiscard.verify.cpp (+23)

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/numeric.ops/sat.nodiscard.verify.cpp b/libcxx/test/libcxx/numerics/numeric.ops/sat.nodiscard.verify.cpp
new file mode 100644
index 0000000000000..63e20f1a60d54
--- /dev/null
+++ b/libcxx/test/libcxx/numerics/numeric.ops/sat.nodiscard.verify.cpp
@@ -0,0 +1,23 @@
+//===----------------------------------------------------------------------===//
+//
+// 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++26
+
+// <numeric>
+
+#include <numeric>
+
+// clang-format off
+void test() {
+  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}}
+}
+// clang-format on

[philnik777]

Let's merge this with bitops.rot/nodiscard.verify.cpp into a single numerics/nodiscard.verify.cpp These are small enough that there isn't much of a point separating them.

[H-G-Hristov]

Done! Thank you!

[github-actions]

✅ With the latest revision this PR passed the C/C++ code formatter.