A C++20 library for sequence-orientated programming
BSL-1.0 License
Flux is a C++20 library for sequence-orientated programming, similar in spirit to C++20 ranges, Python itertools, Rust iterators and others.
Flux offers:
constexpr auto result = flux::ints() // 0,1,2,3,...
.filter(flux::pred::even) // 0,2,4,6,...
.map([](int i) { return i * 2; }) // 0,4,8,12,...
.take(3) // 0,4,8
.sum(); // 12
static_assert(result == 12);
Try it on Compiler Explorer!
Flux can be used with any C++ build system by downloading the latest automatically generated single header file and #include
-ing it along with your own sources.
Flux can be used with CMake's FetchContent
to download the library and keep it up to date. Add the following to your CMakeLists.txt:
include(FetchContent)
FetchContent_Declare(
flux
GIT_REPOSITORY https://github.com/tcbrindle/flux.git
GIT_TAG main # Replace with a git commit id to fix a particular revision
)
FetchContent_MakeAvailable(flux)
and then add
target_link_libraries(my_target PUBLIC flux::flux)
where my_target
is the name of the library or executable target that you want to build with Flux.
If you don't have an existing CMake project or just want to play around, you can find a starter project in this repository.
Flux is available in vcpkg and can be installed with
vcpkg install flux
See the vcpkg documentation for more details.
Flux requires a recent compiler with good support for the C++20 standard. It is tested with:
AppleClang is currently not usable due to missing C++20 support.
Flux provides a broadly equivalent feature set to C++20 Ranges, but uses a slightly different iteration model based around cursors rather than iterators. Flux cursors are a generalisation of array indices, whereas STL iterators are a generalisation of array pointers.
A Flux sequence
provides four basis operations:
flux::first(seq)
returns an object called a cursor, which represents a position in a sequence. For a sequence with N elements there are N+1 possible cursor positions, including the past-the-end (terminal) position.flux::is_last(seq, cursor)
returns a boolean value indicating whether the cursor is in the terminal positionflux::inc(seq, cursor)
increments the given cursor, so that it points to the next element in the sequenceflux::read_at(seq, cursor)
returns the sequence element at the given cursor positionThese basis operations are equivalent to the basis operations on STL iterators (begin()
, iter == end()
, ++iter
and *iter
respectively). The crucial difference is that in the Flux model, you need to provide both the sequence and the cursor to each function call, whereas in the STL model the iterator must know how to increment and dereference itself.
STL iterators are "smart", but Flux cursors are not!
This seemingly small change has some far-reaching consequences. In particular:
iterator
s and const_iterator
s -- the same cursor type is used for both const and non-const access, making cursors and sequences considerably simpler to implement than STL iterators and ranges.Like STL input ranges, basic Flux sequences are assumed to be single-pass by default. Flux also provides various far more powerful sequences, closely modeled on their STL counterparts:
multipass_sequence
s allow multiple cursors to iterate over the sequence independently, potentially passing over each position multiple timesbidirectional_sequence
s are multipass sequences whose cursors can be decremented as well as incrementedrandom_access_sequence
s are bidirectional sequences whose cursors can be incremented or decremented an arbitrary number of places in constant timecontiguous_sequence
s are random-access sequences which are backed by a contiguous, in-memory arrayThe close correspondence between Flux's sequence concepts and their ranges counterparts means that we can easily bridge the gap between the two libraries. In particular, we provide STL-compatible iterators to ensure that every Flux sequence is also a C++20 range, meaning they can be used with existing STL algorithms (and with range-for loops!) just like any other range.
Work-in-progress reference documentation can be found at tristanbrindle.com/flux
Conference | Year | Title |
---|---|---|
C++ on Sea | 2023 | Iteration Revisited: A Safer Iteration Model for C++ |
CppNorth | 2023 | Lightning Talk: Faster Filtering with Flux |
Podcast | Episode | Date | Title |
---|---|---|---|
ADSP | 125 | 2023-04-14 | NanoRange with Tristan Brindle |
ADSP | 126 | 2023-04-21 | Flux (and Flow) with Tristan Brindle |
ADSP | 127 | 2023-04-28 | Flux, ChatGPT & More with Tristan Brindle |
CppCast | 364 | 2023-07-07 | Sequence-Oriented Programming |
Flux is still pre-1.0 and in rapid development. As such, there are no API stability guarantees at this time.
Once Flux 1.0 is released we aim to follow semantic versioning.
Flux is available under the Boost Software License 1.0