Iterators
=========

For most listing operations, libtio makes use of iterators.

Iterators are basic objects that concentrate on bringing you the next element
of a listing operation. Instead of having all elements at once, you get one
element at the time, and need to save it if you want to create a list.

Using iterators
---------------

An iterator in libtio uses the following type:

.. type:: tio_iter_t

	An iterator (as a private structure).

To get the next element on an iterator, you can use the following function:

.. c:function:: int tio_next(tio_iter_t *iter, void **ptr)

	Get the next element on an iterator, which will only be valid until you
	call :c:func:`tio_next` again or :c:func:`tio_end`.

An alias is usually defined for each iterator type, e.g.
:c:func:`tio_next_log` for getting the next log level as a
:type:`char const *`.

This function returns either:

- :macro:`tio_ok` if the gathering has succeeded.
- :macro:`tio_error_iter` if there is no next element (end of iterator).
- another error if the error doesn't come from the iterator itself, but from
  what is behind.

When you're done using the iterator, you must free it using the following
function:

.. c:function:: void tio_end(tio_iter_t *iter)

	Frees an iterator and any linked data.