## Iterator

Iterator — An interface to iterate over the key/value pairs in an initiated object.

## Functions

#define | LT_ITER_INIT()
lt_iter_t * | lt_iter_ref ()
void | lt_iter_unref ()
lt_iter_t * | lt_iter_init ()
void | lt_iter_finish ()
lt_bool_t | lt_iter_next ()

## Types and Values

| lt_iter_t
| lt_iter_tmpl_t

## Description

This class provides a common interface to iterate over the key/value pairs in an initiated object.

## Functions

### LT_ITER_INIT()

    #define LT_ITER_INIT(_obj_) lt_iter_init((lt_iter_tmpl_t *)(_obj_))

This is a convenient macro to call `lt_iter_init()`.

#### Parameters

_obj_ | an object that initialize the iterator with. |

#### Returns

a lt_iter_t.

[transfer full]

### lt_iter_ref ()

    lt_iter_t *
    lt_iter_ref (lt_iter_t *iter);

Increases the reference count of `iter` .

#### Parameters

iter | a lt_iter_t |

#### Returns

the same `iter` object.

[transfer none]

### lt_iter_unref ()

    void
    lt_iter_unref (lt_iter_t *iter);

Decreases the reference count of `iter` . when its reference count drops to 0, the object is finalized (i.e. its memory is freed).

#### Parameters

iter | a lt_iter_t |

### lt_iter_init ()

    lt_iter_t *
    lt_iter_init (lt_iter_tmpl_t *tmpl);

Initialize the iterator with `tmpl` object. this function has to be called before performing any opperation with the iterator and `lt_iter_finish()` when the iterator isn't needed anymore.

    1
    2
    3
    4
    5
    6
    7
    8
    9

    lt_lang_db *lang = lt_lang_db_new();
    lt_pointer_t *key, *val;
    lt_iter_t *iter;

    iter = LT_ITER_INIT (lang);
    while (lt_iter_next(iter, &key, &val)) {
      /* do something with key and value */
    }
    lt_iter_finish(iter);

#### Parameters

tmpl | a lt_iter_tmpl_t |

#### Returns

the initialized iterator object.

[transfer none]

### lt_iter_finish ()

    void
    lt_iter_finish (lt_iter_t *iter);

Finalize the iterator and free its memory.

#### Parameters

iter | a lt_iter_t |

### lt_iter_next ()

    lt_bool_t
    lt_iter_next (lt_iter_t *iter,
                  lt_pointer_t *key,
                  lt_pointer_t *val);

Advances `iter` and retrieves the key and/or value that are now pointed to as a result of this advancement. If `FALSE` is returned, `key` and `value` are not set, and the iterator becomes invalid.

#### Parameters

iter | a lt_iter_t |
key | a location to store the key, or `NULL`. | [allow-none]
val | a location to store the value, or `NULL`. | [allow-none]

#### Returns

`FALSE` if the end of the object that the iterator is adapted has been reached.

## Types and Values

### lt_iter_t

    typedef struct _lt_iter_t lt_iter_t;

All the fields in the lt_iter_t structure are private to the lt_iter_t implementation.

### lt_iter_tmpl_t

    typedef struct _lt_iter_tmpl_t lt_iter_tmpl_t;

All the fields in the lt_iter_tmpl_t structure are private to the lt_iter_tmpl_t implementation.