iterator.h File Reference

Interface for iterator implementations. More...

#include "common.h"

Go to the source code of this file.

Data Structures
struct	cx_iterator_base_s
	Common data for all iterators. More...
struct	cx_iterator_s
	Internal iterator struct - use CxIterator. More...

Macros
#define	CX_ITERATOR_BASE   struct cx_iterator_base_s base
	Declares base attributes for an iterator.
#define	cxIteratorValid(iter)   (iter).base.valid(&(iter))
	Checks if the iterator points to valid data.
#define	cxIteratorCurrent(iter)   (iter).base.current(&iter)
	Returns a pointer to the current element.
#define	cxIteratorNext(iter)   (iter).base.next(&iter)
	Advances the iterator to the next element.
#define	cxIteratorFlagRemoval(iter)   (iter).base.remove |= (iter).base.mutating
	Flags the current element for removal, if this iterator is mutating.
#define	cxIteratorRef(iter)   &((iter).base)
	Obtains a reference to an arbitrary iterator.
#define	cx_foreach(type, elem, iter)   for (type elem; cxIteratorValid(iter) && (elem = (type)cxIteratorCurrent(iter)) != NULL ; cxIteratorNext(iter))
	Loops over an iterator.

Typedefs
typedef struct cx_iterator_base_s	CxIteratorBase
	Convenience type definition for the base structure of an iterator.
typedef struct cx_iterator_s	CxIterator
	Iterator type.

Functions
CxIterator	cxIterator (const void *array, size_t elem_size, size_t elem_count)
	Creates an iterator for the specified plain array.
CxIterator	cxMutIterator (void *array, size_t elem_size, size_t elem_count, bool remove_keeps_order)
	Creates a mutating iterator for the specified plain array.
CxIterator	cxIteratorPtr (const void *array, size_t elem_count)
	Creates an iterator for the specified plain pointer array.
CxIterator	cxMutIteratorPtr (void *array, size_t elem_count, bool remove_keeps_order)
	Creates a mutating iterator for the specified plain pointer array.

Detailed Description

Interface for iterator implementations.

Author

Mike Becker

Olaf Wintermann

Copyright

2-Clause BSD License

Macro Definition Documentation

cx_foreach

#define cx_foreach	(		type,
			elem,
			iter )   for (type elem; cxIteratorValid(iter) && (elem = (type)cxIteratorCurrent(iter)) != NULL ; cxIteratorNext(iter))

Loops over an iterator.

Parameters

type	the type of the elements
elem	the name of the iteration variable
iter	the iterator

CX_ITERATOR_BASE

#define CX_ITERATOR_BASE   struct cx_iterator_base_s base

Declares base attributes for an iterator.

Must be the first member of an iterator structure.

cxIteratorCurrent

#define cxIteratorCurrent

(

iter

)

(iter).base.current(&iter)

Returns a pointer to the current element.

The behavior is undefined if this iterator is invalid.

Parameters

iter	the iterator

Returns

a pointer to the current element

See also

cxIteratorValid()

cxIteratorFlagRemoval

#define cxIteratorFlagRemoval

(

iter

)

(iter).base.remove |= (iter).base.mutating

Flags the current element for removal, if this iterator is mutating.

Does nothing for non-mutating iterators.

Parameters

iter	the iterator

cxIteratorNext

#define cxIteratorNext

(

iter

)

(iter).base.next(&iter)

Advances the iterator to the next element.

Parameters

iter	the iterator

cxIteratorRef

#define cxIteratorRef

(

iter

)

&((iter).base)

Obtains a reference to an arbitrary iterator.

This is useful for APIs that expect some iterator as an argument.

Parameters

iter	the iterator

Returns

(struct cx_iterator_base_s*) a pointer to the iterator

cxIteratorValid

#define cxIteratorValid

(

iter

)

(iter).base.valid(&(iter))

Checks if the iterator points to valid data.

Parameters

iter	the iterator

Return values

true	if the iterator points to valid data
false	if the iterator already moved past the end

Typedef Documentation

CxIterator

typedef struct cx_iterator_s CxIterator

Iterator type.

An iterator points to a certain element in a (possibly unbounded) chain of elements. Iterators that are based on collections (which have a defined "first" element), are supposed to be "position-aware", which means that they keep track of the current index within the collection.

Note

Objects that are pointed to by an iterator are always mutable through that iterator. However, any concurrent mutation of the collection other than by this iterator makes this iterator invalid, and it must not be used anymore.

CxIteratorBase

typedef struct cx_iterator_base_s CxIteratorBase

Convenience type definition for the base structure of an iterator.

See also

CX_ITERATOR_BASE

Function Documentation

cxIterator()

CxIterator cxIterator	(	const void *	array,
		size_t	elem_size,
		size_t	elem_count )

Creates an iterator for the specified plain array.

The array can be NULL in which case the iterator will be immediately initialized such that cxIteratorValid() returns false.

This iterator yields the addresses of the array elements. If you want to iterator over an array of pointers, you can use cxIteratorPtr() to create an iterator which directly yields the stored pointers.

Parameters

array	a pointer to the array (can be NULL)
elem_size	the size of one array element
elem_count	the number of elements in the array

Returns

an iterator for the specified array

See also

cxIteratorPtr()

cxIteratorPtr()

CxIterator cxIteratorPtr	(	const void *	array,
		size_t	elem_count )

Creates an iterator for the specified plain pointer array.

This iterator assumes that every element in the array is a pointer and yields exactly those pointers during iteration (while in contrast an iterator created with cxIterator() would return the addresses of those pointers within the array).

Parameters

array	a pointer to the array (can be NULL)
elem_count	the number of elements in the array

Returns

an iterator for the specified array

See also

cxIterator()

cxMutIterator()

CxIterator cxMutIterator	(	void *	array,
		size_t	elem_size,
		size_t	elem_count,
		bool	remove_keeps_order )

Creates a mutating iterator for the specified plain array.

While the iterator is in use, the array may only be altered by removing elements through cxIteratorFlagRemoval(). Every other change to the array will bring this iterator to an undefined state.

When remove_keeps_order is set to false, removing an element will only move the last element to the position of the removed element, instead of moving all subsequent elements by one. Usually, when the order of elements is not important, this parameter should be set to false.

The array can be NULL in which case the iterator will be immediately initialized such that cxIteratorValid() returns false.

Parameters

array	a pointer to the array (can be NULL)
elem_size	the size of one array element
elem_count	the number of elements in the array
remove_keeps_order	true if the order of elements must be preserved when removing an element

Returns

an iterator for the specified array

cxMutIteratorPtr()

CxIterator cxMutIteratorPtr	(	void *	array,
		size_t	elem_count,
		bool	remove_keeps_order )

Creates a mutating iterator for the specified plain pointer array.

This is the mutating variant of cxIteratorPtr(). See also cxMutIterator().

Parameters

array	a pointer to the array (can be NULL)
elem_count	the number of elements in the array
remove_keeps_order	true if the order of elements must be preserved when removing an element

Returns

an iterator for the specified array

See also

cxMutIterator()

cxIteratorPtr()