Iterator 3 REDLAND Library
Iterator Iterate a sequence of objects across some other object.

## Synopsis

    typedef             librdf_iterator;
    enum                librdf_iterator_get_method_flags;
    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_methodvoid*) (),
                                                             int (next_methodvoid*) (),
                                                             void* (get_methodvoid*, int) (),
                                                             void (finished_methodvoid*) ());
    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

### enum librdf_iterator_get_method_flags

    typedef enum {
      LIBRDF_ITERATOR_GET_METHOD_GET_OBJECT  = 0,
      LIBRDF_ITERATOR_GET_METHOD_GET_CONTEXT = 1,
      LIBRDF_ITERATOR_GET_METHOD_GET_KEY     = 2,
      LIBRDF_ITERATOR_GET_METHOD_GET_VALUE   = 3
    } librdf_iterator_get_method_flags;

Flags for `librdf_new_iterator()` get_method function pointer.

`LIBRDF_ITERATOR_GET_METHOD_GET_OBJECT`

  get object from iterator - implementing `librdf_iterator_get_context()`

`LIBRDF_ITERATOR_GET_METHOD_GET_CONTEXT`

  get context from iterator - implementing `librdf_iterator_get_object()`

`LIBRDF_ITERATOR_GET_METHOD_GET_KEY`

  get iterator key object from iterator - implementing `librdf_iterator_get_key()`

`LIBRDF_ITERATOR_GET_METHOD_GET_VALUE`

  get iterator value from iterator - implementing `librdf_iterator_get_value()`

librdf_iterator_get_method_flags

### 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_handler

### 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_iterator_map_free_context_handler

### librdf_new_iterator ()

    librdf_iterator*    librdf_new_iterator                 (librdf_world *world,
                                                             void *context,
                                                             int (is_end_methodvoid*) (),
                                                             int (next_methodvoid*) (),
                                                             void* (get_methodvoid*, int) (),
                                                             void (finished_methodvoid*) ());

Constructor - create a new librdf_iterator object. The iterator object takes ownership of context and frees it with finished_method. The finished method is not called if librdf_new_iterator fails and returns NULL.

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_new_iterator

### librdf_free_iterator ()

    void                librdf_free_iterator                (librdf_iterator *iterator);

Destructor - destroy a librdf_iterator object.

iterator :

  the librdf_iterator object

librdf_free_iterator

### 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_end

### 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_have_elements

### 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_next

### 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_object

### 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 (can be NULL) or NULL if the iterator has finished.

librdf_iterator_get_context

### 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_key

### 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_get_value

### 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_iterator_add_map

### 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

librdf_new_empty_iterator