Iterators

Iterators concept is the same provided by Java. More...

Typedefs
typedef struct diter	diter_t
	Opaque type for iterators.
Functions
int	diter_hasnext (diter_t *i)
	Has-Next predicate, checks if the iterator has at least another element.
void *	diter_next (diter_t *i)
	Get-Next function, extracts the next element of the iteration.
void	diter_remove (diter_t *i)
	Remove function, removes from the structure the current element.
void	diter_replace (diter_t *i, void *n)
	Replace function, replaces the current element of the structure.

---

Detailed Description

Iterators concept is the same provided by Java.

Every container structure declared in libdacav is provided with a dedicated iterator constructor and a dedicated iterator destructor, while functions that allows to iterate among elements are of general use.

By example, for the dlist_t data type, libdacav provides the dlist_iter_new and the dlist_free functions, while for dhash_t the dhash_iter_new and the dhash_iter_free functions are provided.

After allocating an iterator with the correct primitive (depending on which data structure you are working with), the iteration process is something like:

while (diter_hasnext(my_iterator)) {
    do_something(diter_next(my_iterator));
}
 

Allowed operations:

Once the iterator is allocated, the iterator user can access to the diter_hasnext, diter_next, diter_remove and diter_replace primitive.

The first two are always implemented, since they are somehow mandatory. The diter_remove and diter_replace ones, instead, can be left unimplemented by design. Requiring a diter_remove or a diter_replace operation on an iterator for which they are not implemented doesn't produce any consequence.

Internal use primitive:

Apart from the functions listed above, the library provides some additional primitives that can be used to implement a similar iteration semantics.

See also:

Functions for Iterators

---

Typedef Documentation

typedef struct diter diter_t

Opaque type for iterators.

Constructors and destructors for this type are strictly dependent from the kind of iterator used. Every type of container implements them and gives them an appropriate name.

See also:

dhash_iter_new is an example of iterator constructor;

dhash_iter_free is an example of iterator destructor.

---

Function Documentation

int diter_hasnext

(

diter_t *

i

)

Has-Next predicate, checks if the iterator has at least another element.

Warning:

Iterator semantics requires this function to be called after and before every use of diter_next(). A wrong usage with respect to iterator semantics may lead to an inconsistent state depending on the specific implementation.

Parameters:

[in]

i

The iterator.

Return values:

1	if there's at least another element to iterate on;
0	otherwise.

void* diter_next

(

diter_t *

i

)

Get-Next function, extracts the next element of the iteration.

Warning:

Iterator semantics requires this function to be called after checking the presence of the element thorugh the diter_hasnext() predicate. A wrong usage with respect to iterator semantics may lead to an inconsistent state depending on the specific implementation.

Parameters:

[in]

i

The iterator.

Returns:

The next element, which must exist.

void diter_remove

(

diter_t *

i

)

Remove function, removes from the structure the current element.

The removed element is deallocated according to a user-provided semantics which is part of the container.

See also:

dcprm_t.

Warning:

Iterator semantics requires this function to be called only after checking the presence of the element thorugh the diter_hasnext() predicate. Calling diter_next() before diter_remove() doesn't affect the behaviour. A wrong usage with respect to iterator semantics may lead to an inconsistent state depending on the specific implementation.

Note:

Implementation of a remove function is not mandatory. If the data structure which provides the iterator is not implementing it, calling diter_remove() has no effect. Please refer to the documentation of the container you are iterating on.

Parameters:

[in]

i

The iterator.

void diter_replace	(	diter_t *	i,
		void *	n
	)

Replace function, replaces the current element of the structure.

Warning:

Iterator semantics requires this function to be called only after checking the presence of the element thorugh the diter_hasnext() predicate. Calling diter_next() before diter_remove() doesn't affect the behaviour. A wrong usage with respect to iterator semantics may lead to an inconsistent state depending on the specific implementation.

Note:

Implementation of a remove function is not mandatory. If the data structure which provides the iterator is not implementing it, calling diter_remove() has no effect.

Parameters:

[in]	i	The iterator;
[in]	n	The new element that will replace the next element.