From 2168fc894815bd2ebbcecea32142f1cfc6c384f2 Mon Sep 17 00:00:00 2001 From: Zach Laine Date: Thu, 22 Aug 2019 17:27:58 -0500 Subject: [PATCH] Document the existence of v2, and v1 vs. v2 differences. --- doc/intro.qbk | 6 ++++ doc/stl_interfaces.qbk | 1 + doc/tutorial.qbk | 71 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+) diff --git a/doc/intro.qbk b/doc/intro.qbk index 28e8a3c..b98c1be 100644 --- a/doc/intro.qbk +++ b/doc/intro.qbk @@ -21,6 +21,12 @@ container requirements in the standard. _IFaces_ provides another template called _cont_iface_ that reduces the implementation and testing burden dramatically. +[note C++20 versions of _iter_iface_ and _cont_iface_ are provided (C++20 +provides `std::view_interface`). These are constrained templates using C++20 +concepts. These are in the `boost::stl_interfaces::v2` namespace, and are +considered experimental, because at the time of this writing, no +C++20-conforming compiler exists.] + [heading A Quick Example] Here is an example of the iterator portion of the library. Let's say that we diff --git a/doc/stl_interfaces.qbk b/doc/stl_interfaces.qbk index ef84897..81315c5 100644 --- a/doc/stl_interfaces.qbk +++ b/doc/stl_interfaces.qbk @@ -65,6 +65,7 @@ [def _CRTP_ [@https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern CRTP]] [def _Iterator_ [@https://www.boost.org/doc/libs/release/libs/iterator Boost.Iterator]] [def _Container_ [@https://www.boost.org/doc/libs/release/libs/container Boost.Container]] +[def _cmcstl2_ [@https://github.com/CaseyCarter/cmcstl2 cmcstl2]] [def _emdash_ \u2014] diff --git a/doc/tutorial.qbk b/doc/tutorial.qbk index a9194fa..4dd5310 100644 --- a/doc/tutorial.qbk +++ b/doc/tutorial.qbk @@ -887,3 +887,74 @@ There's nothing much to document about it; it works just like `std::reverse_iterator`. [endsect] + +[section The `v2` Namespace] + +_IFace_ contains an `inline v1` namespace. All the C++14-compatible +*`_interface` templates are implemnted there. Since `v1` is an `inline` +namespace, you can just access these templates without referring to `v1` at +all. + +In the `boost::stl_interfaces::v2` namespace, you will find C++20 versions of +_iter_iface_ and _cont_iface_ are provided; the C++20 standard library +provides `std::view_interface`. + +These are constrained templates using C++20 concepts, and are considered +experimental, because at the time of this writing, no C++20-conforming +compiler exists. + +For each template, you will find two versions: one that uses concepts and +templates defined in the C++20 standard library, and one that uses concepts +and templates defined in the _cmcstl2_ library. + +The first is the final version of the `v2` templates, for use with a +conforming C++20 compiler and standard library. + +The second is a temporary implementation for those who wish to experiment with +a concept-constrained version before C++20 is widely implemented. _cmcstl2_ +is an implementation of the `std::ranges` portion of the C++20 standard +library. To use it: + +- put its headers in your include path, so that they can be included with + `#include `, 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. + +[heading Differences between `v1` and `v2`] + +There are some differences between the `v1` and `v2` implementations, mostly +due to the differences between SFINAE and concepts. Most of these changes are +subtle, and will not be noticeable. + +Differences you will probably notice: + +- _view_iface_ and _cont_iface_ each have a `bool` non-type template parameter + `Contiguous` that indicates whether they have a `begin()` operation that + yields a contiguous iterator. Before C++20, there was no way of determining + that. The `v2` versions do not need this template parameter. + +- The `insert(position, n, value)` overload of _cont_iface_ _emdash_ the one + that inserts `n` copies of `value` before `position` _emdash_ is + unconstrained. That is because the proper constraint causes an infinite + recursion on every compiler I tried. This means that containers that you + should not be able to `insert()` into will still have the `insert(position, + n, value)` overload. The `v2` version is constrained with the identical + constraint, in concept form, and the constraint works as expected. + +Differnces you are less likely to notice: + +- In order to constrain all the member functions of the `v1` implementations + individually, it was necessary to make them templates. Most (though not + all) of the `v2` member functions are not templates. + +- The constraints on member functions in `v1` are all SFINAE-based. The + constraints on member functions in `v2` are all concept-based. + +The subtle differences between SFINAE and concepts and between templates and +non-templates in overload resolution may mean that these less-noticable +differences do affect your code, but this will be rare in practice. + +[endsect]