libcxx/include/__iterator/bounded_iter.h

   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___ITERATOR_BOUNDED_ITER_H
  11 #define _LIBCPP___ITERATOR_BOUNDED_ITER_H
  12
  13 #include <__assert>
  14 #include <__config>
  15 #include <__iterator/iterator_traits.h>
  16 #include <__memory/pointer_traits.h>
  17 #include <__type_traits/enable_if.h>
  18 #include <__type_traits/integral_constant.h>
  19 #include <__type_traits/is_convertible.h>
  20 #include <__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 <__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 that [begin, end) range when it is
  36 // dereferenced.
  37 //
  38 // Arithmetic operations are allowed and the bounds of the resulting iterator
  39 // are not checked. Hence, it is possible to create an iterator pointing outside
  40 // its range, but it is not possible to dereference it.
  41 template <class _Iterator, class = __enable_if_t< __libcpp_is_contiguous_iterator<_Iterator>::value > >
  42 struct __bounded_iter {
  43   using value_type        = typename iterator_traits<_Iterator>::value_type;
  44   using difference_type   = typename iterator_traits<_Iterator>::difference_type;
  45   using pointer           = typename iterator_traits<_Iterator>::pointer;
  46   using reference         = typename iterator_traits<_Iterator>::reference;
  47   using iterator_category = typename iterator_traits<_Iterator>::iterator_category;
  48 #if _LIBCPP_STD_VER >= 20
  49   using iterator_concept = contiguous_iterator_tag;
  50 #endif
  51
  52   // Create a singular iterator.
  53   //
  54   // Such an iterator does not point to any object and is conceptually out of bounds, so it is
  55   // not dereferenceable. Observing operations like comparison and assignment are valid.
  56   _LIBCPP_HIDE_FROM_ABI __bounded_iter() = default;
  57
  58   _LIBCPP_HIDE_FROM_ABI __bounded_iter(__bounded_iter const&) = default;
  59   _LIBCPP_HIDE_FROM_ABI __bounded_iter(__bounded_iter&&)      = default;
  60
  61   template <class _OtherIterator, class = __enable_if_t< is_convertible<_OtherIterator, _Iterator>::value > >
  62   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR __bounded_iter(__bounded_iter<_OtherIterator> const& __other) _NOEXCEPT
  63       : __current_(__other.__current_),
  64         __begin_(__other.__begin_),
  65         __end_(__other.__end_) {}
  66
  67   // Assign a bounded iterator to another one, rebinding the bounds of the iterator as well.
  68   _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator=(__bounded_iter const&) = default;
  69   _LIBCPP_HIDE_FROM_ABI __bounded_iter& operator=(__bounded_iter&&)      = default;
  70
  71 private:
  72   // Create an iterator wrapping the given iterator, and whose bounds are described
  73   // by the provided [begin, end) range.
  74   //
  75   // This constructor does not check whether the resulting iterator is within its bounds.
  76   // However, it does check that the provided [begin, end) range is a valid range (that
  77   // is, begin <= end).
  78   //
  79   // Since it is non-standard for iterators to have this constructor, __bounded_iter must
  80   // be created via `std::__make_bounded_iter`.
  81   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 explicit __bounded_iter(
  82       _Iterator __current, _Iterator __begin, _Iterator __end)
  83       : __current_(__current), __begin_(__begin), __end_(__end) {
  84     _LIBCPP_ASSERT_INTERNAL(__begin <= __end, "__bounded_iter(current, begin, end): [begin, end) is not a valid range");
  85   }
  86
  87   template <class _It>
  88   friend _LIBCPP_CONSTEXPR __bounded_iter<_It> __make_bounded_iter(_It, _It, _It);
  89
  90 public:
  91   // Dereference and indexing operations.
  92   //
  93   // These operations check that the iterator is dereferenceable, that is within [begin, end).
  94   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 reference operator*() const _NOEXCEPT {
  95     _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
  96         __in_bounds(__current_), "__bounded_iter::operator*: Attempt to dereference an out-of-range iterator");
  97     return *__current_;
  98   }
  99
 100   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 pointer operator->() const _NOEXCEPT {
 101     _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
 102         __in_bounds(__current_), "__bounded_iter::operator->: Attempt to dereference an out-of-range iterator");
 103     return std::__to_address(__current_);
 104   }
 105
 106   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 reference operator[](difference_type __n) const _NOEXCEPT {
 107     _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
 108         __in_bounds(__current_ + __n), "__bounded_iter::operator[]: Attempt to index an iterator out-of-range");
 109     return __current_[__n];
 110   }
 111
 112   // Arithmetic operations.
 113   //
 114   // These operations do not check that the resulting iterator is within the bounds, since that
 115   // would make it impossible to create a past-the-end iterator.
 116   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 __bounded_iter& operator++() _NOEXCEPT {
 117     ++__current_;
 118     return *this;
 119   }
 120   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 __bounded_iter operator++(int) _NOEXCEPT {
 121     __bounded_iter __tmp(*this);
 122     ++*this;
 123     return __tmp;
 124   }
 125
 126   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 __bounded_iter& operator--() _NOEXCEPT {
 127     --__current_;
 128     return *this;
 129   }
 130   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 __bounded_iter operator--(int) _NOEXCEPT {
 131     __bounded_iter __tmp(*this);
 132     --*this;
 133     return __tmp;
 134   }
 135
 136   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 __bounded_iter& operator+=(difference_type __n) _NOEXCEPT {
 137     __current_ += __n;
 138     return *this;
 139   }
 140   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
 141   operator+(__bounded_iter const& __self, difference_type __n) _NOEXCEPT {
 142     __bounded_iter __tmp(__self);
 143     __tmp += __n;
 144     return __tmp;
 145   }
 146   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
 147   operator+(difference_type __n, __bounded_iter const& __self) _NOEXCEPT {
 148     __bounded_iter __tmp(__self);
 149     __tmp += __n;
 150     return __tmp;
 151   }
 152
 153   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 __bounded_iter& operator-=(difference_type __n) _NOEXCEPT {
 154     __current_ -= __n;
 155     return *this;
 156   }
 157   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14 friend __bounded_iter
 158   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 _LIBCPP_CONSTEXPR_SINCE_CXX14 friend difference_type
 164   operator-(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
 165     return __x.__current_ - __y.__current_;
 166   }
 167
 168   // Comparison operations.
 169   //
 170   // These operations do not check whether the iterators are within their bounds.
 171   // The valid range for each iterator is also not considered as part of the comparison,
 172   // i.e. two iterators pointing to the same location will be considered equal even
 173   // if they have different validity ranges.
 174   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR friend bool
 175   operator==(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
 176     return __x.__current_ == __y.__current_;
 177   }
 178   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR friend bool
 179   operator!=(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
 180     return __x.__current_ != __y.__current_;
 181   }
 182   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR friend bool
 183   operator<(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
 184     return __x.__current_ < __y.__current_;
 185   }
 186   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR friend bool
 187   operator>(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
 188     return __x.__current_ > __y.__current_;
 189   }
 190   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR friend bool
 191   operator<=(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
 192     return __x.__current_ <= __y.__current_;
 193   }
 194   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR friend bool
 195   operator>=(__bounded_iter const& __x, __bounded_iter const& __y) _NOEXCEPT {
 196     return __x.__current_ >= __y.__current_;
 197   }
 198
 199 private:
 200   // Return whether the given iterator is in the bounds of this __bounded_iter.
 201   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR bool __in_bounds(_Iterator const& __iter) const {
 202     return __iter >= __begin_ && __iter < __end_;
 203   }
 204
 205   template <class>
 206   friend struct pointer_traits;
 207   _Iterator __current_;       // current iterator
 208   _Iterator __begin_, __end_; // valid range represented as [begin, end)
 209 };
 210
 211 template <class _It>
 212 _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR __bounded_iter<_It> __make_bounded_iter(_It __it, _It __begin, _It __end) {
 213   return __bounded_iter<_It>(std::move(__it), std::move(__begin), std::move(__end));
 214 }
 215
 216 #if _LIBCPP_STD_VER <= 17
 217 template <class _Iterator>
 218 struct __libcpp_is_contiguous_iterator<__bounded_iter<_Iterator> > : true_type {};
 219 #endif
 220
 221 template <class _Iterator>
 222 struct pointer_traits<__bounded_iter<_Iterator> > {
 223   using pointer         = __bounded_iter<_Iterator>;
 224   using element_type    = typename pointer_traits<_Iterator>::element_type;
 225   using difference_type = typename pointer_traits<_Iterator>::difference_type;
 226
 227   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR static element_type* to_address(pointer __it) _NOEXCEPT {
 228     return std::__to_address(__it.__current_);
 229   }
 230 };
 231
 232 _LIBCPP_END_NAMESPACE_STD
 233
 234 _LIBCPP_POP_MACROS
 235
 236 #endif // _LIBCPP___ITERATOR_BOUNDED_ITER_H