1// -*- C++ -*-
2//===----------------------------------------------------------------------===//
3//
4// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5// See https://llvm.org/LICENSE.txt for license information.
6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef _LIBCPP___CAPACITY_AWARE_ITERATOR_H
11#define _LIBCPP___CAPACITY_AWARE_ITERATOR_H
12
13#include <__assert>
14#include <__compare/ordering.h>
15#include <__compare/three_way_comparable.h>
16#include <__config>
17#include <__cstddef/size_t.h>
18#include <__iterator/concepts.h>
19#include <__iterator/incrementable_traits.h>
20#include <__iterator/iterator_traits.h>
21#include <__memory/pointer_traits.h>
22#include <__type_traits/is_constructible.h>
23#include <__type_traits/is_convertible.h>
24#include <__utility/move.h>
25
26#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
27# pragma GCC system_header
28#endif
29
30_LIBCPP_PUSH_MACROS
31#include <__undef_macros>
32
33#if _LIBCPP_STD_VER >= 26
34
35_LIBCPP_BEGIN_NAMESPACE_STD
36
37// __capacity_aware_iterator is an iterator that wraps a contiguous iterator and encodes the maximum number of
38// elements that can appear in a range of such iterators. That maximum number of elements must be known at compile-time.
39// As of writing, the only standard library containers which fulfill these requirements are inplace_vector and optional.
40//
41// It also embeds a tag type to prevent mixing iterators from e.g. different containers. This also allows for some
42// algorithms to detect this iterator and perform optimizations based on the added semantic information.
43
44template <class _Iter, class _Tag, size_t _RangeMaxElements>
45class __capacity_aware_iterator {
46private:
47 _Iter __iter_;
48
49 template <class, class, size_t>
50 friend class __capacity_aware_iterator;
51
52public:
53 static_assert(contiguous_iterator<_Iter>, "__capacity_aware_iterator can only be used with contiguous iterators");
54
55 using iterator_category = iterator_traits<_Iter>::iterator_category;
56 using iterator_concept = contiguous_iterator_tag;
57 using difference_type = iter_difference_t<_Iter>;
58 using pointer = iterator_traits<_Iter>::pointer;
59 using reference = iter_reference_t<_Iter>;
60 using value_type = iter_value_t<_Iter>;
61
62 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator()
63 requires is_default_constructible_v<_Iter>
64 = default;
65
66 template <typename _Iter2>
67 requires is_convertible_v<_Iter2, _Iter>
68 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator(
69 const __capacity_aware_iterator<_Iter2, _Tag, _RangeMaxElements>& __y) noexcept
70 : __iter_(__y.__iter_) {}
71
72 template <class _It, class _Tag2, size_t _RangeMaxElems2>
73 _LIBCPP_HIDE_FROM_ABI friend constexpr auto __make_capacity_aware_iterator(_It __iter) noexcept;
74
75private:
76 _LIBCPP_HIDE_FROM_ABI constexpr explicit __capacity_aware_iterator(_Iter __iter) : __iter_(std::move(__iter)) {}
77
78public:
79 [[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator*() const noexcept { return *__iter_; }
80 _LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator->() const noexcept { return std::__to_address(__iter_); }
81
82 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator& operator++() noexcept {
83 ++__iter_;
84 return *this;
85 }
86
87 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator operator++(int) noexcept {
88 __capacity_aware_iterator __tmp(*this);
89 ++*this;
90 return __tmp;
91 }
92
93 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator& operator--() noexcept {
94 --__iter_;
95 return *this;
96 }
97
98 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator operator--(int) noexcept {
99 __capacity_aware_iterator __tmp(*this);
100 --*this;
101 return __tmp;
102 }
103
104 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator& operator+=(difference_type __n) noexcept {
105 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
106 static_cast<size_t>(__n >= 0 ? __n : -__n) <= _RangeMaxElements,
107 "__capacity_aware_iterator::operator+=: Attempting to move iterator past its container's possible range");
108
109 __iter_ += __n;
110 return *this;
111 }
112
113 _LIBCPP_HIDE_FROM_ABI constexpr __capacity_aware_iterator& operator-=(difference_type __n) noexcept {
114 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
115 static_cast<size_t>(__n >= 0 ? __n : -__n) <= _RangeMaxElements,
116 "__capacity_aware_iterator::operator-=: Attempting to move iterator past its container's possible range");
117
118 __iter_ -= __n;
119 return *this;
120 }
121
122 [[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr decltype(auto) operator[](difference_type __n) const noexcept {
123 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
124 static_cast<size_t>(__n >= 0 ? __n : -__n) < _RangeMaxElements,
125 "__capacity_aware_iterator::operator[]: Attempting to index iterator past its container's possible range");
126 return *(*this + __n);
127 }
128
129 _LIBCPP_HIDE_FROM_ABI friend constexpr bool
130 operator==(const __capacity_aware_iterator& __x, const __capacity_aware_iterator& __y) noexcept {
131 return __x.__iter_ == __y.__iter_;
132 }
133
134 _LIBCPP_HIDE_FROM_ABI friend constexpr auto
135 operator<=>(const __capacity_aware_iterator& __x, const __capacity_aware_iterator& __y) noexcept {
136 if constexpr (three_way_comparable_with<_Iter, _Iter, strong_ordering>) {
137 return __x.__iter_ <=> __y.__iter_;
138 } else {
139 if (__x.__iter_ < __y.__iter_) {
140 return strong_ordering::less;
141 } else if (__x.__iter_ == __y.__iter_) {
142 return strong_ordering::equal;
143 }
144 return strong_ordering::greater;
145 }
146 }
147
148 [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
149 operator+(const __capacity_aware_iterator& __i, difference_type __n) noexcept {
150 auto __tmp = __i;
151 __tmp += __n;
152 return __tmp;
153 }
154
155 [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
156 operator+(difference_type __n, const __capacity_aware_iterator& __i) noexcept {
157 auto __tmp = __i;
158 __tmp += __n;
159 return __tmp;
160 }
161
162 [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr __capacity_aware_iterator
163 operator-(const __capacity_aware_iterator& __i, difference_type __n) noexcept {
164 auto __tmp = __i;
165 __tmp -= __n;
166 return __tmp;
167 }
168
169 [[nodiscard]] _LIBCPP_HIDE_FROM_ABI friend constexpr difference_type
170 operator-(const __capacity_aware_iterator& __x, const __capacity_aware_iterator& __y) noexcept {
171 return difference_type(__x.__iter_ - __y.__iter_);
172 }
173};
174
175template <class _It, class _Tag2, size_t _RangeMaxElems2>
176_LIBCPP_HIDE_FROM_ABI constexpr auto __make_capacity_aware_iterator(_It __iter) noexcept {
177 return __capacity_aware_iterator<_It, _Tag2, _RangeMaxElems2>(__iter);
178}
179
180_LIBCPP_END_NAMESPACE_STD
181
182#endif // _LIBCPP_STD_VER >= 26
183
184_LIBCPP_POP_MACROS
185
186#endif // _LIBCPP___CAPACITY_AWARE_ITERATOR_H