CXXIter::IterApi< TSelf > Class Template Reference

Public Iterator API surface. More...

#include <CXXIter.h>

Collaboration diagram for CXXIter::IterApi< TSelf >:

Classes
class	iterator
	C++ iterator implementation for a CXXIter chain. More...

Public Types
using	Iterator = trait::Iterator< TSelf >
	Type of the trait::Iterator implemenation for this. More...
using	Item = typename Iterator::Item
	Type of the elements of this iterator. (Can be references) More...
using	ItemOwned = std::remove_cvref_t< Item >
	Owned Type of the elements of this iterator. (References removed). More...

Public Member Functions
iterator	begin ()
	begin() method, part of C++'s iterator interface More...
iterator	end ()
	end() method, part of C++'s iterator interface More...
constexpr SizeHint	sizeHint () const
	Get the bounds on the remaining length of this iterator, estimated from the source and all of the chained iterations on it. More...
constexpr size_t	size () const
	Get this iterator's exact size. More...
constexpr IterValue< Item >	next ()
	Get the next element from this iterator (if any), wrapped in a CXXIter::IterValue<>. More...
constexpr void	advanceBy (size_t n)
	Advance the iterator by n elements. More...
constexpr IterValue< Item >	nextBack ()
	Get the next element from the back of this iterator (if any), wrapped in a CXXIter::IterValue<>. More...
Consumers
template<typename TUseFn >
constexpr void	forEach (TUseFn useFn)
	Consumer that calls the given function useFn for each of the elements in this iterator. More...
template<template< typename... > typename TTargetContainer, typename... TTargetContainerArgs>
constexpr auto	collect ()
	Consumer that collects all elements from this iterator in a new container of type TTargetContainer. More...
template<typename TTargetContainer >
constexpr TTargetContainer	collect ()
	Consumer that collects all elements from this iterator in a new container of type TTargetContainer. More...
template<typename TTargetContainer >
constexpr void	collectInto (TTargetContainer &container)
	Consumer that collects all elements from this iterator into the given container. More...
template<typename TResult , std::invocable< TResult &, Item && > FoldFn>
constexpr TResult	fold (TResult startValue, FoldFn foldFn)
	Consumer that executes the given foldFn for each item in this iterator, to apply to a working value, which is passed on and passed as second argument to the next call to foldFn. More...
template<std::invocable< const ItemOwned & > TPredicateFn> requires std::same_as<std::invoke_result_t<TPredicateFn, const ItemOwned&>, bool>
constexpr bool	all (TPredicateFn predicateFn)
	Tests if all elements of this iterator match the given predicateFn. More...
constexpr bool	all ()
	Tests if all elements of this iterator yield the value true when casted to bool. More...
template<std::invocable< const ItemOwned & > TPredicateFn>
constexpr bool	any (TPredicateFn predicateFn)
	Tests if any of the elements of this iterator match the given predicateFn. More...
constexpr bool	any ()
	Tests if any of the elements of this iterator yield the value true when casted to bool. More...
constexpr std::optional< size_t >	findIdx (const ItemOwned &searchItem)
	Search for the given searchItem within the items of this iterator, and return the index of the first item from the iterator that is equal to the given searchItem. More...
template<std::invocable< const ItemOwned & > TFindFn>
constexpr std::optional< size_t >	findIdx (TFindFn findFn)
	Search for the iterator with the given findFn, and return the index of the element from this iterator, for which the findFn returned true the first time. More...
template<std::invocable< const ItemOwned & > TFindFn>
constexpr IterValue< Item >	find (TFindFn findFn)
	Searches for an element of this iterator, that satisfies the given findFn predicate. More...
constexpr size_t	count ()
	Consumer that counts the elements in this iterator. More...
template<std::invocable< const ItemOwned & > TPredicateFn>
constexpr size_t	count (TPredicateFn predicateFn)
	Consumer that counts the elements in this iterator, for which the given predicateFn returns true. More...
constexpr size_t	count (const ItemOwned &countItem)
	Consumer that counts the occurences of countItem within this iterator. More...
template<typename TResult = ItemOwned> requires requires(TResult res, Item item) { { res += item }; }
constexpr TResult	sum (TResult startValue=TResult())
	Consumer that calculates the sum of all elements from this iterator. More...
std::string	stringJoin (const std::string &separator)
	Consumer that concatenates the elements of this iterator to a large std::string , where each element is separated by the specified separator. More...
template<StatisticNormalization NORM = StatisticNormalization::N, typename TResult = ItemOwned, typename TCount = ItemOwned>
constexpr std::optional< TResult >	mean (TResult sumStart=TResult())
	Consumer that calculates the mean of all elements of this iterator. More...
template<StatisticNormalization NORM = StatisticNormalization::N, typename TResult = ItemOwned, typename TCount = ItemOwned>
constexpr std::optional< TResult >	variance ()
	Consumer that calculates the variance of all elements of this iterator. More...
template<StatisticNormalization NORM = StatisticNormalization::N, typename TResult = ItemOwned, typename TCount = ItemOwned>
constexpr std::optional< TResult >	stddev ()
	Consumer that calculates the standard deviation of all elements of this iterator. More...
constexpr IterValue< Item >	min ()
	Consumer that yields the smallest element from this iterator. More...
constexpr std::optional< size_t >	minIdx ()
	Consumer that yields the index of the smallest element within this iterator. More...
constexpr IterValue< Item >	max ()
	Consumer that yields the largest element from this iterator. More...
constexpr std::optional< size_t >	maxIdx ()
	Consumer that yields the index of the largest element within this iterator. More...
template<typename TCompValueExtractFn > requires requires(const std::invoke_result_t<TCompValueExtractFn, Item&&>& a, std::remove_cvref_t<decltype(a)> ownedA) { { a < a }; { ownedA = ownedA }; }
constexpr IterValue< Item >	minBy (TCompValueExtractFn compValueExtractFn)
	Consumer that yields the smallest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given compValueExtractFn on each element. More...
template<typename TCompValueExtractFn > requires requires(const std::invoke_result_t<TCompValueExtractFn, Item&&>& a) { { a < a }; }
constexpr std::optional< size_t >	minIdxBy (TCompValueExtractFn compValueExtractFn)
	Consumer that yields the index of the smallest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given compValueExtractFn on each element. More...
template<typename TMaxValueExtractFn > requires requires(const std::invoke_result_t<TMaxValueExtractFn, Item&&>& a, std::remove_cvref_t<decltype(a)> ownedA) { { a > a }; { ownedA = ownedA }; }
constexpr IterValue< Item >	maxBy (TMaxValueExtractFn compValueExtractFn)
	Consumer that yields the largest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given compValueExtractFn on each element. More...
template<typename TMaxValueExtractFn > requires requires(const std::invoke_result_t<TMaxValueExtractFn, Item&&>& a, std::remove_cvref_t<decltype(a)> ownedA) { { a > a }; { ownedA = ownedA }; }
constexpr std::optional< size_t >	maxIdxBy (TMaxValueExtractFn compValueExtractFn)
	Consumer that yields the index of the largest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given TCompValueExtractFn on each element. More...
constexpr IterValue< Item >	last ()
	Consumer that yields the last element of this iterator. More...
constexpr IterValue< Item >	nth (size_t n)
	Return the {n}-th element from this iterator (if available). More...
Chainers
template<typename TItemOutput >
constexpr op::Caster< TSelf, TItemOutput >	cast ()
	Constructs a new iterator that casts the elements of this iterator to the type requested by TItemOutput. More...
constexpr auto	copied ()
	Constructs a new iterator that copies the elements of this iterator. More...
constexpr auto	indexed ()
	Constructs a new iterator that tags each element of this iterator with the corresponding index, stored in a std::pair. More...
constexpr op::FlagLast< TSelf >	flagLast ()
	Constructs a new iterator that tags each element with a boolean value specifying whether the element is the last one in the iterator. Boolean and actual iterator element are stored in a std::pair. More...
template<std::invocable< const ItemOwned & > TFilterFn>
constexpr op::Filter< TSelf, TFilterFn >	filter (TFilterFn filterFn)
	Constructs a new iterator that only contains the elements from this iterator, for which the given filterFn returned true. More...
template<std::invocable< const ItemOwned & > TMapFn> requires util::is_hashable<std::invoke_result_t<TMapFn, const ItemOwned&>>
constexpr op::Unique< TSelf, TMapFn >	unique (TMapFn mapFn)
	Constructs a new iterator that only contains every element of the input iterator only once. More...
constexpr auto	unique ()
	Constructs a new iterator that only contains every element of the input iterator only once. More...
constexpr op::Reverse< TSelf >	reverse ()
	Constructs a new iterator that provides the elements of this iterator in reverse order. More...
template<const size_t CHUNK_SIZE>
constexpr op::Chunked< TSelf, CHUNK_SIZE >	chunked ()
	Create new iterator that collects elements from this iterator in chunks of size up to CHUNK_SIZE, which then constitue the elements of the new iterator. More...
template<const size_t CHUNK_SIZE, const size_t STEP_SIZE = CHUNK_SIZE>
constexpr op::ChunkedExact< TSelf, CHUNK_SIZE, STEP_SIZE >	chunkedExact ()
	Create new iterator that collects elements from this iterator in exact-sized chunks of CHUNK_SIZE, which then constitue the elements of the new iterator. More...
template<std::invocable< Item && > TMapFn>
constexpr auto	map (TMapFn mapFn)
	Creates an iterator that uses the given mapFn to map each element from this iterator to elements of the new iterator. More...
template<std::invocable< Item && > TFlatMapFn>
constexpr auto	flatMap (TFlatMapFn mapFn)
	Creates an iterator that works like map(), but flattens nested containers. More...
template<GeneratorFromFunction< Item > TGeneratorFn>
constexpr auto	generateFrom (TGeneratorFn generatorFn)
	Creates a new iterator containing the items that the given generator produces for each element in this iterator. More...
constexpr auto	flatMap ()
	Creates an iterator that flattens the iterable elements of this iterator. More...
template<std::invocable< Item & > TModifierFn>
constexpr op::InplaceModifier< TSelf, TModifierFn >	modify (TModifierFn modifierFn)
	Allows to inspect and modify each item in-place, that passes through this iterator. More...
template<std::invocable< ItemOwned && > TFilterMapFn> requires util::is_optional<std::invoke_result_t<TFilterMapFn, ItemOwned&&>>
constexpr auto	filterMap (TFilterMapFn filterMapFn)
	Creates a new iterator that filters and maps items from this iterator. More...
constexpr op::SkipN< TSelf >	skip (size_t cnt)
	Creates an iterator that skips the first cnt elements from this iterator, before it yields the remaining items. More...
template<std::invocable< const Item & > TSkipPredicate>
constexpr op::SkipWhile< TSelf, TSkipPredicate >	skipWhile (TSkipPredicate skipPredicate)
	Creates an iterator that skips the first elements of this iterator, for which the given skipPredicate returns true. More...
constexpr op::TakeN< TSelf >	take (size_t cnt)
	Creates an iterator that yields at most the first cnt elements from this iterator. More...
template<std::invocable< const Item & > TTakePredicate> requires std::is_same_v<std::invoke_result_t<TTakePredicate, const Item&>, bool>
constexpr auto	takeWhile (TTakePredicate takePredicate)
	Creates an iterator that yields the first elements of this iterator, for which the given takePredicate returns true. More...
constexpr auto	stepBy (size_t stepWidth)
	Creates an iterator with the requested stepWidth from this iterator. More...
template<typename TOtherIterator >
constexpr op::Zipper< TSelf, std::pair, TOtherIterator >	zip (TOtherIterator &&otherIterator)
	"Zips up" two CXXIter iterators into a single iterator over pairs from both iterators. More...
template<typename... TOtherIterators> requires (CXXIterIterator<TOtherIterators> && ...) && (!std::disjunction_v< std::is_reference<typename trait::Iterator<TOtherIterators>::Item>... > && !IS_REFERENCE)
constexpr op::Zipper< TSelf, std::tuple, TOtherIterators... >	zipTuple (TOtherIterators &&... otherIterators)
	"Zips up" an arbitrary amount of CXXIter iterators into a single iterator over std::tuple<> from both iterators. More...
template<typename TOtherIterator > requires std::is_same_v<Item, typename TOtherIterator::Item>
constexpr op::Chainer< TSelf, TOtherIterator >	chain (TOtherIterator &&otherIterator)
	Chains this iterator with the given otherIterator, resulting in a new iterator that first yields the elements of this iterator, and then the ones from the otherIterator. More...
template<typename... TOtherIterators> requires (CXXIterIterator<TOtherIterators> && ...) && (util::are_same_v<Item, typename TOtherIterators::Item...>)
constexpr op::Alternater< TSelf, TOtherIterators... >	alternate (TOtherIterators &&... otherIterators)
	Alternating the elements of this iterator with the ones from the other given iterator(s). More...
template<typename TOtherIterator > requires (std::is_same_v<Item, typename TOtherIterator::Item>)
constexpr op::Intersperser< TSelf, TOtherIterator >	intersperse (TOtherIterator &&otherIterator)
	Draw elements from the given otherIterator and use the returned elements as separators between the elements of this iterator. More...
template<std::invocable< const Item & > TGroupIdentifierFn> requires util::is_hashable<std::invoke_result_t<TGroupIdentifierFn, const Item&>>
constexpr auto	groupBy (TGroupIdentifierFn groupIdentFn)
	Groups the elements of this iterator according to the values returned by the given groupidentFn. More...
template<bool STABLE, std::invocable< const ItemOwned &, const ItemOwned & > TCompareFn>
constexpr auto	sort (TCompareFn compareFn)
	Creates a new iterator that takes the items from this iterator, and passes them on sorted, using the supplied compareFn. More...
template<SortOrder ORDER = SortOrder::ASCENDING, bool STABLE = false> requires requires(const ItemOwned& a) { { a < a }; { a > a }; }
constexpr auto	sort ()
	Creates a new iterator that takes the items from this iterator, and passes them on sorted. More...
template<SortOrder ORDER = SortOrder::ASCENDING, bool STABLE = false, std::invocable< const ItemOwned & > TSortValueExtractFn> requires requires(const std::invoke_result_t<TSortValueExtractFn, const ItemOwned&>& a) { { a < a }; { a > a }; }
constexpr auto	sortBy (TSortValueExtractFn sortValueExtractFn)
	Creates a new iterator that takes the items from this iterator, and passes them on sorted. More...

Detailed Description

template<CXXIterIterator TSelf>
class CXXIter::IterApi< TSelf >

Public Iterator API surface.

Definition at line 58 of file CXXIter.h.

Member Typedef Documentation

Item

template<CXXIterIterator TSelf>

using CXXIter::IterApi< TSelf >::Item = typename Iterator::Item

Type of the elements of this iterator. (Can be references)

Definition at line 67 of file CXXIter.h.

ItemOwned

template<CXXIterIterator TSelf>

using CXXIter::IterApi< TSelf >::ItemOwned = std::remove_cvref_t<Item>

Owned Type of the elements of this iterator. (References removed).

Definition at line 71 of file CXXIter.h.

Iterator

template<CXXIterIterator TSelf>

using CXXIter::IterApi< TSelf >::Iterator = trait::Iterator<TSelf>

Type of the trait::Iterator implemenation for this.

Definition at line 63 of file CXXIter.h.

Member Function Documentation

advanceBy()

template<CXXIterIterator TSelf>

constexpr void CXXIter::IterApi< TSelf >::advanceBy ( size_t  n )

inlineconstexpr

Advance the iterator by n elements.

If possible, this is a O(1) operation. Some iterator pipeline elements make that impossible though. In these cases, the implementation falls back to pulling n elements and dropping them.

Parameters

n	The amount of elements to advance the iterator by.

Usage Example:

auto src = CXXIter::range<float>(1.337f, 2.0f, 0.25f, 5.0f, 42.0f);
   std::optional<float> output = src.next().toStdOptional();
// output == Some(1.337f);
src.advanceBy(2);
output = src.next().toStdOptional();
// output == Some(5.0f);

Definition at line 195 of file CXXIter.h.

Here is the call graph for this function:

all() [1/2]

template<CXXIterIterator TSelf>

constexpr bool CXXIter::IterApi< TSelf >::all ( )

inlineconstexpr

Tests if all elements of this iterator yield the value true when casted to bool.

Note

This consumes the iterator.

This is an overload of all(TPredicateFn) for item types that support being casted to bool.

Returns

true when all elements of this iterator yielded the value true when casted to a bool, false otherwise.

Usage Example:

• For cases where not all elements of this iterator evaluate to true when casted to bool.

  std::vector<bool> input = { true, true, true, false };
  bool output = CXXIter::from(input).copied().all();
  // output == false
   
  std::vector<bool> input = { false, true, true, true };
  bool output = CXXIter::from(input).copied().all();
  // output == false
   
  std::vector<bool> input = { true, true, false, true };
  bool output = CXXIter::from(input).copied().all();
  // output == false

• For cases where all elements of this iterator evaluate to true when casted to bool.

  std::vector<bool> input = { true, true, true, true };
  bool output = CXXIter::from(input).copied().all();
  // output == true

Definition at line 431 of file CXXIter.h.

all() [2/2]

template<CXXIterIterator TSelf>

template<std::invocable< const ItemOwned & > TPredicateFn>
requires std::same_as<std::invoke_result_t<TPredicateFn, const ItemOwned&>, bool>

constexpr bool CXXIter::IterApi< TSelf >::all ( TPredicateFn  predicateFn )

inlineconstexpr

Tests if all elements of this iterator match the given predicateFn.

Note

This consumes the iterator.

Parameters

predicateFn

Predicate to test all items of this iterator against.

Returns

true when the given predicateFn returned true for all elements of this iterator, false otherwise.

Usage Example: (Using the following predicate)

auto intAsBoolFn = [](uint32_t item) -> bool { return (item != 0); };

• For cases where the predicate does not return true for all elements:

  std::vector<uint32_t> input = { 1, 1, 1, 0 };
  bool output = CXXIter::from(input).copied().all(intAsBoolFn);
  // output == false
   
  std::vector<uint32_t> input = { 0, 1, 1, 1 };
  bool output = CXXIter::from(input).copied().all(intAsBoolFn);
  // output == false
   
  std::vector<uint32_t> input = { 0, 0, 1, 1 };
  bool output = CXXIter::from(input).copied().all(intAsBoolFn);
  // output == false

• For cases where the predicate does return true for all elements:

  std::vector<uint32_t> input = { 1, 1, 1, 1 };
  bool output = CXXIter::from(input).copied().all(intAsBoolFn);
  // output == true

Definition at line 396 of file CXXIter.h.

Here is the call graph for this function:

alternate()

template<CXXIterIterator TSelf>

template<typename... TOtherIterators>
requires (CXXIterIterator<TOtherIterators> && ...) && (util::are_same_v<Item, typename TOtherIterators::Item...>)

constexpr op::Alternater< TSelf, TOtherIterators... > CXXIter::IterApi< TSelf >::alternate ( TOtherIterators &&...  otherIterators )

inlineconstexpr

Alternating the elements of this iterator with the ones from the other given iterator(s).

Everytime an element is polled from the iterator resulting from this call, an element from the current input iterator is forwarded. Then, the current input iterator is switched to the next input. The resulting iterator ends, when the currently active input has no more elements.

Parameters

otherIterators

An arbitrary amount of iterators to alternate the elements of this iterator with.

Returns

A new iterator that interweaves the elements from this iterator and all the given iterators in order.

Usage Example:

   std::vector<int> input1 = {1, 4, 7};
   std::vector<int> input2 = {2, 5};
   std::vector<int> input3 = {3, 6, 9};
   std::vector<int> output = CXXIter::from(input1)
       .alternate(CXXIter::from(input2), CXXIter::from(input3))
       .collect<std::vector>();
// output == {1, 2, 3, 4, 5, 6, 7}

Definition at line 1974 of file CXXIter.h.

any() [1/2]

template<CXXIterIterator TSelf>

constexpr bool CXXIter::IterApi< TSelf >::any ( )

inlineconstexpr

Tests if any of the elements of this iterator yield the value true when casted to bool.

Note

This consumes the iterator.

This is an overload of any(TPredicateFn) for item types that support being casted to bool.

Returns

true when any of the elements of this iterator yielded the value true when casted to a bool, false otherwise.

Usage Example:

• For cases where none of the elements yields the value true when casted to bool.

  std::vector<bool> input = { false, false, false, false };
  bool output = CXXIter::from(input).copied().any();
  // output == false

• For cases where any of the elements yields the value true when casted to bool.

  std::vector<bool> input = { false, true, true, true };
  bool output = CXXIter::from(input).copied().any();
  // output == true
   
  std::vector<bool> input = { true, false, false, false };
  bool output = CXXIter::from(input).copied().any();
  // output == true
   
  std::vector<bool> input = { true, true, true, true };
  bool output = CXXIter::from(input).copied().any();
  // output == true

Definition at line 507 of file CXXIter.h.

any() [2/2]

template<CXXIterIterator TSelf>

template<std::invocable< const ItemOwned & > TPredicateFn>

constexpr bool CXXIter::IterApi< TSelf >::any ( TPredicateFn  predicateFn )

inlineconstexpr

Tests if any of the elements of this iterator match the given predicateFn.

Note

This consumes the iterator.

Parameters

predicateFn

Predicate to test all items of this iterator against.

Returns

true when the given predicateFn returned true for any of the elements of this iterator, false otherwise.

Usage Example: (Using the following predicate)

auto intAsBoolFn = [](uint32_t item) -> bool { return (item != 0); };

• For the case where the predicateFn returns false for all elements:

  std::vector<uint32_t> input = { 0, 0, 0, 0 };
  bool output = CXXIter::from(input).copied().any(intAsBoolFn);
  // output == false

• For the case where the predicateFn returns true for any of the elements:

  std::vector<uint32_t> input = { 0, 1, 1, 1 };
  bool output = CXXIter::from(input).copied().any(intAsBoolFn);
  // output == true
   
  std::vector<uint32_t> input = { 0, 0, 0, 1 };
  bool output = CXXIter::from(input).copied().any(intAsBoolFn);
  // output == true
   
  std::vector<uint32_t> input = { 1, 1, 1, 1 };
  bool output = CXXIter::from(input).copied().any(intAsBoolFn);
  // output == true

Definition at line 472 of file CXXIter.h.

Here is the call graph for this function:

begin()

template<CXXIterIterator TSelf>

iterator CXXIter::IterApi< TSelf >::begin ( )

inline

begin() method, part of C++'s iterator interface

Returns

C++ interface on top of this iterator pipeline.

Definition at line 113 of file CXXIter.h.

Here is the call graph for this function:

cast()

template<CXXIterIterator TSelf>

template<typename TItemOutput >

constexpr op::Caster< TSelf, TItemOutput > CXXIter::IterApi< TSelf >::cast ( )

inlineconstexpr

Constructs a new iterator that casts the elements of this iterator to the type requested by TItemOutput.

This iterator applies the requested type cast to TItemOutput using static_cast<>.

Template Parameters

TItemOutput

Type to cast the elements of this iterator to.

Returns

A new iterator that casts all elements from this iterator to the requested type TItemOutput.

Usage Example:

std::vector<float> input = {1.35, 56.123};
std::vector<double> output = CXXIter::from(input)
        .cast<double>()
        .collect<std::vector>();

Definition at line 1258 of file CXXIter.h.

chain()

template<CXXIterIterator TSelf>

template<typename TOtherIterator >
requires std::is_same_v<Item, typename TOtherIterator::Item>

constexpr op::Chainer< TSelf, TOtherIterator > CXXIter::IterApi< TSelf >::chain ( TOtherIterator &&  otherIterator )

inlineconstexpr

Chains this iterator with the given otherIterator, resulting in a new iterator that first yields the elements of this iterator, and then the ones from the otherIterator.

Parameters

otherIterator

Other iterator whose elements should be "appended" to the elements of this iterator.

Returns

New iterator that consists of a chain of this iterator with the given otherIterator.

Note

For this to work, the elements' types of this iterator and the given otherIterator have to be identical.

Usage Example:

   std::vector<std::string> input1 = {"1337", "42"};
   std::vector<std::string> input2 = {"31337", "64"};
   std::vector<std::string> output = CXXIter::from(input1).copied()
           .chain(CXXIter::from(input2).copied())
           .collect<std::vector>();
// output == {"1337", "42", "31337", "64"}

Definition at line 1948 of file CXXIter.h.

chunked()

template<CXXIterIterator TSelf>

template<const size_t CHUNK_SIZE>

constexpr op::Chunked< TSelf, CHUNK_SIZE > CXXIter::IterApi< TSelf >::chunked ( )

inlineconstexpr

Create new iterator that collects elements from this iterator in chunks of size up to CHUNK_SIZE, which then constitue the elements of the new iterator.

Chunks are of up to CHUNK_SIZE elements in size. If the amount of items in the iterator are not dividable by the requested CHUNK_SIZE the last chunk will be smaller.

Template Parameters

CHUNK_SIZE

Amount of elements from this iterator, that get collected to one chunk.

Returns

New iterator that contains chunks of up to the requested size, containing elements from this iterator as elements.

Usage Example:

• If the amount of elements of the input can be evenly divided up into the requested CHUNK_SIZE :

  std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5, 1, 2, 3};
  auto output = CXXIter::from(input)
          .copied()
          .chunked<3>()
          .collect<std::vector>();
  // output == { {1337, 42, 512}, {31337, 69, 5}, {1, 2, 3} }

• If the amount of elements of the input can not be evenly divided up into the requested CHUNK_SIZE :

  std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5, 1, 2};
  auto output = CXXIter::from(input)
          .copied()
          .chunked<3>()
          .collect<std::vector>();
  // output == { {1337, 42, 512}, {31337, 69, 5}, {1, 2} }

Definition at line 1454 of file CXXIter.h.

chunkedExact()

template<CXXIterIterator TSelf>

template<const size_t CHUNK_SIZE, const size_t STEP_SIZE = CHUNK_SIZE>

constexpr op::ChunkedExact< TSelf, CHUNK_SIZE, STEP_SIZE > CXXIter::IterApi< TSelf >::chunkedExact ( )

inlineconstexpr

Create new iterator that collects elements from this iterator in exact-sized chunks of CHUNK_SIZE, which then constitue the elements of the new iterator.

A chunk is only committed in the new iterator, after it was filled completely. That means, that if the amount of elements in this iterator do not evenly divide up to CHUNK_SIZE sized chunks, the last couple of elements that fail to fill a complete chunk will be dropped.

Where possible (for contiguous memory sources, such as std::vector<> or std::array<>), this method avoids creating copies of the elements, and instead forwards an std::array<>& pointing at the memory position of the current chunk's start. This essentially allows working directly on the source's memory region. If this isn't possible because the source or any previous chainer method calls make direct source memory inaccessible, this will fallback to using a temporary buffer, able to hold an entire chunk, that is filled by pulling elements from this iterator into the buffer, before a const reference to the buffer is passed onwards.

Template Parameters

CHUNK_SIZE	Amount of elements from this iterator, that get collected to one chunk.
STEP_SIZE	Controls the step-size between chunks. Per default, this is set to the same as CHUNK_SIZE, so the produced chunks are directly adjacent. If this is set to a value smaler than CHUNK_SIZE, the generated chunks will overlap. If this is set to a value higher than CHUNK_SIZE, the generated chunks will have gaps in between (those items are dropped).

Returns

New iterator that contains exact-sized (CHUNK_SIZE) chunks of elements from this iterator as elements.

• If this iterator supports contiguous memory access:
  • the resulting iterator's elements will be of type std::array<...>& where the reference points directly to the contiguous memory source's memory region - irrespecting of whether this iterator's elements are referenced or owned/copied. Changing the elements in these chunk references will thus directly change the elements in the source.
• If this iterator doesn't support contiguous memory access (e.g. because of another chainer method between source and chunkedExact())
  • ... and this iterator's elements are references, the resulting iterator's elements will be of type std::array<std::reference_wrapper<...>>& , in order to preserve the ability to modify the elements in-place. In case this is unwanted, prepend the call to chunkedExact() with a call to the copied() chainer method.
  • ... and this iterator's elements are not references, the resulting iterator's elements will be of type const std::array<...>&

Attention

ChunkedExact tries to avoid making unnecessary copies, but that only works if this iterator is sourced by a contiguous source of memory, without any obstructing chainer methods before the call to chunkedExact(). If this isn't possible, the internal chunk buffer and the copies from this iterator into the buffer, can cause an additional strain on memory.

Usage Examples:

Contiguous Memory

---

• If the amount of elements of the input can be evenly divided up into the requested CHUNK_SIZE :

  std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5, 1, 2, 3};
  std::vector<CXXIter::ExactChunk<size_t, 3>> output = CXXIter::from(input)
      .chunkedExact<3>()
      .collect<std::vector>();
  // output == { {1337, 42, 512}, {31337, 69, 5}, {1, 2, 3} }

• If the amount of elements of the input can not be evenly divided up into the requested CHUNK_SIZE :

  std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5, 1, 2};
  std::vector<CXXIter::ExactChunk<size_t, 3>> output = CXXIter::from(input)
      .chunkedExact<3>()
      .collect<std::vector>();
  // output == { {1337, 42, 512}, {31337, 69, 5} }

• Overlapping chunks (STEP_SIZE < CHUNK_SIZE):

  std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5};
  std::vector<CXXIter::ExactChunk<size_t, 3>> output = CXXIter::from(input)
      .chunkedExact<3, 1>()
      .collect<std::vector>();
  // output == { {1337, 42, 512}, {42, 512, 31337}, {512, 31337, 69}, {31337, 69, 5} }

• Gapped Chunks (STEP_SIZE > CHUNK_SIZE):

  std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5, 1};
  std::vector<CXXIter::ExactChunk<size_t, 3>> output = CXXIter::from(input)
      .chunkedExact<3, 4>()
      .collect<std::vector>();
  // output == { {1337, 42, 512}, {69, 5, 1} }

• In-Place source editing

  std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5, 1};
  CXXIter::from(input)
      .chunkedExact<3, 4>()
      .forEach([](std::array<size_t, 3>& chunkRef) {
          chunkRef[0] += 1; chunkRef[1] += 2; chunkRef[2] += 3;
      });
  // input == { 1337+1, 42+2, 512+3, 31337, 69+1, 5+2, 1+3 }

Non-Contiguous Memory

---

• Container that doesn't store its elements in a contiguous region in memory:

  std::deque<size_t> input = {1337, 42, 512, 31337, 69, 5, 1};
  std::vector<CXXIter::ExactChunk<size_t, 3>> output = CXXIter::from(input)
      .copied() // required to avoid std::reference_wrapper<...> in elements produced by chunkedExact()
      .chunkedExact<3, 4>()
      .collect<std::vector>();
  // output == { {1337, 42, 512}, {69, 5, 1} }

• Using chunkedExact() with preceding chainers that prevent contiguous memory access:

  // container would normally support contiguous memory access
     std::vector<size_t> input = {1337, 42, 512, 31337, 69, 5, 1};
  // CXXIter::ExactChunk<size_t&, 3> resolves to std::array<std::reference_wrapper<size_t>, 3>
     std::vector<CXXIter::ExactChunk<size_t&, 3>> output = CXXIter::from(input)
         .filter([](const auto&) { return true; })
         .chunkedExact<3, 4>()
         .collect<std::vector>();
     // output == { {1337, 42, 512}, {69, 5, 1} }

Definition at line 1562 of file CXXIter.h.

collect() [1/2]

template<CXXIterIterator TSelf>

template<template< typename... > typename TTargetContainer, typename... TTargetContainerArgs>

constexpr auto CXXIter::IterApi< TSelf >::collect ( )

inlineconstexpr

Consumer that collects all elements from this iterator in a new container of type TTargetContainer.

Note

This consumes the iterator.

Template Parameters

TTargetContainer	Type-Template for the target container that the elements from this iterator should be collected into. The first template parameter of this Type-Template has to take the type of the elements.
TTargetContainerArgs...	Optional additional type attributes to pass on to the target container. These are appended to the item value type, which is automatically supplied.

Returns

An instance of TTargetContainer with all the elements of this iterator collected into.

Usage Example:

std::vector<std::string> input = {"1337", "42", "64"};
std::vector<std::string> output = CXXIter::from(input)
    .collect<std::vector>();

With Additional container type parameters:

std::vector<std::string> input = {"1337", "42", "64"};
std::vector<std::string, std::allocator<std::string>> output = CXXIter::from(input)
    .collect<std::vector, std::allocator<std::string>>();

Definition at line 273 of file CXXIter.h.

collect() [2/2]

template<CXXIterIterator TSelf>

template<typename TTargetContainer >

constexpr TTargetContainer CXXIter::IterApi< TSelf >::collect ( )

inlineconstexpr

Consumer that collects all elements from this iterator in a new container of type TTargetContainer.

Note

This consumes the iterator.

Template Parameters

TTargetContainer

Fully qualified type of the target container to collect the items of this iterator into.

Returns

An instance of TTargetContainer with all the elements of this iterator collected into.

Usage Example:

• std::vector<std::string>

  std::vector<std::string> input = {"1337", "42", "64"};
  std::vector<std::string> output = CXXIter::from(input)
      .collect<std::vector<std::string>>();

• std::vector<std::string> with explicitly defined allocator

  std::vector<std::string> input = {"1337", "42", "64"};
  std::vector<std::string, std::allocator<std::string>> output = CXXIter::from(input)
      .collect<std::vector<std::string, std::allocator<std::string>>>();

• std::array<std::string, 3>

  std::vector<std::string> input = {"1337", "42", "64"};
  std::array<std::string, 3> output = CXXIter::from(input)
      .collect<std::array<std::string, 3>>();

Definition at line 306 of file CXXIter.h.

Here is the call graph for this function:

collectInto()

template<CXXIterIterator TSelf>

template<typename TTargetContainer >

constexpr void CXXIter::IterApi< TSelf >::collectInto ( TTargetContainer &  container )

inlineconstexpr

Consumer that collects all elements from this iterator into the given container.

Note

This consumes the iterator.

Parameters

container

to collect this iterator's elements into.

Before appending this iterator's elements to the elements already present in the given container, the collector tries to resize the container to its current size + this iterator's expected amount of items.

Usage Example:

   std::vector<std::string> input = {"1337", "42", "64"};
   std::vector<std::string> output = {"prevElement"};
CXXIter::from(input).collectInto(output);
// output == {"prevElement", "1337", "42", "64"}

Definition at line 329 of file CXXIter.h.

copied()

template<CXXIterIterator TSelf>

constexpr auto CXXIter::IterApi< TSelf >::copied ( )

inlineconstexpr

Constructs a new iterator that copies the elements of this iterator.

This function essentially converts an iterator that is passing elements by reference, to an iterator that is passing elements by value midway.

Returns

A new iterator that is passing copies of the original input elements by value.

Usage Example:

std::vector<std::string> input = {"inputString1", "inputString2"};
std::vector<std::string> output = CXXIter::from(input)
    .copied() // clone values, now working with owned copies instead of references to input
    .modify([](std::string& item) { item[item.size() - 1] += 1; }) // modify copies, input untouched
    .collect<std::vector>();

Definition at line 1277 of file CXXIter.h.

Here is the call graph for this function:

count() [1/3]

template<CXXIterIterator TSelf>

constexpr size_t CXXIter::IterApi< TSelf >::count ( )

inlineconstexpr

Consumer that counts the elements in this iterator.

Note

This consumes the iterator.

Returns

The amount of elements in this iterator

Usage Example:

std::vector<int> input = {42, 1337, 52};
size_t output = CXXIter::from(input).count();
// output == 3
std::vector<int> input2 = {};
size_t output2 = CXXIter::from(input2).count();
// output == 0

Definition at line 621 of file CXXIter.h.

Here is the call graph for this function:

count() [2/3]

template<CXXIterIterator TSelf>

constexpr size_t CXXIter::IterApi< TSelf >::count ( const ItemOwned &  countItem )

inlineconstexpr

Consumer that counts the occurences of countItem within this iterator.

Note

This consumes the iterator.

Parameters

countItem

Item for which to count the amount of occurences within this iterator.

Returns

The number of occurences of countItem within this iterator.

Usage Example:

std::vector<int> input = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
size_t output = CXXIter::from(input)
        .map([](int item) { return (item % 2 == 0); })
        .count(true);
// output == 5

Definition at line 663 of file CXXIter.h.

count() [3/3]

template<CXXIterIterator TSelf>

template<std::invocable< const ItemOwned & > TPredicateFn>

constexpr size_t CXXIter::IterApi< TSelf >::count ( TPredicateFn  predicateFn )

inlineconstexpr

Consumer that counts the elements in this iterator, for which the given predicateFn returns true.

Note

This consumes the iterator.

Parameters

predicateFn

Predicate that is run for each element of this iterator, to determine whether it should contribute to the resulting count.

Returns

The amount of elements in this iterator for which the given predicateFn returned true.

Usage Example:

    std::vector<int> input = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
    size_t output = CXXIter::from(input)
            .count([](int item){ return (item % 2 == 0); });
// output == 5

Definition at line 642 of file CXXIter.h.

Here is the call graph for this function:

end()

template<CXXIterIterator TSelf>

iterator CXXIter::IterApi< TSelf >::end ( )

inline

end() method, part of C++'s iterator interface

Returns

C++ interface on top of this iterator pipeline.

Definition at line 119 of file CXXIter.h.

filter()

template<CXXIterIterator TSelf>

template<std::invocable< const ItemOwned & > TFilterFn>

constexpr op::Filter< TSelf, TFilterFn > CXXIter::IterApi< TSelf >::filter ( TFilterFn  filterFn )

inlineconstexpr

Constructs a new iterator that only contains the elements from this iterator, for which the given filterFn returned true.

Parameters

filterFn

Function that decides which element of this iterator to yield in the newly created iterator.

Returns

Iterator that only returns the elements for which the filterFn returns true.

Usage Example:

std::vector<int> input = {1, 2, 3, 4, 5, 6, 7, 8};
std::vector<int> output = CXXIter::from(input)
    .filter([](int item) { return (item % 2) == 0; })
    .collect<std::vector>();

Definition at line 1353 of file CXXIter.h.

filterMap()

template<CXXIterIterator TSelf>

template<std::invocable< ItemOwned && > TFilterMapFn>
requires util::is_optional<std::invoke_result_t<TFilterMapFn, ItemOwned&&>>

constexpr auto CXXIter::IterApi< TSelf >::filterMap ( TFilterMapFn  filterMapFn )

inlineconstexpr

Creates a new iterator that filters and maps items from this iterator.

Parameters

filterMapFn

Function that maps the incomming items to an optional mapped value. If it returns an empty std::optional<> the element is filtered. If it returns an std::optional<> with a value, that item is yielded from the resulting iterator.

Returns

Iterator that yields only the items for which the given filterMapFn returned a mapped value.

Usage Example:

std::vector<int> input = {1, 2, 3, 4, 5, 6, 7, 8};
std::vector<int> output = CXXIter::from(input)
    .filterMap([](int item) -> std::optional<int> {
        if(item % 2 == 0) { return (item + 3); }
        return {};
    })
    .collect<std::vector>();

Definition at line 1757 of file CXXIter.h.

find()

template<CXXIterIterator TSelf>

template<std::invocable< const ItemOwned & > TFindFn>

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::find ( TFindFn  findFn )

inlineconstexpr

Searches for an element of this iterator, that satisfies the given findFn predicate.

Parameters

findFn

Predicate used to search for an element in this iterator.

Returns

An CXXIter::IterValue containing the first element, for which the findFn predicate returned true (if any), otherwise empty.

Usage Example:

• When item is found in the iterator:

  std::vector<std::string> input = {"42", "1337", "52"};
  CXXIter::IterValue<std::string&> output = CXXIter::from(input)
          .find([](const std::string& item) {
              return item.size() == 4;
          });
  // output == Some("1337"&)

• When item is not found in the iterator:

  std::vector<std::string> input = {"42", "1337", "52"};
  CXXIter::IterValue<std::string&> output = CXXIter::from(input)
          .find([](const std::string& item) {
              return item.size() == 3;
          });
  // output == None

Definition at line 602 of file CXXIter.h.

Here is the call graph for this function:

findIdx() [1/2]

template<CXXIterIterator TSelf>

constexpr std::optional< size_t > CXXIter::IterApi< TSelf >::findIdx ( const ItemOwned &  searchItem )

inlineconstexpr

Search for the given searchItem within the items of this iterator, and return the index of the first item from the iterator that is equal to the given searchItem.

Parameters

searchItem

Item to search for in the iterator.

Returns

Index of the given searchItem in the iterator, if found.

Usage Example:

• When item is found in the iterator:

  std::vector<int> input = {42, 1337, 52};
  std::optional<size_t> output = CXXIter::from(input).findIdx(1337);
  // output == Some(1)

• When item is not found in the iterator:

  std::vector<int> input = {"42", "1337", "52"};
  std::optional<size_t> output = CXXIter::from(input).findIdx("not found");
  // output == None

Definition at line 533 of file CXXIter.h.

findIdx() [2/2]

template<CXXIterIterator TSelf>

template<std::invocable< const ItemOwned & > TFindFn>

constexpr std::optional< size_t > CXXIter::IterApi< TSelf >::findIdx ( TFindFn  findFn )

inlineconstexpr

Search for the iterator with the given findFn, and return the index of the element from this iterator, for which the findFn returned true the first time.

Parameters

findFn

Lambda invoked for each element of this stream, to determined whether it is the item that is searched for.

Returns

Index of the first element from this stream, for which the invocation to the given findFn returned true.

Usage Example:

• When item is found in the iterator:

  std::vector<int> input = {1337, 31337, 41, 43, 42, 64};
  std::optional<size_t> output = CXXIter::from(input)
      .findIdx([](int item) { return (item % 2 == 0); });
  // output == Some(4)

• When item is not found in the iterator:

  std::vector<int> input = {1337, 31337, 41, 43};
  std::optional<size_t> output = CXXIter::from(input)
      .findIdx([](int item) { return (item % 2 == 0); });
  // output == None

Definition at line 565 of file CXXIter.h.

Here is the call graph for this function:

flagLast()

template<CXXIterIterator TSelf>

constexpr op::FlagLast< TSelf > CXXIter::IterApi< TSelf >::flagLast ( )

inlineconstexpr

Constructs a new iterator that tags each element with a boolean value specifying whether the element is the last one in the iterator. Boolean and actual iterator element are stored in a std::pair.

Returns

A new iterator whose elements are std::pair with the iterator element in the first, and a boolean flag specifying whether the element will be the last one in the second slot.

Usage Example:

• Flag last element in filtered iterator

     std::vector<std::string> input = {"1337", "42", "420", "64"};
     std::vector<std::pair<std::string&, bool>> output = CXXIter::from(input)
         .filter([](const std::string& el) { return el.size() >= 3; })
         .flagLast()
         .collect<std::vector>();
  // output == {{"1337", false}, {"420", true}}

• Use last flag to filter (remove last element from iterator)

     std::vector<std::string> input = {"1337", "42", "64"};
     std::vector<std::pair<std::string&, bool>> output = CXXIter::from(input)
             .flagLast()
             .filter([](const std::pair<std::string&, bool>& el) { return !el.second; })
             .collect<std::vector>();
  // output == {{"1337", false}, {"42", false}}

Definition at line 1333 of file CXXIter.h.

flatMap() [1/2]

template<CXXIterIterator TSelf>

constexpr auto CXXIter::IterApi< TSelf >::flatMap ( )

inlineconstexpr

Creates an iterator that flattens the iterable elements of this iterator.

This works by pulling elements from this iterator, turning them into iterators themselves, and merging them into the stream of the resulting iterator. This only resolves one layer of nesting, and the elements of this iterator have to be supported by CXXIter (by a fitting SourceTrait implementation).

Returns

New iterator that pulls values from this iterator, and flattens the contained iterable into the new iterator's stream.

Usage Example:

std::vector<std::vector<int>> input = {{1337, 42}, {6, 123, 7888}};
std::vector<int> output = CXXIter::from(std::move(input))
    .flatMap()
    .collect<std::vector>(); // collect into vector containing {1337, 42, 6, 123, 7888}

Definition at line 1712 of file CXXIter.h.

Here is the call graph for this function:

flatMap() [2/2]

template<CXXIterIterator TSelf>

template<std::invocable< Item && > TFlatMapFn>

constexpr auto CXXIter::IterApi< TSelf >::flatMap ( TFlatMapFn  mapFn )

inlineconstexpr

Creates an iterator that works like map(), but flattens nested containers.

This works by pulling elements from this iterator, passing them to the given mapFn, and then taking the returned values to turn them into iterators themselves, to merge them into the stream of the resulting iterator. This only resolves one layer of nesting, and values returned by mapFn have to be supported by CXXIter (by a fitting SourceTrait implementation).

Parameters

mapFn

Function that returns a nesting container, that should be merged into the returned iterator's stream.

Returns

New iterator that pulls values from this iterator, maps them to a nested container, which is then flattened into the new iterator's stream of elements.

Usage Example:

std::vector<std::pair<std::string, std::vector<int>>> input = {{"first pair", {1337, 42}}, {"second pair", {6, 123, 7888}}};
std::vector<int> output = CXXIter::from(std::move(input))
    .flatMap([](auto&& item) { return std::get<1>(item); }) // flatten the std::vector<int> from the pair
    .collect<std::vector>(); // collect into vector containing {1337, 42, 6, 123, 7888}

Definition at line 1611 of file CXXIter.h.

fold()

template<CXXIterIterator TSelf>

template<typename TResult , std::invocable< TResult &, Item && > FoldFn>

constexpr TResult CXXIter::IterApi< TSelf >::fold ( TResult  startValue, FoldFn  foldFn  )

inlineconstexpr

Consumer that executes the given foldFn for each item in this iterator, to apply to a working value, which is passed on and passed as second argument to the next call to foldFn.

Note

This consumes the iterator.

Parameters

startValue	The initial value of the working value passed to foldFn.
foldFn	Function called for each element in this iterator, passed the current workingValue and an element from this iterator.

Returns

The workingValue from the last call to foldFn for the last element from this iterator.

Usage Example:

   std::vector<double> input = {1.331335363800390, 1.331335363800390, 1.331335363800390, 1.331335363800390};
   double output = CXXIter::from(input)
       .fold(1.0, [](double& workingValue, double item) {
           workingValue *= item;
       });
// output ~ 3.141592653589793

Definition at line 353 of file CXXIter.h.

Here is the call graph for this function:

forEach()

template<CXXIterIterator TSelf>

template<typename TUseFn >

constexpr void CXXIter::IterApi< TSelf >::forEach ( TUseFn  useFn )

inlineconstexpr

Consumer that calls the given function useFn for each of the elements in this iterator.

Note

This consumes the iterator.

Parameters

useFn

Function called for each of the elements in this iterator.

Usage Example:

std::vector<std::string> input = {"1337", "42", "64"};
std::vector<std::string> output;
CXXIter::from(input)
        .forEach([&output](std::string& item) {
            output.push_back(std::forward<std::string>(item));
        });

Definition at line 241 of file CXXIter.h.

Here is the call graph for this function:

generateFrom()

template<CXXIterIterator TSelf>

template<GeneratorFromFunction< Item > TGeneratorFn>

constexpr auto CXXIter::IterApi< TSelf >::generateFrom ( TGeneratorFn  generatorFn )

inlineconstexpr

Creates a new iterator containing the items that the given generator produces for each element in this iterator.

Conceptually, this method is very similar to flatMap() since it allows to take one element from this iterator, and returning an arbitrary amount of new elements into the resulting iterator. A big difference is, that with generateFrom(), elements can be produced on the fly using c++20 coroutines, while with flatMap() they need to be present in a supported container at once - taking up memory. The given generatorFn is run for each element in this iterator, producing a generator. This generator is then driven to completion, piping every element it produced into the resulting iterator.

Parameters

generatorFn

Generator function that is executed for each element of this iterator. This function can use co_yield to produce as many elements as it wants. Its return value has to be explicitly specified as CXXIter::Generator with the generated type as template parameter.

Note

Returning references from the generator is supported. Make sure your references stay valid until they are read, though.

Attention

Special care has to be taken with respect to the argument types of the given generatorFn. The generator must take the elements of the stream by-value (copied). If the elements in the stream are moved through the stream, the generatorFn must take them as their owned type. If the elements are passed as references through the stream, the generatorFn can take them as references. If you are getting spurious SEGFAULTs - check your parameter types!

Usage Example:

The example shows a generator that repeats the strings from the source, depending on the string's lengths. Special attention in these examples should be mainly on the parameter types, as well as the explicitly specified return values of the given generator functions.

• Using generateFrom() with a move source, that passes elements by move (generator clones elements and passes them on as owned clones)
  Here, the type of the elements passed through the iterator are owned std::string by move. So the type the generator has to take as parameter is an owned std::string.

  std::vector<std::string> input = {"1337", "42"};
  std::vector<std::string> output = CXXIter::from(std::move(input))
          .generateFrom([](std::string item) -> CXXIter::Generator<std::string> {
              for(size_t i = 0; i < item.size(); ++i) {
                  co_yield item;
              }
          })
          .collect<std::vector>();
  // output == { "1337", "1337", "1337", "1337", "42", "42" }

• Using generateFrom() with a reference source, that passes elements as references (generator clones elements and passes them on as owned clones)
  Here, the type of the elements passed through the iterator are const std::string references. So the type the generator takes can either be a const std::string reference (because they don't reference something temporary, but are references from the permanent source) - or as an owned std::string.

  std::vector<std::string> input = {"1337", "42"};
  std::vector<std::string> output = CXXIter::from(input)
          .generateFrom([](const std::string& item) -> CXXIter::Generator<std::string> {
              for(size_t i = 0; i < item.size(); ++i) {
                  co_yield item;
              }
          })
          .collect<std::vector>();
  // output == { "1337", "1337", "1337", "1337", "42", "42" }

• Using generateFrom() with a reference source, that passes elements as references (generator clones references to elements - and passes on the copied references)
  

  std::vector<std::string> input = {"1337", "42"};
  std::vector<std::string> output = CXXIter::from(input)
          .generateFrom([](const std::string& item) -> CXXIter::Generator<const std::string&> {
              for(size_t i = 0; i < item.size(); ++i) {
                  co_yield item;
              }
          })
          .collect<std::vector>();
  // output == { "1337", "1337", "1337", "1337", "42", "42" }

Definition at line 1689 of file CXXIter.h.

groupBy()

template<CXXIterIterator TSelf>

template<std::invocable< const Item & > TGroupIdentifierFn>
requires util::is_hashable<std::invoke_result_t<TGroupIdentifierFn, const Item&>>

constexpr auto CXXIter::IterApi< TSelf >::groupBy ( TGroupIdentifierFn  groupIdentFn )

inlineconstexpr

Groups the elements of this iterator according to the values returned by the given groupidentFn.

Parameters

groupIdentFn

Function called for each element from this iterator, to determine the grouping value, that is then used to identify the group an item belongs to. The type returned by this function has to implement std::hash<>.

Returns

New iterator whose elements are the calculated groups from the values of this iterator, in the form of a std::pair<> with the group identifier as first value, and a std::vector of all values in the group as second value.

Attention

GroupBy requires to first drain the input iterator, before being able to supply a single element. This leads to additional memory usage.

Usage Example:

struct CakeMeasurement {
   std::string cakeType;
   float cakeWeight;
   bool operator==(const CakeMeasurement& o) const {
       return cakeType == o.cakeType && cakeWeight == o.cakeWeight;
   }
};
std::vector<CakeMeasurement> input = { {"ApplePie", 1.3f}, {"Sacher", 0.5f}, {"ApplePie", 1.8f} };
std::unordered_map<std::string, std::vector<CakeMeasurement>>  output = CXXIter::from(input)
   .groupBy([](const CakeMeasurement& item) { return item.cakeType; })
   .collect<std::unordered_map>();

Definition at line 2050 of file CXXIter.h.

indexed()

template<CXXIterIterator TSelf>

constexpr auto CXXIter::IterApi< TSelf >::indexed ( )

inlineconstexpr

Constructs a new iterator that tags each element of this iterator with the corresponding index, stored in a std::pair.

Returns

A new iterator whose elements are std::pair with an element index in the first, and the original iterator's corresponding element in the second slot.

Usage Example:

   std::vector<std::string> input = {"1337", "42", "64"};
   std::vector<std::pair<size_t, std::string&>> output = CXXIter::from(input)
       .indexed()
       .collect<std::vector>();
// output == {{0, "1337"}, {1, "42"}, {2, "64"}}

Definition at line 1300 of file CXXIter.h.

Here is the call graph for this function:

intersperse()

template<CXXIterIterator TSelf>

template<typename TOtherIterator >
requires (std::is_same_v<Item, typename TOtherIterator::Item>)

constexpr op::Intersperser< TSelf, TOtherIterator > CXXIter::IterApi< TSelf >::intersperse ( TOtherIterator &&  otherIterator )

inlineconstexpr

Draw elements from the given otherIterator and use the returned elements as separators between the elements of this iterator.

This draws one element "into the future" of this iterator, in order to determine if another separator element from the given otherIterator is required. The resulting iterator ends if either this iterator or the otherIterator has no more elements to pull. The resulting iterator will always start and end on an element from this iterator.

Parameters

otherIterator

Iterator whose elements will be inserted as separator elements between the elements of this iterator.

Returns

New iterator that uses the given otherIterator's elements as separators between this iterator's elements.

Usage Example:

• Using infinite separator iterator (int)

  std::vector<int> input = { 1, 2, 3, 4, 5, 6 };
  std::vector<int> output = CXXIter::from(input).copied()
      .intersperse(CXXIter::repeat(0))
      .collect<std::vector>();
  // output == {1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6}

• Using infinite separator iterator (string)

  std::vector<std::string> input = { "Apple", "Orange", "Cake" };
  std::vector<std::string> output = CXXIter::from(input).copied()
      .intersperse(CXXIter::repeat<std::string>(", "))
      .collect<std::vector>();
  // output == {"Apple", ", ", "Orange", ", ", "Cake"}

• Using finite separator iterator that ends earlier than source iterator

  std::vector<int> input = { 1, 2, 3, 4, 5, 6 };
  std::vector<int> output = CXXIter::from(input).copied()
      .intersperse(CXXIter::range(100, 102, 1))
      .collect<std::vector>();
  // output == {1, 100, 2, 101, 3, 102, 4}

Definition at line 2018 of file CXXIter.h.

last()

template<CXXIterIterator TSelf>

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::last ( )

inlineconstexpr

Consumer that yields the last element of this iterator.

Note

This consumes the iterator.

Returns

The last element of this iterator (if any).

Usage Example:

• For a non-empty iterator

  std::vector<int> input = {42, 1337, 52};
  std::optional<int> output = CXXIter::from(input)
     .last()
     .toStdOptional();
  // output == Some(52)

• For an empty iterator:

  std::vector<int> input = {};
  std::optional<int> output = CXXIter::from(input)
     .last()
     .toStdOptional();
  // output == None

Definition at line 1204 of file CXXIter.h.

Here is the call graph for this function:

map()

template<CXXIterIterator TSelf>

template<std::invocable< Item && > TMapFn>

constexpr auto CXXIter::IterApi< TSelf >::map ( TMapFn  mapFn )

inlineconstexpr

Creates an iterator that uses the given mapFn to map each element from this iterator to elements of the new iterator.

This pulls a new value from this iterator, maps it to a new value (can have a completely new type) using the given mapFn and then yields that as new item for thew newly created iterator.

Parameters

mapFn

Function that maps items from this iterator to a new value.

Returns

New iterator that maps the values from this iterator to new values, using the given mapFn.

Usage Example:

std::vector<int> input = {1337, 42};
std::unordered_map<int, std::string> output = CXXIter::from(input)
    .map([](int i) { return std::make_pair(i, std::to_string(i)); }) // construct pair
    .collect<std::unordered_map>(); // collect into map

Definition at line 1585 of file CXXIter.h.

max()

template<CXXIterIterator TSelf>

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::max ( )

inlineconstexpr

Consumer that yields the largest element from this iterator.

Note

This consumes the iterator.

Returns

A CXXIter::IterValue optional either containing the largest element of this iterator (if any), or empty otherwise.

Usage Example:

• For a non-empty iterator

  std::vector<int> input = {42, 1337, 52};
  std::optional<int> output = CXXIter::from(input)
     .max().toStdOptional();
  // output == Some(1337)

• For an empty iterator:

  std::vector<int> input = {};
  std::optional<int> output = CXXIter::from(input)
     .max().toStdOptional();
  // output == None

Definition at line 973 of file CXXIter.h.

Here is the call graph for this function:

maxBy()

template<CXXIterIterator TSelf>

template<typename TMaxValueExtractFn >
requires requires(const std::invoke_result_t<TMaxValueExtractFn, Item&&>& a, std::remove_cvref_t<decltype(a)> ownedA) { { a > a }; { ownedA = ownedA }; }

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::maxBy ( TMaxValueExtractFn  compValueExtractFn )

inlineconstexpr

Consumer that yields the largest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given compValueExtractFn on each element.

Note

This consumes the iterator.

Parameters

compValueExtractFn

Function that, given an element from the input iterator as parameter returns the value by which the item should be compared to others.

Returns

A CXXIter::IterValue optional either containing the largest element of this iterator (if any), or empty otherwise.

Usage Example:

• For a non-empty iterator

     std::vector<std::string> input = {"smol", "middle", "largeString"};
     std::optional<std::string> output = CXXIter::from(input)
         .maxBy([](const std::string& str) { return str.size(); })
     .toStdOptional();
  // output == Some("largeString")

• For an empty iterator:

     std::vector<std::string> input = {};
     std::optional<std::string> output = CXXIter::from(input)
         .maxBy([](const std::string& str) { return str.size(); })
     .toStdOptional();
  // output == None

Definition at line 1122 of file CXXIter.h.

Here is the call graph for this function:

maxIdx()

template<CXXIterIterator TSelf>

constexpr std::optional< size_t > CXXIter::IterApi< TSelf >::maxIdx ( )

inlineconstexpr

Consumer that yields the index of the largest element within this iterator.

Note

This consumes the iterator.

Returns

Index of the largest element within the input iterator (if any).

Usage Example:

• For a non-empty iterator

  std::vector<int> input = {42, 1337, 52};
  std::optional<size_t> output = CXXIter::from(input).maxIdx();
  // output == Some(1)

• For an empty iterator:

  std::vector<int> input = {};
  std::optional<size_t> output = CXXIter::from(input).maxIdx();
  // output == None

Definition at line 996 of file CXXIter.h.

Here is the call graph for this function:

maxIdxBy()

template<CXXIterIterator TSelf>

template<typename TMaxValueExtractFn >
requires requires(const std::invoke_result_t<TMaxValueExtractFn, Item&&>& a, std::remove_cvref_t<decltype(a)> ownedA) { { a > a }; { ownedA = ownedA }; }

constexpr std::optional< size_t > CXXIter::IterApi< TSelf >::maxIdxBy ( TMaxValueExtractFn  compValueExtractFn )

inlineconstexpr

Consumer that yields the index of the largest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given TCompValueExtractFn on each element.

Note

This consumes the iterator.

Parameters

compValueExtractFn

Function that, given an element from the input iterator as parameter, returns the value by which the item should be compared to others.

Returns

Index of the largest element within the input iterator (if any).

Usage Example:

• For a non-empty iterator

  const std::vector<std::string> input = {"middle", "largeString", "smol"};
  std::optional<size_t> output = CXXIter::SrcCRef(input)
     .maxIdxBy([](const std::string& str) { return str.size(); });
  // output = Some(1)

• For an empty iterator:

  const std::vector<std::string> input = {};
  std::optional<size_t> output = CXXIter::SrcCRef(input)
     .maxIdxBy([](const std::string& str) { return str.size(); });
  // output = None

Definition at line 1165 of file CXXIter.h.

Here is the call graph for this function:

mean()

template<CXXIterIterator TSelf>

template<StatisticNormalization NORM = StatisticNormalization::N, typename TResult = ItemOwned, typename TCount = ItemOwned>

constexpr std::optional< TResult > CXXIter::IterApi< TSelf >::mean ( TResult  sumStart = TResult() )

inlineconstexpr

Consumer that calculates the mean of all elements of this iterator.

The mean is calculated by first summing up all elements, and then dividing through the number of elements counted while summing.

Note

This consumes the iterator.

Parameters

sumStart

Optional starting point for the sum of all items. Normally uses default ctor of TResult.

Returns

The mean of all elements of this iterator.

Template Parameters

NORM	Type of the statistical normalization variant to use for the calculation.

See also

StatisticNormalization

Template Parameters

TResult	Type of the mean-calculation's result. This is also the type used for the sum of all elements.
TCount	Type the element counter is converted into, before dividing the sum by. This can be necessary, if TResult is a complex object that only supports the division operator for e.g. double.

Usage Example:

• For a non-empty iterator

  std::vector<float> input = {1.0f, 2.0f, 3.0f};
  std::optional<float> output = CXXIter::from(input).mean();
  // output == Some(2.0f)

• For an empty iterator:

  std::vector<float> input = {};
  std::optional<float> output = CXXIter::from(input).mean();
  // output == None

Definition at line 785 of file CXXIter.h.

Here is the call graph for this function:

min()

template<CXXIterIterator TSelf>

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::min ( )

inlineconstexpr

Consumer that yields the smallest element from this iterator.

Note

This consumes the iterator.

Returns

A CXXIter::IterValue optional either containing the smallest element of this iterator (if any), or empty otherwise.

Usage Example:

• For a non-empty iterator

  std::vector<int> input = {42, 1337, 52};
  std::optional<int> output = CXXIter::from(input)
     .min().toStdOptional();
  // output == Some(42)

• For an empty iterator:

  std::vector<int> input = {};
  std::optional<int> output = CXXIter::from(input)
     .min().toStdOptional();
  // output == None

Definition at line 924 of file CXXIter.h.

Here is the call graph for this function:

minBy()

template<CXXIterIterator TSelf>

template<typename TCompValueExtractFn >
requires requires(const std::invoke_result_t<TCompValueExtractFn, Item&&>& a, std::remove_cvref_t<decltype(a)> ownedA) { { a < a }; { ownedA = ownedA }; }

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::minBy ( TCompValueExtractFn  compValueExtractFn )

inlineconstexpr

Consumer that yields the smallest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given compValueExtractFn on each element.

Note

This consumes the iterator.

Parameters

compValueExtractFn

Function that, given an element from the input iterator as parameter returns the value by which the item should be compared to others.

Returns

A CXXIter::IterValue optional either containing the smallest element of this iterator (if any), or empty otherwise.

Usage Example:

• For a non-empty iterator

     std::vector<std::string> input = {"smol", "middle", "largeString"};
     std::optional<std::string> output = CXXIter::from(input)
         .minBy([](const std::string& str) { return str.size(); })
     .toStdOptional();
  // output == Some("smol")

• For an empty iterator:

     std::vector<std::string> input = {};
     std::optional<std::string> output = CXXIter::from(input)
         .minBy([](const std::string& str) { return str.size(); })
     .toStdOptional();
  // output == None

Definition at line 1032 of file CXXIter.h.

Here is the call graph for this function:

minIdx()

template<CXXIterIterator TSelf>

constexpr std::optional< size_t > CXXIter::IterApi< TSelf >::minIdx ( )

inlineconstexpr

Consumer that yields the index of the smallest element within this iterator.

Note

This consumes the iterator.

Returns

Index of the smallest element within the input iterator (if any).

Usage Example:

• For a non-empty iterator

  std::vector<int> input = {1337, 42, 52};
  std::optional<size_t> output = CXXIter::from(input).minIdx();
  // output == Some(1)

• For an empty iterator:

  std::vector<int> input = {};
  std::optional<size_t> output = CXXIter::from(input).minIdx();
  // output == None

Definition at line 947 of file CXXIter.h.

Here is the call graph for this function:

minIdxBy()

template<CXXIterIterator TSelf>

template<typename TCompValueExtractFn >
requires requires(const std::invoke_result_t<TCompValueExtractFn, Item&&>& a) { { a < a }; }

constexpr std::optional< size_t > CXXIter::IterApi< TSelf >::minIdxBy ( TCompValueExtractFn  compValueExtractFn )

inlineconstexpr

Consumer that yields the index of the smallest element from this iterator. Comparison of items is done using the comparison values returned by invoking the given compValueExtractFn on each element.

Note

This consumes the iterator.

Parameters

compValueExtractFn

Function that, given an element from the input iterator as parameter, returns the value by which the item should be compared to others.

Returns

Index of the smallest element within the input iterator (if any).

Usage Example:

• For a non-empty iterator

  const std::vector<std::string> input = {"middle", "smol", "largeString"};
  std::optional<size_t> output = CXXIter::SrcCRef(input)
     .minIdxBy([](const std::string& str) { return str.size(); });
  // output = Some(1)

• For an empty iterator:

  const std::vector<std::string> input = {};
  std::optional<size_t> output = CXXIter::SrcCRef(input)
     .minIdxBy([](const std::string& str) { return str.size(); });
  // output = None

Definition at line 1074 of file CXXIter.h.

Here is the call graph for this function:

modify()

template<CXXIterIterator TSelf>

template<std::invocable< Item & > TModifierFn>

constexpr op::InplaceModifier< TSelf, TModifierFn > CXXIter::IterApi< TSelf >::modify ( TModifierFn  modifierFn )

inlineconstexpr

Allows to inspect and modify each item in-place, that passes through this iterator.

This can be used instead of a map() with the same type as input and output.

Parameters

modifierFn

Function that is called for each item that passes through this iterator.

Returns

Iterator that forwards the items of this iterator, after they have been inspected and potentially modified by the modifierFn.

Usage Example:

std::unordered_map<int, std::string> input = { {1337, "1337"}, {42, "42"} };
std::unordered_map<int, std::string> output = CXXIter::from(input)
    .modify([](auto& keyValue) { keyValue.second = "-" + keyValue.second; }) // modify input
    .collect<std::unordered_map>(); // copy to output

Definition at line 1732 of file CXXIter.h.

next()

template<CXXIterIterator TSelf>

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::next ( )

inlineconstexpr

Get the next element from this iterator (if any), wrapped in a CXXIter::IterValue<>.

Note

If the returned CXXIter::IterValue is empty, there are no elements left in this iterator. Calling next() again after that is undefined behavior.

Returns

The next element from this iterator (if any), wrapped in a CXXIter::IterValue<>

Usage Example:

   std::optional<float> output = CXXIter::range<float>(1.337f, 2.0f, 0.25f)
       .next().toStdOptional();
// output == Some(1.337f);

Definition at line 175 of file CXXIter.h.

Here is the call graph for this function:

nextBack()

template<CXXIterIterator TSelf>

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::nextBack ( )

inlineconstexpr

Get the next element from the back of this iterator (if any), wrapped in a CXXIter::IterValue<>.

Note

If the returned CXXIter::IterValue is empty, there are no elements left in this iterator. Calling nextBack() again after that is undefined behavior.

This method only exists if the iterator implements the DoubleEndedIterator trait.

Returns

The next element from the back of this iterator (if any), wrapped in a CXXIter::IterValue<>

Usage Example:

   std::optional<float> output = CXXIter::range<float>(1.337f, 2.0f, 0.25f)
       .nextBack().toStdOptional();
// output == Some(0.25f);

Definition at line 213 of file CXXIter.h.

Here is the call graph for this function:

nth()

template<CXXIterIterator TSelf>

constexpr IterValue< Item > CXXIter::IterApi< TSelf >::nth ( size_t  n )

inlineconstexpr

Return the {n}-th element from this iterator (if available).

Parameters

n	Index of the element to return from this iterator.

Returns

The {n}-th element from this iterator.

Usage Example:

• When the n-th element exists:

     std::vector<int> input = {42, 1337, 52};
     std::optional<int> output = CXXIter::from(input).nth(1).toStdOptional();
  // output == Some(1337)

• When the n-th element does not exist:

     std::vector<int> input = {42, 1337, 52};
     std::optional<int> output = CXXIter::from(input).nth(10).toStdOptional();
  // output == None

Definition at line 1229 of file CXXIter.h.

Here is the call graph for this function:

reverse()

template<CXXIterIterator TSelf>

constexpr op::Reverse< TSelf > CXXIter::IterApi< TSelf >::reverse ( )

inlineconstexpr

Constructs a new iterator that provides the elements of this iterator in reverse order.

Attention

If the underlying iterator implements DoubleEndedIterator it is going to be used and this operation will not have an additional cost. If the underlying iterator does not implement DoubleEndedIterator, it will be emulated by first draining the iterator into a container and then providing those elements in reverse. This leads to additional memory usage.

Returns

Iterator that provides the elements of this iterator in reverse order.

Usage Example:

std::vector<size_t> input = {1, 42, 2, 1337, 3, 4, 69, 5, 6, 5};
std::vector<size_t> output = CXXIter::from(input).copied()
   .reverse()
   .collect<std::vector>();
// output == { 5, 6, 5, 69, 4, 3, 1337, 2, 42, 1 }

Definition at line 1421 of file CXXIter.h.

size()

template<CXXIterIterator TSelf>

constexpr size_t CXXIter::IterApi< TSelf >::size ( ) const

inlineconstexpr

Get this iterator's exact size.

Note

This method only exists if the iterator's exact size is known. Operations like IterApi::filter cause the remaining iterator to have an unknown exact size.

Returns

This iterator's exact number of elements.

Usage Example:

• Valid (Exact number of elements is known):

  size_t size = CXXIter::range<float>(0.0f, 2.0f, 0.25f)
          .map([](float blub) { return std::to_string(blub); })
          .sort()
          .intersperse(CXXIter::empty<std::string>())
          .size();
  // size == 8

• Invalid, does not compile (Exact number of elements is unknown):

  size_t size = CXXIter::range<float>(0.0f, 2.0f, 0.25f)
      .map([](float blub) { return std::to_string(blub); })
      .sort()
      .intersperse(CXXIter::empty<std::string>())
      .flatMap()
      .size();

Definition at line 158 of file CXXIter.h.

Here is the call graph for this function:

sizeHint()

template<CXXIterIterator TSelf>

constexpr SizeHint CXXIter::IterApi< TSelf >::sizeHint ( ) const

inlineconstexpr

Get the bounds on the remaining length of this iterator, estimated from the source and all of the chained iterations on it.

Returns

The estimated bounds on the remaining length of this iterator.

Definition at line 128 of file CXXIter.h.

Here is the call graph for this function:

skip()

template<CXXIterIterator TSelf>

constexpr op::SkipN< TSelf > CXXIter::IterApi< TSelf >::skip ( size_t  cnt )

inlineconstexpr

Creates an iterator that skips the first cnt elements from this iterator, before it yields the remaining items.

Parameters

cnt	Amount of elements to skip from this iterator.

Returns

A new iterator that skips cnt elements from this iterator, before yielding the remaining items.

Usage Example:

std::vector<int> input = {42, 42, 42, 42, 1337};
std::vector<int> output = CXXIter::from(input)
    .skip(3) // skip first 3 values
    .collect<std::vector>();

Definition at line 1776 of file CXXIter.h.

skipWhile()

template<CXXIterIterator TSelf>

template<std::invocable< const Item & > TSkipPredicate>

constexpr op::SkipWhile< TSelf, TSkipPredicate > CXXIter::IterApi< TSelf >::skipWhile ( TSkipPredicate  skipPredicate )

inlineconstexpr

Creates an iterator that skips the first elements of this iterator, for which the given skipPredicate returns true.

The skipPredicate is only called until it returned false for the first time, after that its job is done.

Parameters

skipPredicate

Predicate that determines the items whether an item at the beginning of this iterator should be skipped (true). Should return false for the first item yielded from the resulted iterator.

Returns

A new iterator that skips the frist elements from this iterator, until the given skipPredicate returns false for the first time. It then yields all remaining items of this iterator.

Usage Example:

std::vector<int> input = {42, 42, 42, 42, 1337, 42};
std::vector<int> output = CXXIter::from(input)
    .skipWhile([](const int value) { return (value == 42); }) // skip leading 42s
    .collect<std::vector>();

Definition at line 1801 of file CXXIter.h.

sort() [1/2]

template<CXXIterIterator TSelf>

template<SortOrder ORDER = SortOrder::ASCENDING, bool STABLE = false>
requires requires(const ItemOwned& a) { { a < a }; { a > a }; }

constexpr auto CXXIter::IterApi< TSelf >::sort ( )

inlineconstexpr

Creates a new iterator that takes the items from this iterator, and passes them on sorted.

Note

This variant of sort() requires the items to support comparison operators.

Returns

New iterator that returns the items of this iterator sorted.

Attention

Sorter requires to first drain the input iterator, before being able to supply a single element. This leads to additional memory usage.

Template Parameters

ORDER	Decides the sort order of the resulting iterator.
STABLE	If true, uses std::stable_sort internally, if false uses std::sort

Usage Example:

• Sorting in ascending order using a custom comparer:

  std::vector<float> input = {1.0f, 2.0f, 0.5f, 3.0f, -42.0f};
  std::vector<float> output = CXXIter::from(input)
      .sort<CXXIter::ASCENDING, false>()
      .collect<std::vector>();

• Sorting in descending order using a custom comparer:

  std::vector<float> input = {1.0f, 2.0f, 0.5f, 3.0f, -42.0f};
  std::vector<float> output = CXXIter::from(input)
      .sort<CXXIter::DESCENDING, false>()
      .collect<std::vector>();

Definition at line 2116 of file CXXIter.h.

sort() [2/2]

template<CXXIterIterator TSelf>

template<bool STABLE, std::invocable< const ItemOwned &, const ItemOwned & > TCompareFn>

constexpr auto CXXIter::IterApi< TSelf >::sort ( TCompareFn  compareFn )

inlineconstexpr

Creates a new iterator that takes the items from this iterator, and passes them on sorted, using the supplied compareFn.

Parameters

compareFn

Compare function used for the sorting of items.

Returns

New iterator that returns the items of this iterator sorted using the given compareFn.

Attention

Sorter requires to first drain the input iterator, before being able to supply a single element. This leads to additional memory usage.

Template Parameters

STABLE

If true, uses std::stable_sort internally, if false uses std::sort

Usage Example:

• Sorting in ascending order using a custom comparer:

  std::vector<float> input = {1.0f, 2.0f, 0.5f, 3.0f, -42.0f};
  std::vector<float> output = CXXIter::from(input)
      .sort<false>([](const float& a, const float& b) {
          return (a < b);
      })
      .collect<std::vector>();

• Sorting in descending order using a custom comparer:

  std::vector<float> input = {1.0f, 2.0f, 0.5f, 3.0f, -42.0f};
  std::vector<float> output = CXXIter::from(input)
      .sort<false>([](const float& a, const float& b) {
          return (a > b);
      })
      .collect<std::vector>();

Definition at line 2085 of file CXXIter.h.

sortBy()

template<CXXIterIterator TSelf>

template<SortOrder ORDER = SortOrder::ASCENDING, bool STABLE = false, std::invocable< const ItemOwned & > TSortValueExtractFn>
requires requires(const std::invoke_result_t<TSortValueExtractFn, const ItemOwned&>& a) { { a < a }; { a > a }; }

constexpr auto CXXIter::IterApi< TSelf >::sortBy ( TSortValueExtractFn  sortValueExtractFn )

inlineconstexpr

Creates a new iterator that takes the items from this iterator, and passes them on sorted.

In comparison to sort(), which either uses a custom comparator or the items themselves for the sort operation, this variant takes a sortValueExtractFn, which extracts a value for each item in this iterator, that should be used for sorting comparisons.

Returns

New iterator that returns the items of this iterator sorted.

Attention

Sorter requires to first drain the input iterator, before being able to supply a single element. This leads to additional memory usage.

Template Parameters

ORDER	Decides the sort order of the resulting iterator.
STABLE	If true, uses std::stable_sort internally, if false uses std::sort

Usage Example:

• Sorting the items(strings) in ascending order of their length:

  std::vector<std::string> input = {"test1", "test2", "test23", "test", "tes"};
  std::vector<std::string> output = CXXIter::from(input)
      .sortBy<CXXIter::ASCENDING, true>([](const std::string& item) { return item.size(); })
      .collect<std::vector>();

• Sorting the items(strings) in descending order of their length:

  std::vector<std::string> input = {"test1", "test2", "test23", "test", "tes"};
  std::vector<std::string> output = CXXIter::from(input)
      .sortBy<CXXIter::DESCENDING, true>([](const std::string& item) { return item.size(); })
      .collect<std::vector>();

Definition at line 2157 of file CXXIter.h.

stddev()

template<CXXIterIterator TSelf>

template<StatisticNormalization NORM = StatisticNormalization::N, typename TResult = ItemOwned, typename TCount = ItemOwned>

constexpr std::optional< TResult > CXXIter::IterApi< TSelf >::stddev ( )

inlineconstexpr

Consumer that calculates the standard deviation of all elements of this iterator.

The standard deviation is calculated using

See also

variance().

Note

This consumes the iterator.

Returns

The standard deviation of all elements of this iterator.

Template Parameters

NORM	Type of the statistical normalization variant to use for the calculation.

See also

StatisticNormalization

Template Parameters

TResult	Type of the stddev-calculation's result. This is also the type used for the sum of all elements.
TCount	Type the element counter is converted into, before dividing the sum and the squared sum by. This can be necessary, if TResult is a complex object that only supports the division operator for e.g. double.

Usage Example:

• For iterators with at least 2 values:

  std::vector<float> input = {2.0f, 4.0f, 4.0f, 4.0f, 5.0f, 5.0f, 7.0f, 9.0f};
  std::optional<float> output = CXXIter::from(input).stddev();
  // output == Some(2.0f)

• For iterators with at least 2 values with (N-1) norm:

  std::vector<float> input = {1.0f, 2.0f, 3.0f};
  std::optional<float> output = CXXIter::from(input)
     .stddev<CXXIter::StatisticNormalization::N_MINUS_ONE>();
  // output == Some(1.0f)

• For iterators with less than 2 values (not defined):

  std::vector<float> input = {42.0f};
  std::optional<float> output = CXXIter::from(input).stddev();
  // output == None

Definition at line 896 of file CXXIter.h.

stepBy()

template<CXXIterIterator TSelf>

constexpr auto CXXIter::IterApi< TSelf >::stepBy ( size_t  stepWidth )

inlineconstexpr

Creates an iterator with the requested stepWidth from this iterator.

A step width of 1 is a NO-OP, a step width of 2 means that every second element is skipped. The first element is always returned, irrespecting of the requested stepWidth.

Parameters

step	Step width with which elements from this iterator are yielded.

Returns

New iterator with the requested stepWidth

Usage Example:

• Step width of 1 (No-Op):

     std::vector<int> input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
     std::vector<int> output = CXXIter::from(input)
             .stepBy(1)
             .collect<std::vector>();
  // output == {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}

• Step width of 2:

     std::vector<int> input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
     std::vector<int> output = CXXIter::from(input)
             .stepBy(2)
             .collect<std::vector>();
  // output == {0, 2, 4, 6, 8, 10}

Definition at line 1871 of file CXXIter.h.

Here is the call graph for this function:

stringJoin()

template<CXXIterIterator TSelf>

std::string CXXIter::IterApi< TSelf >::stringJoin ( const std::string &  separator )

inline

Consumer that concatenates the elements of this iterator to a large std::string , where each element is separated by the specified separator.

Note

This consumes the iterator.

This method is only available for iterators whose elements are std::string . If that is not the case, convert your items to std::string s first, using a method like map().

Returns

The resulting string concatenation of all items of this iterator.

Usage Example:

• Non-empty iterator with default startValue

  std::vector<int> input = {42, 1337, 52};
  int output = CXXIter::from(input).sum();
  // output == 1431

• Non-Empty iterator with custom startValue of 29906

  std::vector<int> input = {42, 1337, 52};
  int output = CXXIter::from(input).sum(29906);
  // output == 31337

• Empty iterator with default startValue

  std::vector<int> input = {};
  int output = CXXIter::from(input).sum();
  // output == 0

• Empty iterator with custom startValue

  std::vector<int> input = {};
  int output = CXXIter::from(input).sum(31337);
  // output == 31337

Definition at line 746 of file CXXIter.h.

Here is the call graph for this function:

sum()

template<CXXIterIterator TSelf>

template<typename TResult = ItemOwned>
requires requires(TResult res, Item item) { { res += item }; }

constexpr TResult CXXIter::IterApi< TSelf >::sum ( TResult  startValue = TResult() )

inlineconstexpr

Consumer that calculates the sum of all elements from this iterator.

Note

This consumes the iterator.

Parameters

startValue

Starting value from which to start the sum.

Returns

The sum of all elements from this iterator, or startValue if this iterator had no elements.

Usage Example:

• Non-empty iterator with default startValue

  std::vector<int> input = {42, 1337, 52};
  int output = CXXIter::from(input).sum();
  // output == 1431

• Non-Empty iterator with custom startValue of 29906

  std::vector<int> input = {42, 1337, 52};
  int output = CXXIter::from(input).sum(29906);
  // output == 31337

• Empty iterator with default startValue

  std::vector<int> input = {};
  int output = CXXIter::from(input).sum();
  // output == 0

• Empty iterator with custom startValue

  std::vector<int> input = {};
  int output = CXXIter::from(input).sum(31337);
  // output == 31337

Definition at line 708 of file CXXIter.h.

Here is the call graph for this function:

take()

template<CXXIterIterator TSelf>

constexpr op::TakeN< TSelf > CXXIter::IterApi< TSelf >::take ( size_t  cnt )

inlineconstexpr

Creates an iterator that yields at most the first cnt elements from this iterator.

Parameters

cnt	Amount of elements to yield from this iterator.

Returns

A new iterator that yields only at most the first cnt elements from this iterator.

Usage Example:

std::vector<int> input = {42, 57, 64, 128, 1337, 10};
std::vector<int> output = CXXIter::from(input)
    .take(3) // take first 3 values
    .collect<std::vector>();

Definition at line 1818 of file CXXIter.h.

takeWhile()

template<CXXIterIterator TSelf>

template<std::invocable< const Item & > TTakePredicate>
requires std::is_same_v<std::invoke_result_t<TTakePredicate, const Item&>, bool>

constexpr auto CXXIter::IterApi< TSelf >::takeWhile ( TTakePredicate  takePredicate )

inlineconstexpr

Creates an iterator that yields the first elements of this iterator, for which the given takePredicate returns true.

The takePredicate is only called until it returned false for the first time, after that its job is done.

Parameters

takePredicate

Predicate that determines the items returned by the newly constructed iterator. After this predicate yielded false for the first time, the new iterator ends.

Returns

A new iterator that yields the first couple elements from this iterator, until the given predicate returns false for the first time.

Usage Example:

std::vector<int> input = {42, 57, 64, 128, 1337, 10};
std::vector<int> output = CXXIter::from(input)
    .takeWhile([](const int value) { return (value < 1000); }) // take until first item > 1000
    .collect<std::vector>();

Definition at line 1842 of file CXXIter.h.

unique() [1/2]

template<CXXIterIterator TSelf>

constexpr auto CXXIter::IterApi< TSelf >::unique ( )

inlineconstexpr

Constructs a new iterator that only contains every element of the input iterator only once.

This variant uses the input elements directly for the uniqueness-comparison. This requires the input elements to be hashable using std::hash.

Returns

Iterator that does not contain duplicate elements from the input iterator's elements.

Attention

Unique requires extra data storage to remember what items it has already seen. This leads to additional memory usage.

Usage Example:

std::vector<double> input = {1.0, 1.0, 1.5, 1.4, 2.0, 2.1, 2.99, 3.25, 4.5};
std::vector<double> output = CXXIter::from(input)
       .unique()
       .copied()
       .collect<std::vector>();
// output == { 1.0, 1.5, 1.4, 2.0, 2.1, 2.99, 3.25, 4.5 }

Definition at line 1400 of file CXXIter.h.

Here is the call graph for this function:

unique() [2/2]

template<CXXIterIterator TSelf>

template<std::invocable< const ItemOwned & > TMapFn>
requires util::is_hashable<std::invoke_result_t<TMapFn, const ItemOwned&>>

constexpr op::Unique< TSelf, TMapFn > CXXIter::IterApi< TSelf >::unique ( TMapFn  mapFn )

inlineconstexpr

Constructs a new iterator that only contains every element of the input iterator only once.

This variant checks whether the data returned by the given mapFn when invoked with the input's item is unique. This requires the data returned by mapFn to be hashable using std::hash.

Parameters

mapFn

Function that maps the input's element to data that should be used in the uniqueness-check.

Returns

Iterator that does not contain duplicate elements from the input iterator's elements.

Attention

Unique requires extra data storage to remember what items it has already seen. This leads to additional memory usage.

Usage Example:

std::vector<double> input = {1.0, 1.0, 1.5, 1.4, 2.0, 2.1, 2.99, 3.25, 4.5};
std::vector<double> output = CXXIter::from(input)
       .unique([](double item) { return std::floor(item); })
       .copied()
       .collect<std::vector>();
// output == { 1.0, 2.0, 3.25, 4.5 }

Definition at line 1378 of file CXXIter.h.

variance()

template<CXXIterIterator TSelf>

template<StatisticNormalization NORM = StatisticNormalization::N, typename TResult = ItemOwned, typename TCount = ItemOwned>

constexpr std::optional< TResult > CXXIter::IterApi< TSelf >::variance ( )

inlineconstexpr

Consumer that calculates the variance of all elements of this iterator.

The variance is calculated by incrementally calculating a sum and a squared sum of all elements. Then from there, the mean and then the variance are calculated.

Note

This consumes the iterator.

Returns

The variance of all elements of this iterator.

Template Parameters

NORM	Type of the statistical normalization variant to use for the calculation.

See also

StatisticNormalization

Template Parameters

TResult	Type of the variance-calculation's result. This is also the type used for the sum of all elements.
TCount	Type the element counter is converted into, before dividing the sum and the squared sum by. This can be necessary, if TResult is a complex object that only supports the division operator for e.g. double.

See also

https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance

Usage Example:

• For iterators with at least 2 values:

  std::vector<float> input = {2.0f, 4.0f, 4.0f, 4.0f, 5.0f, 5.0f, 7.0f, 9.0f};
  std::optional<float> output = CXXIter::from(input).variance();
  // output == Some(4.0f)

• For iterators with at least 2 values with (N-1) norm:

  std::vector<float> input = {1.0f, 2.0f, 3.0f};
  std::optional<float> output = CXXIter::from(input)
     .variance<CXXIter::StatisticNormalization::N_MINUS_ONE>();
  // output == Some(1.0f)

• For iterators with less than 2 values (not defined):

  std::vector<float> input = {42.0f};
  std::optional<float> output = CXXIter::from(input).variance();
  // output == None

Definition at line 839 of file CXXIter.h.

Here is the call graph for this function:

zip()

template<CXXIterIterator TSelf>

template<typename TOtherIterator >

constexpr op::Zipper< TSelf, std::pair, TOtherIterator > CXXIter::IterApi< TSelf >::zip ( TOtherIterator &&  otherIterator )

inlineconstexpr

"Zips up" two CXXIter iterators into a single iterator over pairs from both iterators.

Constructs new iterator that iterates over std::pair<> instances where values from this iterator are put in the first value, and values from the given otherIterator become the second values. The resulting iterator is only as long as the shorter of both zipped iterators.

Parameters

otherIterator

Second iterator zipped against this iterator.

Returns

New iterator that zips together this iteratore and the given otherIterator into a new iterator over std::pair<> for both zipped iterator's values.

Usage Example:

std::vector<std::string> input1 = {"1337", "42"};
std::vector<int> input2 = {1337, 42};
std::vector<std::pair<std::string, int>> output = CXXIter::from(input1).copied()
   .zip(CXXIter::from(input2).copied())
   .collect<std::vector>();

Definition at line 1898 of file CXXIter.h.

zipTuple()

template<CXXIterIterator TSelf>

template<typename... TOtherIterators>
requires (CXXIterIterator<TOtherIterators> && ...) && (!std::disjunction_v< std::is_reference<typename trait::Iterator<TOtherIterators>::Item>... > && !IS_REFERENCE)

constexpr op::Zipper< TSelf, std::tuple, TOtherIterators... > CXXIter::IterApi< TSelf >::zipTuple ( TOtherIterators &&...  otherIterators )

inlineconstexpr

"Zips up" an arbitrary amount of CXXIter iterators into a single iterator over std::tuple<> from both iterators.

Constructs new iterator that iterates over std::tuple<> instances where values from this iterator are put in the first value, and values from the given otherIterators are stored after that in order. The resulting iterator is only as long as the shortest of all iterators part of the zip.

Parameters

otherIterators

Other iterators zipped against this iterator.

Returns

New iterator that zips together this iteratore and the given otherIterators into a new iterator over std::tuple<> for all of the zipped iterator's values.

Usage Example:

   std::vector<std::string> input1 = {"1337", "42"};
   std::vector<int> input2 = {1337, 42, 80};
   std::vector<float> input3 = {1337.0f, 42.0f, 64.0f};
   std::vector<std::tuple<std::string, int, float>> output = CXXIter::from(input1).copied()
           .zipTuple(CXXIter::from(input2).copied(), CXXIter::from(input3).copied())
           .collect<std::vector>();
// output == { {"1337", 1337, 1337.0f}, {"42", 42, 42.0f} }

Definition at line 1925 of file CXXIter.h.

---

The documentation for this class was generated from the following file:

• include/CXXIter/CXXIter.h