class IteratorBase

Declaration

template <class Iter, class ItemT>
class IteratorBase { /* full declaration omitted */ };

Description

The base class for all [`Iterator`]($sus::iter::Iterator) types. The [`Iterator`]($sus::iter::Iterator) concept requires that a type subclasses from `IteratorBase` and is `final` in order to be considered an [`Iterator`]($sus::iter::Iterator). No code should refer to `IteratorBase` except for defining the base class of an iterator, and it should be treated as an implementation detail only.

Declared at: sus/iter/iterator_defn.h:57

Templates

Iter

ItemT

Method Overview

• protected constexpr IteratorBase<Iter, Item>() noexcept
• public template <class f:auto>constexpr bool all(::sus::fn::FnMut<bool (sus::iter::IteratorBase::Item)> auto f) noexcept
• public template <class f:auto>constexpr bool any(::sus::fn::FnMut<bool (sus::iter::IteratorBase::Item)> auto f) noexcept
• protected inline constexpr const Iter & as_subclass() const
• protected inline constexpr Iter & as_subclass_mut()
• public constexpr auto begin() & noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto by_ref() & noexcept
• public template <class Other>constexpr Iterator<sus::iter::IteratorBase::Item> auto chain(Other && other) && noexcept
• public constexpr Iterator<std::remove_cvref_t<Item>> auto cloned() && noexcept
• public template <class Other, int &... , class OtherItem = typename IntoIteratorOutputType<Other>::Item>constexpr std::weak_ordering cmp(Other && other) && noexcept
• public template <class Other, int &... , class OtherItem = typename IntoIteratorOutputType<Other>::Item, class cmp:auto>constexpr std::weak_ordering cmp_by(Other && other, ::sus::fn::FnMut<std::weak_ordering (const std::remove_reference_t<Item> &, const std::remove_reference_t<OtherItem> &)> auto cmp) && noexcept
• public template <class C>constexpr C collect() && noexcept
• public constexpr ::sus::collections::Vec<ItemT> collect_vec() && noexcept
• public constexpr Iterator<std::remove_cvref_t<Item>> auto copied() && noexcept
• public constexpr ::sus::num::usize count() && noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto cycle() && noexcept
• public constexpr auto end() & noexcept
• public constexpr auto enumerate() && noexcept
• public template <class Other, int &... , class OtherItem = typename IntoIteratorOutputType<Other>::Item>constexpr bool eq(Other && other) && noexcept
• public template <class Other, int &... , class OtherItem = typename IntoIteratorOutputType<Other>::Item, class eq_fn:auto>constexpr bool eq_by(Other && other, ::sus::fn::FnMut<bool (const std::remove_reference_t<Item> &, const std::remove_reference_t<OtherItem> &)> auto eq_fn) && noexcept
• public template <class pred:auto>constexpr Iterator<sus::iter::IteratorBase::Item> auto filter(::sus::fn::FnMut<bool (const std::remove_reference_t<Item> &)> auto pred) && noexcept
• public template <class MapFn, int &... , class R = std::invoke_result_t<MapFn &, ItemT &&>, class InnerR = ::sus::option::__private::IsOptionType<R>::inner_type>constexpr Iterator<InnerR> auto filter_map(MapFn f) && noexcept
• public template <class pred:auto>constexpr Option<sus::iter::IteratorBase::Item> find(::sus::fn::FnMut<bool (const int &)> auto pred) noexcept
• public template <class FindFn, int &... , class R, class InnerR = ::sus::option::__private::IsOptionType<R>::inner_type>constexpr Option<InnerR> find_map(FindFn f) noexcept
• public template <class F, int &... , class R, class InnerR>constexpr Iterator<InnerR> auto flat_map(F f) && noexcept
• public constexpr auto flatten() && noexcept
• public template <class F>constexpr void for_each(F f) && noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto fuse() && noexcept
• public template <class Other, int &... , class OtherItem>constexpr bool ge(Other && other) && noexcept
• public template <class GenFn, int &... , class R, class GenR = __private::IsGenerator<R>::type>Iterator<GenR> auto generate(GenFn generator_fn) && noexcept
• public template <class Other, int &... , class OtherItem>constexpr bool gt(Other && other) && noexcept
• public template <class fn:auto>constexpr Iterator<sus::iter::IteratorBase::Item> auto inspect(::sus::fn::FnMut<void (const int &)> auto fn) && noexcept
• public constexpr Iter && into_iter() && noexcept
• public constexpr bool is_sorted() noexcept
• public template <class compare:auto>constexpr bool is_sorted_by(::sus::fn::FnMut<std::weak_ordering (const int &, const int &)> auto compare) noexcept
• public constexpr Option<sus::iter::IteratorBase::Item> last() && noexcept
• public template <class Other, int &... , class OtherItem>constexpr bool le(Other && other) && noexcept
• public template <class Other, int &... , class OtherItem>constexpr bool lt(Other && other) && noexcept
• public template <class MapFn, int &... , class R>constexpr Iterator<R> auto map(MapFn fn) && noexcept
• public template <class MapFn, int &... , class R, class InnerR = ::sus::option::__private::IsOptionType<R>::inner_type>constexpr Iterator<InnerR> auto map_while(MapFn fn) && noexcept
• public constexpr Option<sus::iter::IteratorBase::Item> max() && noexcept
• public template <class compare:auto>constexpr Option<sus::iter::IteratorBase::Item> max_by(sus::fn::FnMut<std::weak_ordering (const int &, const int &)> auto compare) && noexcept
• public constexpr Option<sus::iter::IteratorBase::Item> min() && noexcept
• public template <class compare:auto>constexpr Option<sus::iter::IteratorBase::Item> min_by(sus::fn::FnMut<std::weak_ordering (const int &, const int &)> auto compare) && noexcept
• public template <class Other, int &... , class OtherItem>constexpr bool ne(Other && other) && noexcept
• public constexpr Option<sus::iter::IteratorBase::Item> nth(sus::num::usize n) noexcept
• public constexpr Option<sus::iter::IteratorBase::Item> nth_back(sus::num::usize n) noexcept
• public template <class Other, int &... , class OtherItem>constexpr std::partial_ordering partial_cmp(Other && other) && noexcept
• public template <class Other, int &... , class OtherItem, class cmp:auto>constexpr std::partial_ordering partial_cmp_by(Other && other, ::sus::fn::FnMut<std::partial_ordering (const int &, const int &)> auto cmp) && noexcept
• public template <class B, class pred:auto>constexpr sus::Tuple<B, B> partition(::sus::fn::FnMut<bool (const int &)> auto pred) && noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto peekable() && noexcept
• public template <class pred:auto>constexpr Option<sus::num::usize> position(::sus::fn::FnMut<bool (sus::iter::IteratorBase::Item &&)> auto pred) noexcept
• public template <class P = ItemT>constexpr P product() && noexcept
• public constexpr IteratorRange<Iter> range() && noexcept
• public template <class F, int &... , class R>constexpr Option<sus::iter::IteratorBase::Item> reduce(F f) && noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto rev() && noexcept
• public template <class pred:auto>constexpr Option<sus::iter::IteratorBase::Item> rfind(::sus::fn::FnMut<bool (const int &)> auto pred) noexcept
• public template <class pred:auto>constexpr Option<sus::num::usize> rposition(::sus::fn::FnMut<bool (sus::iter::IteratorBase::Item &&)> auto pred) noexcept
• public template <class State, class F, int &... , class R, class InnerR = ::sus::option::__private::IsOptionType<R>::inner_type>constexpr Iterator<InnerR> auto scan(State initial_state, F f) && noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto skip(sus::num::usize n) && noexcept
• public template <class pred:auto>constexpr Iterator<sus::iter::IteratorBase::Item> auto skip_while(::sus::fn::FnMut<bool (const int &)> auto pred) && noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto step_by(sus::num::usize step) && noexcept
• public template <class Other, int &... , class OtherItem>constexpr std::strong_ordering strong_cmp(Other && other) && noexcept
• public template <class Other, int &... , class OtherItem, class cmp:auto>constexpr std::strong_ordering strong_cmp_by(Other && other, ::sus::fn::FnMut<std::strong_ordering (const int &, const int &)> auto cmp) && noexcept
• public template <class P = ItemT>constexpr P sum() && noexcept
• public constexpr Iterator<sus::iter::IteratorBase::Item> auto take(sus::num::usize n) && noexcept
• public template <class pred:auto>constexpr Iterator<sus::iter::IteratorBase::Item> auto take_while(::sus::fn::FnMut<bool (const int &)> auto pred) && noexcept
• public template <class B, class F, int &... , class R>constexpr R try_fold(B init, F f) noexcept
• public template <class F, int &... , class R>constexpr R try_for_each(F f) noexcept
• public template <class B, class F, int &... , class R>constexpr R try_rfold(B init, F f) noexcept
• public template <class CollectionA, class CollectionB, int &... , class ItemA = ::sus::option::__private::IsTupleOfSizeTwo<ItemT>::first_type, class ItemB = ::sus::option::__private::IsTupleOfSizeTwo<ItemT>::second_type>constexpr sus::Tuple<CollectionA, CollectionB> unzip() && noexcept
• public template <class Other, int &... , class OtherItem>constexpr Iterator<sus::Tuple<ItemT, OtherItem>> auto zip(Other && other) && noexcept

Methods

¶constexpr IteratorBase<Iter, Item>() noexcept

Declared at: sus/iter/iterator_defn.h:59

¶template <class f : auto>
constexpr bool all(
    ::sus::fn::FnMut<
        bool(sus::iter::IteratorBase::Item)> auto
        f) noexcept

Declared at: sus/iter/iterator_defn.h:100

Templates

f:auto

Parameters

::sus::fn::FnMut<bool( sus::iter::IteratorBase::Item)> auto f

¶template <class f : auto>
constexpr bool any(
    ::sus::fn::FnMut<
        bool(sus::iter::IteratorBase::Item)> auto
        f) noexcept

Declared at: sus/iter/iterator_defn.h:110

Templates

f:auto

Parameters

::sus::fn::FnMut<bool( sus::iter::IteratorBase::Item)> auto f

¶inline constexpr const Iter& as_subclass() const

Declared at: sus/iter/iterator_defn.h:68

¶inline constexpr Iter& as_subclass_mut()

Declared at: sus/iter/iterator_defn.h:71

¶constexpr auto begin() & noexcept

Description

Adaptor for use in ranged for loops.

Declared at: sus/iter/iterator_defn.h:77

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
by_ref() & noexcept

Description

Returns an iterator that refers to this iterator, and for which operations on it will also be applied to this iterator. This is useful to allow applying iterator adapters while still retaining ownership of the original iterator.

Declared at: sus/iter/iterator_defn.h:117

¶template <class Other>
constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
chain(Other&& other) && noexcept

Description

Takes two iterators and creates a new iterator over both in sequence. `chain()` will return a new iterator which will first iterate over values from the first iterator and then over values from the second iterator. In other words, it links two iterators together, in a chain. 🔗 `sus::iter::Once` is commonly used to adapt a single value into a chain of other kinds of iteration.

Declared at: sus/iter/iterator_defn.h:133

Templates

Other

Parameters

Other&& other

¶constexpr Iterator<std::remove_cvref_t<Item>> auto
cloned() && noexcept

Description

Creates an iterator which clones all of its elements. This is useful when you have an iterator over `T & `, but you need an iterator over `T`. There is no guarantee whatsoever about the clone method actually being called or optimized away. So code should not depend on either.

Declared at: sus/iter/iterator_defn.h:142

¶template <class Other,
          int&...,
          class OtherItem =
              typename IntoIteratorOutputType<
                  Other>::Item>
constexpr std::weak_ordering cmp(
    Other&& other) && noexcept

Description

[Lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) compares the elements of this `Iterator` with those of another.

Declared at: sus/iter/iterator_defn.h:150

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <class Other,
          int&...,
          class OtherItem =
              typename IntoIteratorOutputType<
                  Other>::Item,
          class cmp : auto>
constexpr std::weak_ordering cmp_by(
    Other&& other,
    ::sus::fn::FnMut<std::weak_ordering(
        const std::remove_reference_t<Item>&,
        const std::remove_reference_t<
            OtherItem>&)> auto cmp) && noexcept

Description

[Lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) compares the elements of this `Iterator` with those of another with respect to the specified comparison function.

Declared at: sus/iter/iterator_defn.h:157

Templates

Other

int &

OtherItem

cmp:auto

Parameters

Other&& other

::sus::fn::FnMut<std::weak_ordering( const std::remove_reference_t<Item>&, const std::remove_reference_t< OtherItem>&)> auto cmp

¶template <class C>
constexpr C collect() && noexcept

Description

Transforms an iterator into a collection. collect() can turn anything iterable into a relevant collection. If this is used anything like in Rust, it would be one of the more powerful methods in the subspace library, used in a variety of contexts. The most basic pattern in which collect() is used is to turn one collection into another. You take a collection, call iter on it, do a bunch of transformations, and then collect() at the end. collect() can also create instances of types that are not typical collections. For example, a string can be built from chars, and an iterator of Result <T , E> items can be collected into Result <Collection <T >, E>. Or an iterator of Option <T > can be collected into Option <Collection <T >>. Because collect() is so general, and C++ lacks strong type inference, collect() doesn't know the type of collection that you want to produce, so you will always need to pass it a type argument, such as: ```cpp sus::move(iter).collect <MyCollection <i32 >>() ```

Declared at: sus/iter/iterator_defn.h:1125

Templates

C

¶constexpr ::sus::collections::Vec<ItemT>
collect_vec() && noexcept

Description

Transforms an iterator into a Vec. This function is a shorthand for `it.collect <Vec <Item >>()` in order to avoid the need for specifying a template argument. See `collect()` for more details.

Declared at: sus/iter/iterator_defn.h:1136

¶constexpr Iterator<std::remove_cvref_t<Item>> auto
copied() && noexcept

Description

Creates an iterator which copies all of its elements. This is useful when you have an iterator over `T & `, but you need an iterator over `T`.

Declared at: sus/iter/iterator_defn.h:167

¶constexpr ::sus::num::usize count() && noexcept

Description

Consumes the iterator, and returns the number of elements that were in it. The function walks the iterator until it sees an Option holding #None. # Panics If the iterator has more than `usize::MAX` elements in it the `usize` will catch overflow and panic. To avoid panic, you may use a fold over `OverflowInteger <usize >` that increments the count each iteration.

Declared at: sus/iter/iterator_defn.h:180

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
cycle() && noexcept

Description

Repeats an iterator endlessly. ``` asdaa ``` Instead of stopping at `None`, the iterator will instead start again, from the beginning. After iterating again, it will start at the beginning again. And again. And again. Forever. Note that in case the original iterator is empty, the resulting iterator will also be empty. The iterator must be `Clone` as it will be cloned in order to be repeatedly iterated.

Declared at: sus/iter/iterator_defn.h:194

¶constexpr auto end() & noexcept

Description

Adaptor for use in ranged for loops.

Declared at: sus/iter/iterator_defn.h:81

¶constexpr auto enumerate() && noexcept

Description

Creates an iterator which gives the current iteration count as well as the next value. The iterator returned yields pairs `(i, val)`, where `i` is the current index of iteration and `val` is the value returned by the iterator. `enumerate()` keeps its count as a `usize`. If you want to count by a different sized integer, the `zip()` function provides similar functionality. # Overflow Behavior The method does no guarding against overflows, so enumerating more than `usize::MAX` elements either produces the wrong result or panics depending on your build configuration. If debug assertions are enabled, a panic is guaranteed. # Panics The returned iterator might panic if the to-be-returned index would overflow a `usize`.

Declared at: sus/iter/iterator_defn.h:216

¶template <class Other,
          int&...,
          class OtherItem =
              typename IntoIteratorOutputType<
                  Other>::Item>
constexpr bool eq(Other&& other) && noexcept

Description

Determines if the elements of this `Iterator` are equal to those of another.

Declared at: sus/iter/iterator_defn.h:223

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <class Other,
          int&...,
          class OtherItem =
              typename IntoIteratorOutputType<
                  Other>::Item,
          class eq_fn : auto>
constexpr bool eq_by(
    Other&& other,
    ::sus::fn::FnMut<bool(
        const std::remove_reference_t<Item>&,
        const std::remove_reference_t<
            OtherItem>&)> auto eq_fn) && noexcept

Description

Determines if the elements of this `Iterator` are equal to those of another with respect to the specified equality function.

Declared at: sus/iter/iterator_defn.h:229

Templates

Other

int &

OtherItem

eq_fn:auto

Parameters

Other&& other

::sus::fn::FnMut<bool( const std::remove_reference_t<Item>&, const std::remove_reference_t< OtherItem>&)> auto eq_fn

¶template <class pred : auto>
constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
filter(::sus::fn::FnMut<
       bool(const std::remove_reference_t<
            Item>&)> auto pred) && noexcept

Declared at: sus/iter/iterator_defn.h:240

Templates

pred:auto

Parameters

::sus::fn::FnMut<bool( const std::remove_reference_t<Item>&)> auto pred

¶template <
    class MapFn,
    int&...,
    class R =
        std::invoke_result_t<MapFn&, ItemT&&>,
    class InnerR = ::sus::option::__private::
        IsOptionType<R>::inner_type>
constexpr Iterator<InnerR> auto filter_map(
    MapFn f) && noexcept

Declared at: sus/iter/iterator_defn.h:249

Templates

MapFn

int &

R

InnerR

Parameters

MapFn f

¶template <class pred : auto>
constexpr Option<sus::iter::IteratorBase::Item>
find(::sus::fn::FnMut<bool(const int&)> auto
         pred) noexcept

Declared at: sus/iter/iterator_defn.h:262

Templates

pred:auto

Parameters

::sus::fn::FnMut<bool(const int&)> auto pred

¶template <class FindFn,
          int&...,
          class R,
          class InnerR =
              ::sus::option::__private::
                  IsOptionType<R>::inner_type>
constexpr Option<InnerR> find_map(
    FindFn f) noexcept

Description

Applies function to the elements of iterator and returns the first non-none result. `sus::move(iter).find_map(f)` is equivalent to `sus::move(iter).filter_map(f).next()`.

Declared at: sus/iter/iterator_defn.h:276

Templates

FindFn

int &

R

InnerR

Parameters

FindFn f

¶template <class F, int&..., class R, class InnerR>
constexpr Iterator<InnerR> auto flat_map(
    F f) && noexcept

Description

Creates an iterator that works like map, but flattens nested structure. The `map()` adapter is very useful, but only when the closure argument produces values. If it produces an iterator instead, there’s an extra layer of indirection. `flat_map()` will remove this extra layer on its own. You can think of `flat_map(f)` as the semantic equivalent of mapping, and then flattening as in `map(f).flatten()`. Another way of thinking about `flat_map()`: `map()`'s closure returns one item for each element, and `flat_map()`'s closure returns an iterator for each element.

Declared at: sus/iter/iterator_defn.h:295

Templates

F

int &

R

InnerR

Parameters

F f

¶constexpr auto flatten() && noexcept

Description

Creates an iterator that flattens nested structure. This is useful when you have an iterator of iterators or an iterator of things that can be turned into iterators and you want to remove one level of indirection. In other words, this type maps `Iterator[Iterable[T]]` into `Iterator[T]`.

Declared at: sus/iter/iterator_defn.h:304

¶template <class F>
constexpr void for_each(F f) && noexcept

Description

Calls a closure on each element of an iterator. This is equivalent to using a for loop on the iterator, although break and continue are not possible from a closure. It’s generally more idiomatic to use a for loop, but for_each may be more legible when processing items at the end of longer iterator chains. In some cases for_each may also be faster than a loop, because it avoids constructing a proxy type for the loop to consume.

Declared at: sus/iter/iterator_defn.h:367

Templates

F

Parameters

F f

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
fuse() && noexcept

Description

Creates an iterator which ends after the first None. After an iterator returns `None`, future calls may or may not yield `Some(T)` again. `fuse()` adapts an iterator, ensuring that after a `None` is given, it will always return None forever. This is useful for cases where the iterator may continue to be polled after it has returned None. TODO: Implement a FusedIterator concept though a tag of some sort, so that fuse() can be a no-op in that case?

Declared at: sus/iter/iterator_defn.h:380

¶template <class Other, int&..., class OtherItem>
constexpr bool ge(Other&& other) && noexcept

Description

Determines if the elements of this Iterator are [lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) greater than or equal to those of another.

Declared at: sus/iter/iterator_defn.h:399

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <
    class GenFn,
    int&...,
    class R,
    class GenR = __private::IsGenerator<R>::type>
Iterator<GenR> auto generate(
    GenFn generator_fn) && noexcept

Description

Creates an iterator from a generator function that consumes the current iterator. Coroutines can not be constexpr, so this function is not constexpr to avoid deeper compiler errors.

Declared at: sus/iter/iterator_defn.h:391

Templates

GenFn

int &

R

GenR

Parameters

GenFn generator_fn

¶template <class Other, int&..., class OtherItem>
constexpr bool gt(Other&& other) && noexcept

Description

Determines if the elements of this Iterator are [lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) greater than those of another.

Declared at: sus/iter/iterator_defn.h:407

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <class fn : auto>
constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
inspect(::sus::fn::FnMut<void(const int&)> auto
            fn) && noexcept

Declared at: sus/iter/iterator_defn.h:418

Templates

fn:auto

Parameters

::sus::fn::FnMut<void(const int&)> auto fn

¶constexpr Iter&& into_iter() && noexcept

Description

An Iterator also satisfies IntoIterator, which simply returns itself. sus::iter::IntoIterator trait implementation.

Declared at: sus/iter/iterator_defn.h:86

¶constexpr bool is_sorted() noexcept

Description

Checks if the elements of this iterator are sorted. That is, it returns true if for each consecutive element `a` and `b`, `a < = b` is true. If the iterator yields exactly zero or one element, true is returned.

Declared at: sus/iter/iterator_defn.h:427

¶template <class compare : auto>
constexpr bool is_sorted_by(
    ::sus::fn::FnMut<std::weak_ordering(
        const int&,
        const int&)> auto compare) noexcept

Declared at: sus/iter/iterator_defn.h:436

Templates

compare:auto

Parameters

::sus::fn::FnMut<std::weak_ordering( const int&, const int&)> auto compare

¶constexpr Option<sus::iter::IteratorBase::Item>
last() && noexcept

Description

Consumes the iterator, returning the last element. This method will evaluate the iterator until it returns `None`. While doing so, it keeps track of the current element. After `None` is returned, `last()` will then return the last element it saw.

Declared at: sus/iter/iterator_defn.h:462

¶template <class Other, int&..., class OtherItem>
constexpr bool le(Other&& other) && noexcept

Description

Determines if the elements of this Iterator are [lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) less than or equal to those of another.

Declared at: sus/iter/iterator_defn.h:447

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <class Other, int&..., class OtherItem>
constexpr bool lt(Other&& other) && noexcept

Description

Determines if the elements of this Iterator are [lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) less than those of another.

Declared at: sus/iter/iterator_defn.h:455

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <class MapFn, int&..., class R>
constexpr Iterator<R> auto map(
    MapFn fn) && noexcept

Description

Creates an iterator which uses a closure to map each element to another type. The returned iterator's type is whatever is returned by the closure.

Declared at: sus/iter/iterator_defn.h:470

Templates

MapFn

int &

R

Parameters

MapFn fn

¶template <class MapFn,
          int&...,
          class R,
          class InnerR =
              ::sus::option::__private::
                  IsOptionType<R>::inner_type>
constexpr Iterator<InnerR> auto map_while(
    MapFn fn) && noexcept

Description

Creates an iterator that both yields elements based on a predicate and maps. `map_while()` takes a closure as an argument that returns Options. It will call this closure on each element of the iterator, and yield elements while it returns an Option with a value in it.

Declared at: sus/iter/iterator_defn.h:483

Templates

MapFn

int &

R

InnerR

Parameters

MapFn fn

¶constexpr Option<sus::iter::IteratorBase::Item>
max() && noexcept

Description

Returns the maximum element of an iterator. If several elements are equally maximum, the last element is returned. If the iterator is empty, None is returned. Note that `f32`/`f64` doesn’t implement `StrongOrd` due to NaN being incomparable. You can work around this by using [`Iterator::reduce`]( sus::iter::IteratorBase::reduce): ```cpp sus_check( sus::Array <f32 , 3>(2.4, f32::NAN, 1.3) .into_iter() .reduce( &f 32::max) .unwrap() == 2.4 ); ```

Declared at: sus/iter/iterator_defn.h:503

¶template <class compare : auto>
constexpr Option<sus::iter::IteratorBase::Item>
max_by(sus::fn::FnMut<std::weak_ordering(
           const int&,
           const int&)> auto compare) && noexcept

Declared at: sus/iter/iterator_defn.h:511

Templates

compare:auto

Parameters

sus::fn::FnMut<std::weak_ordering( const int&, const int&)> auto compare

¶constexpr Option<sus::iter::IteratorBase::Item>
min() && noexcept

Description

Returns the minimum element of an iterator. If several elements are equally minimum, the first element is returned. If the iterator is empty, None is returned. Note that `f32`/`f64` doesn’t implement `StrongOrd` due to NaN being incomparable. You can work around this by using [`Iterator::reduce`]( sus::iter::IteratorBase::reduce): ```cpp sus_check( sus::Array <f32 , 3>(2.4, f32::NAN, 1.3) .into_iter() .reduce( &f 32::min) .unwrap() == 2.4 ); ```

Declared at: sus/iter/iterator_defn.h:549

¶template <class compare : auto>
constexpr Option<sus::iter::IteratorBase::Item>
min_by(sus::fn::FnMut<std::weak_ordering(
           const int&,
           const int&)> auto compare) && noexcept

Declared at: sus/iter/iterator_defn.h:557

Templates

compare:auto

Parameters

sus::fn::FnMut<std::weak_ordering( const int&, const int&)> auto compare

¶template <class Other, int&..., class OtherItem>
constexpr bool ne(Other&& other) && noexcept

Description

Determines if the elements of this `Iterator` are not equal to those of another.

Declared at: sus/iter/iterator_defn.h:582

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶constexpr Option<sus::iter::IteratorBase::Item>
nth(sus::num::usize n) noexcept

Description

Returns the nth element of the iterator. Like most indexing operations, the count starts from zero, so `nth(0u)` returns the first value, `nth(1u)` the second, and so on. Note that all preceding elements, as well as the returned element, will be consumed from the iterator. That means that the preceding elements will be discarded, and also that calling `nth(0u)` multiple times on the same iterator will return different elements. `nth()` will return `None` if `n` is greater than or equal to the length of the iterator. It will stop at the first `None` encountered in the iterator and return `None`.

Declared at: sus/iter/iterator_defn.h:597

Parameters

sus::num::usize n

¶constexpr Option<sus::iter::IteratorBase::Item>
nth_back(sus::num::usize n) noexcept

Description

Returns the nth element from the end of the iterator. This is essentially the reversed version of Iterator::nth(). Although like most indexing operations, the count starts from zero, so nth_back(0) returns the first value from the end, nth_back(1) the second, and so on. Note that all elements between the end and the returned element will be consumed, including the returned element. This also means that calling nth_back(0) multiple times on the same iterator will return different elements. nth_back() will return None if n is greater than or equal to the length of the iterator. It will stop at the first `None` encountered in the iterator and return `None`.

Declared at: sus/iter/iterator_defn.h:613

Parameters

sus::num::usize n

¶template <class Other, int&..., class OtherItem>
constexpr std::partial_ordering partial_cmp(
    Other&& other) && noexcept

Description

[Lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) compares the elements of this `Iterator` with those of another. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements. As soon as an order can be determined, the evaluation stops and a result is returned. For floating-point numbers, NaN does not have a total order and will result in `std::partial_ordering::unordered` when compared.

Declared at: sus/iter/iterator_defn.h:628

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <class Other,
          int&...,
          class OtherItem,
          class cmp : auto>
constexpr std::partial_ordering partial_cmp_by(
    Other&& other,
    ::sus::fn::FnMut<std::partial_ordering(
        const int&,
        const int&)> auto cmp) && noexcept

Description

[Lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) compares the elements of this `Iterator` with those of another with respect to the specified comparison function.

Declared at: sus/iter/iterator_defn.h:635

Templates

Other

int &

OtherItem

cmp:auto

Parameters

Other&& other

::sus::fn::FnMut<std::partial_ordering( const int&, const int&)> auto cmp

¶template <class B, class pred : auto>
constexpr sus::Tuple<B, B> partition(
    ::sus::fn::FnMut<bool(const int&)> auto
        pred) && noexcept

Description

Consumes an iterator, creating two disjoint collections from it. The predicate passed to `partition()` can return `true` or `false`. `partition()` returns a pair, all of the elements for which the predicate returned `true`, and all of the elements for which it returned `false`.

Declared at: sus/iter/iterator_defn.h:649

Templates

B

pred:auto

Parameters

::sus::fn::FnMut<bool(const int&)> auto pred

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
peekable() && noexcept

Description

Creates an iterator which can use the `peek()` and `peek_mut()` methods to look at the next element of the iterator without consuming it. See their documentation for more information. A peekable iterator also supports conditionally pulling the next item out of the iterator, which is built on top of `peek()`. Note that the underlying iterator is still advanced when `peek()` or `peek_mut()` are called for the first time: In order to retrieve the next element, `next()` is called on the underlying iterator, hence any side effects (i.e. anything other than fetching the next value) of the `next()` method will occur.

Declared at: sus/iter/iterator_defn.h:665

¶template <class pred : auto>
constexpr Option<sus::num::usize> position(
    ::sus::fn::FnMut<bool(
        sus::iter::IteratorBase::Item&&)> auto
        pred) noexcept

Declared at: sus/iter/iterator_defn.h:685

Templates

pred:auto

Parameters

::sus::fn::FnMut<bool( sus::iter::IteratorBase::Item&&)> auto pred

¶template <class P = ItemT>
constexpr P product() && noexcept

Description

Iterates over the entire iterator, multiplying all the elements. An empty iterator returns the "one" value of the type. `product()` can be used to multiply any type implementing [`Product`]($sus::iter::Product), including [numerics]($sus::num), [`Option`]($sus::option::Option) and [`Result`]($sus::result::Result). # Panics / When calling `product()` and a primitive integer type is being returned, method will panic if the computation overflows. Using `product <OverflowInteger <T >>()` will allow the caller to handle overflow without a panic.

Declared at: sus/iter/iterator_defn.h:706

Templates

P

¶constexpr IteratorRange<Iter> range() && noexcept

Description

Converts the iterator into a `std::ranges::range` for use with the std ranges library. This provides stdlib compatibility for iterators in libraries that expect stdlib types. The `sus/iter/compat_ranges.h` header must be included separately to use this method, to avoid pulling in large stdlib headers by default.

Declared at: sus/iter/iterator_defn.h:717

¶template <class F, int&..., class R>
constexpr Option<sus::iter::IteratorBase::Item>
reduce(F f) && noexcept

Description

Reduces the elements to a single one, by repeatedly applying a reducing operation. If the iterator is empty, returns `None`; otherwise, returns the result of the reduction. The reducing function is a closure with two arguments: an 'accumulator', and an element. For iterators with at least one element, this is the same as `fold()` with the first element of the iterator as the initial accumulator value, folding every subsequent element into it. # Reducing References If the iterator is over references, the `reduce()` function will be limited to returning a reference; in most cases to one of the members in the iterator. To reduce and produce a new value, first apply `.copied()` or `.cloned()` and then `reduce()` that, such as `it.copied().reduce(...)` which will ensure the `reduce()` function is able to work with values instead of references. This example uses `copied()` to copy each `i32` and sum them. ```cpp auto a = sus::Array <i32 , 3>(2, 3, 4); auto out = a.iter().copied().reduce( [](i32 acc, i32 v) { return acc + v; }); sus_check(out.as_value() == 2 + 3 + 4); ```

Declared at: sus/iter/iterator_defn.h:752

Templates

F

int &

R

Parameters

F f

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
rev() && noexcept

Description

Reverses an iterator's direction. Usually, iterators iterate from front to back. After using `rev()`, an iterator will instead iterate from back to front. This is only possible if the iterator has an end, so `rev()` only works on `DoubleEndedIterator`s.

Declared at: sus/iter/iterator_defn.h:761

¶template <class pred : auto>
constexpr Option<sus::iter::IteratorBase::Item>
rfind(::sus::fn::FnMut<bool(const int&)> auto
          pred) noexcept

Declared at: sus/iter/iterator_defn.h:774

Templates

pred:auto

Parameters

::sus::fn::FnMut<bool(const int&)> auto pred

¶template <class pred : auto>
constexpr Option<sus::num::usize> rposition(
    ::sus::fn::FnMut<bool(
        sus::iter::IteratorBase::Item&&)> auto
        pred) noexcept

Declared at: sus/iter/iterator_defn.h:827

Templates

pred:auto

Parameters

::sus::fn::FnMut<bool( sus::iter::IteratorBase::Item&&)> auto pred

¶template <class State,
          class F,
          int&...,
          class R,
          class InnerR =
              ::sus::option::__private::
                  IsOptionType<R>::inner_type>
constexpr Iterator<InnerR> auto scan(
    State initial_state,
    F f) && noexcept

Description

An iterator adapter which, like `fold()`, holds internal state, but unlike `fold()`, produces a new iterator. To write a function with internal state that receives the current iterator as input and yields items in arbitrary ways, see `generate()`. `scan()` is a less general tool where the given function is executed for each item in the iterator in order. However `scan()` is constexpr while generator coroutiunes can not be. `scan()` takes two arguments: an initial value which seeds the internal state, and a closure with two arguments, the first being a mutable reference to the internal state and the second an iterator element. The closure can mutate the internal state to share state between iterations. On iteration, the closure will be applied to each element of the iterator and the return value from the closure, an `Option`, is returned by the next method. Thus the closure can return `Some(value)` to yield value, or `None` to end the iteration.

Declared at: sus/iter/iterator_defn.h:856

Templates

State

F

int &

R

InnerR

Parameters

State initial_state

F f

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
skip(sus::num::usize n) && noexcept

Description

Creates an iterator that skips the first `n` elements. `skip(n)` skips elements until `n` elements are skipped or the end of the iterator is reached (whichever happens first). After that, all the remaining elements are yielded. In particular, if the original iterator is too short, then the returned iterator is empty.

Declared at: sus/iter/iterator_defn.h:864

Parameters

sus::num::usize n

¶template <class pred : auto>
constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
skip_while(::sus::fn::FnMut<bool(const int&)> auto
               pred) && noexcept

Declared at: sus/iter/iterator_defn.h:873

Templates

pred:auto

Parameters

::sus::fn::FnMut<bool(const int&)> auto pred

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
step_by(sus::num::usize step) && noexcept

Description

Creates an iterator starting at the same point, but stepping by the given amount at each iteration. The first element of the iterator will always be returned, regardless of the step given. After that, skipped elements will be lazily walked over as needed. `step_by()` behaves like the sequence `next()`, `nth(step-1)`, `self.nth(step-1)`, ... # Panics The `step` must be greater than 0, or the function will panic. A step size of 1 returns every element.

Declared at: sus/iter/iterator_defn.h:891

Parameters

sus::num::usize step

¶template <class Other, int&..., class OtherItem>
constexpr std::strong_ordering strong_cmp(
    Other&& other) && noexcept

Description

[Lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) compares the elements of this `Iterator` with those of another. Strong ordering requires each item being compared that compares equal to share the same identity (be replaceable). Typically `Ord` is sufficient, which is required for `cmp()` and `cmp_by()`, where items that compare equivalent may still have different internal state. The comparison works like short-circuit evaluation, returning a result without comparing the remaining elements. As soon as an order can be determined, the evaluation stops and a result is returned.

Declared at: sus/iter/iterator_defn.h:907

Templates

Other

int &

OtherItem

Parameters

Other&& other

¶template <class Other,
          int&...,
          class OtherItem,
          class cmp : auto>
constexpr std::strong_ordering strong_cmp_by(
    Other&& other,
    ::sus::fn::FnMut<std::strong_ordering(
        const int&,
        const int&)> auto cmp) && noexcept

Description

[Lexicographically]($sus::cmp::Ord#how-can-i-implement-ord?) compares the elements of this `Iterator` with those of another with respect to the specified comparison function.

Declared at: sus/iter/iterator_defn.h:914

Templates

Other

int &

OtherItem

cmp:auto

Parameters

Other&& other

::sus::fn::FnMut<std::strong_ordering( const int&, const int&)> auto cmp

¶template <class P = ItemT>
constexpr P sum() && noexcept

Description

Sums the elements of an iterator. Takes each element, adds them together, and returns the result. An empty iterator returns the zero value of the type. `sum()` can be used to multiply any type implementing [`Sum`]($sus::iter::Sum), including [numerics]($sus::num), [`Option`]($sus::option::Option) and [`Result`]($sus::result::Result). # Panics / When calling `sum()` and a primitive integer type is being returned, method will panic if the computation overflows. Using `sum <OverflowInteger <T >>()` will allow the caller to handle overflow without a panic.

Declared at: sus/iter/iterator_defn.h:940

Templates

P

¶constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
take(sus::num::usize n) && noexcept

Description

Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. `take(n)` yields elements until `n` elements are yielded or the end of the iterator is reached (whichever happens first). The returned iterator is a prefix of length `n` if the original iterator contains at least `n` elements, otherwise it contains all of the (fewer than `n`) elements of the original iterator.

Declared at: sus/iter/iterator_defn.h:950

Parameters

sus::num::usize n

¶template <class pred : auto>
constexpr Iterator<
    sus::iter::IteratorBase::Item> auto
take_while(::sus::fn::FnMut<bool(const int&)> auto
               pred) && noexcept

Declared at: sus/iter/iterator_defn.h:960

Templates

pred:auto

Parameters

::sus::fn::FnMut<bool(const int&)> auto pred

¶template <class B, class F, int&..., class R>
constexpr R try_fold(B init, F f) noexcept

Description

This function acts like `fold()` but the closure returns a type that satisfies `sus::ops::Try` and which converts to the accumulator type on success through the Try concept. If the closure ever returns failure, the fold operation immediately stops and returns the failure (short-circuiting). See `fold()` for more on how to use this function. Unlike `fold()` this function may be used on an iterator without fully consuming it, since it can stop iterating early. Also unlike `fold()` the `sus::ops::Try` concept limits the accumulator value to not being a reference.

Declared at: sus/iter/iterator_defn.h:1032

Templates

B

F

int &

R

Parameters

B init

F f

¶template <class F, int&..., class R>
constexpr R try_for_each(F f) noexcept

Description

An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error. This can also be thought of as the fallible form of `for_each()` or as the stateless version of `try_fold()`. The closure must return a type that satisfies `sus::ops::Try`Default. For each success value returned, the iteration will continue. When a failure is returned from the closure, iteration will stop and the failure will be returned from `for_each()`. On success, the default success value of the `TryDefault` is returned. Unlike `for_each()` this function may be used on an iterator without fully consuming it, since it can stop iterating early.

Declared at: sus/iter/iterator_defn.h:1061

Templates

F

int &

R

Parameters

F f

¶template <class B, class F, int&..., class R>
constexpr R try_rfold(B init, F f) noexcept

Description

This is the reverse version of [`Iterator::try_fold()`]($sus::iter::IteratorBase::try_fold): it takes elements starting from the back of the iterator.

Declared at: sus/iter/iterator_defn.h:1042

Templates

B

F

int &

R

Parameters

B init

F f

¶template <
    class CollectionA,
    class CollectionB,
    int&...,
    class ItemA = ::sus::option::__private::
        IsTupleOfSizeTwo<ItemT>::first_type,
    class ItemB = ::sus::option::__private::
        IsTupleOfSizeTwo<ItemT>::second_type>
constexpr sus::Tuple<CollectionA, CollectionB>
unzip() && noexcept

Description

Converts an iterator of pairs into a pair of collections. `unzip()` consumes an entire iterator of pairs, producing two collections: one from the left elements of the pairs, and one from the right elements. This function is, in some sense, the opposite of `zip()`.

Declared at: sus/iter/iterator_defn.h:1079

Templates

CollectionA

CollectionB

int &

ItemA

ItemB

¶template <class Other, int&..., class OtherItem>
constexpr Iterator<
    sus::Tuple<ItemT, OtherItem>> auto
zip(Other&& other) && noexcept

Description

"Zips up" two iterators into a single iterator of pairs. `zip()` returns a new iterator that will iterate over two other iterators, returning a tuple where the first element comes from the first iterator, and the second element comes from the second iterator. In other words, it zips two iterators together, into a single one. If either iterator returns `None`, `next()` from the zipped iterator will return `None`. If the zipped iterator has returned `None`, further calls to `next()` will try advance both iterators, and if either returns `None` the zipped iterator will continue to return `None`. The zipped iterator is not fused if both iterators are not fused, and both resume returning values. To "undo" the result of zipping up two iterators, see unzip.

Declared at: sus/iter/iterator_defn.h:1099

Templates

Other

int &

OtherItem

Parameters

Other&& other