z::core::generator< T, S > Class Template Reference

An arbitrary generator for producing sequential results on-the-fly. More...

#include <generator.hpp>

Inheritance diagram for z::core::generator< T, S >:

Public Member Functions
	generator (const S &initial, std::function< const std::optional< T >(S &)> lambda)
	Constructor with an initial state.
generatorIter< T, S >	begin () const noexcept override
	Begin iterator (start of the range)
generatorIter< T, S >	end () const noexcept override
	End iterator (end of the range)
std::optional< T >	next ()
	Get the next item from the generator.
long	count ()
	Get the total count of items that will be generated.
array< T >	collect ()
	Concatenate all generator elements into an array.
long	consume ()
	Consume and discard all items from the generator.
array< T >	take (int count)
	Take a certain number of items from the generator.
template<typename U >
generator< U, S >	map (std::function< U(const T &)> mapLambda) noexcept
	Applies a transformation function to each item that comes out of the generator.
generator	filter (std::function< T(const T &)> filterLambda) noexcept
	Filters the generatred items based on a predicate and returns a new generator that yields only the items that satisfy the predicate.
T	reduce (const T &defaultValue, std::function< T(const T &, const T &)> reduceLambda)
	Reduces the generator to a single value by applying a binary operation cumulatively to all yielded values.
generator &	forEach (std::function< void(const T &)> newLambda) noexcept
	Binds a function to run each time an item comes out of the generator.
generator< T, countedState >	skip (long count) noexcept
	Skips a certain number of items from the generator.
generator< T, countedState >	limit (long count) noexcept
	Limits the number of items that the generator will std::optional.
template<typename U , typename S2 >
generator< std::pair< T, U >, generator< U, S2 > >	pair (generator< U, S2 > &other) noexcept
	Pair items from this generator with those of another generator.
generator< T, std::pair< bool, generator & > >	zip (generator &other) noexcept
	Zip this generator with another generator.
generator< std::pair< long, T >, std::pair< long, generator< T, S > > >	enumerate () noexcept
	Enumerate the items in this generator.
generator< T, std::pair< generator, std::optional< T > > >	diff (generator &other) noexcept
	List the items in this generator which differ from another generator.
generator< array< T >, generator >	chunk (long chunkSize) noexcept
	Get chunks of items from the generator.
template<typename U = T, typename std::enable_if< is_iterator< U >::value, int >::type = 0>
auto	flatten () noexcept
	Break up a chunked generator into its constituent generated items.
generator< std::pair< T, std::optional< T > >, std::pair< std::optional< T >, generator > >	peek () noexcept
	Allow peeking at the next item in the generator as items are generated.
template<typename U >
generator< T, bool >	chain (generator< T, U > &other) noexcept
	Chains two generators together.
generator< long, generator< long, long >::countedState >	skip (long count) noexcept
	Template specialization for the skip function with generators that only output longs.
Public Member Functions inherited from z::core::iterable< generatorIter< T, S > >
virtual	~iterable () noexcept
	Virtual destructor.

Detailed Description

template<typename T, typename S>
class z::core::generator< T, S >

An arbitrary generator for producing sequential results on-the-fly.

This class encapsulates generator functionality with any state data the generator may require. Some ideal uses for this class include looping over large sets of data that can't all be loaded at runtime, or loading data in batches while still outputting only a small bit at a time.

Template Parameters

T	The type of data that the generator returns.
S	The state data for the generator.

Examples

customGenerator.cpp.

Constructor & Destructor Documentation

generator()

template<typename T , typename S >

z::core::generator< T, S >::generator ( const S &  initial, std::function< const std::optional< T >(S &)>  lambda  )

inline

Constructor with an initial state.

Parameters

initial	The initial value of the generator's state.
lambda	The generator function.

Member Function Documentation

begin()

template<typename T , typename S >

generatorIter< T, S > z::core::generator< T, S >::begin ( ) const

inlineoverridevirtualnoexcept

Begin iterator (start of the range)

Returns

An iterator that will give the first value in the generator.

Implements z::core::iterable< generatorIter< T, S > >.

chain()

template<typename T , typename S >

template<typename U >

generator< T, bool > z::core::generator< T, S >::chain ( generator< T, U > &  other )

inlinenoexcept

Chains two generators together.

This function takes two generators and chains them together, so that multiple generators can be used as a single generator. That is, the items from this are generated first, and once this generator is exhausted, items from the other generator are generated until exhaustion.

Note

Generators chained together this way must yield values of the same type.

Template Parameters

U	The state type of the other generator.

Parameters

other

The generator to chain after this generator.

Returns

A new generator that first yields items from this generator and then the other.

chunk()

template<typename T , typename S >

generator< array< T >, generator > z::core::generator< T, S >::chunk ( long  chunkSize )

inlinenoexcept

Get chunks of items from the generator.

This function will yield chunks of items from the generator, where each chunk is an array of items of at most the specified size. If the generator runs out of items, the last chunk may contain fewer items.

Parameters

chunkSize

The size of each chunk.

Returns

A new generator that yields arrays of items, each of at most the specified size.

collect()

template<typename T , typename S >

array< T > z::core::generator< T, S >::collect ( )

inline

Concatenate all generator elements into an array.

Note

This function will consume the generator, and it will not be able to be used again.

Returns

An array containing all elements from the generator.

consume()

template<typename T , typename S >

long z::core::generator< T, S >::consume ( )

inline

Consume and discard all items from the generator.

Note

This function will consume the generator, and it will not be able to be used again.

Returns

The number of items that were generated.

count()

template<typename T , typename S >

long z::core::generator< T, S >::count ( )

inline

Get the total count of items that will be generated.

Warning

This function will consume the generator, and it will not be able to be used again.

Returns

The number of items that were generated.

diff()

template<typename T , typename S >

generator< T, std::pair< generator, std::optional< T > > > z::core::generator< T, S >::diff ( generator< T, S > &  other )

inlinenoexcept

List the items in this generator which differ from another generator.

This function is only useful for generators that yield items of the same type. (if the generators yielded different types, ALL items would be considered different!)

As an example of how this works, if you have two generators that yield strings, generator1 yields "apple", "banana", "cherry", "melon", and generator2 yields "banana", "cherry", "date", "fig", then calling generator1.diff(generator2) will yield "apple" and "melon".

Note

If the other generator runs out of items, the rest of the items from this generator will be yielded, as they are considered different from nothing.

Parameters

other

The other generator to compare against.

Returns

A new generator that yields only items that are different from the items in the other generator.

end()

template<typename T , typename S >

generatorIter< T, S > z::core::generator< T, S >::end ( ) const

inlineoverridevirtualnoexcept

End iterator (end of the range)

Returns

A dummy iterator indicating the end of the range.

Implements z::core::iterable< generatorIter< T, S > >.

enumerate()

template<typename T , typename S >

generator< std::pair< long, T >, std::pair< long, generator< T, S > > > z::core::generator< T, S >::enumerate ( )

inlinenoexcept

Enumerate the items in this generator.

This function wraps the existing generator in another generator that yields pairs of indices and items. The first item will have index 0, the second item will have index 1, and so on.

Returns

A new generator that yields pairs of indices and items.

filter()

template<typename T , typename S >

generator z::core::generator< T, S >::filter ( std::function< T(const T &)>  filterLambda )

inlinenoexcept

Filters the generatred items based on a predicate and returns a new generator that yields only the items that satisfy the predicate.

This function wraps the existing generator in another generator, and as each item is generated, applies the given lambda function as a predicate, and only yields items that satisfy the predicate.

Parameters

filterLambda

A function that takes a constant reference to an item of type T and returns a boolean indicating whether the item should be yielded.

Returns

A new generator that yields only items that satisfy the predicate.

flatten()

template<typename T , typename S >

template<typename U = T, typename std::enable_if< is_iterator< U >::value, int >::type = 0>

auto z::core::generator< T, S >::flatten ( )

inlinenoexcept

Break up a chunked generator into its constituent generated items.

Returns

A new generator that yields the individual items that were previously yielded in chunks.

Note

This member function is only enabled if the current generator yields iterables.

forEach()

template<typename T , typename S >

generator & z::core::generator< T, S >::forEach ( std::function< void(const T &)>  newLambda )

inlinenoexcept

Binds a function to run each time an item comes out of the generator.

This function wraps the existing generator function in another function, effectively binding extra logic to this generator. each item on-the-fly as it's generated.

Note

This function does not consume the generator directly, it just runs the given function each time an item is generated.

Parameters

newLambda

A function that takes a constant reference to an element of type T and returns nothing.

Returns

A reference to this generator, with the new function bound.

limit()

template<typename T , typename S >

generator< T, countedState > z::core::generator< T, S >::limit ( long  count )

inlinenoexcept

Limits the number of items that the generator will std::optional.

Parameters

count

The maximum number of items to std::optional.

Returns

A new generator that yields the given number of items.

map()

template<typename T , typename S >

template<typename U >

generator< U, S > z::core::generator< T, S >::map ( std::function< U(const T &)>  mapLambda )

inlinenoexcept

Applies a transformation function to each item that comes out of the generator.

This function wraps the existing generator in another generator, effectively transforming each item on-the-fly as it's generated.

Template Parameters

U	The type of items that this new generator yields.

Parameters

mapLambda

A function that takes a constant reference to an element of type T and returns an element of type U.

Returns

A new generator that yields the transformed elements.

next()

template<typename T , typename S >

std::optional< T > z::core::generator< T, S >::next ( )

inline

Get the next item from the generator.

If there are no more items, the optional object will not contain anything.

Returns

A std::optional object containing the next value, if any.

pair()

template<typename T , typename S >

template<typename U , typename S2 >

generator< std::pair< T, U >, generator< U, S2 > > z::core::generator< T, S >::pair ( generator< U, S2 > &  other )

inlinenoexcept

Pair items from this generator with those of another generator.

This function combines two generators into a single generator that yields pairs of items from both generators. If one generator runs out of items, the resulting generator will stop yielding items.

Parameters

other

The other generator to pair with.

Returns

A new generator that yields pairs of items from both generators.

peek()

template<typename T , typename S >

generator< std::pair< T, std::optional< T > >, std::pair< std::optional< T >, generator > > z::core::generator< T, S >::peek ( )

inlinenoexcept

Allow peeking at the next item in the generator as items are generated.

The generator that this function produces will yield std::pairs containing (1) the current value, and (2) a yield object containing the next value, if any. It is up to the programmer to properly check that the yield has a value.

Returns

A new generator that yields a pair of (item, z::core::std::optional<item>).

reduce()

template<typename T , typename S >

T z::core::generator< T, S >::reduce ( const T &  defaultValue, std::function< T(const T &, const T &)>  reduceLambda  )

inline

Reduces the generator to a single value by applying a binary operation cumulatively to all yielded values.

This function applies a binary operation (provided as a lambda) to combine all yielded items into a single value. If the generator doesn't yield anything, the provided default value is returned.

Note

Especially for long lists of items, this is significantly more memory-efficient than calling collect()and then reduce() on the resulting array, as an intermediate array does not need to be constructed.

Parameters

defaultValue	The value to return if the array is empty.
reduceLambda	A function that takes two elements of type T and returns their combined result of type T.

Returns

The result of the reduction operation.

skip() [1/2]

template<typename T , typename S >

generator< T, countedState > z::core::generator< T, S >::skip ( long  count )

inlinenoexcept

Skips a certain number of items from the generator.

This function will skip a certain number of items from the generator, or all items if there are fewer than the requested count.

Note

This function does not consume the generator directly, it just skips items as they are generated.

Parameters

count

The number of items to skip.

Returns

A new generator that skips the given number of items.

skip() [2/2]

generator< long, generator< long, long >::countedState > z::core::generator< long, long >::skip ( long  count )

noexcept

Template specialization for the skip function with generators that only output longs.

Parameters

count

The number of items to skip.

Returns

A new generator that skips the given number of items.

take()

template<typename T , typename S >

array< T > z::core::generator< T, S >::take ( int  count )

inline

Take a certain number of items from the generator.

This function will take a certain number of items from the generator, or all items if there are fewer than the requested count.

Parameters

count

The number of items to take.

Returns

An array containing the taken items.

zip()

template<typename T , typename S >

generator< T, std::pair< bool, generator & > > z::core::generator< T, S >::zip ( generator< T, S > &  other )

inlinenoexcept

Zip this generator with another generator.

This function combines two generators into a single generator that yields items from each generator in an alternating pattern. If one generator runs out of items, then only items from the other generator will be yielded.

Parameters

other

The other generator to zip with.

Returns

A new generator that yields alternating items from both generators.

---

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

• z/core/generator.hpp