README.md
1# stl_interfaces
2
3An updated C++20-friendly version of the `iterator_facade` and
4`iterator_adaptor` parts of Boost.Iterator (now called `iterator_interface`);
5a pre-C++20 version of C++20's `view_interface`; and a new template called
6`container_interface`, meant to aid the creation of new containers; all
7targeting standardization. This library requires at least C++14.
8
9For the iterator portion -- if you need to write an iterator, `iterator_interface` turns this:
10
11```c++
12 struct repeated_chars_iterator
13 {
14 using value_type = char;
15 using difference_type = std::ptrdiff_t;
16 using pointer = char const *;
17 using reference = char const;
18 using iterator_category = std::random_access_iterator_tag;
19
20 constexpr repeated_chars_iterator() noexcept :
21 first_(nullptr),
22 size_(0),
23 n_(0)
24 {}
25 constexpr repeated_chars_iterator(
26 char const * first,
27 difference_type size,
28 difference_type n) noexcept :
29 first_(first),
30 size_(size),
31 n_(n)
32 {}
33
34 constexpr reference operator*() const noexcept
35 {
36 return first_[n_ % size_];
37 }
38
39 constexpr value_type operator[](difference_type n) const noexcept
40 {
41 return first_[(n_ + n) % size_];
42 }
43
44 constexpr repeated_chars_iterator & operator++() noexcept
45 {
46 ++n_;
47 return *this;
48 }
49 constexpr repeated_chars_iterator operator++(int)noexcept
50 {
51 repeated_chars_iterator retval = *this;
52 ++*this;
53 return retval;
54 }
55 constexpr repeated_chars_iterator & operator+=(difference_type n) noexcept
56 {
57 n_ += n;
58 return *this;
59 }
60
61 constexpr repeated_chars_iterator & operator--() noexcept
62 {
63 --n_;
64 return *this;
65 }
66 constexpr repeated_chars_iterator operator--(int)noexcept
67 {
68 repeated_chars_iterator retval = *this;
69 --*this;
70 return retval;
71 }
72 constexpr repeated_chars_iterator & operator-=(difference_type n) noexcept
73 {
74 n_ -= n;
75 return *this;
76 }
77
78 friend constexpr bool operator==(
79 repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
80 {
81 return lhs.first_ == rhs.first_ && lhs.n_ == rhs.n_;
82 }
83 friend constexpr bool operator!=(
84 repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
85 {
86 return !(lhs == rhs);
87 }
88 friend constexpr bool operator<(
89 repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
90 {
91 return lhs.first_ == rhs.first_ && lhs.n_ < rhs.n_;
92 }
93 friend constexpr bool operator<=(
94 repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
95 {
96 return lhs == rhs || lhs < rhs;
97 }
98 friend constexpr bool operator>(
99 repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
100 {
101 return rhs < lhs;
102 }
103 friend constexpr bool operator>=(
104 repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
105 {
106 return rhs <= lhs;
107 }
108
109 friend constexpr repeated_chars_iterator
110 operator+(repeated_chars_iterator lhs, difference_type rhs) noexcept
111 {
112 return lhs += rhs;
113 }
114 friend constexpr repeated_chars_iterator
115 operator+(difference_type lhs, repeated_chars_iterator rhs) noexcept
116 {
117 return rhs += lhs;
118 }
119 friend constexpr repeated_chars_iterator
120 operator-(repeated_chars_iterator lhs, difference_type rhs) noexcept
121 {
122 return lhs -= rhs;
123 }
124 friend constexpr difference_type operator-(
125 repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
126 {
127 return lhs.n_ - rhs.n_;
128 }
129
130 private:
131 char const * first_;
132 difference_type size_;
133 difference_type n_;
134 };
135```
136
137into this:
138
139```c++
140struct repeated_chars_iterator : boost::stl_interfaces::iterator_interface<
141 repeated_chars_iterator,
142 std::random_access_iterator_tag,
143 char,
144 char>
145{
146 constexpr repeated_chars_iterator() noexcept :
147 first_(nullptr),
148 size_(0),
149 n_(0)
150 {}
151 constexpr repeated_chars_iterator(
152 char const * first, difference_type size, difference_type n) noexcept :
153 first_(first),
154 size_(size),
155 n_(n)
156 {}
157
158 constexpr char operator*() const noexcept { return first_[n_ % size_]; }
159 constexpr repeated_chars_iterator & operator+=(std::ptrdiff_t i) noexcept
160 {
161 n_ += i;
162 return *this;
163 }
164 constexpr auto operator-(repeated_chars_iterator other) const noexcept
165 {
166 return n_ - other.n_;
167 }
168
169private:
170 char const * first_;
171 difference_type size_;
172 difference_type n_;
173};
174```
175
176The code size savings are even more dramatic for `view_interface` and
177`container_interface`! If you don't ever write iterators, range views, or
178containers, this is not for you.
179
180Online docs: https://boostorg.github.io/stl_interfaces.
181
182This library includes a temporary implementation for those who wish to experiment with
183a concept-constrained version before C++20 is widely implemented. Casey Carter's cmcstl2
184is an implementation of the `std::ranges` portion of the C++20 standard library. To use it:
185
186- check out the cmcstl2 branch of this library; then
187
188- put its headers in your include path, so that they can be included with
189 `#include <stl2/foo.hpp>`; and
190
191- build with GCC 8 or 9, including the `-fconcepts` and `-std=c++2a` flags.
192
193GCC 8 and 9 are the only compilers with an adequate concepts implementation at
194the time of this writing.
195
196
197[](https://travis-ci.org/boostorg/stl_interfaces)
198[](https://ci.appveyor.com/project/tzlaine/stl-interfaces)
199[](LICENSE_1_0.txt)
200
){kind=link}
){kind=link}