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]arrayThe array to iterate over.
Template Parameters
TType of the array elements.
NSize 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]iterableThe collection to iterate over.
Template Parameters
IType 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]iteratorThe iterator object to iterate over.
Template Parameters
IType 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]iterableThe 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]cThe 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]cThe 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]itThe iterator, may be any iterable object.
Template Parameters
IType 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]valueThe single value to iterate over.
Template Parameters
TType 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]it1The first iterator, may be any iterable object.
[in]it2The second iterator, may be any iterable object.
Template Parameters
TThe value type of the result iterator.
I1Type of the first iterator.
I2Type 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]selectIf true, iterate over first, otherwise over second.
[in]it1The first iterator, may be any iterable object.
[in]it2The second iterator, may be any iterable object.
Template Parameters
TThe value type of the result iterator.
I1Type of the first iterator.
I2Type 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]valuesThe values to iterate over, may be any iterable object.
[in]fnThe function which maps each original value to the target value of the returned iterator.
Template Parameters
IType of the values.
MAPType 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]valuesThe values to iterate over, may be any iterable object.
[in]filterThe filter function. If !filter(x) is true, x will be removed from the iteration.
Template Parameters
IType of the values.
FILTERType 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]it1The first iterator, may be any iterable object.
[in]it2The second iterator, may be any iterable object.
Template Parameters
I1Type of the first iterator.
I2Type 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
maxon::Iterable::Concat
static ConcatForEachIterator< T, typename IteratorType< I1 && >::type, typename IteratorType< I2 && >::type > Concat(I1 &&it1, I2 &&it2)
Definition: foreach.h:1400
Int
maxon::Int Int
Definition: ge_sys_math.h:49
maxon::Iterable::EraseIterator
static MAXON_ATTRIBUTE_FORCE_INLINE maxon::EraseIterator< COLLECTION, false > EraseIterator(COLLECTION &c)
Definition: foreach.h:1318
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:168
maxon::Iterable::Map
static MapForEachIterator< MAP, typename IteratorType< I && >::type > Map(I &&values, MAP &&fn)
Definition: foreach.h:1450
maxon::GetSum
MAXON_ATTRIBUTE_FORCE_INLINE std::remove_reference< ITERABLETYPE >::type::ValueType GetSum(ITERABLETYPE &&array)
Returns the sum of all elements.
Definition: lib_math.h:260
maxon::Iterable::GetSingleton
static SingletonForEachIterator< T > GetSingleton(T &&value)
Definition: foreach.h:1374
maxon::Iterable::IndexIterator
static IndexForEachIterator< typename IteratorType< I && >::type > IndexIterator(I &&it)
Definition: foreach.h:1362
maxon::Iterable::Reverse
static maxon::details::ReverseIterable< ITERABLE > Reverse(ITERABLE &&iterable)
Definition: foreach.h:1296
maxon::Iterable::Conditional
static ConditionalForEachIterator< T, typename IteratorType< I1 && >::type, typename IteratorType< I2 && >::type > Conditional(Bool select, I1 &&it1, I2 &&it2)
Definition: foreach.h:1427
maxon::Iterable::SwapEraseIterator
static MAXON_ATTRIBUTE_FORCE_INLINE maxon::EraseIterator< COLLECTION, true > SwapEraseIterator(COLLECTION &c)
Definition: foreach.h:1342
maxon::Iterable::Get
static AutoIterator< T[N]> Get(T(&array)[N])
Definition: foreach.h:1237