CIIterator Struct Reference

#include <CIIterator.h>

Inheritance diagram for CIIterator:

Public Member Functions
CBool	CIIterator_HasNext (struct CIIterator *self)
void	CIIterator_Next (struct CIIterator *self, void *element)
CBool	CIIterator_HasPrevious (struct CIIterator *self)
void	CIIterator_Previous (struct CIIterator *self, void *element)
CBool	CIIterator_Set (struct CIIterator *self, void *element)
CBool	CIIterator_Remove (struct CIIterator *self)
size_t	CIIterator_Index (struct CIIterator *self)

Data Fields
struct CInterface	interface

Detailed Description

Defines an interface for traversing collections of data and modifying the list while traversing. An interator always starts with its cursor positioned before the first index in a collection. Calls to CIIterator_Next() and CIIterator_Previous() move the cursor through the collection one element at a time. Empty elements in the collection are skipped. After a call to CIIterator_Next() or CIIterator_Previous(), the cursor is put between the two elements. For example:

  element 0     element 1     element 2     element 3     ...     element n-1
^            ^             ^             ^             ^       ^               ^

'^' are the possible cursor positions.
Below is an example of using an iterator with the CIList structure. Note, this example assumes the iterator passed into the function has elements that are ascii strings. Since the iterator structure is copy by value, it's very important to know how large the iterator's elements are when iterating over them.

void printListElements( struct CIIterator* iter, size_t element_size ) 
{
    char* element = malloc(element_size);
    while( CIIterator_HasNext(iter) ) {
        CIIterator_Next(iter, element);
        printf("Got element: %.*s\n", element_size, element);
    }
}

Member Function Documentation

CBool CIIterator_HasNext

(

struct CIIterator *

self

)

Evaluates if there is a next element in the collection. If this returns a logical true, then CIIterator_Next() will get the next element in the collection.

Parameters

self	The iterator.

Returns

• logical true (1): CIIterator_Next() will get another element in the collection.
• logical false (0): At the end of the list. CIIterator_Next() will get nothing.

CBool CIIterator_HasPrevious

(

struct CIIterator *

self

)

Evaluates if there is a previous element in the collection. If this returns a logical true, then CIIterator_Previous() will get the previous element in the collection.

Parameters

self	The iterator.

Returns

• logical true (1): CIIterator_Previous() will get another element in the collection.
• logical false (0): At the end of the collection. CIIterator_Previous() will get nothing.

size_t CIIterator_Index

(

struct CIIterator *

self

)

Gets the index of the element in the collection last returned by a call to CIIterator_Next() or CIIterator_Previous(). If no call to those methods has been made yet, this does nothing and returns zero. Note, zero can be a valid index, so a returned value of zero is not an error code.

Parameters

self	The iterator.

Returns

The index in the collection of the last element returned by a call to CIIterator_Next() or CIIterator_Previous().

void CIIterator_Next	(	struct CIIterator *	self,
		void *	element
	)

Gets the next element in the collection. If CIIterator_HasNext() returns a logical true, then this function will get a valid element. If CIIterator_HasNext() returned a logical false, then this function does nothing. This does not happen because of the call to CIIterator_HasNext(), CIIterator_HasNext() will only tell the application how this method is going to behave.

Parameters

self	The iterator
element	The next element in the collection will be copied to the the memory pointed to by this.

void CIIterator_Previous	(	struct CIIterator *	self,
		void *	element
	)

Gets the previous element in the collection. If CIIterator_HasPrevious() returns a logical true, then this function will get a valid element. If CIIterator_HasPrevious() returned a logical false, then this function does nothing.

Parameters

self	The iterator
element	The previous element in the collection will be copied to the the memory pointed to by this.

CBool CIIterator_Remove

(

struct CIIterator *

self

)

Removes the element in the collection last returned by a call to CIIterator_Next() or CIIterator_Previous(). If no call to those methods has been made yet, then this does nothing and returns a logical false.

Parameters

self	The iterator.

Returns

• locical true (1): The element in the collection was remove.
• logical false (0): Could not remove an element because no call to CIIterator_Next() or CIIterator_Previous() has been made.

CBool CIIterator_Set	(	struct CIIterator *	self,
		void *	element
	)

Sets the element in the collection last returned by a call to CIIterator_Next() or CIIterator_Previous(). If no call to those methods has been made yet, then this does nothing and returns a logical false.

Parameters

self	The iterator.
element	Memory pointed to will be copied into the collection

Returns

• locical true (1): The element in the collection was set.
• logical false (0): Could not set the element because no call to CIIterator_Next() or CIIterator_Previous() has been made.

---

The documentation for this struct was generated from the following file:

• liba/util/CIIterator.h