CI System	Compilers	Status (master)
Travis CI	gcc, clang
Appveyor	MSVC

Enumerable

Enumerable is a library inspired by IEnumerable in c#. The twist is that it is implemented in c++ !

Some core concepts in the library is deffered execution, dependency inversion, lazy evaluation. No matter how complex a sequence object is created, there should be no memory allocation or processing performed until the sequence is actually iterated!

• Installation
• Using
  • Creating Enumerable object
  • Reducing a sequence to a single value
  • Transforms
• Methods
  • Sequence transforming functions
  • Sequence reducing functions
  • Enumerable-overloads
• More details

Installation

The installation procedure for using the library is pretty simple

1. Clone the repository

2. Add the include folder to your include paths.

If you want to contribute, see Contributing(TBD) for more detailed instructions.

Using

Include the header file <enumerable/enumerable.h>.

Creating Enumerable object

If you have a standard container you can use the overloaded function Enumerable(T) to obtain an object that implements EnumerableBase.

std::vector<int> myIntVector;
auto intEnumerable = Enumerable(myIntVector);

The overloads of Enumerable return an object that reference the source collection(Unless explicitly specified). This means one can add elements to it after creating the enumerable-object. In the following snippet, we populate the source vector and sinks all the elements into the printInt function.

void printInt(int value)
{
   printf("%d\n", value);
}

// Populate source
myIntVector = { 1, 2, 3};

// Call printInt for every element in the sequence
intEnumerable.forEach(printInt);
// Output:
// 1
// 2
// 3

Reducing a sequence to a single value

forEach can be considered to be a sink which every member of the sequence is deposited into. Besides sinks there are functions that reduce the sequence into a return value.

int staticIntArray[4] = { -1, 5, 2, 3};

printf("Max: %d\n", Enumerable(staticIntArray).max());
// Output:
// Max: 5

Besides max there are all(pred), any(pred), contains, count, count(pred), various elementAt(idx), first, last, min, sequenceEqual(seq), and toContainer. There is also a very generic reduce function which you can use to reduce the sequence however you like!

Some of these mentioned functions take a pred parameter, which is a predicate. count(pred) only counts the elements that pass the predicate, while any(pred) returns true of any element in the sequence passes the predicate.

bool hasNegative = Enumerable(staticIntArray).any([](int x) { return x < 0;});
size_t positiveCount = Enumerable(staticIntArray).count([](int x){ return x >= 0; });

printf("Has Negative: %d", hasNegtive);
printf("Number of elements with value > 0: %d\n", positiveCount);
// Output:
// Has Negative: 1
// Number of elements with value > 0: 3

Transforming sequences

The really good part comes when we start to apply transformations and filters to our sequences to create new sequence objects!

The simplest transformations are probably select and where. They implement the standard map and filter operations.

// Predicate that determines if a value is positive
bool isPositive(int value) { return value >= 0; }

// Take integer radius, return floating point area.
double calculateArea(int radius) { return radius*radius*3.14; }

// Create an object representing the sequence of all positive values in staticIntArray
auto positiveSequence = Enumerable(staticIntArray).where(isPositive);

// Create a sequence of areas values from positiveSequence
auto areaSequence = positiveSequence.select(calculateArea);

for( double area : areaSequence)
{
   printf("Area: %f\n", area);
}

// Output:
// Area: 78.539816339744830961566084581988
// Area: 12.566370614359172953850573533118
// Area: 3.1415926535897932384626433832795

In this example, we first filter the sequence with the predicate function isPositive. Then we transform the contents of that sequence using select with calculateArea. Then we use a ranged for loop to enumerate the results. Of special interest is that select not only modifies the value but also changes the domain of the value; From an int domain to a double domain. The sequence object created could of course contain more complex values, for example pointers to class objects on the heap from the source value.

Other methods that return new sequence objects (all of which implement EnumerableBase) include dynamicCast<T>, staticCast<T>, constCast<T>, reinterpretCast<T>, ofType<T>, concat(seq), defaultIfEmpty, valueIfEmpty(value), distinct, except(seq), intersect(seq), join(seq, kf1,kf2,jf).

Methods

The list of methods is split into two groups. The first group transforms a sequence into a new sequence. The second group consists of all the other sequences.

Sequence transforming functions

In the following descriptions, this refers to the sequence which operations are applied to. (ex this.defaultIfEmpty())

Sequence reducing functions

The following methods do not return a new sequence. Most of them reduce the sequence to a single value. At the end there are two methods which break this pattern.

Enumerable overloads

These are the overloads of Enumerable

More details

Any sequence object really only consists of two things:

• The source sequence
• The operations to apply (filtering, transforming)

In the case where the source is an array or a std-container, the source sequence is a reference and there are no operations (though there are iterators to keep track of state). If a sequence is created using select on a such sequence, it would look like

• Select source sequence
  • container reference
  • container iterators
• Transform -function to apply

If that object would be filtered with where then we'd get an object with the following contents

• Where source sequence
  • Select source sequence
    • container reference
    • container iterators
  • Transform -function to apply
• Filter -function to apply

This structure is known at compile time. The objects can live on the stack, no matter how complex our chaining is. They really only contain the operations that they represent. It is not until they are iterated that memory and cpu is used.

This has a drawback(for which there is a good solution!). It makes it really hard to design functions which accept sequence objects, as just a few chained operations produce tricky templated types. It also means that it is hard to create object members which represent sequences. Thus it becomes hard to store a sequence of operations.

The way these problems are solved is two-fold. First, since every enumerable/sequence object inherits and implements EnumerableBase they also inherit and implement IEnumerable<T>, where T is the type of the elements in the sequence.

void mySinkFunction(IEnumerable<int>& intSequence)
{
   ...
}

One can then either wrap the sequence in Enumerable(intSequence) to obtain a new object which can be ranged-for -looped over (or sinked, or anything). Or one can use the primitives T value()and bool moveNext() to manually iterate the sequence.

But hey, that doesn't help me with storing produced sequences as members or globals!

There is a solution for that as well. The function makeHeapEnumerable returns an object of the type HeapEnumerable<T>. This type can be declared as a parameter type or member. The function makeHeapEnumerable allocates memory on the heap, puts a copy of itself(the sequence object) into that memory, and then constructs a HeapEnumerable<T>object which is now responsible for that memory. After that it is safe to pass the object around. It effectively becomes a first-order sequence object which contains a referene to an anonymous source.

// Declare global
HeapEnumerable<int> g_intSequence;

// Later set contents of sequence.
if(something())
{
   g_intSequence = g_networkSource
      .select(createObjects)
      .filter(validObjects)
      .select([](auto& obj) { return obj.timestamp; });
}
else
{
   g_intSequence = g_polygons
      .select([](auto& polygon){ return polygon.points.count(); });
}

Here we use something() to determine if we should produce random int´s from a network source or from polygons.

Rest is old readme.

It supplies a CRTP-template which implements various functions like .all() or .select. It expects that what inherits from it implements a moveNext() and value() function. Various functions return values, like .all(predicate) which reduces a sequence to a boolean if the predicate evaluates to true for all elements in the sequence. Other operations return a new sequence based on the first sequence, like .select(transform) where transform is [](auto x){ return x*2;} will return a sequence where elements are twice as large as the elements in the source sequence. Sequences that are returned do in turn inherit from the interface, allowing multiple manipulating operations to be chained seamlessly like .where(filter).select(transform). Computation/processing is done in a deferred manner; only when the final sequence is traversed will the operations be applied. To force processing and allocation at known time, one can use .toContainer() or .pushBack(T& container)

Arrays and standard containers can be wrapped in in the interface with the Enumerable(sequence)-function which has various overloads. This constructs an object that implements the interface. The various interface-functions which result in a new sequence create copies of the source sequence. This means that a .select(transform) can be copied to multiple variables, each of which will be a sequence that can be iterated once. They thus have their own complete state of all chained operations. But the first sequence object will contain a reference to its source container/sequence. Thus any sequence might end up advancing the source. If the source sequence wraps a container like a std::vector or a normal array then the resulting sequences can be iterated once each. If the source sequence consists of bytes read from a socket, then any advancement in any sequence naturally advances the source.

The interface inherits an IEnumerable interface wich moveNext() and value(). Thus a library function can accept an IEnumerable without knowing the operations that lead to the sequence. And IEnumerable can be wrapped with Enumerable() and result in a sequence with the transformation/aggregation functions and be further chained. But at this point the new sequences will be sourced with a reference, and can only be advanced once.