iterator.h File Reference

Defines iterators, structures and functions suitable for enumerating other data structures. More...

#include "uevloop/utils/linked-list.h"
#include "uevloop/utils/closure.h"

Include dependency graph for iterator.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	uel_iterator_t
	Iterators are data structures that wrap arbitrary collections of data and define ways of enumerating them. More...
struct	uel_iterator_array_t
	A specialised iterator suitable for iterating over arrays of arbitrary data. More...

Macros
#define	UEL_ITERATOR_MAP_BOUNDLESS   UINT_MAX

Typedefs
typedef uel_iterator_t	uel_iterator_llist_t
	Alias to uel_iterator_t. Iterator suitable to traverse linked lists. More...

Functions
bool	uel_iterator_foreach (uel_iterator_t *iterator, uel_closure_t *closure)
	Applies a closure to an enumerable collection. More...
size_t	uel_iterator_map (uel_iterator_t *iterator, uel_closure_t *closure, void **destination, size_t limit)
	Applies a closure to an enumerable collection and stores its results. More...
void *	uel_iterator_find (uel_iterator_t *iterator, uel_closure_t *closure)
	Finds the first element enumerated by an iterator that passes the supplied test. More...
size_t	uel_iterator_count (uel_iterator_t *iterator, uel_closure_t *closure)
	Counts elements enumerated by an iterator that pass the supplied test. More...
bool	uel_iterator_all (uel_iterator_t *iterator, uel_closure_t *closure)
	Determines whether all elements enumerated by an iterator pass the supplied test or not. More...
bool	uel_iterator_none (uel_iterator_t *iterator, uel_closure_t *closure)
	Determines whether all elements enumerated by an iterator fail the supplied test or not. More...
bool	uel_iterator_any (uel_iterator_t *iterator, uel_closure_t *closure)
	Determines whether any elements enumerated by an iterator pass the supplied test or not. More...
void *	uel_iterator_array_next (uel_iterator_array_t *iterator, void *last)
	Yields elements in a array. More...
uel_iterator_array_t	uel_iterator_array_create (void *collection, size_t count, size_t size)
	Creates a new array iterator. More...
void *	uel_iterator_llist_next (uel_iterator_t *iterator, void *last)
	Yields elements in a linked list. More...
uel_iterator_llist_t	uel_iterator_llist_create (uel_llist_t *list)
	Creates a new linked list iterator. More...

Detailed Description

Defines iterators, structures and functions suitable for enumerating other data structures.

Macro Definition Documentation

UEL_ITERATOR_MAP_BOUNDLESS

#define UEL_ITERATOR_MAP_BOUNDLESS   UINT_MAX

Defines the maximum possible iteration limit for the uel_iterator_map() function.

Typedef Documentation

uel_iterator_llist_t

typedef uel_iterator_t uel_iterator_llist_t

Alias to uel_iterator_t. Iterator suitable to traverse linked lists.

Because when traversing a linked list we need only know one element to know the next one, there is no need to store any additional state in linked list iterators.

Function Documentation

uel_iterator_all()

bool uel_iterator_all	(	uel_iterator_t *	iterator,
		uel_closure_t *	closure
	)

Determines whether all elements enumerated by an iterator pass the supplied test or not.

Parameters

iterator	The iterator that enumerates the elements of some collection
closure	The test to be applied against each enumerated element

Returns

Whether all elements are approved by the test closure.

uel_iterator_any()

bool uel_iterator_any	(	uel_iterator_t *	iterator,
		uel_closure_t *	closure
	)

Determines whether any elements enumerated by an iterator pass the supplied test or not.

Parameters

iterator	The iterator that enumerates the elements of some collection
closure	The test to be applied against each enumerated element

Returns

Whether any elements are approved by the test closure. If such element is found, this function returns early.

uel_iterator_array_create()

uel_iterator_array_t uel_iterator_array_create	(	void *	collection,
		size_t	count,
		size_t	size
	)

Creates a new array iterator.

Parameters

collection	The array to be enumerated
count	The number of elements in this array
size	The size of each element in the array

Returns

The created iterator

uel_iterator_array_next()

void* uel_iterator_array_next	(	uel_iterator_array_t *	iterator,
		void *	last
	)

Yields elements in a array.

Parameters

iterator	The iterator thar enumerates the elements in the target array
last	The last element yielded. If NULL, returns the first element.

Returns

The next element in the array with respect to the last one provided. If there are no more elements in the array, this returns NULL.

uel_iterator_count()

size_t uel_iterator_count	(	uel_iterator_t *	iterator,
		uel_closure_t *	closure
	)

Counts elements enumerated by an iterator that pass the supplied test.

Parameters

iterator	The iterator that enumerates the elements of some collection
closure	The test to be applied against each enumerated element

Returns

How many elements successfully passed the supplied test

uel_iterator_find()

void* uel_iterator_find	(	uel_iterator_t *	iterator,
		uel_closure_t *	closure
	)

Finds the first element enumerated by an iterator that passes the supplied test.

Parameters

iterator	The iterator that enumerates the elements of some collection
closure	The test to be applied against each enumerated element

Returns

The address of the first element that passes the supplied test. If no such element is found, returns NULL.

uel_iterator_foreach()

bool uel_iterator_foreach	(	uel_iterator_t *	iterator,
		uel_closure_t *	closure
	)

Applies a closure to an enumerable collection.

Parameters

iterator	The iterator that enumerates the elements of some collection
closure	The closure to be invoked with each element in the enumerated collection as parameter. If this closure returns false, the iteration will be halted.

Returns

Whether the collection was fully iterated over or if the process was halted by returning false.

uel_iterator_llist_create()

uel_iterator_llist_t uel_iterator_llist_create

(

uel_llist_t *

list

)

Creates a new linked list iterator.

Parameters

list	The linked list to be enumerated

Returns

The created iterator

uel_iterator_llist_next()

void* uel_iterator_llist_next	(	uel_iterator_t *	iterator,
		void *	last
	)

Yields elements in a linked list.

Parameters

iterator	The iterator thar enumerates the elements in the target list
last	The last element yielded. If NULL, returns the first element.

Returns

The next element in the list with respect to the last one provided. If there are no more elements in the list, this returns NULL.

uel_iterator_map()

size_t uel_iterator_map	(	uel_iterator_t *	iterator,
		uel_closure_t *	closure,
		void **	destination,
		size_t	limit
	)

Applies a closure to an enumerable collection and stores its results.

This function takes an iterator that enumerates elements in a collection and yields each one to a closure. The return value of each closure call is stored in an array.

Parameters

iterator	The iterator that enumerates the elements of some collection
closure	The closure to be invoked with each element in the enumerated collection ad parameter.
destination	The destination of the data produced by the invoked closure. This must be an array of void pointers large enough to store all produced data
limit	The maximum size of the destination buffer. If collection is larger than this array, in elements, it will not be iterated entirely, only up to the limitth element.

Returns

The number of effectively iterated elements.

uel_iterator_none()

bool uel_iterator_none	(	uel_iterator_t *	iterator,
		uel_closure_t *	closure
	)

Determines whether all elements enumerated by an iterator fail the supplied test or not.

Parameters

iterator	The iterator that enumerates the elements of some collection
closure	The test to be applied against each enumerated element

Returns

Whether all elements are reproved by the test closure.