Implement iterate algorithms

Problem:
- There is no algorithm that generalizes `std::iota`. Filling a range 2
  elements at a time is hard, more complex patterns are increasingly
  difficult.

Solution:
- Implement `iterate` and `iterate_n` which fill a range based on the
  execution of a binary operation which takes the previous value.

Author: jgopel

doc/algorithm.qbk

@@ -224,6 +224,16 @@ Write a sequence of n increasing values to an output iterator
 Raise a value to an integral power ([^constexpr] since C++14)
 [endsect:power]
 
+[section:iterate                   iterate                   ]
+[*[^[link header.boost.algorithm.iterate_hpp                         iterate]                     ] ]
+Store the result of a unary function to each element of a range. This is a generalization of iota.
+[endsect:iterate]
+
+[section:iterate                   iterate                   ]
+[*[^[link header.boost.algorithm.iterate_hpp                         iterate]                     ] ]
+Store the result of a unary function to n element of a range. This is a generalization of iota.
+[endsect:iterate]
+
 [endsect:misc_inner_algorithms]
 
 [endsect:Misc]

include/boost/algorithm/iterate.hpp

@@ -0,0 +1,43 @@
+/*
+   Copyright (c) Jonathan Gopel 2022.
+
+   Distributed under the Boost Software License, Version 1.0. (See accompanying
+   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+*/
+
+#ifndef BOOST_ALGORITHM_ITERATE_HPP
+#define BOOST_ALGORITHM_ITERATE_HPP
+
+#include <boost/config.hpp>
+
+#include <utility>
+
+namespace boost {
+namespace algorithm {
+
+template <class OutputIterator, class TInit, class UnaryOperation>
+BOOST_CXX14_CONSTEXPR TInit iterate(OutputIterator first, OutputIterator last,
+                                    TInit init,
+                                    UnaryOperation op) // TODO: BOOST_NOEXCEPT?
+{
+  for (; first != last; ++first, init = op(std::move(init))) {
+    *first = init;
+  }
+  return init;
+}
+
+template <class OutputIterator, class Size, class TInit, class UnaryOperation>
+BOOST_CXX14_CONSTEXPR std::pair<OutputIterator, TInit>
+iterate(OutputIterator first, Size n, TInit init,
+        UnaryOperation op) // TODO: BOOST_NOEXCEPT?
+{
+  for (; n > 0; n -= 1, ++first, init = op(std::move(init))) {
+    *first = init;
+  }
+  return std::make_pair(std::move(first), std::move(init));
+}
+
+} // namespace algorithm
+} // namespace boost
+
+#endif // BOOST_ALGORITHM_ITERATE_HPP

test/Jamfile.v2

@@ -90,6 +90,8 @@ alias unit_test_framework
 # Find tests
      [ run find_not_test.cpp unit_test_framework        : : : : find_not_test ]
      [ run find_backward_test.cpp unit_test_framework   : : : : find_backward_test ]
+# Iterate tests
+     [ run iterate_test.cpp unit_test_framework : : : : iterate_test ]
    ;
 }
 

test/iterate_test.cpp

@@ -0,0 +1,118 @@
+/*
+   Copyright (c) Jonathan Gopel 2022.
+
+   Distributed under the Boost Software License, Version 1.0. (See accompanying
+   file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+*/
+
+#include <boost/algorithm/iterate.hpp>
+
+#include <boost/config.hpp>
+
+#define BOOST_TEST_MAIN
+#include <boost/test/unit_test.hpp>
+
+#include <boost/algorithm/cxx14/equal.hpp>
+
+#include <algorithm>
+#include <array>
+#include <functional>
+
+using data_t = int;
+
+static const int NUM_ELEMENTS = 4;
+
+void test_iterate() {
+  { // iota
+    std::array<data_t, NUM_ELEMENTS> actual{};
+
+    boost::algorithm::iterate(
+        std::begin(actual), std::end(actual), 15,
+        [](const data_t value) -> data_t { return value + 1; });
+
+    std::array<data_t, NUM_ELEMENTS> expected{15, 16, 17, 18};
+    BOOST_CHECK(std::size(actual) == std::size(expected));
+    BOOST_CHECK(
+        std::equal(std::begin(actual), std::end(actual), std::begin(expected)));
+  }
+  { // striding
+    std::array<data_t, NUM_ELEMENTS> actual{};
+
+    boost::algorithm::iterate(
+        std::begin(actual), std::end(actual), 15,
+        [](const data_t value) -> data_t { return value + 2; });
+
+    std::array<data_t, NUM_ELEMENTS> expected{15, 17, 19, 21};
+    BOOST_CHECK(std::size(actual) == std::size(expected));
+    BOOST_CHECK(
+        std::equal(std::begin(actual), std::end(actual), std::begin(expected)));
+  }
+}
+
+void test_iterate_n() {
+  { // iota
+    std::array<data_t, NUM_ELEMENTS> actual{};
+
+    boost::algorithm::iterate(
+        std::begin(actual), std::size(actual), 15,
+        [](const data_t value) -> data_t { return value + 1; });
+
+    std::array<data_t, NUM_ELEMENTS> expected{15, 16, 17, 18};
+    BOOST_CHECK(std::size(actual) == std::size(expected));
+    BOOST_CHECK(
+        std::equal(std::begin(actual), std::end(actual), std::begin(expected)));
+  }
+  { // striding
+    std::array<data_t, NUM_ELEMENTS> actual{};
+
+    boost::algorithm::iterate(
+        std::begin(actual), std::size(actual), 15,
+        [](const data_t value) -> data_t { return value + 2; });
+
+    std::array<data_t, NUM_ELEMENTS> expected{15, 17, 19, 21};
+    BOOST_CHECK(std::size(actual) == std::size(expected));
+    BOOST_CHECK(
+        std::equal(std::begin(actual), std::end(actual), std::begin(expected)));
+  }
+}
+
+BOOST_CXX14_CONSTEXPR inline bool constexpr_test_iterate() {
+  std::array<data_t, NUM_ELEMENTS> actual{};
+
+  boost::algorithm::iterate(
+      std::begin(actual), std::end(actual), 15,
+      [](const data_t value) -> data_t { return value + 1; });
+
+  std::array<data_t, NUM_ELEMENTS> expected{15, 16, 17, 18};
+  return (std::size(actual) == std::size(expected)) and
+         boost::algorithm::equal(std::begin(actual), std::end(actual),
+                                 std::begin(expected), std::end(expected));
+}
+
+BOOST_CXX14_CONSTEXPR inline bool constexpr_test_iterate_n() {
+  std::array<data_t, NUM_ELEMENTS> actual{};
+
+  boost::algorithm::iterate(
+      std::begin(actual), std::size(actual), 15,
+      [](const data_t value) -> data_t { return value + 1; });
+
+  std::array<data_t, NUM_ELEMENTS> expected{15, 16, 17, 18};
+  return (std::size(actual) == std::size(expected)) and
+         boost::algorithm::equal(std::begin(actual), std::end(actual),
+                                 std::begin(expected), std::end(expected));
+}
+
+BOOST_AUTO_TEST_CASE(test_main) {
+  test_iterate();
+  test_iterate_n();
+
+  {
+    BOOST_CXX14_CONSTEXPR bool result = constexpr_test_iterate();
+    BOOST_CHECK(result);
+  }
+
+  {
+    BOOST_CXX14_CONSTEXPR bool result = constexpr_test_iterate_n();
+    BOOST_CHECK(result);
+  }
+}