Stream of triples (#librdf_statement). 3 REDLAND Library
Stream of triples (#librdf_statement). Sequence of RDF Triples.

## Synopsis

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

### enum librdf_stream_get_method_flags

    typedef enum {
      LIBRDF_STREAM_GET_METHOD_GET_OBJECT = LIBRDF_ITERATOR_GET_METHOD_GET_OBJECT,
      LIBRDF_STREAM_GET_METHOD_GET_CONTEXT = LIBRDF_ITERATOR_GET_METHOD_GET_CONTEXT
    } librdf_stream_get_method_flags;

Flags for `librdf_new_stream()` get_method function pointer.

`LIBRDF_STREAM_GET_METHOD_GET_OBJECT`

  get object from iterator - implementing `librdf_stream_get_object()`

`LIBRDF_STREAM_GET_METHOD_GET_CONTEXT`

  get context from iterator - implementing `librdf_stream_get_context()`

librdf_stream_get_method_flags

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

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

### librdf_new_stream ()

    librdf_stream*      librdf_new_stream                   (librdf_world *world,
                                                             void *context,
                                                             int (is_end_methodvoid*) (),
                                                             int (next_methodvoid*) (),
                                                             void* (get_methodvoid*, int) (),
                                                             void (finished_methodvoid*) ());

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

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

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

### librdf_free_stream ()

    void                librdf_free_stream                  (librdf_stream *stream);

Destructor - destroy an libdf_stream object.

stream :

  librdf_stream object

librdf_free_stream

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

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

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

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

librdf_stream_get_context

### 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 the statement to return, or NULL to remove it from the stream.

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_add_map

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

librdf_stream_print

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