Concept Subspace :: sus :: iter :: Iterator

source
template <class T, class Item>
concept Iterator
requires 
requires(std::remove_cvref_t<T>& t, const std::remove_cvref_t<T>& c) {
      // Has a T::Item typename.
      requires(!std::is_void_v<typename std::remove_cvref_t<T>::Item>);
      // The T::Item matches the concept input.
      requires(std::same_as<typename std::remove_cvref_t<T>::Item, Item>);
      // Subclasses from IteratorBase<T, T::Item>.
      requires ::sus::ptr::SameOrSubclassOf<
          std::remove_cvref_t<T>*, IteratorBase<std::remove_cvref_t<T>, Item>*>;
      // Required methods.
      { t.next() } noexcept -> std::same_as<::sus::option::Option<Item>>;
      { c.size_hint() } noexcept -> std::same_as<SizeHint>;
    }

A concept for all implementations of iterators. See IteratorBase for the methods on an Iterator.

Types that satisfy this concept can be used in for loops and provide all the methods of an iterator type, which are found in IteratorBase.

Any Iterator's full definition includes a number of other methods as well, built on top of next, and so you get them for free.

Iterators are also composable, and it's possible to chain them together to do more complex forms of processing.

Required methods.

An iterator has two required methods.

  • auto next() -> Option<Item>

    Returns an Option containing the next Item as long as there are elements, and once they've all been exhausted, will return None to indicate that iteration is finished. Individual iterators may choose to resume iteration, and so calling next again may or may not eventually start returning an Item again at some point.

  • auto size_hint() const -> SizeHint

    Returns a SizeHint containing a lower bound and optional upper bound on the number of elements left to be yielded by the iterator. An upper bound of None indicates either an unknown upper bound or a bound that is larger than usize. Returning lower = 0 and upper = None is correct for any iterator, but providing a more accurate bound can benefit performance optiomizations. Returning an incorrect bound is technically possible but is a violation of the Iterator protocol.