Skip to content

Latest commit

 

History

History
146 lines (96 loc) · 8.49 KB

README.md

File metadata and controls

146 lines (96 loc) · 8.49 KB
Raw

Standard License windows macos linux codecov

🅕🅛🅤🅧

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

A Quick Example

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!

Getting Started

Single header

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.

CMake

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.

vcpkg

Flux is available in vcpkg and can be installed with

vcpkg install flux

See the vcpkg documentation for more details.

Compiler support

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

The Flux difference

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 position
  • flux::inc(seq, cursor) increments the given cursor, so that it points to the next element in the sequence
  • flux::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 and const_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 times
  • bidirectional_sequences are multipass sequences whose cursors can be decremented as well as incremented
  • random_access_sequences are bidirectional sequences whose cursors can be incremented or decremented an arbitrary number of places in constant time
  • contiguous_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.

Documentation

Work-in-progress reference documentation can be found at tristanbrindle.com/flux

Audio and Video

Conference Talks

Conference Year Title
C++ on Sea 2023 Iteration Revisited: A Safer Iteration Model for C++
CppNorth 2023 Lightning Talk: Faster Filtering with Flux

Podcasts

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

Stability

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.

License

Flux is available under the Boost Software License 1.0