[libcxx-commits] [libcxx] [libc++] Applied `[[nodiscard]]` to `optional::iterator` (PR #198489)
Hristo Hristov via libcxx-commits
libcxx-commits at lists.llvm.org
Sat May 23 00:36:50 PDT 2026
https://github.com/H-G-Hristov updated https://github.com/llvm/llvm-project/pull/198489
>From 80a85ae3db85ca6dc8af541226a7eea70287bdee Mon Sep 17 00:00:00 2001
From: Hristo Hristov <hghristov.rmm at gmail.com>
Date: Tue, 19 May 2026 13:34:27 +0300
Subject: [PATCH] [libc++] `[[nodiscard]]` to `__bounded_iter`
Towards [libc++] Apply `[[nodiscard]]` to the Standard Library
Fixes #172124
---
libcxx/include/__iterator/bounded_iter.h | 15 ++---
.../__iterator/capacity_aware_iterator.h | 10 ++--
.../views.span/nodiscard.iterator.verify.cpp | 55 +++++++++++++++++++
.../nodiscard.iterator.verify.cpp | 52 ++++++++++++++++++
.../string.view/nodiscard.iterator.verify.cpp | 52 ++++++++++++++++++
.../optional/nodiscard.iterator.verify.cpp | 55 +++++++++++++++++++
6 files changed, 227 insertions(+), 12 deletions(-)
create mode 100644 libcxx/test/libcxx/containers/views/views.span/nodiscard.iterator.verify.cpp
create mode 100644 libcxx/test/libcxx/strings/basic.string/nodiscard.iterator.verify.cpp
create mode 100644 libcxx/test/libcxx/strings/string.view/nodiscard.iterator.verify.cpp
create mode 100644 libcxx/test/libcxx/utilities/optional/nodiscard.iterator.verify.cpp
diff --git a/libcxx/include/__iterator/bounded_iter.h b/libcxx/include/__iterator/bounded_iter.h
index 84d4d8f4a98a8..743151b2ea497 100644
--- a/libcxx/include/__iterator/bounded_iter.h
+++ b/libcxx/include/__iterator/bounded_iter.h
@@ -114,7 +114,7 @@ struct __bounded_iter {
// that the iterator is always within `[begin, end]`, we only need to check it's not pointing to
// `end`. This is easier for the optimizer because it aligns with the `iter != container.end()`
// checks that typical callers already use (see https://llvm.org/PR78829).
- _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 reference operator*() const _NOEXCEPT {
+ [[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 reference operator*() const _NOEXCEPT {
_LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
__current_ != __end_, "__bounded_iter::operator*: Attempt to dereference an iterator at the end");
return *__current_;
@@ -126,7 +126,8 @@ struct __bounded_iter {
return std::__to_address(__current_);
}
- _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 reference operator[](difference_type __n) const _NOEXCEPT {
+ [[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 reference
+ operator[](difference_type __n) const _NOEXCEPT {
_LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
__n >= __begin_ - __current_, "__bounded_iter::operator[]: Attempt to index an iterator past the start");
_LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
@@ -169,13 +170,13 @@ struct __bounded_iter {
__current_ += __n;
return *this;
}
- _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
+ [[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
operator+(__bounded_iter const& __self, difference_type __n) _NOEXCEPT {
__bounded_iter __tmp(__self);
__tmp += __n;
return __tmp;
}
- _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
+ [[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
operator+(difference_type __n, __bounded_iter const& __self) _NOEXCEPT {
__bounded_iter __tmp(__self);
__tmp += __n;
@@ -190,13 +191,13 @@ struct __bounded_iter {
__current_ -= __n;
return *this;
}
- _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
+ [[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
operator-(__bounded_iter const& __self, difference_type __n) _NOEXCEPT {
__bounded_iter __tmp(__self);
__tmp -= __n;
return __tmp;
}
- _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend difference_type
+ [[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend difference_type
operator-(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
return __x.__current_ - __y.__current_;
}
@@ -277,7 +278,7 @@ struct pointer_traits<__bounded_iter<_Iterator> > {
using element_type = typename pointer_traits<_Iterator>::element_type;
using difference_type = typename pointer_traits<_Iterator>::difference_type;
- _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR static element_type* to_address(pointer __it) _NOEXCEPT {
+ [[__nodiscard__]] _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR static element_type* to_address(pointer __it) _NOEXCEPT {
return std::__to_address(__it.__current_);
}
};
diff --git a/libcxx/include/__iterator/capacity_aware_iterator.h b/libcxx/include/__iterator/capacity_aware_iterator.h
index 4fbe2a6028175..3b8046c145bca 100644
--- a/libcxx/include/__iterator/capacity_aware_iterator.h
+++ b/libcxx/include/__iterator/capacity_aware_iterator.h
@@ -76,7 +76,7 @@ class __capacity_aware_iterator {
_LIBCPP_HIDE_FROM_ABI constexpr explicit __capacity_aware_iterator(_Iter __iter) : __iter_(std::move(__iter)) {}
public:
- _LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator*() const noexcept { return *__iter_; }
+ [[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator*() const noexcept { return *__iter_; }
_LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator->() const noexcept { return std::__to_address(__iter_); }
_LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator& operator++() noexcept {
@@ -145,28 +145,28 @@ class __capacity_aware_iterator {
}
}
- _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
+ [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
operator+(const __capacity_aware_iterator& __i, difference_type __n) noexcept {
auto __tmp = __i;
__tmp += __n;
return __tmp;
}
- _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
+ [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
operator+(difference_type __n, const __capacity_aware_iterator& __i) noexcept {
auto __tmp = __i;
__tmp += __n;
return __tmp;
}
- _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
+ [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
operator-(const __capacity_aware_iterator& __i, difference_type __n) noexcept {
auto __tmp = __i;
__tmp -= __n;
return __tmp;
}
- _LIBCPP_HIDE_FROM_ABI friend constexpr difference_type
+ [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr difference_type
operator-(const __capacity_aware_iterator& __x, const __capacity_aware_iterator& __y) noexcept {
return difference_type(__x.__iter_ - __y.__iter_);
}
diff --git a/libcxx/test/libcxx/containers/views/views.span/nodiscard.iterator.verify.cpp b/libcxx/test/libcxx/containers/views/views.span/nodiscard.iterator.verify.cpp
new file mode 100644
index 0000000000000..f9ab0106536f1
--- /dev/null
+++ b/libcxx/test/libcxx/containers/views/views.span/nodiscard.iterator.verify.cpp
@@ -0,0 +1,55 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+
+// <span>
+
+// Check that functions are marked [[nodiscard]]
+
+#include <span>
+#include <vector>
+
+#include "test_macros.h"
+
+void test() {
+ using Container = std::span<std::vector<int>>;
+
+ Container c;
+ Container::iterator it = c.begin();
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ ASSERT_SAME_TYPE(Container::iterator, std::__bounded_iter<std::vector<int>*>);
+#else
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ *it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it[0];
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it + 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ 1 + it;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ std::pointer_traits<Container::iterator>::to_address(it);
+#endif
+}
diff --git a/libcxx/test/libcxx/strings/basic.string/nodiscard.iterator.verify.cpp b/libcxx/test/libcxx/strings/basic.string/nodiscard.iterator.verify.cpp
new file mode 100644
index 0000000000000..0ba76c2ace37a
--- /dev/null
+++ b/libcxx/test/libcxx/strings/basic.string/nodiscard.iterator.verify.cpp
@@ -0,0 +1,52 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+// <string>
+
+// Check that functions are marked [[nodiscard]]
+
+#include <string>
+
+#include "test_macros.h"
+
+void test() {
+ typedef std::basic_string<char> Container;
+
+ Container c;
+ Container::iterator it = c.begin();
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ ASSERT_SAME_TYPE(Container::iterator, std::__bounded_iter<char*>);
+#else
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ *it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it[0];
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it + 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ 1 + it;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ std::pointer_traits<Container::iterator>::to_address(it);
+#endif
+}
diff --git a/libcxx/test/libcxx/strings/string.view/nodiscard.iterator.verify.cpp b/libcxx/test/libcxx/strings/string.view/nodiscard.iterator.verify.cpp
new file mode 100644
index 0000000000000..5b25814b00017
--- /dev/null
+++ b/libcxx/test/libcxx/strings/string.view/nodiscard.iterator.verify.cpp
@@ -0,0 +1,52 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+// <string_view>
+
+// Check that functions are marked [[nodiscard]]
+
+#include <string_view>
+
+#include "test_macros.h"
+
+void test() {
+ typedef std::basic_string_view<char> Container;
+
+ Container c;
+ Container::iterator it = c.begin();
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ ASSERT_SAME_TYPE(Container::iterator, std::__bounded_iter<const char*>);
+#else
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ *it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it[0];
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it + 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ 1 + it;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ std::pointer_traits<Container::iterator>::to_address(it);
+#endif
+}
diff --git a/libcxx/test/libcxx/utilities/optional/nodiscard.iterator.verify.cpp b/libcxx/test/libcxx/utilities/optional/nodiscard.iterator.verify.cpp
new file mode 100644
index 0000000000000..6f1d5a4a8c18a
--- /dev/null
+++ b/libcxx/test/libcxx/utilities/optional/nodiscard.iterator.verify.cpp
@@ -0,0 +1,55 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+
+// <optional>
+
+// Check that functions are marked [[nodiscard]]
+
+#include <optional>
+
+#include "test_macros.h"
+
+void test() {
+ using Container = std::optional<int>;
+
+ Container c;
+ Container::iterator it = c.begin();
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS_IN_OPTIONAL)
+ ASSERT_SAME_TYPE(Container::iterator, std::__bounded_iter<int*>);
+#else
+ ASSERT_SAME_TYPE(Container::iterator, std::__capacity_aware_iterator<int*, std::optional<int>, 1>);
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ *it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS_IN_OPTIONAL)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it[0];
+#endif
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it + 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ 1 + it;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - 1;
+
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ it - it;
+
+#if defined(_LIBCPP_ABI_BOUNDED_ITERATORS_IN_OPTIONAL)
+ // expected-warning at +1 {{ignoring return value of function declared with 'nodiscard' attribute}}
+ std::pointer_traits<Container::iterator>::to_address(it);
+#endif
+}
More information about the libcxx-commits
mailing list