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___CXX03___ITERATOR_BOUNDED_ITER_H
11 #define _LIBCPP___CXX03___ITERATOR_BOUNDED_ITER_H
12
13 #include <__cxx03/__assert>
14 #include <__cxx03/__config>
15 #include <__cxx03/__iterator/iterator_traits.h>
16 #include <__cxx03/__memory/pointer_traits.h>
17 #include <__cxx03/__type_traits/enable_if.h>
18 #include <__cxx03/__type_traits/integral_constant.h>
19 #include <__cxx03/__type_traits/is_convertible.h>
20 #include <__cxx03/__utility/move.h>
21
22 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
23 # pragma GCC system_header
24 #endif
25
26 _LIBCPP_PUSH_MACROS
27 #include <__cxx03/__undef_macros>
28
29 _LIBCPP_BEGIN_NAMESPACE_STD
30
31 // Iterator wrapper that carries the valid range it is allowed to access.
32 //
33 // This is a simple iterator wrapper for contiguous iterators that points
34 // within a [begin, end] range and carries these bounds with it. The iterator
35 // ensures that it is pointing within [begin, end) range when it is
36 // dereferenced. It also ensures that it is never iterated outside of
37 // [begin, end]. This is important for two reasons:
38 //
39 // 1. It allows `operator*` and `operator++` bounds checks to be `iter != end`.
40 // This is both less for the optimizer to prove, and aligns with how callers
41 // typically use iterators.
42 //
43 // 2. Advancing an iterator out of bounds is undefined behavior (see the table
44 // in [input.iterators]). In particular, when the underlying iterator is a
45 // pointer, it is undefined at the language level (see [expr.add]). If
46 // bounded iterators exhibited this undefined behavior, we risk compiler
47 // optimizations deleting non-redundant bounds checks.
48 template <class _Iterator, class = __enable_if_t< __libcpp_is_contiguous_iterator<_Iterator>::value > >
49 struct __bounded_iter {
50 using value_type = typename iterator_traits<_Iterator>::value_type;
51 using difference_type = typename iterator_traits<_Iterator>::difference_type;
52 using pointer = typename iterator_traits<_Iterator>::pointer;
53 using reference = typename iterator_traits<_Iterator>::reference;
54 using iterator_category = typename iterator_traits<_Iterator>::iterator_category;
55
56 // Create a singular iterator.
57 //
58 // Such an iterator points past the end of an empty span, so it is not dereferenceable.
59 // Observing operations like comparison and assignment are valid.
60 _LIBCPP_HIDE_FROM_ABI __bounded_iter() = default;
61
62 _LIBCPP_HIDE_FROM_ABI __bounded_iter(__bounded_iter const&) = default;
63 _LIBCPP_HIDE_FROM_ABI __bounded_iter(__bounded_iter&&) = default;
64
65 template <class _OtherIterator, __enable_if_t< is_convertible<_OtherIterator, _Iterator>::value, int> = 0>
__bounded_iter__bounded_iter66 _LIBCPP_HIDE_FROM_ABI __bounded_iter(__bounded_iter<_OtherIterator> const& __other) _NOEXCEPT
67 : __current_(__other.__current_),
68 __begin_(__other.__begin_),
69 __end_(__other.__end_) {}
70
71 // Assign a bounded iterator to another one, rebinding the bounds of the iterator as well.
72 _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator=(__bounded_iter const&) = default;
73 _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator=(__bounded_iter&&) = default;
74
75 private:
76 // Create an iterator wrapping the given iterator, and whose bounds are described
77 // by the provided [begin, end] range.
78 //
79 // The constructor does not check whether the resulting iterator is within its bounds. It is a
80 // responsibility of the container to ensure that the given bounds are valid.
81 //
82 // Since it is non-standard for iterators to have this constructor, __bounded_iter must
83 // be created via `std::__make_bounded_iter`.
__bounded_iter__bounded_iter84 _LIBCPP_HIDE_FROM_ABI explicit __bounded_iter(_Iterator __current, _Iterator __begin, _Iterator __end)
85 : __current_(__current), __begin_(__begin), __end_(__end) {
86 _LIBCPP_ASSERT_INTERNAL(
87 __begin <= __current, "__bounded_iter(current, begin, end): current and begin are inconsistent");
88 _LIBCPP_ASSERT_INTERNAL(
89 __current <= __end, "__bounded_iter(current, begin, end): current and end are inconsistent");
90 }
91
92 template <class _It>
93 friend __bounded_iter<_It> __make_bounded_iter(_It, _It, _It);
94
95 public:
96 // Dereference and indexing operations.
97 //
98 // These operations check that the iterator is dereferenceable. Since the class invariant is
99 // that the iterator is always within `[begin, end]`, we only need to check it's not pointing to
100 // `end`. This is easier for the optimizer because it aligns with the `iter != container.end()`
101 // checks that typical callers already use (see
102 // https://github.com/llvm/llvm-project/issues/78829).
103 _LIBCPP_HIDE_FROM_ABI reference operator*() const _NOEXCEPT {
104 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
105 __current_ != __end_, "__bounded_iter::operator*: Attempt to dereference an iterator at the end");
106 return *__current_;
107 }
108
109 _LIBCPP_HIDE_FROM_ABI pointer operator->() const _NOEXCEPT {
110 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
111 __current_ != __end_, "__bounded_iter::operator->: Attempt to dereference an iterator at the end");
112 return std::__to_address(__current_);
113 }
114
115 _LIBCPP_HIDE_FROM_ABI reference operator[](difference_type __n) const _NOEXCEPT {
116 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
117 __n >= __begin_ - __current_, "__bounded_iter::operator[]: Attempt to index an iterator past the start");
118 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
119 __n < __end_ - __current_, "__bounded_iter::operator[]: Attempt to index an iterator at or past the end");
120 return __current_[__n];
121 }
122
123 // Arithmetic operations.
124 //
125 // These operations check that the iterator remains within `[begin, end]`.
126 _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator++() _NOEXCEPT {
127 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
128 __current_ != __end_, "__bounded_iter::operator++: Attempt to advance an iterator past the end");
129 ++__current_;
130 return *this;
131 }
132 _LIBCPP_HIDE_FROM_ABI __bounded_iter operator++(int) _NOEXCEPT {
133 __bounded_iter __tmp(*this);
134 ++*this;
135 return __tmp;
136 }
137
138 _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator--() _NOEXCEPT {
139 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
140 __current_ != __begin_, "__bounded_iter::operator--: Attempt to rewind an iterator past the start");
141 --__current_;
142 return *this;
143 }
144 _LIBCPP_HIDE_FROM_ABI __bounded_iter operator--(int) _NOEXCEPT {
145 __bounded_iter __tmp(*this);
146 --*this;
147 return __tmp;
148 }
149
150 _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator+=(difference_type __n) _NOEXCEPT {
151 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
152 __n >= __begin_ - __current_, "__bounded_iter::operator+=: Attempt to rewind an iterator past the start");
153 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
154 __n <= __end_ - __current_, "__bounded_iter::operator+=: Attempt to advance an iterator past the end");
155 __current_ += __n;
156 return *this;
157 }
158 _LIBCPP_HIDE_FROM_ABI friend __bounded_iter operator+(__bounded_iter const& __self, difference_type __n) _NOEXCEPT {
159 __bounded_iter __tmp(__self);
160 __tmp += __n;
161 return __tmp;
162 }
163 _LIBCPP_HIDE_FROM_ABI friend __bounded_iter operator+(difference_type __n, __bounded_iter const& __self) _NOEXCEPT {
164 __bounded_iter __tmp(__self);
165 __tmp += __n;
166 return __tmp;
167 }
168
169 _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator-=(difference_type __n) _NOEXCEPT {
170 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
171 __n <= __current_ - __begin_, "__bounded_iter::operator-=: Attempt to rewind an iterator past the start");
172 _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
173 __n >= __current_ - __end_, "__bounded_iter::operator-=: Attempt to advance an iterator past the end");
174 __current_ -= __n;
175 return *this;
176 }
177 _LIBCPP_HIDE_FROM_ABI friend __bounded_iter operator-(__bounded_iter const& __self, difference_type __n) _NOEXCEPT {
178 __bounded_iter __tmp(__self);
179 __tmp -= __n;
180 return __tmp;
181 }
182 _LIBCPP_HIDE_FROM_ABI friend difference_type
183 operator-(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
184 return __x.__current_ - __y.__current_;
185 }
186
187 // Comparison operations.
188 //
189 // These operations do not check whether the iterators are within their bounds.
190 // The valid range for each iterator is also not considered as part of the comparison,
191 // i.e. two iterators pointing to the same location will be considered equal even
192 // if they have different validity ranges.
193 _LIBCPP_HIDE_FROM_ABI friend bool operator==(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
194 return __x.__current_ == __y.__current_;
195 }
196
197 _LIBCPP_HIDE_FROM_ABI friend bool operator!=(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
198 return __x.__current_ != __y.__current_;
199 }
200
201 // TODO(mordante) disable these overloads in the LLVM 20 release.
202 _LIBCPP_HIDE_FROM_ABI friend bool operator<(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
203 return __x.__current_ < __y.__current_;
204 }
205 _LIBCPP_HIDE_FROM_ABI friend bool operator>(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
206 return __x.__current_ > __y.__current_;
207 }
208 _LIBCPP_HIDE_FROM_ABI friend bool operator<=(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
209 return __x.__current_ <= __y.__current_;
210 }
211 _LIBCPP_HIDE_FROM_ABI friend bool operator>=(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
212 return __x.__current_ >= __y.__current_;
213 }
214
215 private:
216 template <class>
217 friend struct pointer_traits;
218 template <class, class>
219 friend struct __bounded_iter;
220 _Iterator __current_; // current iterator
221 _Iterator __begin_, __end_; // valid range represented as [begin, end]
222 };
223
224 template <class _It>
__make_bounded_iter(_It __it,_It __begin,_It __end)225 _LIBCPP_HIDE_FROM_ABI __bounded_iter<_It> __make_bounded_iter(_It __it, _It __begin, _It __end) {
226 return __bounded_iter<_It>(std::move(__it), std::move(__begin), std::move(__end));
227 }
228
229 template <class _Iterator>
230 struct __libcpp_is_contiguous_iterator<__bounded_iter<_Iterator> > : true_type {};
231
232 template <class _Iterator>
233 struct pointer_traits<__bounded_iter<_Iterator> > {
234 using pointer = __bounded_iter<_Iterator>;
235 using element_type = typename pointer_traits<_Iterator>::element_type;
236 using difference_type = typename pointer_traits<_Iterator>::difference_type;
237
238 _LIBCPP_HIDE_FROM_ABI static element_type* to_address(pointer __it) _NOEXCEPT {
239 return std::__to_address(__it.__current_);
240 }
241 };
242
243 _LIBCPP_END_NAMESPACE_STD
244
245 _LIBCPP_POP_MACROS
246
247 #endif // _LIBCPP___CXX03___ITERATOR_BOUNDED_ITER_H
248