Stream of triples (#librdf_statement).

## Stream of triples (#librdf_statement). Stream of triples (#librdf_statement). — Sequence of RDF Triples. |

## Synopsis

    typedef     librdf_stream;
    librdf_statement* (*librdf_stream_map_handler)
                                                (librdf_stream *stream,
                                                 void *map_context,
                                                 librdf_statement *item);
    void        (*librdf_stream_map_free_context_handler)
                                                (void *map_context);
    librdf_stream* librdf_new_stream            (librdf_world *world,
                                                 void *context,
                                                 int (*is_end_method) (void*),
                                                 int (*next_method) (void*),
                                                 void* (*get_method) (void*, int),
                                                 void (*finished_method) (void*));
    librdf_stream* librdf_new_stream_from_node_iterator
                                                (librdf_iterator *iterator,
                                                 librdf_statement *statement,
                                                 librdf_statement_part field);
    librdf_stream* librdf_new_empty_stream      (librdf_world *world);
    void        librdf_free_stream              (librdf_stream *stream);
    int         librdf_stream_end               (librdf_stream *stream);
    int         librdf_stream_next              (librdf_stream *stream);
    librdf_statement* librdf_stream_get_object  (librdf_stream *stream);
    void*       librdf_stream_get_context       (librdf_stream *stream);
    int         librdf_stream_add_map           (librdf_stream *stream,
                                                 librdf_stream_map_handler map_function,
                                                 librdf_stream_map_free_context_handler free_context,
                                                 void *map_context);
    void        librdf_stream_print             (librdf_stream *stream,
                                                 FILE *fh);

## Description

Iterate a sequence of RDF triples from some object.

## Details

### librdf_stream

    typedef struct librdf_stream_s librdf_stream;

Redland stream class.

### librdf_stream_map_handler ()

    librdf_statement* (*librdf_stream_map_handler)
                                                (librdf_stream *stream,
                                                 void *map_context,
                                                 librdf_statement *item);

Map function for a librdf_stream map operation.

See `librdf_stream_add_map()`.

`stream` : | Stream 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_stream_map_free_context_handler ()

    void        (*librdf_stream_map_free_context_handler)
                                                (void *map_context);

Free handler function for a librdf_stream map operation.

See `librdf_stream_add_map()`.

`map_context` : | Map data context pointer.

### librdf_new_stream ()

    librdf_stream* librdf_new_stream            (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_stream.

Creates a new stream with an implementation based on the passed in functions. The functions next_statement and end_of_stream will be called multiple times until either of them signify the end of stream by returning NULL or non 0 respectively. The finished function is called once only when the stream object is destroyed with `librdf_free_stream()`

A mapping function can be set for the stream using `librdf_stream_add_map()` function which allows the statements generated by the stream to be filtered and/or altered as they are generated before passing back to the user.

`world` : | redland world object
`context` : | context to pass to the stream implementing objects
`is_end_method` : | pointer to function to test for end of stream
`next_method` : | pointer to function to move to the next statement in stream
`get_method` : | pointer to function to get the current statement
`finished_method` : | pointer to function to finish the stream.
Returns : | a new librdf_stream object or NULL on failure

### librdf_new_stream_from_node_iterator ()

    librdf_stream* librdf_new_stream_from_node_iterator
                                                (librdf_iterator *iterator,
                                                 librdf_statement *statement,
                                                 librdf_statement_part field);

Constructor - create a new librdf_stream from an iterator of nodes.

Creates a new librdf_stream using the passed in librdf_iterator which generates a series of librdf_node objects. The resulting nodes are then inserted into the given statement and returned. The field attribute indicates which statement node is being generated.

`iterator` : | librdf_iterator of librdf_node objects
`statement` : | librdf_statement prototype with one NULL node space
`field` : | node part of statement
Returns : | a new librdf_stream object or NULL on failure

### librdf_new_empty_stream ()

    librdf_stream* librdf_new_empty_stream      (librdf_world *world);

Constructor - create a new librdf_stream with no content.

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

### librdf_free_stream ()

    void        librdf_free_stream              (librdf_stream *stream);

Destructor - destroy an libdf_stream object.

`stream` : | librdf_stream object

### librdf_stream_end ()

    int         librdf_stream_end               (librdf_stream *stream);

Test if the stream has ended.

`stream` : | librdf_stream object
Returns : | non 0 at end of stream.

### librdf_stream_next ()

    int         librdf_stream_next              (librdf_stream *stream);

Move to the next librdf_statement in the stream.

`stream` : | librdf_stream object
Returns : | non 0 if the stream has finished

### librdf_stream_get_object ()

    librdf_statement* librdf_stream_get_object  (librdf_stream *stream);

Get the current librdf_statement in the stream.

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

`stream` : | librdf_stream object
Returns : | the current librdf_statement object or NULL at end of stream.

### librdf_stream_get_context ()

    void*       librdf_stream_get_context       (librdf_stream *stream);

Get the context of the current object on the stream.

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

`stream` : | the librdf_stream object
Returns : | The context node or NULL if the stream has finished.

### librdf_stream_add_map ()

    int         librdf_stream_add_map           (librdf_stream *stream,
                                                 librdf_stream_map_handler map_function,
                                                 librdf_stream_map_free_context_handler free_context,
                                                 void *map_context);

Add a librdf_stream mapping function.

Adds an stream mapping function which operates over the stream 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.

`stream` : | the stream
`map_function` : | the function to perform the mapping
`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_stream_print ()

    void        librdf_stream_print             (librdf_stream *stream,
                                                 FILE *fh);

Print the stream.

This prints the remaining statements of the stream to the given file handle. Note that after this method is called the stream will be empty so that `librdf_stream_end()` will always be true and `librdf_stream_next()` will always return NULL. The only useful operation is to dispose of the stream with the `librdf_free_stream()` destructor.

This method is for debugging and the format of the output should not be relied on.

`stream` : | the stream object
`fh` : | the FILE stream to print to

## See Also

Provides a way to operate across a sequence of RDF Triples that are generated one-by-one on demand. The generated triples can be from some API call in the librdf_model class, from listing a graph content as individual triples, from parsing a syntax or returning an RDF graph result from a query. Streams can be passed into methods for the reverse operations such as adding to a graph, serializing a graph to a syntax. Streams pass individual triples (librdf_statement) between objects and are usually lazily generated and consumed.