I/O Stream

## I/O Stream I/O Stream — Providing streaming I/O writing to files, strings or user code. |

## Synopsis

    typedef     raptor_iostream;
    int         (*raptor_iostream_init_func)    (void *context);
    void        (*raptor_iostream_finish_func)  (void *context);
    int         (*raptor_iostream_write_byte_func)
                                                (void *context,
                                                 const int byte);
    int         (*raptor_iostream_write_bytes_func)
                                                (void *context,
                                                 const void *ptr,
                                                 size_t size,
                                                 size_t nmemb);
    void        (*raptor_iostream_write_end_func)
                                                (void *context);
                raptor_iostream_handler;
    raptor_iostream* raptor_new_iostream_from_handler
                                                (void *context,
                                                 const raptor_iostream_handler *handler);
    raptor_iostream* raptor_new_iostream_to_sink
                                                (void);
    raptor_iostream* raptor_new_iostream_to_filename
                                                (const char *filename);
    raptor_iostream* raptor_new_iostream_to_file_handle
                                                (FILE *handle);
    raptor_iostream* raptor_new_iostream_to_string
                                                (void **string_p,
                                                 size_t *length_p,
                                                 void* (*malloc_handler) (size_t size));
    void        raptor_free_iostream            (raptor_iostream *iostr);
    int         raptor_iostream_write_bytes     (raptor_iostream *iostr,
                                                 const void *ptr,
                                                 size_t size,
                                                 size_t nmemb);
    int         raptor_iostream_write_byte      (raptor_iostream *iostr,
                                                 const int byte);
    void        raptor_iostream_write_end       (raptor_iostream *iostr);
    int         raptor_iostream_write_string    (raptor_iostream *iostr,
                                                 const void *string);
    int         raptor_iostream_write_counted_string
                                                (raptor_iostream *iostr,
                                                 const void *string,
                                                 size_t len);
    size_t      raptor_iostream_get_bytes_written_count
                                                (raptor_iostream *iostr);
    int         raptor_iostream_write_decimal   (raptor_iostream *iostr,
                                                 int integer);
    int         raptor_iostream_format_hexadecimal
                                                (raptor_iostream *iostr,
                                                 unsigned int integer,
                                                 int width);
    int         raptor_iostream_write_stringbuffer
                                                (raptor_iostream *iostr,
                                                 raptor_stringbuffer *sb);
    int         raptor_iostream_write_string_ntriples
                                                (raptor_iostream *iostr,
                                                 unsigned char *string,
                                                 size_t len,
                                                 const char delim);
    void        raptor_iostream_write_statement_ntriples
                                                (raptor_iostream *iostr,
                                                 const raptor_statement *statement);

## Description

An class providing an I/O writer abstraction that allows generating output that can be stored or passed on to system files, strings allocated in memory (usually via raptor_stringbuffer), system file handles (`FILE*`) or to a user function.

## Details

### raptor_iostream

    raptor_iostream* raptor_iostream;

Raptor I/O Stream class

### raptor_iostream_init_func ()

    int         (*raptor_iostream_init_func)    (void *context);

Handler function for raptor_iostream initialising.

`context` : | stream context data
Returns : | non-0 on failure.

### raptor_iostream_finish_func ()

    void        (*raptor_iostream_finish_func)  (void *context);

Handler function for raptor_iostream terminating.

`context` : | stream context data

### raptor_iostream_write_byte_func ()

    int         (*raptor_iostream_write_byte_func)
                                                (void *context,
                                                 const int byte);

Handler function for implementing `raptor_iostream_write_byte()`.

`context` : | stream context data
`byte` : | byte to write
Returns : | non-0 on failure.

### raptor_iostream_write_bytes_func ()

    int         (*raptor_iostream_write_bytes_func)
                                                (void *context,
                                                 const void *ptr,
                                                 size_t size,
                                                 size_t nmemb);

Handler function for implementing `raptor_iostream_write_bytes()`.

`context` : | stream context data
`ptr` : | pointer to bytes to write
`size` : | size of item
`nmemb` : | number of items
Returns : | non-0 on failure.

### raptor_iostream_write_end_func ()

    void        (*raptor_iostream_write_end_func)
                                                (void *context);

Handler function for implementing `raptor_iostream_write_end()`.

`context` : | stream context data

### raptor_iostream_handler

    typedef struct {
      raptor_iostream_init_func         init;
      raptor_iostream_finish_func       finish;
      raptor_iostream_write_byte_func   write_byte;
      raptor_iostream_write_bytes_func  write_bytes;
      raptor_iostream_write_end_func    write_end;
    } raptor_iostream_handler;

I/O stream implementation handler structure.

raptor_iostream_init_func `init`; | initialisation handler - optional, called at most once
raptor_iostream_finish_func `finish`; | finishing handler - optional, called at most once
raptor_iostream_write_byte_func `write_byte`; | write byte handler - required
raptor_iostream_write_bytes_func `write_bytes`; | write bytes handler - required
raptor_iostream_write_end_func `write_end`; | write end handler - optional, called at most once

### raptor_new_iostream_from_handler ()

    raptor_iostream* raptor_new_iostream_from_handler
                                                (void *context,
                                                 const raptor_iostream_handler *handler);

Create a new iostream over a user-defined handler.

`context` : | pointer to context information to pass in to calls
`handler` : | pointer to handler methods
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_to_sink ()

    raptor_iostream* raptor_new_iostream_to_sink
                                                (void);

Create a new iostream to a sink.

Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_to_filename ()

    raptor_iostream* raptor_new_iostream_to_filename
                                                (const char *filename);

Constructor - create a new iostream writing to a filename.

`filename` : | Output filename to open and write to
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_to_file_handle ()

    raptor_iostream* raptor_new_iostream_to_file_handle
                                                (FILE *handle);

Constructor - create a new iostream writing to a FILE*.

The `handle` must already be open for writing. NOTE: This does not fclose the `handle` when it is finished.

`handle` : | FILE* handle to write to
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_to_string ()

    raptor_iostream* raptor_new_iostream_to_string
                                                (void **string_p,
                                                 size_t *length_p,
                                                 void* (*malloc_handler) (size_t size));

Constructor - create a new iostream writing to a string.

If `malloc_handler` is null, raptor will allocate it using it's own memory allocator. *`string_p` is set to NULL on failure (and *`length_p` to 0 if `length_p` is not NULL).

`string_p` : | pointer to location to hold string
`length_p` : | pointer to location to hold length of string (or NULL)
`malloc_handler` : | pointer to malloc to use to make string (or NULL)
Returns : | new raptor_iostream object or NULL on failure

### raptor_free_iostream ()

    void        raptor_free_iostream            (raptor_iostream *iostr);

Destructor - destroy an iostream.

`iostr` : | iostream object

### raptor_iostream_write_bytes ()

    int         raptor_iostream_write_bytes     (raptor_iostream *iostr,
                                                 const void *ptr,
                                                 size_t size,
                                                 size_t nmemb);

Write bytes to the iostream.

`iostr` : | raptor iostream
`ptr` : | start of objects to write
`size` : | size of object
`nmemb` : | number of objects
Returns : | number of objects written or less than nmemb or 0 on failure

### raptor_iostream_write_byte ()

    int         raptor_iostream_write_byte      (raptor_iostream *iostr,
                                                 const int byte);

Write a byte to the iostream.

`iostr` : | raptor iostream
`byte` : | byte to write
Returns : | non-0 on failure

### raptor_iostream_write_end ()

    void        raptor_iostream_write_end       (raptor_iostream *iostr);

End writing to the iostream.

`iostr` : | raptor iostream

### raptor_iostream_write_string ()

    int         raptor_iostream_write_string    (raptor_iostream *iostr,
                                                 const void *string);

Write a NULL-terminated string to the iostream.

`iostr` : | raptor iostream
`string` : | string
Returns : | non-0 on failure

### raptor_iostream_write_counted_string ()

    int         raptor_iostream_write_counted_string
                                                (raptor_iostream *iostr,
                                                 const void *string,
                                                 size_t len);

Write a counted string to the iostream.

`iostr` : | raptor iostream
`string` : | string
`len` : | string length
Returns : | non-0 on failure

### raptor_iostream_get_bytes_written_count ()

    size_t      raptor_iostream_get_bytes_written_count
                                                (raptor_iostream *iostr);

Get the number of bytes written to the iostream.

`iostr` : | raptor iostream
Returns : | number of bytes written or 0 if non written so far

### raptor_iostream_write_decimal ()

    int         raptor_iostream_write_decimal   (raptor_iostream *iostr,
                                                 int integer);

Write an integer in decimal to the iostream.

`iostr` : | raptor iostream
`integer` : | integer to format as decimal
Returns : | non-0 on failure

### raptor_iostream_format_hexadecimal ()

    int         raptor_iostream_format_hexadecimal
                                                (raptor_iostream *iostr,
                                                 unsigned int integer,
                                                 int width);

Write an integer in hexadecimal to the iostream.

Always 0-fills the entire field and writes in uppercase A-F

`iostr` : | raptor iostream
`integer` : | unsigned integer to format as hexadecimal
`width` : | field width
Returns : | non-0 on failure

### raptor_iostream_write_stringbuffer ()

    int         raptor_iostream_write_stringbuffer
                                                (raptor_iostream *iostr,
                                                 raptor_stringbuffer *sb);

Write a stringbuffer to an iostream.

`iostr` : | raptor iostream
`sb` : | raptor_stringbuffer to write
Returns : | non-0 on failure

### raptor_iostream_write_string_ntriples ()

    int         raptor_iostream_write_string_ntriples
                                                (raptor_iostream *iostr,
                                                 unsigned char *string,
                                                 size_t len,
                                                 const char delim);

Write an UTF-8 string using N-Triples escapes to an iostream.

`iostr` : | raptor_iostream to write to
`string` : | UTF-8 string to write
`len` : | length of UTF-8 string
`delim` : | Terminating delimiter character for string (such as " or >) or \0 for no escaping.
Returns : | non-0 on failure such as bad UTF-8 encoding.

### raptor_iostream_write_statement_ntriples ()

    void        raptor_iostream_write_statement_ntriples
                                                (raptor_iostream *iostr,
                                                 const raptor_statement *statement);

Write a raptor_statement formatted in N-Triples format to a raptor_iostream

`iostr` : | raptor iosteram
`statement` : | statement to write