• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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[![Build Status](https://travis-ci.org/boostorg/stl_interfaces.svg?branch=develop)](https://travis-ci.org/boostorg/stl_interfaces)
198[![Build Status](https://ci.appveyor.com/api/projects/status/github/tzlaine/stl-interfaces?branch=develop&svg=true)](https://ci.appveyor.com/project/tzlaine/stl-interfaces)
199[![License](https://img.shields.io/badge/license-boost-brightgreen.svg)](LICENSE_1_0.txt)
200