[ceph.git] / ceph / src / boost / libs / stl_interfaces / README.md

# stl_interfaces

An updated C++20-friendly version of the `iterator_facade` and
`iterator_adaptor` parts of Boost.Iterator (now called `iterator_interface`);
a pre-C++20 version of C++20's `view_interface`; and a new template called
`container_interface`, meant to aid the creation of new containers; all
targeting standardization.  This library requires at least C++14.

For the iterator portion -- if you need to write an iterator, `iterator_interface` turns this:

```c++
    struct repeated_chars_iterator
    {
        using value_type = char;
        using difference_type = std::ptrdiff_t;
        using pointer = char const *;
        using reference = char const;
        using iterator_category = std::random_access_iterator_tag;

        constexpr repeated_chars_iterator() noexcept :
            first_(nullptr),
            size_(0),
            n_(0)
        {}
        constexpr repeated_chars_iterator(
            char const * first,
            difference_type size,
            difference_type n) noexcept :
            first_(first),
            size_(size),
            n_(n)
        {}

        constexpr reference operator*() const noexcept
        {
            return first_[n_ % size_];
        }

        constexpr value_type operator[](difference_type n) const noexcept
        {
            return first_[(n_ + n) % size_];
        }

        constexpr repeated_chars_iterator & operator++() noexcept
        {
            ++n_;
            return *this;
        }
        constexpr repeated_chars_iterator operator++(int)noexcept
        {
            repeated_chars_iterator retval = *this;
            ++*this;
            return retval;
        }
        constexpr repeated_chars_iterator & operator+=(difference_type n) noexcept
        {
            n_ += n;
            return *this;
        }

        constexpr repeated_chars_iterator & operator--() noexcept
        {
            --n_;
            return *this;
        }
        constexpr repeated_chars_iterator operator--(int)noexcept
        {
            repeated_chars_iterator retval = *this;
            --*this;
            return retval;
        }
        constexpr repeated_chars_iterator & operator-=(difference_type n) noexcept
        {
            n_ -= n;
            return *this;
        }

        friend constexpr bool operator==(
            repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
        {
            return lhs.first_ == rhs.first_ && lhs.n_ == rhs.n_;
        }
        friend constexpr bool operator!=(
            repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
        {
            return !(lhs == rhs);
        }
        friend constexpr bool operator<(
            repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
        {
            return lhs.first_ == rhs.first_ && lhs.n_ < rhs.n_;
        }
        friend constexpr bool operator<=(
            repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
        {
            return lhs == rhs || lhs < rhs;
        }
        friend constexpr bool operator>(
            repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
        {
            return rhs < lhs;
        }
        friend constexpr bool operator>=(
            repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
        {
            return rhs <= lhs;
        }

        friend constexpr repeated_chars_iterator
        operator+(repeated_chars_iterator lhs, difference_type rhs) noexcept
        {
            return lhs += rhs;
        }
        friend constexpr repeated_chars_iterator
        operator+(difference_type lhs, repeated_chars_iterator rhs) noexcept
        {
            return rhs += lhs;
        }
        friend constexpr repeated_chars_iterator
        operator-(repeated_chars_iterator lhs, difference_type rhs) noexcept
        {
            return lhs -= rhs;
        }
        friend constexpr difference_type operator-(
            repeated_chars_iterator lhs, repeated_chars_iterator rhs) noexcept
        {
            return lhs.n_ - rhs.n_;
        }

    private:
        char const * first_;
        difference_type size_;
        difference_type n_;
    };
```

into this:

```c++
struct repeated_chars_iterator : boost::stl_interfaces::iterator_interface<
                                     repeated_chars_iterator,
                                     std::random_access_iterator_tag,
                                     char,
                                     char>
{
    constexpr repeated_chars_iterator() noexcept :
        first_(nullptr),
        size_(0),
        n_(0)
    {}
    constexpr repeated_chars_iterator(
        char const * first, difference_type size, difference_type n) noexcept :
        first_(first),
        size_(size),
        n_(n)
    {}

    constexpr char operator*() const noexcept { return first_[n_ % size_]; }
    constexpr repeated_chars_iterator & operator+=(std::ptrdiff_t i) noexcept
    {
        n_ += i;
        return *this;
    }
    constexpr auto operator-(repeated_chars_iterator other) const noexcept
    {
        return n_ - other.n_;
    }

private:
    char const * first_;
    difference_type size_;
    difference_type n_;
};
```

The code size savings are even more dramatic for `view_interface` and
`container_interface`! If you don't ever write iterators, range views, or
containers, this is not for you.

Online docs: https://boostorg.github.io/stl_interfaces.

This library includes a temporary implementation for those who wish to experiment with
a concept-constrained version before C++20 is widely implemented.  Casey Carter's cmcstl2
is an implementation of the `std::ranges` portion of the C++20 standard library.  To use it:

- check out the cmcstl2 branch of this library; then

- put its headers in your include path, so that they can be included with
  `#include <stl2/foo.hpp>`; and

- build with GCC 8 or 9, including the `-fconcepts` and `-std=c++2a` flags.

GCC 8 and 9 are the only compilers with an adequate concepts implementation at
the time of this writing.


[![Build Status](https://travis-ci.org/boostorg/stl_interfaces.svg?branch=develop)](https://travis-ci.org/boostorg/stl_interfaces)
[![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)
[![License](https://img.shields.io/badge/license-boost-brightgreen.svg)](LICENSE_1_0.txt)
Commit	Line	Data
20effc67 TL	1	# stl_interfaces
	2
	3	An updated C++20-friendly version of the `iterator_facade` and
	4	`iterator_adaptor` parts of Boost.Iterator (now called `iterator_interface`);
	5	a 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
	7	targeting standardization. This library requires at least C++14.
	8
	9	For 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
137	into this:
138
139	```c++
140	struct 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
169	private:
170	char const * first_;
171	difference_type size_;
172	difference_type n_;
173	};
174	```
175
176	The code size savings are even more dramatic for `view_interface` and
177	`container_interface`! If you don't ever write iterators, range views, or
178	containers, this is not for you.
179
180	Online docs: https://boostorg.github.io/stl_interfaces.
181
182	This library includes a temporary implementation for those who wish to experiment with
183	a concept-constrained version before C++20 is widely implemented. Casey Carter's cmcstl2
184	is 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
193	GCC 8 and 9 are the only compilers with an adequate concepts implementation at
194	the 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)