Awesome
CXXIter
CXXIter is a ergonomic C++ Iterator interface for STL containers, similar to the iterators found in Rust or C#'s LINQ. It supports passing values by (const) reference or by using move semantics, which is tricky in some places, since references can not be stored in STL containers.
The API
A full API-Documentation can be found here.
Entry
The CXXIter interface is entered by instantiating one of the possible source classes.
The type of the source determines how the values from the container are passed (const reference / reference / move semantics).
For that, there exist the three sources CXXIter::SrcCRef, CXXIter::SrcRef, and CXXIter::SrcMov respectively.
std::vector<float> input = {1.34f, 1.37f};
CXXIter::SrcCRef constRefIter(input);
CXXIter::SrcRef mutableRefIter(input);
CXXIter::SrcMov moveIter(std::move(input));
There is also the shortcut using CXXIter::from(), which tries to determine the type of the source class to use, depending on the type of the given input parameter:
const std::vector<float> constInput = {1.34f, 1.37f};
std::vector<float> input = {1.34f, 1.37f};
auto constRefIter = CXXIter::from(constInput);
auto mutableRefIter = CXXIter::from(input);
auto moveIter = CXXIter::from(std::move(input));
Chaining
From there, everything returned by calling a member function either returns another iterator, or resolves the iterator to a final result. There are a lot of chain functions. Here some examples:
cast - Casting the elements of the iterator
std::vector<float> input = {1.35, 56.123};
std::vector<double> output = CXXIter::from(input)
.cast<double>()
.collect<std::vector>();
filter - Filtering elements of the iterator
std::vector<int> input = {1, 2, 3, 4, 5, 6, 7, 8};
std::vector<int> output = CXXIter::from(input)
.filter([](int item) { return (item % 2) == 0; })
.collect<std::vector>();
flatMap - Merging nested containers into the outer iterator
std::vector<std::pair<std::string, std::vector<int>>> input = {
{"first pair", {1337, 42}},
{"second pair", {6, 123, 7888}}
};
std::vector<int> output = CXXIter::from(std::move(input))
.flatMap([](auto&& item) { return std::get<1>(item); })
.collect<std::vector>();
zip - Zipping two iterators together so they run in parallel (yielding pairs)
std::vector<std::string> input1 = {"1337", "42"};
std::vector<int> input2 = {1337, 42};
std::vector<std::pair<std::string, int>> output = CXXIter::from(input1).copied()
.zip(CXXIter::from(input2).copied())
.collect<std::vector>();
Consuming
Without calling a consumer method on the created iterator, no actual work is done.
There is a wide variety of consumers, ranging from simple aggregating ones, such as count(), or sum(), to the classics such as collect() and forEach().
Examples
For a large list of examples, have a look at the unit-tests in tests/.
Benchmarks
CXXIter's design tries to avoid any structural slowdowns. As such, it does avoid using virtual dispatch in hot paths, as well as the usage of std::function<>.
Here are the benchmark results from the simple benchmark in the tests/ folder on my machine (Ryzen 5800X), comparing a native, a C++20 ranges and a CXXIter implementation of each micro-benchmark.
Compiler: gcc version 12.2.1 20221020
--------------------------------------------------------------------------------------------
Benchmark Time CPU Iterations
--------------------------------------------------------------------------------------------
FilterMap_Native/Small 198 ns 198 ns 71457425
FilterMap_CXX20Ranges/Small 182 ns 182 ns 67359112
FilterMap_CXXIter/Small 233 ns 233 ns 63686125
FilterMap_Native/Large 2883871358 ns 2883876073 ns 5
FilterMap_CXX20Ranges/Large 3255969494 ns 3255896584 ns 5
FilterMap_CXXIter/Large 3323312771 ns 3323321153 ns 4
Filter_Native/Large 416454279 ns 416454614 ns 35
Filter_CXX20Ranges/Large 381753661 ns 381728809 ns 37
Filter_CXXIter/Large 480220190 ns 480220984 ns 29
Filter_Native/Small 64.2 ns 64.2 ns 262228564
Filter_CXX20Ranges/Small 65.6 ns 65.6 ns 212019379
Filter_CXXIter/Small 66.6 ns 66.6 ns 210251620
Map_Native/Large 726392652 ns 726391678 ns 19
Map_CXX20Ranges/Large 709160787 ns 709064098 ns 20
Map_CXXIter/Large 730594430 ns 730572539 ns 19
Map_Native/Small 68.6 ns 68.6 ns 167033097
Map_CXX20Ranges/Small 64.6 ns 64.6 ns 169229151
Map_CXXIter/Small 67.6 ns 67.6 ns 207433543
Cast_Native/Large 301692473 ns 301692325 ns 47
Cast_CXX20Ranges/Large 300917110 ns 300850142 ns 47
Cast_CXXIter/Large 306349150 ns 306340990 ns 47
Cast_Native/Small 80.4 ns 80.4 ns 173120146
Cast_CXX20Ranges/Small 66.7 ns 66.7 ns 208613349
Cast_CXXIter/Small 67.2 ns 67.2 ns 193698681
GroupBy_Native/Large 1566267584 ns 1566269799 ns 9
GroupBy_CXXIter/Large 1742169188 ns 1741891872 ns 8
GroupBy_Native/Small 202 ns 202 ns 69780765
GroupBy_CXXIter/Small 274 ns 274 ns 51176489
ChunkedExactMath_CXXIter/Large 101300921 ns 101301257 ns 138
ChunkedExactMath_Native/Large 101656993 ns 101657235 ns 138
ChunkedExactMath_CXXIter/Small 11.8 ns 11.8 ns 1000000000
ChunkedExactMath_Native/Small 12.0 ns 12.0 ns 1000000000
OverlappingChunkedExactMath_CXXIter/Large 297710325 ns 297709856 ns 47
OverlappingChunkedExactMath_Native/Large 293148257 ns 293149023 ns 48
OverlappingChunkedExactMath_CXXIter/Small 25.5 ns 25.5 ns 551919955
OverlappingChunkedExactMath_Native/Small 25.7 ns 25.7 ns 542539508
Time: lower is better, Iterations: higher is better
Including In Your Project
To include CXXIter in your cmake project, you can do this:
include(FetchContent)
# fetching CXXIter from github
FetchContent_Declare(
CXXIter
GIT_REPOSITORY "https://github.com/seijikun/CXXIter"
GIT_TAG master
)
FetchContent_MakeAvailable(CXXIter)
# "link" your project against CXXIter, which adds the correct include paths
target_link_libraries(${PROJECT_NAME} PRIVATE CXXIter)