Range adapting functions

Detailed Description

Range adapting functions take one or more existing ranges and return lazy Adapted ranges that can be iterated over.

Lazy means that new elements are produced on the fly whenever they are needed instead of being precomputed when the range is created.

Functions
template<typename R >
enumerated< R >	itertools::enumerate (R &&rg)
	Lazy-enumerate a given range (similar to Python's enumerate).
template<typename R , size_t N>
auto	itertools::make_product (std::array< R, N > &arr)
	Create a cartesian product range from an array of ranges.
template<typename R , size_t N>
auto	itertools::make_product (std::array< R, N > const &arr)
	Const overload of make_product(std::array<R, N> &).
template<typename... Rs>
itertools::multiplied< Rs... >	itertools::product (Rs &&...rgs)
	Lazy-multiply a given number of ranges by forming their cartesian product.
template<typename R >
sliced< R >	itertools::slice (R &&rg, std::ptrdiff_t start_idx, std::ptrdiff_t end_idx)
	Lazy-slice a given range.
template<typename R >
strided< R >	itertools::stride (R &&rg, std::ptrdiff_t stride)
	Lazy-stride through a given range.
template<typename R , typename F >
auto	itertools::transform (R &&rg, F lambda)
	Lazy-transform a given range by applying a unary callable object to every element of the original range.
template<typename... Rs>
zipped< Rs... >	itertools::zip (Rs &&...rgs)
	Lazy-zip ranges together (similar to Python's zip).

Function Documentation

enumerate()

template<typename R >

enumerated< R > itertools::enumerate ( R && rg )

nodiscard

#include <itertools/enumerate.hpp>

Lazy-enumerate a given range (similar to Python's enumerate).

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:

std::vector<char> vec { 'a', 'b', 'c' };
 
for (auto [idx, val] : enumerate(vec)) {
  std::cout << "(" << idx << ", " << val << ")\n";
}

Output:

(0, a)
(1, b)
(2, c)

See also std::ranges::views::enumerate.

Template Parameters

R	Range type.

Parameters

rg	Range to enumerate.

Returns

A itertools::enumerated range.

Definition at line 168 of file enumerate.hpp.

make_product()

template<typename R , size_t N>

auto itertools::make_product ( std::array< R, N > & arr )

nodiscard

#include <itertools/product.hpp>

Create a cartesian product range from an array of ranges.

Template Parameters

R	Range type.
N	Number of ranges.

Parameters

arr	Array of ranges.

Returns

A product (itertools::multiplied) range from the ranges in the array.

Definition at line 259 of file product.hpp.

product()

template<typename... Rs>

itertools::multiplied< Rs... > itertools::product ( Rs &&... rgs )

nodiscard

#include <itertools/product.hpp>

Lazy-multiply a given number of ranges by forming their cartesian product.

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:

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";
}

Output:

(1, a)
(1, b)
(2, a)
(2, b)
(3, a)
(3, b)

See also std::ranges::views::cartesian_product.

Template Parameters

Rs	Range types.

Parameters

rgs	Ranges to be used.

Returns

A product (itertools::multiplied) range.

Definition at line 240 of file product.hpp.

slice()

template<typename R >

sliced< R > itertools::slice ( R && rg, std::ptrdiff_t start_idx, std::ptrdiff_t end_idx )

nodiscard

#include <itertools/slice.hpp>

Lazy-slice a given range.

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.

This function returns an iterable lazy object, which can be used in range-based for loops:

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
}

Output:

2 3
4 5

Template Parameters

R	Range type.

Parameters

rg	Range to be sliced.
start_idx	Index where the slice starts.
end_idx	Index of the first element past the end of the sliced range (excluded).

Returns

A itertools::sliced range.

Definition at line 137 of file slice.hpp.

stride()

template<typename R >

strided< R > itertools::stride ( R && rg, std::ptrdiff_t stride )

nodiscard

#include <itertools/stride.hpp>

Lazy-stride through a given range.

Only every Nth element of the original range is taken into account. If the given stride (N) is <= 0, an exception is thrown.

This function returns an iterable lazy object, which can be used in range-based for loops:

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 << " ";
}

Output:

1 4 7 10
1

See also See also std::ranges::views::stride.

Template Parameters

R	Range type.

Parameters

rg	Original range.
stride	Number of elements to skip when incrementing.

Returns

A itertools::strided range.

Definition at line 178 of file stride.hpp.

transform()

template<typename R , typename F >

auto itertools::transform ( R && rg, F lambda )

nodiscard

#include <itertools/transform.hpp>

Lazy-transform a given range by applying a unary callable object to every element of the original range.

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:

std::list<int> list { 1, 2, 3, 4, 5 };
 
for (auto i : itertools::transform(list, [](int i) { return i * i; })) {
  std::cout << i << " ";
}

Output:

1 4 9 16 25

See also std::ranges::views::transform.

Template Parameters

R	Range type.
F	Callable type.

Parameters

rg	Range to transform.
lambda	Callable to be applied to the given range.

Returns

A itertools::transformed range.

Definition at line 188 of file transform.hpp.

zip()

template<typename... Rs>

zipped< Rs... > itertools::zip ( Rs &&... rgs )

nodiscard

#include <itertools/zip.hpp>

Lazy-zip ranges together (similar to Python's zip).

An arbitrary number of ranges are zipped together into a tuple. The zipped range will have as many elements as the shortest given range.

This function returns an iterable lazy object, which can be used in range-based for loops:

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 << ") ";
}

Output:

(1, 1) (2, 2) (3, 3)
(1, 1, a) (2, 2, b) (3, 3, c)

See also std::ranges::views::zip.

Template Parameters

Rs	Range types.

Parameters

rgs	Ranges to zip.

Returns

A itertools::zipped range.

Definition at line 218 of file zip.hpp.