[libcxx-commits] [libcxx] [libc++] Implement a type-safe iterator for optional (PR #154239)

[Louis Dionne via libcxx-commits]

================
@@ -0,0 +1,174 @@
+// -*- 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
+//
+//===----------------------------------------------------------------------===//
+
+/*
+ * __upper_bounded_iterator is an iterator that wraps an underlying iterator.
+ * It stores the underlying container type to prevent mixing iterators, and allow algorithms
+ * to optimize based on the underlying container type.
+ * It also stores the absolute maximum amount of elements the container can have, known at compile-time.
+ * As of writing, the only standard library containers which have this property are inplace_vector and optional.
+ */
+
+#ifndef _LIBCPP___ITERATOR_UPPER_BOUNDED_ITERATOR_H
+#define _LIBCPP___ITERATOR_UPPER_BOUNDED_ITERATOR_H
+
+#include <__compare/ordering.h>
+#include <__compare/three_way_comparable.h>
+#include <__config>
+#include <__cstddef/size_t.h>
+#include <__iterator/incrementable_traits.h>
+#include <__iterator/iterator_traits.h>
+#include <__memory/pointer_traits.h>
+#include <__type_traits/is_constructible.h>
+#include <__utility/move.h>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#  pragma GCC system_header
+#endif
+
+_LIBCPP_PUSH_MACROS
+#include <__undef_macros>
+
+#if _LIBCPP_STD_VER >= 26
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+template <class _Iter, class _Container, std::size_t _Max_Elements>
+class __upper_bounded_iterator {
+private:
+  _Iter __iter_;
+
+  friend _Container;
+
+public:
+  using iterator_category = iterator_traits<_Iter>::iterator_category;
+  using iterator_concept  = _Iter::iterator_concept;
+  using value_type        = iter_value_t<_Iter>;
+  using difference_type   = iter_difference_t<_Iter>;
+  using reference         = iter_reference_t<_Iter>;
+
+  _LIBCPP_HIDE_FROM_ABI constexpr __upper_bounded_iterator()
+    requires is_default_constructible_v<_Iter>
+  = default;
+
+  _LIBCPP_HIDE_FROM_ABI constexpr explicit __upper_bounded_iterator(_Iter __iter) : __iter_(std::move(__iter)) {}
+
+  _LIBCPP_HIDE_FROM_ABI constexpr _Iter __base() const noexcept(noexcept(_Iter(__iter_))) { return __iter_; }
+  _LIBCPP_HIDE_FROM_ABI constexpr auto __max_elements() const noexcept { return _Max_Elements; }
+
+  _LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator*() const { return *__iter_; }
+  _LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator->() const
+    requires requires { __iter_.operator->(); }
+  {
+    return __iter_.operator->();
+  }
+
+  _LIBCPP_HIDE_FROM_ABI constexpr __upper_bounded_iterator& operator++() {
+    ++__iter_;
+    return *this;
+  }
+
+  _LIBCPP_HIDE_FROM_ABI constexpr __upper_bounded_iterator operator++(int) {
+    __upper_bounded_iterator __tmp(*this);
+    ++*this;
+    return __tmp;
+  }
+
+  _LIBCPP_HIDE_FROM_ABI constexpr __upper_bounded_iterator& operator--() {
+    --__iter_;
+    return *this;
+  }
+
+  _LIBCPP_HIDE_FROM_ABI constexpr __upper_bounded_iterator operator--(int) {
+    __upper_bounded_iterator __tmp(*this);
+    --*this;
+    return __tmp;
+  }
+
+  _LIBCPP_HIDE_FROM_ABI constexpr __upper_bounded_iterator& operator+=(difference_type __x) {
+    __iter_ += __x;
----------------
ldionne wrote:

```suggestion
  _LIBCPP_HIDE_FROM_ABI constexpr __upper_bounded_iterator& operator+=(difference_type __n) {
    __iter_ += __n;
```

Here, but also in `operator++`, I believe we have a precondition that `__n <= _MaxElements`. We should check it, and add a test to ensure that we catch the misuse when hardening is enabled.

It's also interesting to notice that you can do `operator++` on an iterator, and then `operator+=` should in theory assert that we don't try to increment by more than `_MaxElements-1` (instead of `_MaxElements`), since the iterator has already been incremented. Obviously, doing that requires storing additional information in the iterator, and that's not what we're trying to achieve here.

However, since we have `__bounded_iter` which does that, I feel like `__upper_bounded_iterator` might not be the best name: it strongly suggests that we do something like `__bounded_iter` where we store actual bounds at runtime.

https://github.com/llvm/llvm-project/pull/154239