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:
- A large selection of algorithms and sequence adaptors for creating powerful and efficient data pipelines
- Much improved safety compared with standard library iterators and ranges
- Improved ease of use in common cases, particularly for defining your own sequences and adaptors
- Improved run-time efficiency for some common operations
- Compatibility with existing standard library types and concepts
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:
- GCC 11.3 and newer
- LLVM Clang 16 and newer
- MSVC 2022
- AppleClang/Xcode 16
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 position
These 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:
- Because we have access to the sequence object during increment and dereference operations, we can provide inexpensive universal bounds checking for sequences (with a clearly marked opt-out where needed)
- Because we need the sequence object in order to do anything useful with a cursor, dangling cursors are not possible by design: if the sequence object is no longer around, the cursor can't be used
- Because a cursor only represents a position in a sequence (like an integer index for an array), cursor invalidation is much less likely when modifying the underlying sequence -- and if the element at the given position no longer exists, this will be caught by the bounds check at the next attempted read.
- Because element access requires the original sequence, we don't need to make a distinction between mutable
iterators andconst_iterators -- 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_sequences allow multiple cursors to iterate over the sequence independently, potentially passing over each position multiple timesbidirectional_sequences are multipass sequences whose cursors can be decremented as well as incrementedrandom_access_sequences are bidirectional sequences whose cursors can be incremented or decremented an arbitrary number of places in constant timecontiguous_sequences are random-access sequences which are backed by a contiguous, in-memory array
The 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