irate

A C++17 library for iterating over C++ containers.

why?

This project is mainly for learning purposes - if you need this sort of functionallity then you should consider using cppitertools or range-v3.

install

irate is header only so you can simply copy the include folder into your own project. Alternatively you can install irate somewhere via the install target and pick up the irate cmake config file which exports the cmake target irate::irate.

functionallity

zip

Allows iterating over any number of containers simultaneously. Iteration will stop upon reaching the end of the shortest container:

#include <irate/zip.hpp>

#include <iostream>
#include <list>
#include <vector>

int main()
{
    const std::vector vec{1.0, 20.0, 3.0, 4.0, 42.0, 100.0, 42.0};
    const std::list lst{'i', 'r', 'a', 't', 'e'};

    for (auto [v, l] : irate::zip(vec, lst))
    {
        std::cout << v << ", " << l << "\n";
    }

    return 0;
}

1	i
20	r
3	a
4	t
42	e

enumerate

Iterate over a single container along with an index which may start at any value (enumerate(x, start)) or from 0 by default (enumerate(x)):

#include <irate/enumerate.hpp>

#include <iostream>
#include <vector>

int main()
{
    const std::vector vec{42.0, 666.0, 3.14};

    for (auto [ix, val] : irate::enumerate(vec, 10))
    {
        std::cout << ix << ", " << val << "\n";
    }

    return 0;
}

10	42
11	666
12	3.14

range

As in python, range(end), range(begin, end), and range(begin, end, step) are supported. In the simplest case:

#include <irate/range.hpp>

#include <iostream>

int main()
{
    for (auto ix : irate::range(5))
    {
        std::cout << ix << "\n";
    }

    return 0;
}

0

1

2

3

4

product

Cartesian product of iterables:

#include <irate/product.hpp>

#include <iostream>
#include <list>
#include <vector>

int main()
{
    const std::vector vec{-10.0, 10.0, 100.0};
    const std::list lst{"foo", "bar"};

    for (auto [v, l] : irate::product(vec, lst))
    {
        std::cout << v << ", " << l << "\n";
    }

    return 0;
}

-10	foo
-10	bar
10	foo
10	bar
100	foo
100	bar

testing

irate uses catch2 for unit testing. To build and run the tests pass -DIRATE_TEST=ON to the cmake command then you can build the tests with make and run them with ctest or by running the test binaries in build/test.

benchmarks

A simple benchmark can be built by adding the cmake variable -DIRATE_BENCHMARK=ON. It requires google benchmark and range-v3 to be installed somewhere. If they are installed in a non-standard location (i.e. not /usr/local) then you can pass their install location to cmake using CMAKE_PREFIX_PATH.

On my laptop configuring with:

cmake path/to/irate -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-8 -DCMAKE_CXX_FLAGS=-march=native -DIRATE_BENCHMARK=ON

the benchmark results are:

~/workspace/irate/release/benchmark/zip_benchmark --benchmark_color=false

---------------------------------------------------------------------------
Benchmark                    Time           CPU Iterations UserCounters...
---------------------------------------------------------------------------
fixture/BM_irate            39 ns         39 ns   17974556 test=5.67854
fixture/BM_range_v3         40 ns         40 ns   17326655 test=5.67854
fixture/BM_loop             40 ns         40 ns   17421502 test=5.67854

~/workspace/irate/release/benchmark/product_benchmark --benchmark_color=false

---------------------------------------------------------------------------
Benchmark                    Time           CPU Iterations UserCounters...
---------------------------------------------------------------------------
fixture/BM_irate          1302 ns       1302 ns     522892 test=-251.067
fixture/BM_range_v3       1310 ns       1310 ns     536559 test=-251.067
fixture/BM_loop           1335 ns       1335 ns     515426 test=-251.067

~/workspace/irate/release/benchmark/enumerate_benchmark --benchmark_color=false

---------------------------------------------------------------------------
Benchmark                    Time           CPU Iterations UserCounters...
---------------------------------------------------------------------------
fixture/BM_irate            39 ns         39 ns   18355584 test=-48.0793
fixture/BM_range_v3         39 ns         39 ns   18061843 test=-48.0793
fixture/BM_loop             29 ns         29 ns   23787363 test=-48.0793

~/workspace/irate/release/benchmark/range_benchmark --benchmark_color=false

---------------------------------------------------------------------------
Benchmark                    Time           CPU Iterations UserCounters...
---------------------------------------------------------------------------
fixture/BM_irate           251 ns        251 ns    2766288 test=4.95k
fixture/BM_range_v3        253 ns        253 ns    2761372 test=4.95k
fixture/BM_loop            254 ns        254 ns    2760285 test=4.95k