Add sorting functions that track number of swaps

Author: hmenke

c++/itertools/itertools.hpp

@@ -27,6 +27,7 @@
 #include "./range.hpp"
 #include "./slice.hpp"
 #include "./stride.hpp"
+#include "./sort.hpp"
 #include "./transform.hpp"
 #include "./zip.hpp"
 

c++/itertools/sort.hpp

@@ -0,0 +1,128 @@
+// Copyright (c) 2024 Simons Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0.txt
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Authors: Thomas Hahn, Olivier Parcollet, Nils Wentzell, chuffa
+
+/**
+ * @file
+ * @brief Provides functions for sorting ranges.
+ */
+
+#ifndef _ITERTOOLS_SORT_HPP
+#define _ITERTOOLS_SORT_HPP
+
+#include <algorithm>  // for iter_swap
+#include <cstddef>    // for size_t
+#include <functional> // for less
+#include <iterator>   // for forward_iterator, prev, random_access_iterator
+
+namespace itertools {
+
+  /**
+   * @ingroup sorting
+   * @brief Bubble sort
+   *
+   * @details Sort the elements in the range [@p first, @p last) in the order
+   * prescribed by the comparison function @p comp. The underlying sorting
+   * algorithm is bubble sort. The sorting is stable, i.e. already sorted
+   * elements will not be swapped. The number of swaps necessary to get the
+   * elements into sorted order is recorded and returned.
+   *
+   * Computational complexity: \f$\mathcal{O}(n^2)\f$
+   *
+   * This function is eager and puts the range in sorted order.
+   *
+   * @param first Forward iterator for the first element of the range.
+   * @param last Forward iterator for the element \a after the last of the range.
+   * @param comp Comparison function callable with two dereferenced iterators.
+   * @return Number of swaps necessary to sort the range.
+   */
+  template <class ForwardIt, class Compare>
+    requires std::forward_iterator<ForwardIt>
+  std::size_t bubble_sort(ForwardIt first, ForwardIt last, Compare comp) {
+    if (first == last) { return 0; }
+    std::size_t n_swaps = 0;
+    for (ForwardIt sorted = first; first != last; last = sorted) {
+      sorted = first;
+      for (ForwardIt curr = first, prev = first; ++curr != last; ++prev) {
+        if (comp(*curr, *prev)) {
+          std::iter_swap(curr, prev);
+          sorted = curr;
+          ++n_swaps;
+        }
+      }
+    }
+    return n_swaps;
+  }
+
+  /**
+   * @ingroup sorting
+   * @overload
+   *
+   * Sets the default comparison function to `std::less{}`.
+   */
+  template <class ForwardIt>
+    requires std::forward_iterator<ForwardIt>
+  std::size_t bubble_sort(ForwardIt first, ForwardIt last) {
+    return bubble_sort(first, last, std::less{});
+  }
+
+  /**
+   * @ingroup sorting
+   * @brief Insertion sort
+   *
+   * @details Sort the elements in the range [@p first, @p last) in the order
+   * prescribed by the comparison function @p comp. The underlying sorting
+   * algorithm is insertion sort. The sorting is stable, i.e. already sorted
+   * elements will not be swapped. The number of swaps necessary to get the
+   * elements into sorted order is recorded and returned.
+   *
+   * Computational complexity: \f$\mathcal{O}(n^2)\f$
+   *
+   * This function is eager and puts the range in sorted order.
+   *
+   * @param first Random-access iterator for the first element of the range.
+   * @param last Random-access iterator for the element \a after the last of the range.
+   * @param comp Comparison function callable with two dereferenced iterators.
+   * @return Number of swaps necessary to sort the range.
+   */
+  template <class RandomIt, class Compare>
+    requires std::random_access_iterator<RandomIt>
+  std::size_t insertion_sort(RandomIt first, RandomIt last, Compare comp) {
+    if (first == last) { return 0; }
+    std::size_t swaps = 0;
+    for (RandomIt i = std::next(first); i != last; ++i) {
+      for (RandomIt j = i; j != first && comp(*j, *std::prev(j)); --j) {
+        std::iter_swap(std::prev(j), j);
+        ++swaps;
+      }
+    }
+    return swaps;
+  }
+
+  /**
+   * @ingroup sorting
+   * @overload
+   *
+   * Sets the default comparison function to `std::less{}`.
+   */
+  template <class RandomIt>
+    requires std::random_access_iterator<RandomIt>
+  std::size_t insertion_sort(RandomIt first, RandomIt last) {
+    return insertion_sort(first, last, std::less{});
+  }
+
+} // namespace itertools
+
+#endif // _ITERTOOLS_SORT_HPP

doc/DoxygenLayout.xml

@@ -54,6 +54,10 @@
         </tab>
         <tab type="user" url="@ref itertools::product_range" title="product_range"/>
       </tab>
+      <tab type="usergroup" url="@ref sorting" title="Sorting">
+        <tab type="user" url="@ref itertools::bubble_sort" title="bubble_sort"/>
+        <tab type="user" url="@ref itertools::insertion_sort" title="insertion_sort"/>
+      </tab>
       <tab type="usergroup" url="@ref utilities" title="Utilities">
         <tab type="user" url="@ref itertools::chunk_range" title="chunk_range"/>
         <tab type="user" url="@ref itertools::distance" title="distance"/>
@@ -287,4 +291,4 @@
     </memberdecl>
     <detaileddescription title=""/>
   </directory>
-</doxygenlayout>
+</doxygenlayout>

doc/documentation.md

@@ -80,6 +80,16 @@ The following classes and functions related to integer ranges are defined in **i
 * @ref itertools::foreach "foreach"
 * @ref itertools::product_range "product_range"
 
+## Sorting
+
+We provide alternatives to `std::sort` that keep track of the number of swaps
+that have to be performed to put a range into a sorted order.
+
+The following sorting functions are defined in **itertools**:
+
+* @ref itertools::bubble_sort "bubble_sort"
+* @ref itertools::insertion_sort "insertion_sort"
+
 ## Utilities
 
 @ref utilities are mostly internal implementation details and should not concern everyday users.
@@ -94,4 +104,4 @@ The following utilities are defined in **itertools**:
 * @ref itertools::make_sentinel "make_sentinel"
 * @ref itertools::make_vector_from_range "make_vector_from_range"
 * @ref itertools::omp_chunk "omp_chunk"
-* @ref itertools::sentinel_t "sentinel_t"
+* @ref itertools::sentinel_t "sentinel_t"

doc/groups.dox

@@ -44,6 +44,14 @@
  * `start + i * step`.
  */
 
+/**
+ * @defgroup sorting Sorting
+ * @brief Functions to sort ranges.
+ *
+ * @details We provide alternatives to @p std::sort that keep track of the
+ * number of swaps that have to be performed to put a range into a sorted order.
+ */
+
 /**
  * @defgroup utilities Utilities
  * @brief Utilities are mostly internal implementation details and should not concern everyday users.

test/c++/itertools.cpp

@@ -19,9 +19,11 @@
 
 #include <algorithm>
 #include <array>
+#include <forward_list>
 #include <list>
 #include <iostream>
 #include <numeric>
+#include <random>
 #include <utility>
 #include <vector>
 
@@ -369,6 +371,66 @@ TEST(Itertools, RangeRandomAccessOperations) {
   }
 }
 
+inline static std::default_random_engine &randint_engine() {
+  static thread_local std::default_random_engine eng{std::random_device{}()};
+  return eng;
+}
+
+template <typename T> inline static T randint(T a, T b) {
+  static_assert(std::is_integral<T>::value && sizeof(T) > 1, "The type must be an integer!");
+  return std::uniform_int_distribution<T>(a, b)(randint_engine());
+}
+
+TEST(Itertools, BubbleSort) {
+  // Create a vector of random length and fill it with random numbers.
+  std::forward_list<int> test1;
+  for (auto _ : range(randint(0, 100))) { test1.push_front(randint(-1000, 1000)); }
+  std::forward_list<int> test2 = test1; // Make a copy, sorting is in-place
+
+  bubble_sort(test1.begin(), test1.end());
+  test2.sort();
+  for (auto [lhs, rhs] : zip(test1, test2)) { EXPECT_EQ(lhs, rhs); }
+
+  bubble_sort(test1.begin(), test1.end(), std::greater{});
+  test2.sort(std::greater{});
+  for (auto [lhs, rhs] : zip(test1, test2)) { EXPECT_EQ(lhs, rhs); }
+}
+
+TEST(Itertools, BubbleSortSwaps) {
+  std::vector<int> test1 = {100, 2, 3, 56, 200, 3, -52, 3, 3, 99, 33, 177, -199};
+  std::vector<int> test2 = test1; // Make a copy, sorting is in-place
+
+  std::size_t swaps = bubble_sort(test1.begin(), test1.end());
+  std::sort(test2.begin(), test2.end());
+  for (auto [lhs, rhs] : zip(test1, test2)) { EXPECT_EQ(lhs, rhs); }
+  EXPECT_EQ(swaps, 37);
+}
+
+TEST(Itertools, InsertionSort) {
+  // Create a vector of random length and fill it with random numbers.
+  std::vector<int> test1(randint(0, 100));
+  for (auto &e : test1) { e = randint(-1000, 1000); }
+  std::vector<int> test2 = test1; // Make a copy, sorting is in-place
+
+  insertion_sort(test1.begin(), test1.end());
+  std::sort(test2.begin(), test2.end());
+  for (auto [lhs, rhs] : zip(test1, test2)) { EXPECT_EQ(lhs, rhs); }
+
+  insertion_sort(test1.begin(), test1.end(), std::greater{});
+  std::sort(test2.begin(), test2.end(), std::greater{});
+  for (auto [lhs, rhs] : zip(test1, test2)) { EXPECT_EQ(lhs, rhs); }
+}
+
+TEST(Itertools, InsertionSortSwaps) {
+  std::vector<int> test1 = {100, 2, 3, 56, 200, 3, -52, 3, 3, 99, 33, 177, -199};
+  std::vector<int> test2 = test1; // Make a copy, sorting is in-place
+
+  std::size_t swaps = insertion_sort(test1.begin(), test1.end());
+  std::sort(test2.begin(), test2.end());
+  for (auto [lhs, rhs] : zip(test1, test2)) { EXPECT_EQ(lhs, rhs); }
+  EXPECT_EQ(swaps, 37);
+}
+
 int main(int argc, char **argv) {
   ::testing::InitGoogleTest(&argc, argv);
   return RUN_ALL_TESTS();