[doc] lots of doc and CHANGELOG

Author: h-2

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## unreleased
+
+### Progress implementing std::views::X equivalents
+
+| Standard    | adaptors |factories | Comment                    |
+|-------------|---------:|---------:|----------------------------|
+| C++20       | 14/15    |   5/5    | `lazy_split` not planned   |
+| C++23       |  2/13    |   1/1    |                            |
+| C++26       |  1/03    |   --     |                            |
+| C++29       |  1/??    |   --     |                            |
+| extra       |     1    |          |                            |
+

docs/feature_table.md

@@ -4,6 +4,7 @@
 
 | Range adaptor              | $O(n)$ constr  | min cat | max cat  | sized | common    | Remarks                                  |
 |----------------------------|:--------------:|---------|----------|:-----:|:---------:|------------------------------------------|
+| `radr::all`                |                | input   | contig   |  =    |  =        |                                          |
 | `radr::as_const`           |                | fwd     | contig   |  =    |  =        | make the range *and* its elements const  |
 | `radr::as_rvalue`          |                | input   | input/ra |  =    |  =        | returns only input ranges in C++20       |
 | `radr::drop(n)`            | !(ra+sized)    | input   | contig   |  =    |  ⊜        |                                          |
@@ -16,12 +17,12 @@
 | `radr::slice(m, n)`        | !(ra+sized)    | input   | contig   |  =    |  =        | get subrange between m and n             |
 | `radr::split(pat)`         | always         | input   | fwd      |  -    |  ⊝        |                                          |
 | `radr::take(n)`            |                | input   | contig   |  =    |  ra+sized |                                          |
-| `radr::take_exactly(n)`    |                | input   | contig   |  +    |  ra+sized | turns unsized into size of n             |
 | `radr::take_while(fn)`     |                | input   | contig   |  -    |  -        |                                          |
 | `radr::to_common`          | !(common)      | fwd     | contig   |  ⊕    |  +        |                                          |
 | `radr::to_single_pass`     |                | input   | input    |  -    |  -        | demotes range category to single-pass    |
 | `radr::transform(fn)`      |                | input   | ra       |  =    |  =        |                                          |
 | `radr::values`             |                | input   | ra       |  =    |  =        |                                          |
+| `radr::uncheckd_take(n)`   |                | input   | contig   |  +    |  ra+sized | turns unsized into size of n             |
 
 **min cat** underlying range required to be at least input (`input_range`), fwd (`forward_range`), bidi (`bidirectional_range`),
 ra (`random_access_range`) or contig (`contiguous_range`)<br>

docs/implementation_status.md

@@ -4,6 +4,17 @@ This library is a **work-in-progress**.
 We try to stay close to standard library interfaces, but we neither promise full API compatibility with `std::ranges::` nor do we currently promise stability between releases of this library.
 The latter will likely change at some point.
 
+### Progress implementing std::views::X equivalents (adaptor objects and factory objects)
+
+| Standard    | adaptors |factories | Comment                    |
+|-------------|---------:|---------:|----------------------------|
+| C++20       | 14/15    |   5/5    | `lazy_split` not planned   |
+| C++23       |  2/13    |   1/1    |                            |
+| C++26       |  1/03    |   --     |                            |
+| C++29       |  1/??    |   --     |                            |
+| extra       |     1    |          |                            |
+
+See below for details. Note that the list of adaptors in C++26 and C++29 is not yet final.
 
 ## Range adaptor classes
 
@@ -22,27 +33,28 @@ Instead all range adaptor objects in this library (see below) return a specialis
 
 We plan to add equivalent objects for all standard library adaptors.
 
-| Range adaptors (objects) | C++XY | | Equivalent in `std::`          | C++XY     | Differences of `radr` objects            |
-|--------------------------|-------|-|--------------------------------|-----------|------------------------------------------|
-| `radr::as_const`         | C++20 | | `std::views::as_const`         | **C++23** | make the range *and* its elements const  |
-| `radr::as_rvalue`        | C++20 | | `std::views::as_rvalue`        | **C++23** | *returns only input ranges in C++20      |
-| `radr::drop(n)`          | C++20 | | `std::views::drop`             | C++20     |                                          |
-| `radr::drop_while(fn)`   | C++20 | | `std::views::drop_while`       | C++20     |                                          |
-| `radr::elements<I>`      | C++20 | | `std::views::elements`         | C++20     |                                          |
-| `radr::filter(fn)`       | C++20 | | `std::views::filter`           | C++20     |                                          |
-| `radr::join`             | C++20 | | `std::views::join`             | C++20     |                                          |
-| `radr::keys`             | C++20 | | `std::views::keys`             | C++20     |                                          |
-| `radr::reverse`          | C++20 | | `std::views::reverse`          | C++20     |                                          |
-| `radr::slice(m, n)`      | C++20 | | *not yet available*            |           | get subrange between m and n             |
-| `radr::split(pat)`       | C++20 | | `std::views::split`            | C++20     |                                          |
-| *not planned*            | C++20 | | `std::views::lazy_split`       | C++20     | use `radr::to_single_pass | radr::split` |
-| `radr::take(n)`          | C++20 | | `std::views::take`             | C++20     |                                          |
-| `radr::take_exactly(n)`  | C++20 | | *not yet available*            |           | turns unsized into sized                 |
-| `radr::take_while(fn)`   | C++20 | | `std::views::take_while`       | C++20     |                                          |
-| `radr::to_common`        | C++20 | | `std::views::common`[^diff]    | C++20     | turns non-common into common             |
-| `radr::to_single_pass`   | C++20 | | `std::views::to_input`[^diff]  | **C++26** | demotes range category to input          |
-| `radr::transform(fn)`    | C++20 | | `std::views::transform`        | C++20     |                                          |
-| `radr::values`           | C++20 | | `std::views::values`           | C++20     |                                          |
+| Range adaptors (objects)  | C++XY | | Equivalent in `std::`          | C++XY     | Differences of `radr` objects            |
+|---------------------------|-------|-|--------------------------------|-----------|------------------------------------------|
+| `radr::all`               | C++20 | | `std::views::all`              | C++20     |                                          |
+| `radr::as_const`          | C++20 | | `std::views::as_const`         | **C++23** | make the range *and* its elements const  |
+| `radr::as_rvalue`         | C++20 | | `std::views::as_rvalue`        | **C++23** | *returns only input ranges in C++20      |
+| `radr::drop(n)`           | C++20 | | `std::views::drop`             | C++20     |                                          |
+| `radr::drop_while(fn)`    | C++20 | | `std::views::drop_while`       | C++20     |                                          |
+| `radr::elements<I>`       | C++20 | | `std::views::elements`         | C++20     |                                          |
+| `radr::filter(fn)`        | C++20 | | `std::views::filter`           | C++20     |                                          |
+| `radr::join`              | C++20 | | `std::views::join`             | C++20     |                                          |
+| `radr::keys`              | C++20 | | `std::views::keys`             | C++20     |                                          |
+| `radr::reverse`           | C++20 | | `std::views::reverse`          | C++20     |                                          |
+| `radr::slice(m, n)`       | C++20 | | *not yet available*            |           | get subrange between m and n             |
+| `radr::split(pat)`        | C++20 | | `std::views::split`            | C++20     |                                          |
+| *not planned*             | C++20 | | `std::views::lazy_split`       | C++20     | use `radr::to_single_pass ╎ radr::split` |
+| `radr::take(n)`           | C++20 | | `std::views::take`             | C++20     |                                          |
+| `radr::take_while(fn)`    | C++20 | | `std::views::take_while`       | C++20     |                                          |
+| `radr::to_common`         | C++20 | | `std::views::common`[^diff]    | C++20     | turns non-common into common             |
+| `radr::to_single_pass`    | C++20 | | `std::views::to_input`[^diff]  | **C++26** | demotes range category to input          |
+| `radr::transform(fn)`     | C++20 | | `std::views::transform`        | C++20     |                                          |
+| `radr::values`            | C++20 | | `std::views::values`           | C++20     |                                          |
+| `radr::unchecked_take(n)` | C++20 | | `std::views::unchecked_take`   | **C++29** | turns unsized into sized                 |
 
 All range adaptors from this library are available in C++20, although `radr::as_rvalue` behaves slightly different between modes.
 
@@ -62,6 +74,8 @@ All range adaptors from this library are available in C++20, although `radr::as_
 | `radr::repeat(val[, bound])`  | C++20 | | `std::views::repeat`    | **C++23** | allows indirect storage and static bounds |
 | `radr::single(val)`           | C++20 | | `std::views::single`    | C++20     | allows indirect storage                   |
 
+The standard library groups `counted` with "range adaptors" and not "range factories", 
+although you create it on an iterator and not a range.
 
 ## Notable functions
 

include/radr/rad/split.hpp

@@ -13,12 +13,14 @@
 #pragma once
 
 #include <iterator>
+#include <ranges>
 
 #include "radr/custom/subborrow.hpp"
 #include "radr/detail/detail.hpp"
 #include "radr/detail/pipe.hpp"
 #include "radr/factory/single.hpp"
 #include "radr/rad/as_const.hpp"
+#include "radr/rad/to_single_pass.hpp"
 #include "radr/range_access.hpp"
 
 namespace radr::detail
@@ -305,25 +307,71 @@ inline namespace cpo
 {
 
 /*!\brief radr::split(urange, pattern)
+ * \tparam URange Type of \p urange.
+ * \tparam Patttern Type of \p pattern.
  * \param urange The underlying range.
  * \param pattern The pattern to split by.
  * \details
  *
+ * Turns a range into a range-of-ranges, by splitting on the provided pattern.
+ * The pattern will not be included in the output.
+ *
  * ## Multi-pass ranges
  *
  * The pattern can be one of:
  *   * a std::ref-wrapped lvalue of a range whose elements are comparable to the underlying range.
  *   * an rvalue of a range whose elements are comparable to the underlying range (only if the pattern is a borrowed_mp_range).
  *   * a std::ref-wrapped lvalue of a delimiter element that is comparable to elements of the underlying range.
  *   * an rvalue of a delimiter element that is comparable to elements of the underlying range (only if that value is default constructible and copyable without throwing).
+ *   * Note that string-literal patterns (`"foobar"`) are not supported. Use string_views instead (`"foobar"sv`).
+ *
+ * Requirements:
+ *   * `radr::mp_range<URange>`
+ *   * for Pattern, see above.
+ *
+ * The returned "outer range"-type models radr::mp_range and preserves std::ranges::borrowed_range.
+ * It is never bidirectional, common, sized or mutable.
+ *
+ * The returned "inner range"-type is created via the radr::subborrow customisation point.
+ * Unless customised otherwise, it always models:
+ *   * std::ranges::borrowed_range
+ *   * std::ranges::sized_range
+ *   * radr::common_range
+ *
+ * It preserves from the underlying range:
+ *   * categories up to std::ranges::contiguous_range
+ *   * radr::mutable_range
+ *   * radr::constant_range
+ *
+ * Construction of the adaptor is in O(n), because the first inner range is searched on construction
+ * (which could be the full range).
  *
- * Note that string-literal patterns (`"foobar"`) are not supported. Use string_views instead (`"foobar"sv`).
+ * ### Notable differences to std::views::split
+ *
+ * Due to radr::subborrow being used, splitting a string_view results in string_views:
+ *
+ * ```cpp
+ * auto subs = "foo bar bax"sv | radr::split(' ');
+ * auto frst = *subs.begin(); // this is a string_view, too
+ * ```
  *
  * ## Single-pass ranges
  *
- * The pattern can be delimiter element (rvalue or lvalue) comparable to the elements of the underlying range.
+ * The pattern must be delimiter element (rvalue or lvalue) comparable to the elements of the underlying range.
+ * Ranges as patterns are not supported for single-pass inputs.
+ *
+ * Requirements:
+ *   * `std::ranges::input_range<URange>`
+ *   * `std::equality_comparable_with<std::ranges::range_reference_t<URange>, Pattern>`
+ *
+ * Both, the "outer range"-type and the "inner range"-type are a radr::generator.
+ * This design is fully lazy; no read-ahead happens.
  *
  */
 inline constexpr auto split = detail::pipe_with_args_fn{detail::split_coro, detail::split_borrow};
+
+[[deprecated(
+  "Instead of radr::lazy_split, just use radr::split. Or use `radr::to_single_pass | radr::split` which is lazier, but "
+  "does not support range-as-a-pattern.")]] inline constexpr auto lazy_split = split;
 } // namespace cpo
 } // namespace radr

include/radr/rad/take.hpp

@@ -142,6 +142,53 @@ namespace radr
 
 inline namespace cpo
 {
+/*!\brief Take up to n elements from the underlying range.
+ * \param[in] urange The underlying range.
+ * \param[in] n Number of elements.
+ * \tparam URange Type of \p urange.
+ * \details
+ *
+ * Takes \p n elements from \p urange, or all elements if \p urange is smaller than \p n.
+ *
+ * ## Multi-pass ranges
+ *
+ * Requirements:
+ *   * `radr::mp_range<URange>`
+ *
+ * For underlying ranges that are radr::safely_indexable_range, this adaptor invokes the radr::subborrow
+ * customisation point.
+ * Unless customised otherwise and if the range was sized, it will preserve all range concepts and be
+ * transparent (same iterator and senintel types as \p urange).
+ * If it was infinite, it will become sized and common.
+ *
+ * For underlying ranges that are not radr::safely_indexable_range, this adaptors preserves:
+ *   * categories up to std::ranges::contiguous_range
+ *   * std::ranges::borrowed_range
+ *   * radr::mutable_range
+ *   * radr::constant_range
+ *   * std::ranges::sized_range
+ *
+ * It does not preserve:
+ *   * radr::common_range
+ *
+ * ### Notable differences to std::views::take
+ *
+ *   * Subrange customisation through radr::subborrow.
+ *   * Returns sized, common ranges for infinite inputs like radr::iota and radr::repeat.
+ *
+ * ## Single-pass ranges
+ *
+ * Requirements:
+ *   * `std::ranges::input_range<URange>`
+ *
+ * ### Notable difference std::views::take
+ *
+ * std::views::take takes \p n elements from the underlying range but then silently advances over the `n+1`-th element,
+ * resulting in unexpected behaviour (e.g. skipped/missing elements in a stream).
+ * See https://www.youtube.com/watch?v=dvi0cl8ccNQ for an explenation.
+ *
+ * We **fixed this bug** for radr::take on single-pass ranges.
+ */
 inline constexpr auto take = detail::pipe_with_args_fn{detail::take_coro, detail::take_borrow};
 } // namespace cpo
 } // namespace radr