Functions for Iterators

Apart from the diter_hasnext(), diter_next(), diter_remove() and diter_replace() functions, the library provides some additional primitives that can be used to implement a similar iteration semantics. More...

Typedefs
typedef int(*	dhasnext_t )(void *iterable)
	Type defining the Has-Next function for iterators.
typedef void *(*	dnext_t )(void *iterable)
	Type defining the Next function for iterators.
typedef void(*	dremove_t )(void *iterable)
	Type defining the Remove function for iterators.
typedef void(*	dreplace_t )(void *iterable, void *new_val)
	Type defining the Replace function for iterators.
Functions
diter_t *	diter_new (dnext_t nx, dhasnext_t hnx, dremove_t rm, dreplace_t rep, unsigned iterable_size)
	Raw constructor for iterator.
void *	diter_get_iterable (diter_t *i)
	Getter for the iterable structure.
void	diter_free (diter_t *it)
	Destructor for the raw iterator.

---

Detailed Description

Apart from the diter_hasnext(), diter_next(), diter_remove() and diter_replace() functions, the library provides some additional primitives that can be used to implement a similar iteration semantics.

These primitive are diter_new(), diter_free() and diter_get_iterable(). They are meant to be used by an iterator provider. The first two respectively allocate and deallocate a raw iterator, while the third one can be used to retrieve a pointer to the iterator's reserved memory area. Confused? The following example will make it clear.

Usage example:

Basing on the data structure you are writing, a different kind of information may be needed in order to build. The dlist_t implementation, for instance, requires the following internal structure:

struct iterable {
    dlist_t *first;
    dlist_t *cursor;
    dlist_t **list;
};
 

The iterator functions are provided as private (static) procedures, which are used as callback by the generic iterator implementation:

static
int iter_hasnext (struct iterable *it)
{
    ...
}

static
void *iter_next (struct iterable *it)
{
    ...
}

static
void iter_remove (struct iterable *it, dfree_cb_t f)
{
    ...
}

static
void iter_replace (struct iterable *it, void *new_val)
{
    ...
}
 

The allocation phase requires the construction of a raw iterator, which is parametrized with the dlist_t specific iteration functions. The fifth parameter of diter_new gives the auxiliary memory used by the specific iterator implementation, while the diter_get_iterable function will return a pointer to the memory zone itself:

diter_t *dlist_iter_new (dlist_t **l)
{
    diter_t *ret = diter_new((dnext_t)iter_next, (dhasnext_t)iter_hasnext,
                             (dremove_t)iter_remove,
                             (dreplace_t)iter_replace,
                             sizeof(struct iterable));
    struct iterable *it = diter_get_iterable(ret);
    it->cursor = it->first = *l;
    it->list = l;
    return ret;
}
 

---

Typedef Documentation

typedef int(* dhasnext_t)(void *iterable)

Type defining the Has-Next function for iterators.

This type is used by the container internals, that must provide such a function to the iterator building procedure.

Parameters:

[in]

iterable

This parameter strictly depends on the interator implementation. It typically contains some data used by the iterating process.

Return values:

1	if the iterator has more elements;
0	if the iterator has no more elements.

See also:

Functions for Iterators.

typedef void*(* dnext_t)(void *iterable)

Type defining the Next function for iterators.

Note:

This type is used by the container internals, that must provide such a function to the iterator building procedure. If you are just using the library, you probably will never care about this data type.

Parameters:

[in]

iterable

This parameter strictly depends on the interator implementation. It typically contains some data used by the iterating process.

Returns:

The next value of the iterator.

See also:

Functions for Iterators.

typedef void(* dremove_t)(void *iterable)

Type defining the Remove function for iterators.

Note:

This type is used by the container internals, that must provide such a function to the iterator building procedure. If you are just using the library, you probably will never care about this data type.

Parameters:

[in]

iterable

This parameter strictly depends on the interator implementation. It typically contains some data used by the iterating process;

See also:

Functions for Iterators.

typedef void(* dreplace_t)(void *iterable, void *new_val)

Type defining the Replace function for iterators.

Note:

This type is used by the container internals, that must provide such a function to the iterator building procedure. If you are just using the library, you probably will never care about this data type.

Parameters:

[in]	iterable	This parameter strictly depends on the interator implementation. It typically contains some data used by the iterating process;
[in]	new_val	This parameter corresponds to the replacement for the element, and it's provided by the user through the diter_replace procedure.

See also:

Functions for Iterators.

---

Function Documentation

void diter_free

(

diter_t *

it

)

Destructor for the raw iterator.

Typically called after freeing the 'iterable' structure elements, if any.

Note:

This function is used by the container internals. If you are just using the library, you probably will never care about this data type.

Parameters:

[in]

it

The iterator to be freed.

See also:

Functions for Iterators

void* diter_get_iterable

(

diter_t *

i

)

Getter for the iterable structure.

Note:

This function is used by the container internals. If you are just using the library, you probably will never care about this data type.

Given a raw iterator, this function returns the address of the memory area reserved for 'iterable' structure data.

Parameters:

[in]

i

The raw iterator.

Returns:

The allocated area to be initialized.

See also:

Functions for Iterators.

diter_t* diter_new	(	dnext_t	nx,
		dhasnext_t	hnx,
		dremove_t	rm,
		dreplace_t	rep,
		unsigned	iterable_size
	)

Raw constructor for iterator.

Note:

This function is used by the container internals. If you are just using the library, you probably will never care about this data type.

Parameters:

[in]	nx	The counterpart of the Next function of an iterator;
[in]	hnx	The counterpart of the Has-Next function of an iterator;
[in]	rm	The counterpart of the Remove function of an iterator;
[in]	rep	The counterpart of the Replace function of an iterator;
[in]	iterable_size	The size of the iterable structure, which strictly depends on the internal implementation of an iterator.

Returns:

The raw iterator, whose iterable zone must be initialized.

See also:

Functions for Iterators.