Iterator

## Iterator Iterator — Iterate a sequence of objects across some other object. |

## Synopsis

    typedef     librdf_iterator;
    void*       (*librdf_iterator_map_handler)  (librdf_iterator *iterator,
                                                 void *map_context,
                                                 void *item);
    void        (*librdf_iterator_map_free_context_handler)
                                                (void *map_context);
    librdf_iterator* librdf_new_iterator        (librdf_world *world,
                                                 void *context,
                                                 int (*is_end_method) (void*),
                                                 int (*next_method) (void*),
                                                 void* (*get_method) (void*, int),
                                                 void (*finished_method) (void*));
    void        librdf_free_iterator            (librdf_iterator *iterator);
    int         librdf_iterator_end             (librdf_iterator *iterator);
    int         librdf_iterator_have_elements   (librdf_iterator *iterator);
    int         librdf_iterator_next            (librdf_iterator *iterator);
    void*       librdf_iterator_get_object      (librdf_iterator *iterator);
    void*       librdf_iterator_get_context     (librdf_iterator *iterator);
    void*       librdf_iterator_get_key         (librdf_iterator *iterator);
    void*       librdf_iterator_get_value       (librdf_iterator *iterator);
    int         librdf_iterator_add_map         (librdf_iterator *iterator,
                                                 librdf_iterator_map_handler map_function,
                                                 librdf_iterator_map_free_context_handler free_context,
                                                 void *map_context);
    librdf_iterator* librdf_new_empty_iterator  (librdf_world *world);

## Description

Provides a way to operate across a sequence of objects that are generated one-by-one on demand. The returned objects can be of any type but the main public methods are on the librdf_model classs and return sequence of librdf_node objects such as `librdf_model_get_sources()`.

## Details

### librdf_iterator

    typedef struct librdf_iterator_s librdf_iterator;

Redland iterator class.

### librdf_iterator_map_handler ()

    void*       (*librdf_iterator_map_handler)  (librdf_iterator *iterator,
                                                 void *map_context,
                                                 void *item);

Map function for a librdf_iterator map operation.

See `librdf_iterator_add_map()`.

`iterator` : | Iterator that this map is operating over.
`map_context` : | Map data context pointer.
`item` : | Pointer to the current item in the iteration.
Returns : | ; item in keep the iteration or NULL to remove it

### librdf_iterator_map_free_context_handler ()

    void        (*librdf_iterator_map_free_context_handler)
                                                (void *map_context);

Free handler function for a librdf_iterator map operation.

See `librdf_iterator_add_map()`.

`map_context` : | Map data context pointer.

### librdf_new_iterator ()

    librdf_iterator* librdf_new_iterator        (librdf_world *world,
                                                 void *context,
                                                 int (*is_end_method) (void*),
                                                 int (*next_method) (void*),
                                                 void* (*get_method) (void*, int),
                                                 void (*finished_method) (void*));

Constructor - create a new librdf_iterator object.

`world` : | redland world object
`context` : | context to pass to the iterator functions
`is_end_method` : | function to call to see if the iteration has ended
`next_method` : | function to get the next element
`get_method` : | function to get the next element
`finished_method` : | function to destroy the iterator context (or NULL if not needed)
Returns : | a new librdf_iterator object or NULL on failure

### librdf_free_iterator ()

    void        librdf_free_iterator            (librdf_iterator *iterator);

Destructor - destroy a librdf_iterator object.

`iterator` : | the librdf_iterator object

### librdf_iterator_end ()

    int         librdf_iterator_end             (librdf_iterator *iterator);

Test if the iterator has finished.

`iterator` : | the librdf_iterator object
Returns : | non 0 if the iterator has finished

### librdf_iterator_have_elements ()

    int         librdf_iterator_have_elements   (librdf_iterator *iterator);

Test if the iterator has finished.

DEPRECATED - use !librdf_iterator_end(iterator)

`iterator` : | the librdf_iterator object
Returns : | 0 if the iterator has finished

### librdf_iterator_next ()

    int         librdf_iterator_next            (librdf_iterator *iterator);

Move to the next iterator element.

`iterator` : | the librdf_iterator object
Returns : | non 0 if the iterator has finished

### librdf_iterator_get_object ()

    void*       librdf_iterator_get_object      (librdf_iterator *iterator);

Get the current object from the iterator.

This method returns a SHARED pointer to the current iterator object which should be copied by the caller to preserve it if the iterator is moved on librdf_iterator_next or if it should last after the iterator is closed.

`iterator` : | the librdf_iterator object
Returns : | The next element or NULL if the iterator has finished.

### librdf_iterator_get_context ()

    void*       librdf_iterator_get_context     (librdf_iterator *iterator);

Get the context of the current object on the iterator.

This method returns a SHARED pointer to the current context node object which should be copied by the caller to preserve it if the iterator is moved on librdf_iterator_next or if it should last after the iterator is closed.

`iterator` : | the librdf_iterator object
Returns : | The context or NULL if the iterator has finished.

### librdf_iterator_get_key ()

    void*       librdf_iterator_get_key         (librdf_iterator *iterator);

Get the key of the current object on the iterator.

`iterator` : | the librdf_iterator object
Returns : | The context or NULL if the iterator has finished.

### librdf_iterator_get_value ()

    void*       librdf_iterator_get_value       (librdf_iterator *iterator);

Get the value of the current object on the iterator.

`iterator` : | the librdf_iterator object
Returns : | The context or NULL if the iterator has finished.

### librdf_iterator_add_map ()

    int         librdf_iterator_add_map         (librdf_iterator *iterator,
                                                 librdf_iterator_map_handler map_function,
                                                 librdf_iterator_map_free_context_handler free_context,
                                                 void *map_context);

Add a librdf_iterator mapping function.

Adds an iterator mapping function which operates over the iterator to select which elements are returned; it will be applied as soon as this method is called.

Several mapping functions can be added and they are applied in the order given

The mapping function should return non 0 to allow the element to be returned.

`iterator` : | the iterator
`map_function` : | the function to operate
`free_context` : | the function to use to free the context (or NULL)
`map_context` : | the context to pass to the map function
Returns : | Non 0 on failure

### librdf_new_empty_iterator ()

    librdf_iterator* librdf_new_empty_iterator  (librdf_world *world);

Constructor - create a new librdf_iterator with no content.

`world` : | redland world object
Returns : | a new librdf_iterator object or NULL on failure