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

## Functions

void * | (*librdf_iterator_map_handler) ()
void | (*librdf_iterator_map_free_context_handler) ()
librdf_iterator * | librdf_new_iterator ()
void | librdf_free_iterator ()
int | librdf_iterator_end ()
int | librdf_iterator_have_elements ()
int | librdf_iterator_next ()
void * | librdf_iterator_get_object ()
void * | librdf_iterator_get_context ()
void * | librdf_iterator_get_key ()
void * | librdf_iterator_get_value ()
int | librdf_iterator_add_map ()
librdf_iterator * | librdf_new_empty_iterator ()

## Types and Values

typedef | librdf_iterator
enum | librdf_iterator_get_method_flags

## 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()`.

## Functions

### 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()`.

#### Parameters

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()`.

#### Parameters

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

#### Parameters

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.

#### Parameters

iterator | the librdf_iterator object |

### librdf_iterator_end ()

    int
    librdf_iterator_end (librdf_iterator *iterator);

Test if the iterator has finished.

#### Parameters

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);

`librdf_iterator_have_elements` is deprecated and should not be used in newly-written code.

Test if the iterator has finished.

DEPRECATED - use !librdf_iterator_end(iterator)

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

iterator | the librdf_iterator object |

#### Returns

The context (can be NULL) 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

world | redland world object |

#### Returns

a new librdf_iterator object or NULL on failure

## Types and Values

### librdf_iterator

    typedef struct librdf_iterator_s librdf_iterator;

Redland iterator class.

### enum librdf_iterator_get_method_flags

Flags for `librdf_new_iterator()` get_method function pointer.

#### Members

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()` |