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(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(init)) {
+    *first = init;
+  }
+  return std::make_pair(first, 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,131 @@
+/*
+   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 "iterator_test.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>
+#include <vector>
+
+typedef int data_t;
+
+static const int NUM_ELEMENTS = 4;
+
+BOOST_CONSTEXPR data_t add_one(const data_t value) { return value + 1; }
+
+BOOST_CONSTEXPR data_t add_two(const data_t value) { return value + 2; }
+
+void test_iterate() {
+  { // iota
+    std::vector<data_t> actual(NUM_ELEMENTS);
+
+    boost::algorithm::iterate(actual.begin(), actual.end(), 15, add_one);
+
+    std::vector<data_t> expected(NUM_ELEMENTS);
+    expected.at(0) = 15;
+    expected.at(1) = 16;
+    expected.at(2) = 17;
+    expected.at(3) = 18;
+    BOOST_CHECK(actual.size() == expected.size());
+    BOOST_CHECK(std::equal(actual.begin(), actual.end(), expected.begin()));
+  }
+  { // striding
+    std::vector<data_t> actual(NUM_ELEMENTS);
+
+    boost::algorithm::iterate(actual.begin(), actual.end(), 15, add_two);
+
+    std::vector<data_t> expected(NUM_ELEMENTS);
+    expected.at(0) = 15;
+    expected.at(1) = 17;
+    expected.at(2) = 19;
+    expected.at(3) = 21;
+    BOOST_CHECK(std::equal(actual.begin(), actual.end(), expected.begin()));
+  }
+}
+
+void test_iterate_n() {
+  { // iota
+    std::vector<data_t> actual(NUM_ELEMENTS);
+
+    boost::algorithm::iterate(actual.begin(), actual.size(), 15, add_one);
+
+    std::vector<data_t> expected(NUM_ELEMENTS);
+    expected.at(0) = 15;
+    expected.at(1) = 16;
+    expected.at(2) = 17;
+    expected.at(3) = 18;
+    BOOST_CHECK(actual.size() == expected.size());
+    BOOST_CHECK(std::equal(actual.begin(), actual.end(), expected.begin()));
+  }
+  { // striding
+    std::vector<data_t> actual(NUM_ELEMENTS);
+
+    boost::algorithm::iterate(actual.begin(), actual.size(), 15, add_two);
+
+    std::vector<data_t> expected(NUM_ELEMENTS);
+    expected.at(0) = 15;
+    expected.at(1) = 17;
+    expected.at(2) = 19;
+    expected.at(3) = 21;
+    BOOST_CHECK(actual.size() == expected.size());
+    BOOST_CHECK(std::equal(actual.begin(), actual.end(), expected.begin()));
+  }
+}
+
+BOOST_CXX14_CONSTEXPR inline bool constexpr_test_iterate() {
+  int actual[] = {0, 0, 0, 0};
+
+  boost::algorithm::iterate(input_iterator<int *>(actual),
+                            input_iterator<int *>(actual + NUM_ELEMENTS), 15,
+                            add_one);
+
+  int expected[] = {15, 16, 17, 18};
+  return boost::algorithm::equal(
+      input_iterator<int *>(actual),
+      input_iterator<int *>(actual + NUM_ELEMENTS),
+      input_iterator<int *>(expected),
+      input_iterator<int *>(expected + NUM_ELEMENTS));
+}
+
+BOOST_CXX14_CONSTEXPR inline bool constexpr_test_iterate_n() {
+  int actual[] = {0, 0, 0, 0};
+
+  boost::algorithm::iterate(input_iterator<int *>(actual), NUM_ELEMENTS, 15,
+                            add_one);
+
+  int expected[] = {15, 16, 17, 18};
+  return boost::algorithm::equal(
+      input_iterator<int *>(actual),
+      input_iterator<int *>(actual + NUM_ELEMENTS),
+      input_iterator<int *>(expected),
+      input_iterator<int *>(expected + NUM_ELEMENTS));
+}
+
+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);
+  }
+}