📚 Document counting_iterator

Problem:
- `counting_iterator` is undiscoverable because it is not documented.

Solution:
- Add documentation for `counting_iterator`.

Author: elbeno

README.md

@@ -19,6 +19,6 @@ Compiler support:
 
 | Branch | GCC versions | Clang versions |
 | --- | --- | --- |
-| [main](https://github.com/intel/cpp-std-extensions/tree/main) | 12 thru 14 | 18 thru 21 |
+| [main](https://github.com/intel/cpp-std-extensions/tree/main) | 12 thru 14 | 18 thru 22 |
 | [cpp20](https://github.com/intel/cpp-std-extensions/tree/cpp20) | 12 thru 14 | 14 thru 21 |
 

docs/intro.adoc

@@ -16,20 +16,15 @@
 
 The following compilers are supported:
 
-* clang 14
-* clang 15
-* clang 16
-* clang 17
 * clang 18
 * clang 19
 * clang 20
-* clang 21
+* clang 22
 * gcc 12
 * gcc 13
 * gcc 14
 
-In general, `stdx` supports the C\\++17 standard; however some functionality is
-available only in C++20 and later.
+In general, `stdx` targets the C++23 standard.
 
 === Dependencies
 

docs/iterator.adoc

@@ -23,3 +23,27 @@ constexpr auto c = stdx::ct_capacity(a); // std::size_t{4}
 * `stdx::cx_vector`
 
 `ct_capacity_v` is a corresponding variable template of type `std::size_t`.
+
+=== `counting_iterator`
+
+A `counting_iterator` is a random access iterator that counts up indefinitely
+from some integral starting value. It is useful for enumerating sequences:
+
+[source,cpp]
+----
+stdx::for_each(
+    std::cbegin(input), std::cend(input),
+    [](auto const &elem, auto idx) {
+      // do something with element and index
+    },
+    stdx::counting_iterator{});
+----
+
+By default, it produces `int` values starting from `0`.
+It also can be given a starting value, and it will respect the type:
+
+[source,cpp]
+----
+auto i1 = stdx::counting_iterator{17};  // 17, 18, 19...
+auto i2 = stdx::counting_iterator{'A'}; // A, B, C...
+----

test/algorithm.cpp

@@ -1,4 +1,5 @@
 #include <stdx/algorithm.hpp>
+#include <stdx/iterator.hpp>
 #include <stdx/tuple_algorithms.hpp>
 #include <stdx/tuple_destructure.hpp>
 
@@ -61,6 +62,19 @@ TEST_CASE("n-ary for_each", "[algorithm]") {
     CHECK(output == std::array{3, 6, 9, 12});
 }
 
+TEST_CASE("for_each with counting_iterator", "[algorithm]") {
+    auto const input = std::array{1, 2, 3, 4};
+    auto output = decltype(input){};
+    auto [op, i] = stdx::for_each(
+        std::cbegin(input), std::cend(input),
+        [it = std::begin(output)](auto... ns) mutable {
+            *it++ = (0 + ... + ns);
+        },
+        stdx::counting_iterator{1});
+    CHECK(i == stdx::counting_iterator{5});
+    CHECK(output == std::array{2, 4, 6, 8});
+}
+
 TEST_CASE("unary for_each_n", "[algorithm]") {
     auto const input = std::array{1, 2, 3, 4};
     auto sum = 0;