v2.0.x release preparation

CMakeLists.txt

@@ -19,7 +19,7 @@ cmake_policy(VERSION ${CMAKE_VERSION})
 
 # ############
 # Define Project
-project(itertools VERSION 1.3.0 LANGUAGES CXX)
+project(itertools VERSION 2.0.0 LANGUAGES CXX)
 get_directory_property(IS_SUBPROJECT PARENT_DIRECTORY)
 
 # Get the git hash & print status

c++/itertools/enumerate.hpp

@@ -35,9 +35,9 @@ namespace itertools {
    * @ingroup range_iterators
    * @brief Iterator for an itertools::enumerated range.
    *
-   * @details It stores an iterator of the original range and an index. Incrementing advances the iterator
-   * and the index by 1. Dereferencing returns a std::pair consisting of the current index and the current
-   * dereferenced value of the original iterator.
+   * @details It stores an iterator of the original range and an index. Incrementing advances the iterator and the index 
+   * by 1. Dereferencing returns a `std::pair` consisting of the current index and the current dereferenced value of the 
+   * original iterator.
    *
    * See itertools::enumerate(R &&) for more details.
    *
@@ -139,17 +139,11 @@ namespace itertools {
    * @ingroup range_adapting_functions
    * @brief Lazy-enumerate a given range (similar to Python's enumerate).
    *
-   * @details Each element in the original range is assigned an index, starting from zero. This function
-   * returns an iterable lazy object (a itertools::enumerated range), which iterates over tuples consisting
-   * of the index and the value of the dereferenced iterator of the original range:
+   * @details Each element in the original range is assigned an index, starting from zero. This function returns an 
+   * iterable lazy object (a itertools::enumerated range), which iterates over tuples consisting of the index and the 
+   * value of the dereferenced iterator of the original range:
    *
-   * @code{.cpp}
-   * std::vector<char> vec { 'a', 'b', 'c' };
-   *
-   * for (auto [idx, val] : enumerate(vec)) {
-   *   std::cout << "(" << idx << ", " << val << ")\n";
-   * }
-   * @endcode
+   * @include doc_enumerate.cpp
    *
    * Output:
    *

c++/itertools/omp_chunk.hpp

@@ -31,7 +31,8 @@ namespace itertools {
    * @ingroup utilities
    * @brief Distribute a range as evenly as possible across all OMP threads.
    *
-   * @details See chunk_range(std::ptrdiff_t, std::ptrdiff_t, long, long) and slice(R &&, std::ptrdiff_t, std::ptrdiff_t) for more details.
+   * @details See chunk_range(std::ptrdiff_t, std::ptrdiff_t, long, long) and slice(R &&, std::ptrdiff_t, 
+   * std::ptrdiff_t) for more details.
    *
    * @tparam R Range type.
    * @param rg Range to chunk.

c++/itertools/product.hpp

@@ -41,9 +41,9 @@ namespace itertools {
    * - `its_end` contains the end iterators of all ranges
    * - `its` contains the current iterators of all ranges
    *
-   * Incrementing is done from right to left, i.e. the iterator of the last range is incremented first.
-   * Once an iterator reaches the end of its range, it is reset to the beginning and the iterator of the
-   * previous range is incremented once.
+   * Incrementing is done from right to left, i.e. the iterator of the last range is incremented first. Once an iterator 
+   * reaches the end of its range, it is reset to the beginning and the iterator of the previous range is incremented 
+   * once.
    *
    * Dereferencing returns a tuple containing the results of dereferencing each iterator.
    *
@@ -184,7 +184,8 @@ namespace itertools {
 
     /**
      * @brief End of the product range.
-     * @return itertools::sentinel_t containing the end iterator of the first original range, i.e. `std::end(std::get<0>(tu))`.
+     * @return itertools::sentinel_t containing the end iterator of the first original range, i.e. 
+     * `std::end(std::get<0>(tu))`.
      */
     [[nodiscard]] auto end() noexcept { return make_sentinel(std::end(std::get<0>(tu))); }
 
@@ -206,19 +207,14 @@ namespace itertools {
   /**
    * @brief Lazy-multiply a given number of ranges by forming their cartesian product.
    *
-   * @details An arbitrary number of ranges are multiplied together into a cartesian product range.
-   * They are traversed such that the last range is traversed the fastest (see the example below).
+   * @details An arbitrary number of ranges are multiplied together into a cartesian product range. They are traversed 
+   * such that the last range is traversed the fastest (see the example below). 
+   * 
    * The number of elements in a product range is equal to the product of the sizes of the given ranges.
+   * 
    * This function returns an iterable lazy object, which can be used in range-based for loops:
    *
-   * @code{.cpp}
-   * std::vector<int> v1 { 1, 2, 3 };
-   * std::vector<char> v2 { 'a', 'b' };
-   *
-   * for (auto [i, c] : product(v1, v2)) {
-   *   std::cout << "(" << i << ", " << c << ")\n";
-   * }
-   * @endcode
+   * @include doc_product.cpp
    *
    * Output:
    *
@@ -231,7 +227,8 @@ namespace itertools {
    * (3, b)
    * ```
    *
-   * See also <a href="https://en.cppreference.com/w/cpp/ranges/cartesian_product_view">std::ranges::views::cartesian_product</a>.
+   * See also <a href="https://en.cppreference.com/w/cpp/ranges/cartesian_product_view">
+   * std::ranges::views::cartesian_product</a>.
    *
    * @tparam Rs Range types.
    * @param rgs Ranges to be used.

c++/itertools/range.hpp

@@ -49,26 +49,7 @@ namespace itertools {
    *
    * This function returns an iterable lazy object, which can be used in range-based for loops:
    *
-   * @code{.cpp}
-   * for (auto i : range(5)) {
-   *   std::cout << i << " ";
-   * }
-   * std::cout << "\n";
-   *
-   * for (auto i : range(-2, 1)) {
-   *   std::cout << i << " ";
-   * }
-   * std::cout << "\n";
-   *
-   * for (auto i : range(10, 3, -2)) {
-   *   std::cout << i << " ";
-   * }
-   * std::cout << "\n";
-   *
-   * for (auto i : range(0, 10, -1)) {
-   *   std::cout << i << " "; // empty
-   * }
-   * @endcode
+   * @include doc_range.cpp
    *
    * Output:
    *
@@ -106,7 +87,8 @@ namespace itertools {
 
     /**
      * @brief Default constructor.
-     * @deprecated Use range::range(long, long) or range::range(long, long, long) instead.
+     * @deprecated Use range::range(std::integral auto, std::integral auto) or range::range(std::integral auto, 
+     * std::integral auto, std::integral auto) instead.
      */
     [[deprecated("range default construction deprecated. Use range::all for full range in slicing operation")]] range() = default;
 
@@ -370,11 +352,7 @@ namespace itertools {
    * @details The given integers specify the excluded last values of the individual itertools::range objects. Each range
    * starts at 0 and has a step size of 1.
    *
-   * @code{.cpp}
-   * for (auto [i1, i2] : product_range(2, 3)) {
-   *   std::cout << "(" << i1 << ", " << i2 << ")\n";
-   * }
-   * @endcode
+   * @include doc_product_range.cpp
    *
    * Output:
    *
@@ -407,25 +385,7 @@ namespace itertools {
   /**
    * @brief Create a cartesian product range of integer ranges from a tuple of integers.
    *
-   * @details The integers in the given tuple specify the excluded last values of the individual itertools::range
-   * objects. Each range starts at 0 and has a step size of 1.
-   *
-   * @code{.cpp}
-   * for (auto [i1, i2] : product_range(std::make_tuple(2, 3))) {
-   *   std::cout << "(" << i1 << ", " << i2 << ")\n";
-   * }
-   * @endcode
-   *
-   * Output:
-   *
-   * ```
-   * (0, 0)
-   * (0, 1)
-   * (0, 2)
-   * (1, 0)
-   * (1, 1)
-   * (1, 2)
-   * ```
+   * @details It simply forwards the integers in the given tuple to itertools::product_range.
    *
    * @tparam Is Integer types.
    * @param idx_tpl Tuple containing the excluded last values of the integer ranges.
@@ -439,25 +399,7 @@ namespace itertools {
   /**
    * @brief Create a cartesian product range of integer ranges from an array of integers.
    *
-   * @details The integers in the given array specify the excluded last values of the individual itertools::range
-   * objects. Each range starts at 0 and has a step size of 1.
-   *
-   * @code{.cpp}
-   * for (auto [i1, i2] : product_range(std::array{2, 3})) {
-   *   std::cout << "(" << i1 << ", " << i2 << ")\n";
-   * }
-   * @endcode
-   *
-   * Output:
-   *
-   * ```
-   * (0, 0)
-   * (0, 1)
-   * (0, 2)
-   * (1, 0)
-   * (1, 1)
-   * (1, 2)
-   * ```
+   * @details It simply forwards the integers in the given array to itertools::product_range.
    *
    * @tparam I Integer type.
    * @tparam N Number of elements in the array.
@@ -472,12 +414,7 @@ namespace itertools {
   /**
    * @brief Apply a function to every element of an integer itertools::range.
    *
-   * @code{.cpp}
-   * // print out the first 10 squares
-   * itertools::foreach(itertools::range(1, 11), [](int i) {
-   *   std::cout << i * i << " ";
-   * });
-   * @endcode
+   * @include doc_for_each.cpp
    *
    * Output:
    *

c++/itertools/slice.hpp

@@ -96,30 +96,16 @@ namespace itertools {
    * @ingroup range_adapting_functions
    * @brief Lazy-slice a given range.
    *
-   * @details Only the part of the given range between the `start_idx` and the `end_idx` is taken into account.
-   * If `end_idx` is bigger than the size of the original range, the slice ends at the end of the original range.
-   * If `end_idx` is smaller than `start_idx`, the slice is empty. Note that the behaviour is undefined if
-   * `start_idx` is smaller than zero.
+   * @details Only the part of the given range between the `start_idx` and the `end_idx` is taken into account:
+   * 
+   * - If `end_idx` is bigger than the size of the original range, the slice ends at the end of the original range. 
+   * - If `end_idx` is smaller than `start_idx`, the slice is empty. 
+   * 
+   * @note The behaviour is undefined if `start_idx` is smaller than zero.
    *
    * This function returns an iterable lazy object, which can be used in range-based for loops:
    *
-   * @code{.cpp}
-   * std::array<int, 5> arr { 1, 2, 3, 4, 5 };
-   *
-   * for (auto i : slice(arr, 1, 3)) {
-   *     std::cout << i << " ";
-   * }
-   * std::cout << "\n";
-   *
-   * for (auto i : slice(arr, 3, 7)) {
-   *     std::cout << i << " ";
-   * }
-   * std::cout << "\n";
-   *
-   * for (auto i : slice(arr, 4, 3)) {
-   *     std::cout << i << " "; // empty slice
-   * }
-   * @endcode
+   * @include doc_slice.cpp
    *
    * Output:
    *

c++/itertools/stride.hpp

@@ -148,18 +148,7 @@ namespace itertools {
    *
    * This function returns an iterable lazy object, which can be used in range-based for loops:
    *
-   * @code{.cpp}
-   * std::vector<int> vec { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
-   *
-   * for (auto i : stride(vec, 3)) {
-   *   std::cout << i << " ";
-   * }
-   * std::cout << "\n";
-   *
-   * for (auto i : stride(vec, 10)) {
-   *   std::cout << i << " ";
-   * }
-   * @endcode
+   * @include doc_stride.cpp
    *
    * Output:
    *

c++/itertools/transform.hpp

@@ -36,9 +36,9 @@ namespace itertools {
    * @ingroup range_iterators
    * @brief Iterator for a itertools::transformed range.
    *
-   * @details It stores an iterator of the original range and a callable object that is used to transform the
-   * elements of the original range. Incrementing simply increments the iterator. Dereferencing returns the
-   * result of the callable object applied to the dereferenced iterator, i.e. the transformed element.
+   * @details It stores an iterator of the original range and a callable object that is used to transform the elements 
+   * of the original range. Incrementing simply increments the iterator. Dereferencing returns the result of the 
+   * callable object applied to the dereferenced iterator, i.e. the transformed element.
    *
    * See itertools::transform(R &&, F) for more details.
    *
@@ -161,15 +161,10 @@ namespace itertools {
    *
    * @details The value type of the transformed range depends on the return type of the callable.
    *
-   * This function returns an iterable lazy object (a itertools::transformed range), which can be used in range-based for loops:
+   * This function returns an iterable lazy object (a itertools::transformed range), which can be used in range-based 
+   * for loops:
    *
-   * @code{.cpp}
-   * std::list<int> list { 1, 2, 3, 4, 5 };
-   *
-   * for (auto i : itertools::transform(list, [](int i) { return i * i; })) {
-   *   std::cout << i << " ";
-   * }
-   * @endcode
+   * @include doc_transform.cpp
    *
    * Output:
    *

c++/itertools/utils.hpp

@@ -38,8 +38,8 @@ namespace itertools {
   /**
    * @brief Calculate the distance between two iterators.
    *
-   * @details It is similar to <a href="https://en.cppreference.com/w/cpp/iterator/distance">std::distance</a>,
-   * except that it can be used for two different iterator types, e.g. in case one of them is a const iterator.
+   * @details It is similar to <a href="https://en.cppreference.com/w/cpp/iterator/distance">std::distance</a>, except 
+   * that it can be used for two different iterator types, e.g. in case one of them is a const iterator.
    *
    * @tparam Iter1 Iterator type #1.
    * @tparam Iter2 Iterator type #2.
@@ -87,7 +87,7 @@ namespace itertools {
    * @param last Last value of the range (excluded).
    * @param n_chunks Number of chunks to divide the range into.
    * @param rank Rank of the calling process.
-   * @return Pair of indices specifying the first and last (excluded) value of the chunk assigned to the calling
+   * @return Pair of indices specifying the first and last (excluded) value of the chunk assigned to the calling 
    * process.
    */
   [[nodiscard]] inline std::pair<std::ptrdiff_t, std::ptrdiff_t> chunk_range(std::ptrdiff_t first, std::ptrdiff_t last, long n_chunks, long rank) {

c++/itertools/zip.hpp

@@ -76,8 +76,8 @@ namespace itertools {
     /**
      * @brief Equal-to operator for a itertools::zip_iter and an itertools::sentinel_t.
      *
-     * @details Only one of the iterators has to be equal to the corresponding iterator of the sentinel. In case
-     * the original ranges have different lengths, the itertools::zipped range should have the length of the shortest range.
+     * @details Only one of the iterators has to be equal to the corresponding iterator of the sentinel. In case the 
+     * original ranges have different lengths, the itertools::zipped range should have the length of the shortest range.
      *
      * @tparam SentinelIter Iterator type of the sentinel.
      * @param s itertools::sentinel_t to compare with.
@@ -189,18 +189,7 @@ namespace itertools {
    *
    * This function returns an iterable lazy object, which can be used in range-based for loops:
    *
-   * @code{.cpp}
-   * std::vector<int> v1 { 1, 2, 3 };
-   * std::vector<char> v2 { 'a', 'b', 'c', 'd', 'e' };
-   *
-   * for (auto [i1, i2] : zip(v1, v1)) {
-   *   std::cout << "(" << i1 << ", " << i2 << ") ";
-   * }
-   *
-   * for (auto [i1, i2, c3] : zip(v1, v1, v2)) {
-   *   std::cout << "(" << i1 << ", " << i2 << ", " << c3 << ") ";
-   * }
-   * @endcode
+   * @include doc_zip.cpp
    *
    * Output:
    *

doc/CMakeLists.txt

@@ -25,6 +25,9 @@ add_custom_target(doxygen ALL
   VERBATIM
 )
 
+# Compile example codes
+add_subdirectory(examples)
+
 # ############
 # Install
 install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ COMPONENT documentation DESTINATION share/doc/${PROJECT_NAME}