docstrings

Author: storm-ptr

README.md

@@ -1,88 +1,27 @@
-<img align="right" src="https://user-images.githubusercontent.com/3381451/40880432-5b9e7086-66b9-11e8-9718-4b1ea4eae317.png" width="25%">
+<img align="right" src="https://user-images.githubusercontent.com/3381451/40880432-5b9e7086-66b9-11e8-9718-4b1ea4eae317.png" width="20%">
 
 [![Build Status](https://travis-ci.org/storm-ptr/step.svg?branch=master)](https://travis-ci.org/storm-ptr/step)
 [![Build Status](https://ci.appveyor.com/api/projects/status/github/storm-ptr/step?svg=true&branch=master)](https://ci.appveyor.com/project/storm-ptr/step/branch/master)
 
 Step is a library of STL-like algorithms and data structures (C++17, header-only).
 
-Algorithms:
-* <details><summary>edit distance</summary><p>
-
-  [wiki](https://en.wikipedia.org/wiki/Levenshtein_distance)
-  ```C++
-  pairs_t pairs;
-  step::edit_distance::join("this"sv, "has"sv, std::back_inserter(pairs));
-  CHECK(pairs ==
-        pairs_t{{'t', std::nullopt}, {'h', 'h'}, {'i', 'a'}, {'s', 's'}});
-  ```
-  </p></details>
-* <details><summary>longest common subsequence</summary><p>
-  
-  [wiki](https://en.wikipedia.org/wiki/Longest_common_subsequence_problem)
-  ```C++
-  std::string str;
-  step::longest_common_subsequence::intersection("LCS is the basis of "sv,
-                                                 "the diff utility"sv,
-                                                 std::back_inserter(str));
-  CHECK(str == "the if ");
-  ```
-  </p></details>
-* <details><summary>longest common substring</summary><p>
-
-  [wiki](https://en.wikipedia.org/wiki/Longest_common_substring_problem)
-  ```C++
-  auto range = step::longest_common_substring::find_with_suffix_tree(
-      "the longest string that is #", "a substring of two strings $");
-  CHECK("string " == std::string(range.first, range.second));
-  ```
-  </p></details>
-* <details><summary>longest increasing subsequence</summary><p>
-
-  [wiki](https://en.wikipedia.org/wiki/Longest_increasing_subsequence)
-  ```C++
-  std::vector v{6, 3, 4, 8, 10, 5, 7, 1, 9, 2};
-  int expect[] = {3, 4, 5, 7, 9};
-  auto it = step::longest_increasing_subsequence::partition(v);
-  CHECK(std::equal(v.begin(), it, std::begin(expect), std::end(expect)));
-  ```
-  </p></details>
-* <details><summary>longest repeated substring</summary><p>
-
-  [wiki](https://en.wikipedia.org/wiki/Longest_repeated_substring_problem)
-  ```C++
-  auto range = step::longest_repeated_substring::find_with_suffix_array(
-      "the longest substring of a string that occurs at least twice");
-  CHECK("string " == std::string(range.first, range.second));
-  ```
-    </p></details>
-* <details><summary>maximum subarray</summary><p>
-
-  [wiki](https://en.wikipedia.org/wiki/Maximum_subarray_problem)
-  ```C++
-  int arr[] = {-2, -3, 4, -1, -2, 1, 5, -3};
-  std::array expect{4, -1, -2, 1, 5};
-  auto range = step::maximum_subarray::find(arr);
-  CHECK(std::equal(range.first, range.second, expect.begin(), expect.end()));
-  ```
-  </p></details>
-
-Data structures:
-* <details><summary>suffix array</summary><p>
-
-  [wiki](https://en.wikipedia.org/wiki/Suffix_array)
-  ```C++
-  auto str = "how can I quickly search for text within a document?"sv;
-  step::suffix_array arr{str};
-  CHECK(arr.find("quick"sv) == 10);
-  ```
-  </p></details>
-* <details><summary>suffix tree</summary><p>
-
-  [wiki](https://en.wikipedia.org/wiki/Suffix_tree)
-  ```C++
-  auto str = "use the quick find feature to search for a text"sv;
-  step::suffix_tree tree{};
-  std::copy(str.begin(), str.end(), std::back_inserter(tree));
-  CHECK(tree.find("quick"sv) == 8);
-  ```
-  </p></details>
+### Algorithms:
+* [edit distance](https://en.wikipedia.org/wiki/Levenshtein_distance)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/edit_distance.hpp#L15-L19))
+* [longest common subsequence</summary>](https://en.wikipedia.org/wiki/Longest_common_subsequence_problem)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/longest_common_subsequence.hpp#L13-L17),
+   [example](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/example/diff/main.cpp#L53-L71))
+* [longest common substring](https://en.wikipedia.org/wiki/Longest_common_substring_problem)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/longest_common_substring.hpp#L13-L15))
+* [longest increasing subsequence](https://en.wikipedia.org/wiki/Longest_increasing_subsequence)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/longest_increasing_subsequence.hpp#L14-L17))
+* [longest repeated substring](https://en.wikipedia.org/wiki/Longest_repeated_substring_problem)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/longest_repeated_substring.hpp#L13-L15))
+* [maximum subarray](https://en.wikipedia.org/wiki/Maximum_subarray_problem)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/maximum_subarray.hpp#L13-L16))
+
+### Data structures:
+* [suffix array](https://en.wikipedia.org/wiki/Suffix_array)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/suffix.hpp#L20-L22))
+* [suffix tree](https://en.wikipedia.org/wiki/Suffix_tree)
+  ([snippet](https://github.com/storm-ptr/step/blob/7007e6030168d54d55e707022f7531752cc8f20b/test/suffix.hpp#L27-L30))

detail/hirschberg.hpp

@@ -5,7 +5,6 @@
 
 #include <step/detail/utility.hpp>
 
-/// @see https://en.wikipedia.org/wiki/Hirschberg's_algorithm
 namespace step::hirschberg {
 
 template <class RandomIt1, class RandomIt2, class DynamicProg, class BinaryOp>
@@ -30,6 +29,7 @@ auto partition_point(RandomIt1 first1,
     return op(split1, split2);
 }
 
+/// @see https://en.wikipedia.org/wiki/Hirschberg's_algorithm
 template <class RandomIt1, class RandomIt2, class OutputIt, class DynamicProg>
 OutputIt trace(RandomIt1 first1,
                RandomIt1 last1,

edit_distance.hpp

@@ -35,7 +35,6 @@ template <class Equal>
 struct dynamic_programming {
     Equal eq;
 
-    /// @see https://en.wikipedia.org/wiki/Wagner–Fischer_algorithm
     template <class RandomIt1, class RandomIt2>
     auto make_last_row(RandomIt1 first1,
                        RandomIt1 last1,
@@ -89,15 +88,16 @@ struct dynamic_programming {
 
 }  // namespace detail
 
-/**
- * Find the optimal sequence alignment between two strings. Optimality is
- * measured with the Levenshtein distance, defined to be the sum of the costs of
- * insertions, replacements, deletions, and null actions needed to change one
- * string into the other.
- * Time complexity O(N*M), space complexity O(min(N,M)), where:
- * N = std::distance(first1, last1), M = std::distance(first2, last2).
- * @see https://en.wikipedia.org/wiki/Levenshtein_distance
- */
+/// Find the optimal sequence alignment between two strings.
+
+/// Optimality is measured with the Levenshtein distance,
+/// defined to be the sum of the costs of
+/// insertions, replacements, deletions, and null actions needed
+/// to change one string into the other.
+/// Time complexity O(N*M), space complexity O(min(N,M)), where:
+/// N = std::distance(first1, last1), M = std::distance(first2, last2).
+/// @see https://en.wikipedia.org/wiki/Levenshtein_distance
+/// @see https://en.wikipedia.org/wiki/Wagner%E2%80%93Fischer_algorithm
 template <class RandomIt1, class RandomIt2, class OutputIt, class Equal>
 OutputIt join(RandomIt1 first1,
               RandomIt1 last1,

kahan.hpp

@@ -7,11 +7,9 @@
 
 namespace step::kahan {
 
-/**
- * Reduces the numerical error in the total obtained by adding a sequence of
- * floating point numbers. (What about complex numbers?)
- * @see https://en.wikipedia.org/wiki/Kahan_summation_algorithm
- */
+/// Reduces the numerical error in the total obtained by adding a sequence of
+/// floating point numbers. (What about complex numbers?)
+/// @see https://en.wikipedia.org/wiki/Kahan_summation_algorithm
 template <class T>
 class floating_point {
     T value_{};

longest_common_subsequence.hpp

@@ -12,7 +12,6 @@ template <class Equal>
 struct dynamic_programming {
     Equal eq;
 
-    /// @see https://www.geeksforgeeks.org/longest-common-subsequence/
     template <class RandomIt1, class RandomIt2>
     auto make_last_row(RandomIt1 first1,
                        RandomIt1 last1,
@@ -48,14 +47,14 @@ struct dynamic_programming {
 
 }  // namespace detail
 
-/**
- * Find the longest subsequence present in two sequences. A subsequence is a
- * sequence that appears in the same relative order, but not necessarily
- * contiguous.
- * Time complexity O(N*M), space complexity O(min(N,M)), where:
- * N = std::distance(first1, last1), M = std::distance(first2, last2).
- * @see https://en.wikipedia.org/wiki/Longest_common_subsequence_problem
- */
+/// Find the longest subsequence present in two sequences.
+
+/// A subsequence is a sequence that appears in the same relative order,
+/// but not necessarily contiguous.
+/// Time complexity O(N*M), space complexity O(min(N,M)), where:
+/// N = std::distance(first1, last1), M = std::distance(first2, last2).
+/// @see https://en.wikipedia.org/wiki/Longest_common_subsequence_problem
+/// @see https://www.geeksforgeeks.org/longest-common-subsequence/
 template <class RandomIt1, class RandomIt2, class OutputIt, class Equal>
 OutputIt intersection(RandomIt1 first1,
                       RandomIt1 last1,

longest_common_substring.hpp

@@ -6,7 +6,6 @@
 #include <step/suffix_array.hpp>
 #include <step/suffix_tree.hpp>
 
-/// @see https://en.wikipedia.org/wiki/Longest_common_substring_problem
 namespace step::longest_common_substring {
 namespace detail {
 
@@ -78,14 +77,14 @@ struct suffix_tree_searcher {
 
 }  // namespace detail
 
-/**
- * Find the longest string that is a substring of two strings.
- * Time complexity O((N+M)*log(N+M)*log(N+M)), space complexity O(N+M), where:
- * N = std::distance(first1, last1) and M = std::distance(first2, last2).
- * A suffix array with optional parameter is used under the hood:
- * @param Compare - to determine the order of characters.
- * @return a pair of iterators defining the wanted substring.
- */
+/// Find the longest string that is a substring of two strings.
+
+/// Time complexity O((N+M)*log(N+M)*log(N+M)), space complexity O(N+M), where:
+/// N = std::distance(first1, last1) and M = std::distance(first2, last2).
+/// A suffix array with optional parameter is used under the hood:
+/// @tparam Compare - to determine the order of characters.
+/// @return a pair of iterators defining the wanted substring.
+/// @see https://en.wikipedia.org/wiki/Longest_common_substring_problem
 template <class Compare = std::less<>, class RandomIt1, class RandomIt2>
 auto find_with_suffix_array(RandomIt1 first1,
                             RandomIt1 last1,
@@ -104,15 +103,13 @@ auto find_with_suffix_array(const RandomRng1& rng1, const RandomRng2& rng2)
         std::begin(rng1), std::end(rng1), std::begin(rng2), std::end(rng2));
 }
 
-/**
- * Find the longest string that is a substring of two strings,
- * padded with unique string terminators.
- * Time complexity O((N+M)*log(N+M)), space complexity O(N+M), where:
- * N = std::distance(first1, last1) and M = std::distance(first2, last2).
- * A suffix tree with optional parameter is used under the hood:
- * @param Map - to associate characters with edges.
- * @return a pair of iterators defining the wanted substring.
- */
+/// Find the longest string that is a substring of two strings,
+/// padded with unique string terminators.
+/// Time complexity O((N+M)*log(N+M)), space complexity O(N+M), where:
+/// N = std::distance(first1, last1) and M = std::distance(first2, last2).
+/// A suffix tree with optional parameter is used under the hood:
+/// @tparam Map - to associate characters with edges.
+/// @return a pair of iterators defining the wanted substring.
 template <template <class...> class Map = std::unordered_map,
           class RandomIt1,
           class RandomIt2>

longest_increasing_subsequence.hpp

@@ -10,14 +10,9 @@
 #include <unordered_map>
 #include <vector>
 
-// @see https://en.wikipedia.org/wiki/Longest_increasing_subsequence
 namespace step::longest_increasing_subsequence {
 namespace detail {
 
-/*
- * @see
- * https://www.geeksforgeeks.org/longest-monotonically-increasing-subsequence-size-n-log-n/
- */
 class increasing_subsequences {
     std::vector<size_t> tails_;
     std::unordered_map<size_t, std::optional<size_t>> prevs_;
@@ -57,25 +52,28 @@ class increasing_subsequences {
 
 }  // namespace detail
 
-/**
- * Finds a subsequence of a given sequence in which the subsequence's elements
- * are in sorted order, lowest to highest, and in which the subsequence is as
- * long as possible. This subsequence is not necessarily contiguous, or unique.
- * Reorders the elements in such a way that all elements for the subsequence
- * precede the others.
- * @return iterator to the end of the subsequence.
- * Time complexity O(N*log(N)), space complexity O(N), where:
- * N = std::distance(first, last).
- */
+/// Find longest increasing subsequence (LIS) in the array.
+
+/// The subsequence's elements are in sorted order, lowest to highest.
+/// This subsequence is not necessarily contiguous, or unique.
+/// Reorders the elements in such a way that all elements for the subsequence
+/// precede the others.
+/// @return iterator to the end of the subsequence.
+/// Time complexity O(N*log(N)), space complexity O(N), where:
+/// N = std::distance(first, last).
+/// @see https://en.wikipedia.org/wiki/Longest_increasing_subsequence
+/// @see
+/// https://www.geeksforgeeks.org/longest-monotonically-increasing-subsequence-size-n-log-n/
 template <class RandomIt, class Compare>
-auto partition(RandomIt first, RandomIt last, Compare cmp)
+auto partition(RandomIt first, RandomIt last, Compare&& cmp)
 {
     using std::swap;
     auto it = first;
-    for (auto i : detail::increasing_subsequences{first, last, cmp}.longest()) {
-        swap(first[i], *it);
-        ++it;
-    }
+    for (auto i :
+         detail::increasing_subsequences{
+             first, last, std::forward<Compare>(cmp)}
+             .longest())
+        swap(first[i], *it++);
     return it;
 }
 
@@ -86,10 +84,10 @@ auto partition(RandomIt first, RandomIt last)
 }
 
 template <class RandomRng, class Compare>
-auto partition(RandomRng& rng, Compare cmp)
+auto partition(RandomRng& rng, Compare&& cmp)
 {
     return longest_increasing_subsequence::partition(
-        std::begin(rng), std::end(rng), cmp);
+        std::begin(rng), std::end(rng), std::forward<Compare>(cmp));
 }
 
 template <class RandomRng>

longest_repeated_substring.hpp

@@ -6,7 +6,6 @@
 #include <step/suffix_array.hpp>
 #include <step/suffix_tree.hpp>
 
-/// @see https://en.wikipedia.org/wiki/Longest_repeated_substring_problem
 namespace step::longest_repeated_substring {
 namespace detail {
 
@@ -51,14 +50,14 @@ struct suffix_tree_searcher {
 
 }  // namespace detail
 
-/**
- * Find the longest substring of text that occurs at least twice.
- * Time complexity O(N*log(N)*log(N)), space complexity O(N), where:
- * N = std::distance(first, last).
- * A suffix array with optional parameter is used under the hood:
- * @param Compare - to determine the order of characters.
- * @return a pair of iterators defining the wanted substring.
- */
+/// Find the longest substring of text that occurs at least twice.
+
+/// Time complexity O(N*log(N)*log(N)), space complexity O(N), where:
+/// N = std::distance(first, last).
+/// A suffix array with optional parameter is used under the hood:
+/// @tparam Compare - to determine the order of characters.
+/// @return a pair of iterators defining the wanted substring.
+/// @see https://en.wikipedia.org/wiki/Longest_repeated_substring_problem
 template <class Compare = std::less<>, class RandomIt>
 auto find_with_suffix_array(RandomIt first, RandomIt last)
 {
@@ -73,15 +72,13 @@ auto find_with_suffix_array(const RandomRng& rng)
         std::begin(rng), std::end(rng));
 }
 
-/**
- * Find the longest substring of text (padded with unique string terminator)
- * that occurs at least twice.
- * Time complexity O(N*log(N)), space complexity O(N), where:
- * N = std::distance(first, last).
- * A suffix tree with optional parameter is used under the hood:
- * @param Map - to associate characters with edges.
- * @return a pair of iterators defining the wanted substring.
- */
+/// Find the longest substring of text (padded with unique string terminator)
+/// that occurs at least twice.
+/// Time complexity O(N*log(N)), space complexity O(N), where:
+/// N = std::distance(first, last).
+/// A suffix tree with optional parameter is used under the hood:
+/// @tparam Map - to associate characters with edges.
+/// @return a pair of iterators defining the wanted substring.
 template <template <class...> class Map = std::unordered_map, class RandomIt>
 auto find_with_suffix_tree(RandomIt first, RandomIt last)
 {