The Iterator Class
[The Classes]

The class to iterator over the containers. More...

Data Structures
struct	Cmaid_Iter
	The Iterator Class structure Do not manipulate the attributes directly. More...
Modules
	The Iterator Interface
Typedefs
typedef struct Cmaid_Iter	Cmaid_Iter
	Type definition of the Iterator Class.
Functions
CMAID_INLINE void	cmaid_iter_start (Cmaid_Iter *it)
	Move the iterator to the start.
CMAID_INLINE void *	cmaid_iter_iter_goto (Cmaid_Iter *it, const Cmaid_Iter *to_it)
	move the given iterator to the second iterator's place
CMAID_INLINE void *	cmaid_iter_index_goto (Cmaid_Iter *it, int index)
	move the iterator to the give position
CMAID_INLINE int	cmaid_iter_index_get (Cmaid_Iter *it)
	Retrieve the current index.
CMAID_INLINE Cmaid_Container *	cmaid_iter_container_get (Cmaid_Iter *it)
	Retrieve the parent container of the iterator.
CMAID_INLINE void *	cmaid_iter_current (Cmaid_Iter *it)
	Returns the data pointer of the current node.
CMAID_INLINE void *	cmaid_iter_next (Cmaid_Iter *it)
	Walks to the next node and returns its data pointer.
CMAID_INLINE void *	cmaid_iter_previous (Cmaid_Iter *it)
	Walks to the previous node and returns its data pointer.
CMAID_INLINE void	cmaid_iter_remove (Cmaid_Iter *it)
	Remove the current node.

---

Detailed Description

The class to iterator over the containers.

The iterator class forms the heart of Cmaid and makes Cmaid different to other abstract data type libraries. Like in any other data type library you can iterate with them over a container and remove objects from the container, but unlike in other implementations the iterator points still to a valid node if you remove an object, even if you did not removed it with the iterator itself.

Attaching and detaching the iterator

Before you can use the iterator you have to attach it to the container, you want to work with. The container will save a reference to the iterator so it can adjust the iterator after a node was removed or added. Keep in mind to always detach an iterator after the iterator is not be used any longer, for example if it is going to be out of scope.

Example:

 extern Cmaid_Container *c;
 Cmaid_Iter it;

 cmaid_container_iter_attach(c, &it);
 // work with the iterator
 cmaid_container_iter_detach(c, &it);

The circular concept of the iterators

The underlying concept of iterators is a circular list. You can figure this with having a empty node that links the beginning with the end. After the iterator was attached to a container or after calling cmaid_iter_start(), the iterator is pointing to this empty node. Calling cmaid_iter_current() will return NULL, because the node is empty, but calling cmaid_iter_next() will perform a step to the next node, i.e. the first node and returns it value. The same works for cmaid_iter_previous().

Example:

 cmaid_iter_start(&it); // "it" is pointing to the node before the first node
 cmaid_iter_next(&it);  // "it" points now to the first node, if the container
                        // is not empty
 while ((item = cmaid_iter_next(&it))
      printf("%s\n", item); // prints every string in the container except
                            // the first one
 // "it" is now pointing to the node before the first node again

---

Function Documentation

CMAID_INLINE Cmaid_Container* cmaid_iter_container_get

(

Cmaid_Iter *

it

)

Retrieve the parent container of the iterator.

Parameters:

it

The iterator to work with

Returns:

Return the parent container of the given iterator This function returns the parent container of the given iterator

CMAID_INLINE void* cmaid_iter_current

(

Cmaid_Iter *

it

)

Returns the data pointer of the current node.

Parameters:

it

The iterator to retrieve the current data

Returns:

Returns a pointer to the current data pointer This functions returns the data pointer of the current node. If the iterator does not point to a valid data node, i.e. the iterator is not attached to a container or the iterator is pointing to the start point, it will return NULL.

CMAID_INLINE int cmaid_iter_index_get

(

Cmaid_Iter *

it

)

Retrieve the current index.

Parameters:

it

the iterator to get the index

Returns:

the index of the node the iterator is pointing to This function will return the current pointer position.

CMAID_INLINE void* cmaid_iter_index_goto	(	Cmaid_Iter *	it,
		int	index
	)

move the iterator to the give position

Parameters:

	it	the iterator to move
	index	the new position of the iterator

CMAID_INLINE void* cmaid_iter_iter_goto	(	Cmaid_Iter *	it,
		const Cmaid_Iter *	to_it
	)

move the given iterator to the second iterator's place

Parameters:

	it	the iter to move
	to_it	the new position for the iterator This function moves the given iterator to the same position like the given iterator has. This will fail if the iterators are for different containers.

CMAID_INLINE void* cmaid_iter_next

(

Cmaid_Iter *

it

)

Walks to the next node and returns its data pointer.

Parameters:

it

The iterator to retrieve the next data

Returns:

Returns a pointer to the next data pointer This function call will move the iterator to the next item inside of the container and return the data pointer of it. If the iterator is pointing to the virtual start node it will go to the first node in the container. If it is pointing to the last node of the container it will go back to the virtual start node and returns NULL.

CMAID_INLINE void* cmaid_iter_previous

(

Cmaid_Iter *

it

)

Walks to the previous node and returns its data pointer.

Parameters:

it

The iterator to retrieve the previous data

Returns:

Returns a pointer to the previous data pointer This function call will move the iterator to the previous item inside of the container and return the data pointer of it. If the iterator is pointing to the virtual start node it will go to the last node in the container. If it is pointing to the first node of the container it will go back to the virtual start node and returns NULL.

CMAID_INLINE void cmaid_iter_remove

(

Cmaid_Iter *

it

)

Remove the current node.

Parameters:

it

The iterator to removoe the current node

Returns:

Returns no value This function will remove the current node and perform a step backwards. So if you are calling next you will land on the same node as if you hadn't remove the selected node.

CMAID_INLINE void cmaid_iter_start

(

Cmaid_Iter *

it

)

Move the iterator to the start.

Parameters:

it

the iterator to move

Returns:

Returns no value Move the iterator to the start. The start is a virtual item quite before the first node and quite after the last node. This is normal the place where you start to iterate