Sequence Access

first

template<sequence Seq>
auto first(Seq &seq) -> cursor_t<Seq>;

Returns a cursor to the first element of seq.

Complexity:

Constant if multipass_sequence<Seq>, otherwise linear

is_last

template<sequence Seq>
auto is_last(Seq &seq, cursor_t<Seq> const &cur) -> bool;

Returns true if cur is at the past-the-end position of seq.

Complexity:

Constant

last

template<bounded_sequence Seq>
auto last(Seq &seq) -> cursor_t<Seq>;

Returns a cursor which is in the past-the-end position of seq.

is_last(seq, last(seq)) is always true.

Complexity:

Constant

inc

template<sequence Seq>
auto inc(Seq &seq, cursor_t<Seq> &cur) -> cursor_t<Seq>&;

Advances the cursor by one position.

Returns:

A reference to cur

Complexity:

Constant if random_access_sequence<Seq>, otherwise linear.

template<random_access_sequence Seq>
auto inc(Seq &seq, cursor_t<Seq> &cur, distance_t offset) -> cursor_t<Seq>&

Advances the cursor by offset positions, or decrements it if offset is negative.

Returns:

A reference to cur

Complexity:

Constant

dec

template<bidirectional_sequence Seq>
auto dec(Seq &seq, cursor_t<Seq> &cur) -> cursor_t<Seq>&;

Decrements the cursor by one position

Returns:

A reference to cur

Complexity:

Constant if random_access_sequence<Seq>, otherwise linear

read_at

template<sequence Seq>
auto read_at(Seq &seq, cursor_t<Seq> const &cur) -> element_t<Seq>;

Accesses the element at the given cursor position.

Complexity:

Constant

read_at_unchecked

template<sequence Seq>
auto read_at_unchecked(Seq &seq, cursor_t<Seq> const &cur) -> element_t<Seq>;

Accesses the element at the given cursor position without performing safety checks.

Danger

Using this function can result in undefined behaviour that would otherwise be caught by Flux’s safety checks.

Complexity:

Constant

move_at

template<sequence Seq>
auto move_at(Seq &seq, cursor_t<Seq> const &cur) -> rvalue_element_t<Seq>;

Accesses the element at the given cursor position as an rvalue reference or prvalue temporary.

Complexity:

Constant

move_at_unchecked

template<sequence Seq>
auto move_at_unchecked(Seq &seq, cursor_t<Seq> const &cur) -> rvalue_element_t<Seq>;

Accesses the element at the given cursor position as an rvalue reference or prvalue temporary without performing safety checks.

Danger

Using this function can result in undefined behaviour that would otherwise be caught by Flux’s safety checks.

Complexity:

Constant

distance

template<multipass_sequence Seq>
auto distance(Seq &seq, cursor_t<Seq> const &from, cursor_t<seq> const &to) -> distance_t;

Returns number of times from needs to be incremented until it is equal to to.

For random-access sequences, to may point to an earlier position than from, in which case the result will be negative.

Complexity:

Constant if random_access_sequence<Seq>, otherwise linear

data

template<contiguous_sequence Seq>
auto data(Seq &seq) -> std::add_pointer_t<std::remove_reference_t<element_t<Seq>>>;

Provides a pointer to the start of the underlying raw storage of a contiguous_sequence.

Complexity:

Constant

size

auto size(sized_sequence auto &seq) -> distance_t;

Returns the number of elements in the sequence. Performs no iteration.

Complexity:

Constant

usize

auto usize(sized_sequence auto &seq) -> std::size_t;

Returns the number of elements in the sequence as an unsigned std::size_t.

Complexity:

Constant

next

template<sequence Seq>
auto next(Seq &seq, cursor_t<Seq> cur) -> cursor_t<Seq>;

Returns a new cursor which points to the next position after cur.

Complexity:

Constant if random_access_sequence<Seq>, otherwise linear

template<sequence Seq>
auto next(Seq &seq, cursor_t<Seq> cur, distance_t offset) -> cursor_t<Seq>;

If offset is non-negative, returns a new cursor which points to a position offset places past cur.

If offset is negative:

• If Seq is bidirectional, returns a new cursor which points to a position -offset places before cur

• Otherwise, returns cur

Complexity:

Constant if random_access_sequence<Seq>, otherwise linear

prev

template<bidirectional_sequence Seq>
auto prev(Seq &seq, cursor_t<Seq> cur) -> cursor_t<Seq>;

Returns a new cursor which points to the position before cur

Complexity:

Constant if random_access_sequence<Seq>, otherwise linear

is_empty

template<sequence Seq>
requires sized_sequence<Seq> || multipass_sequence<Seq>
auto is_empty(Seq &seq) -> bool;

Returns true if seq contains no elements.

Equivalent to:

if constexpr (sized_sequence<Seq>) {
    return size(seq) == 0;
} else {
    return is_last(seq, first(seq));
}

Complexity:

Constant

swap_with

template<sequence Seq1, sequence Seq2>
requires element_swappable_with<Seq1, Seq2>
auto swap_with(Seq1 &seq1, cursor_t<Seq1> const &cur1, Seq2 &seq2, cursor_t<Seq2> const &cur2) -> void;

Swaps the elements at position cur1 of seq1 and position cur2 of seq2.

Complexity:

Constant

swap_at

template<multipass_sequence Seq>
requires element_swappable_with<Seq, Seq>
auto swap_at(Seq &seq, cursor_t<Seq> const &cur1, cursor_t<Seq> const &cur2) -> void;

Swaps the elements at position cur1 and cur2.

Equivalent to swap_with(seq, cur1, seq, cur2)

Complexity:

Constant

front

template<multipass_sequence Seq>
auto front(Seq &seq) -> optional<element_t<Seq>>;

If seq is empty, returns a disengaged optional. Otherwise, returns an engaged optional containing the first element of seq (which may be a reference).

Complexity:

Constant

back

template<bidirectional_sequence Seq>
requires bounded_sequence<Seq>
auto back(Seq &seq) -> optional<element_t<Seq>>;

If seq is empty, returns a disengaged optional. Otherwise, returns an engaged optional containing the rear-most element of seq (which may be a reference).

Complexity:

Constant

begin

auto begin(sequence auto &seq) -> std::input_iterator auto;

Returns a C++20 iterator of implementation-defined type pointing to the first element of seq. The resulting iterator forms a valid range with the sentinel returned by end(seq).

The category of the returned iterator depends on the properties of seq. Multipass, bidirectional, random-access and contiguous sequences will return forward, bidirectional, random-access and contiguous iterators respectively.

Complexity:

Constant

end

auto end(sequence auto &seq)

If seq is a bounded_sequence whose cursor type satisfies std::copy_constructible, returns an iterator of the same type as begin(seq) which points to the past-the-end position of seq.

Otherwise, returns std::default_sentinel.

Complexity:

Constant