248 lines · c
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-exception7//8//===----------------------------------------------------------------------===//9 10#ifndef _LIBCPP___CXX03___ITERATOR_BOUNDED_ITER_H11#define _LIBCPP___CXX03___ITERATOR_BOUNDED_ITER_H12 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_header24#endif25 26_LIBCPP_PUSH_MACROS27#include <__cxx03/__undef_macros>28 29_LIBCPP_BEGIN_NAMESPACE_STD30 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 points34// within a [begin, end] range and carries these bounds with it. The iterator35// ensures that it is pointing within [begin, end) range when it is36// dereferenced. It also ensures that it is never iterated outside of37// [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 callers41// typically use iterators.42//43// 2. Advancing an iterator out of bounds is undefined behavior (see the table44// in [input.iterators]). In particular, when the underlying iterator is a45// pointer, it is undefined at the language level (see [expr.add]). If46// bounded iterators exhibited this undefined behavior, we risk compiler47// optimizations deleting non-redundant bounds checks.48template <class _Iterator, class = __enable_if_t< __libcpp_is_contiguous_iterator<_Iterator>::value > >49struct __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>66 _LIBCPP_HIDE_FROM_ABI __bounded_iter(__bounded_iter<_OtherIterator> const& __other) _NOEXCEPT67 : __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 75private:76 // Create an iterator wrapping the given iterator, and whose bounds are described77 // by the provided [begin, end] range.78 //79 // The constructor does not check whether the resulting iterator is within its bounds. It is a80 // 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 must83 // be created via `std::__make_bounded_iter`.84 _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 95public:96 // Dereference and indexing operations.97 //98 // These operations check that the iterator is dereferenceable. Since the class invariant is99 // that the iterator is always within `[begin, end]`, we only need to check it's not pointing to100 // `end`. This is easier for the optimizer because it aligns with the `iter != container.end()`101 // checks that typical callers already use (see102 // 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_type183 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 even192 // 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 215private:216 template <class>217 friend struct pointer_traits;218 template <class, class>219 friend struct __bounded_iter;220 _Iterator __current_; // current iterator221 _Iterator __begin_, __end_; // valid range represented as [begin, end]222};223 224template <class _It>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 229template <class _Iterator>230struct __libcpp_is_contiguous_iterator<__bounded_iter<_Iterator> > : true_type {};231 232template <class _Iterator>233struct 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_STD244 245_LIBCPP_POP_MACROS246 247#endif // _LIBCPP___CXX03___ITERATOR_BOUNDED_ITER_H248