Iterable Class Reference

#include <foreach.h>

Detailed Description

Iterable defines some static helper functions to construct foreach iterators. A foreach iterator supports the foreach-protocol consisting of the following class members:

• A member type alias std::true_type IsForEachIterator; indicates that the class defines a foreach iterator.
• explicit operator Bool() checks if the iterator object has a valid current value. When this returns false for the first time, the iteration terminates.
• operator ++() advances the iterator object.
• The function operator *() const to return the current iteration value.
• A move or copy constructor for the iterator is needed for some operations of Iterable.

Given this protocol, an iteration over all values is done by

for (MyForEachIterator it = ...; it; ++it)
{
  MyValueType& value = *it;
  ...
}

The foreach iterators returned by Iterable functions support range-based for loops:

for (const auto& v : Iterable::Concat(array, Iterable::GetSingleton(x)))
{
  ...
}

See also

$ref foreach

Classes
class	IteratorType

Public Types
template<typename ITERABLE >
using	ValueType = typename IteratorType< ITERABLE >::ValueType

Static Public Member Functions
template<typename T , Int N>
static AutoIterator< T[N]>	Get (T(&array)[N])
template<typename I >
static SFINAEHelper< AutoIterator< typename std::remove_reference< I >::type >, typename std::remove_reference< I >::type::ConstIterator >::type	Get (I &&iterable)
template<typename I >
static SFINAEHelper< I &&, typename std::remove_reference< I >::type::IsForEachIterator >::type	Get (I &&iterator)
template<typename ITERABLE >
static maxon::details::ReverseIterable< ITERABLE >	Reverse (ITERABLE &&iterable)
template<typename COLLECTION >
static MAXON_ATTRIBUTE_FORCE_INLINE maxon::EraseIterator< COLLECTION, false >	EraseIterator (COLLECTION &c)
template<typename COLLECTION >
static MAXON_ATTRIBUTE_FORCE_INLINE maxon::EraseIterator< COLLECTION, true >	SwapEraseIterator (COLLECTION &c)
template<typename I >
static IndexForEachIterator< typename IteratorType< I && >::type >	IndexIterator (I &&it)
template<typename T >
static SingletonForEachIterator< T >	GetSingleton (T &&value)
template<typename T = void, typename I1 , typename I2 >
static ConcatForEachIterator< T, typename IteratorType< I1 && >::type, typename IteratorType< I2 && >::type >	Concat (I1 &&it1, I2 &&it2)
template<typename T = void, typename I1 , typename I2 >
static ConditionalForEachIterator< T, typename IteratorType< I1 && >::type, typename IteratorType< I2 && >::type >	Conditional (Bool select, I1 &&it1, I2 &&it2)
template<typename I , typename MAP >
static MapForEachIterator< MAP, typename IteratorType< I && >::type >	Map (I &&values, MAP &&fn)
template<typename I , typename FILTER >
static FilterForEachIterator< FILTER, typename IteratorType< I && >::type >	Filter (I &&values, FILTER &&filter)
template<typename I1 , typename I2 >
static ZipForEachIterator< typename IteratorType< I1 && >::type, typename IteratorType< I2 && >::type >	Zip (I1 &&it1, I2 &&it2)
template<typename I >
static Bool	Any (I &&iterable)
template<typename I , typename MAP >
static Bool	Any (I &&iterable, MAP &&map)
template<typename I >
static Bool	All (I &&iterable)
template<typename I , typename MAP >
static Bool	All (I &&iterable, MAP &&map)

Member Typedef Documentation

ValueType

using ValueType = typename IteratorType<ITERABLE>::ValueType

Member Function Documentation

Get() [1/3]

static AutoIterator<T[N]> Get ( T(&)  array[N] )

static

Constructs an AutoIterator from a C++ array.

Parameters

[in]

array

The array to iterate over.

Template Parameters

T	Type of the array elements.
N	Size of array.

Returns

AutoIterator over array.

Get() [2/3]

static SFINAEHelper<AutoIterator<typename std::remove_reference<I>::type>, typename std::remove_reference<I>::type::ConstIterator>::type Get ( I &&  iterable )

static

Constructs an AutoIterator from an iterable collection. An iterable collection has Begin() and End() functions returning suitable iterators to iterate over the collection. The returned AutoIterator will iterate over all values from Begin() to End().

Parameters

[in]

iterable

The collection to iterate over.

Template Parameters

I	Type of the collection.

Returns

AutoIterator over iterable.

Get() [3/3]

static SFINAEHelper<I&&, typename std::remove_reference<I>::type::IsForEachIterator>::type Get ( I &&  iterator )

static

Returns the passed parameter. This overload of the other Get function is useful to get a foreach iterator from an object which may be either a foreach iterator itself, or an iterable collection for which an AutoIterator can be created, by just writing

auto it = Iterable::Get(object);

If object is already a foreach iterator, it will just be moved to it, otherwise it will be an AutoIterator for object.

Parameters

[in]

iterator

The iterator object to iterate over.

Template Parameters

I	Type of the iterator.

Returns

iterable.

Reverse()

static maxon::details::ReverseIterable<ITERABLE> Reverse ( ITERABLE &&  iterable )

static

This function can be used in a range-based for loop to reverse the iteration such that it starts at the last element of the iterable and moves towards the first element. The function can only be used for iterables which have suitable – operator.

Note

It does the decrement in operator*, so a use outside of range-based for loops is risky because you might use operator* more than once.

for (const X& value : Iterable::Reverse(xarray))
{
}

Parameters

[in]

iterable

The iterable to iterate over in reverse direction.

Returns

Temporary object to be used in a range-based for loop.

EraseIterator()

static MAXON_ATTRIBUTE_FORCE_INLINE maxon::EraseIterator<COLLECTION, false> EraseIterator ( COLLECTION &  c )

static

This function returns a for-each iterator over the given collection c which allows you to remove the current iteration value from within a ranged-based for loop.

for (auto it = Iterable::EraseIterator(array); it; ++it)
{
  if (*it == valueToErase)
    it.Erase();
}

The iterator provides an Erase function which allows to erase the current iteration value from the underlying collection. After erasure, the current element must not be accessed any longer. But it is allowed to advance the iterator using ++, then it will point to the element behind the erased one.

Parameters

[in,out]

c

The collection to iterate over.

Returns

Foreach iterator over c which allows to safely erase the current element from within a for loop.

See also

SwapEraseIterator

SwapEraseIterator()

static MAXON_ATTRIBUTE_FORCE_INLINE maxon::EraseIterator<COLLECTION, true> SwapEraseIterator ( COLLECTION &  c )

static

This function returns a for-each iterator over the given collection c which allows you to remove the current iteration value from within a ranged-based for loop.

for (auto it = Iterable::SwapEraseIterator(array); it; ++it)
{
  if (*it == valueToErase)
    it.Erase();
}

The iterator provides an Erase function which allows to erase the current iteration value from the underlying collection by the collections's SwapErase function. This will generally be more efficient than the normal Erase, but it changes the order of the collection starting at the current position. After erasure, the current element must not be accessed any longer. But it is allowed to advance the iterator using ++, then it will point to the element behind the erased one.

Parameters

[in,out]

c

The collection to iterate over.

Returns

Foreach iterator over c which allows to safely erase the current element from within a for loop.

See also

EraseIterator

IndexIterator()

static IndexForEachIterator<typename IteratorType<I&&>::type> IndexIterator ( I &&  it )

static

Returns a foreach iterator which iterates over the given iterator and also maintains an index. The index starts with 0 and is automatically incremented for each iteration step, it can be obtained from the iterator using its GetIndex() function. Example:

for (auto it = Iterable::IndexIterator(set); it; ++it)
{
  DiagnosticOutput("Value at index @ is @", it.GetIndex(), *it);
}

Parameters

[in]

it

The iterator, may be any iterable object.

Template Parameters

I	Type of the iterator.

Returns

Foreach iterator iterating over it.

GetSingleton()

static SingletonForEachIterator<T> GetSingleton ( T &&  value )

static

Constructs a singleton foreach iterator. The iterator will iterate a single time over the given value.

Parameters

[in]

value

The single value to iterate over.

Template Parameters

T	Type of the value.

Returns

Foreach iterator iterating a single time over the single value.

Concat()

static ConcatForEachIterator<T, typename IteratorType<I1&&>::type, typename IteratorType<I2&&>::type> Concat ( I1 &&  it1, I2 &&  it2  )

static

Concatenates two foreach iterators. The returned iterator will iterate at first over the first iterator, then over the second one. This example will iterate over array at first, then over the single value x:

for (const auto& i : Iterable::Concat(array, Iterable::GetSingleton(x)))
{
  ...
}

The result type of the returned iterator will be the common type of the value types of the two input iterators if you don't specify the T parameter. If such a common type doesn't exist, you have to specify the T parameter.

Parameters

[in]	it1	The first iterator, may be any iterable object.
[in]	it2	The second iterator, may be any iterable object.

Template Parameters

T	The value type of the result iterator.
I1	Type of the first iterator.
I2	Type of the second iterator.

Returns

Foreach iterator iterating over first, then over second.

Conditional()

static ConditionalForEachIterator<T, typename IteratorType<I1&&>::type, typename IteratorType<I2&&>::type> Conditional ( Bool  select, I1 &&  it1, I2 &&  it2  )

static

Returns a foreach iterator which iterates over either first or second, depending on select. If select is true, the iterator will iterate over all values of first (second won't be used at all), and vice versa if select is false. Example:

for (const auto& i : Iterable::Conditional(sel, arrayA, arrayB))
{
  ...
}

The result type of the returned iterator will be the common type of the value types of the two input iterators if you don't specify the T parameter. If such a common type doesn't exist, you have to specify the T parameter.

Parameters

[in]	select	If true, iterate over first, otherwise over second.
[in]	it1	The first iterator, may be any iterable object.
[in]	it2	The second iterator, may be any iterable object.

Template Parameters

T	The value type of the result iterator.
I1	Type of the first iterator.
I2	Type of the second iterator.

Returns

Conditional foreach iterator iterating over first if select is true, over second otherwise.

Map()

static MapForEachIterator<MAP, typename IteratorType<I&&>::type> Map ( I &&  values, MAP &&  fn  )

static

Returns a foreach iterator which maps each of the values of the underlying iterator values by the given function fn. I.e., if the original values are v1, v2, ..., the returned iterator will yield the values fn(v1), fn(v2), ...

For example, to compute the sum of the squared values of an array using GetSum, you write

BaseArray<Int> array;
...
Int sum = GetSum(Iterable::Map(array, [](Int x) { return x * x; }));

Parameters

[in]	values	The values to iterate over, may be any iterable object.
[in]	fn	The function which maps each original value to the target value of the returned iterator.

Template Parameters

I	Type of the values.
MAP	Type of the mapping function.

Returns

Foreach iterator iterating over values, mapped by fn.

Filter()

static FilterForEachIterator<FILTER, typename IteratorType<I&&>::type> Filter ( I &&  values, FILTER &&  filter  )

static

Returns a foreach iterator which iterates only over those values which pass the given filter. A value x passes the filter unless !filter(x) is true.

Parameters

[in]	values	The values to iterate over, may be any iterable object.
[in]	filter	The filter function. If !filter(x) is true, x will be removed from the iteration.

Template Parameters

I	Type of the values.
FILTER	Type of the filter function.

Returns

Foreach iterator iterating over values, but removing those which don't pass filter.

Zip()

static ZipForEachIterator<typename IteratorType<I1&&>::type, typename IteratorType<I2&&>::type> Zip ( I1 &&  it1, I2 &&  it2  )

static

Returns a foreach iterator which iterates over two iterators in lockstep. For each iteration step, the zip iterator has a pair as its value with the first value of the pair coming from it1 and the second value from it2. The iteration ends as soon as one of the two iterators reaches its end.

Parameters

[in]	it1	The first iterator, may be any iterable object.
[in]	it2	The second iterator, may be any iterable object.

Template Parameters

I1	Type of the first iterator.
I2	Type of the second iterator.

Returns

Foreach iterator iterating over pairs of values from it1 and it2 in a lockstep fashion.

Any() [1/2]

static Bool Any ( I &&  iterable )

static

Any() [2/2]

static Bool Any ( I &&  iterable, MAP &&  map  )

static

All() [1/2]

static Bool All ( I &&  iterable )

static

All() [2/2]

static Bool All ( I &&  iterable, MAP &&  map  )

static