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);
    int                 (*raptor_iostream_write_end_func)   (void *context);
    int                 (*raptor_iostream_read_bytes_func)  (void *context,
                                                             void *ptr,
                                                             size_t size,
                                                             size_t nmemb);
    int                 (*raptor_iostream_read_eof_func)    (void *context);
                        raptor_iostream_handler;
    raptor_iostream *   raptor_new_iostream_from_handler    (raptor_world *world,
                                                             void *user_data,
                                                             const raptor_iostream_handler * const handler);
    raptor_iostream *   raptor_new_iostream_from_sink       (raptor_world *world);
    raptor_iostream *   raptor_new_iostream_from_filename   (raptor_world *world,
                                                             const char *filename);
    raptor_iostream *   raptor_new_iostream_from_file_handle
                                                            (raptor_world *world,
                                                             FILE *handle);
    raptor_iostream *   raptor_new_iostream_from_string     (raptor_world *world,
                                                             void *string,
                                                             size_t length);
    raptor_iostream *   raptor_new_iostream_to_sink         (raptor_world *world);
    raptor_iostream *   raptor_new_iostream_to_filename     (raptor_world *world,
                                                             const char *filename);
    raptor_iostream *   raptor_new_iostream_to_file_handle  (raptor_world *world,
                                                             FILE *handle);
    raptor_iostream *   raptor_new_iostream_to_string       (raptor_world *world,
                                                             void **string_p,
                                                             size_t *length_p,
                                                             raptor_data_malloc_handler const malloc_handler);
    void                raptor_free_iostream                (raptor_iostream *iostr);
    int                 raptor_iostream_hexadecimal_write   (unsigned int integer,
                                                             int width,
                                                             raptor_iostream *iostr);
    int                 raptor_iostream_read_bytes          (void *ptr,
                                                             size_t size,
                                                             size_t nmemb,
                                                             raptor_iostream *iostr);
    int                 raptor_iostream_read_eof            (raptor_iostream *iostr);
    unsigned long       raptor_iostream_tell                (raptor_iostream *iostr);
    int                 raptor_iostream_counted_string_write
                                                            (const void *string,
                                                             size_t len,
                                                             raptor_iostream *iostr);
    int                 raptor_iostream_decimal_write       (int integer,
                                                             raptor_iostream *iostr);
    int                 raptor_iostream_string_write        (const void *string,
                                                             raptor_iostream *iostr);
    int                 raptor_iostream_write_byte          (const int byte,
                                                             raptor_iostream *iostr);
    int                 raptor_iostream_write_bytes         (const void *ptr,
                                                             size_t size,
                                                             size_t nmemb,
                                                             raptor_iostream *iostr);
    int                 raptor_iostream_write_end           (raptor_iostream *iostr);
    int                 raptor_bnodeid_ntriples_write       (const unsigned char *bnodeid,
                                                             size_t len,
                                                             raptor_iostream *iostr);
    enum                raptor_escaped_write_bitflags;
    int                 raptor_string_escaped_write         (const unsigned char *string,
                                                             size_t len,
                                                             const char delim,
                                                             unsigned int flags,
                                                             raptor_iostream *iostr);
    int                 raptor_term_escaped_write           (const raptor_term *term,
                                                             unsigned int flags,
                                                             raptor_iostream *iostr);
    int                 raptor_uri_escaped_write            (raptor_uri *uri,
                                                             raptor_uri *base_uri,
                                                             unsigned int flags,
                                                             raptor_iostream *iostr);
    int                 raptor_string_ntriples_write        (const unsigned char *string,
                                                             size_t len,
                                                             const char delim,
                                                             raptor_iostream *iostr);
    int                 raptor_string_python_write          (const unsigned char *string,
                                                             size_t len,
                                                             const char delim,
                                                             unsigned int mode,
                                                             raptor_iostream *iostr);

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

    int                 (*raptor_iostream_write_end_func)   (void *context);

Handler function for implementing `raptor_iostream_write_end()`.

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

### raptor_iostream_read_bytes_func ()

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

Handler function for implementing `raptor_iostream_read_bytes()`.

`context` : | stream context data
`ptr` : | pointer to buffer to read into
`size` : | size of buffer
`nmemb` : | number of items
Returns : | number of items read, 0 or < `size` on EOF, <0 on failure

### raptor_iostream_read_eof_func ()

    int                 (*raptor_iostream_read_eof_func)    (void *context);

Handler function for implementing `raptor_iostream_read_eof()`.

`context` : | stream context data
Returns : | non-0 if EOF

### raptor_iostream_handler

    typedef struct {
      int version;

      /* V1 functions */
      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;

      /* V2 functions */
      raptor_iostream_read_bytes_func   read_bytes;
      raptor_iostream_read_eof_func     read_eof;
    } raptor_iostream_handler;

I/O stream implementation handler structure.

int `version`; | interface version. Presently 1 or 2.
raptor_iostream_init_func `init`; | initialisation handler - optional, called at most once (V1)
raptor_iostream_finish_func `finish`; | finishing handler - optional, called at most once (V1)
raptor_iostream_write_byte_func `write_byte`; | write byte handler - required (for writing) (V1)
raptor_iostream_write_bytes_func `write_bytes`; | write bytes handler - required (for writing) (V1)
raptor_iostream_write_end_func `write_end`; | write end handler - optional (for writing), called at most once (V1)
raptor_iostream_read_bytes_func `read_bytes`; | read bytes handler - required (for reading) (V2)
raptor_iostream_read_eof_func `read_eof`; | read EOF handler - required (for reading) (V2)

### raptor_new_iostream_from_handler ()

    raptor_iostream *   raptor_new_iostream_from_handler    (raptor_world *world,
                                                             void *user_data,
                                                             const raptor_iostream_handler * const handler);

Create a new iostream over a user-defined handler

`world` : | raptor_world object
`user_data` : | 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_from_sink ()

    raptor_iostream *   raptor_new_iostream_from_sink       (raptor_world *world);

Create a new read iostream from a sink, returning no data.

Provides an I/O source that returns end of input immediately on reads, and throw away all writes. Same as `raptor_new_iostream_to_sink()`

`world` : | raptor world
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_from_filename ()

    raptor_iostream *   raptor_new_iostream_from_filename   (raptor_world *world,
                                                             const char *filename);

Constructor - create a new iostream reading from a filename.

`world` : | raptor world
`filename` : | Input filename to open and read from
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_from_file_handle ()

    raptor_iostream *   raptor_new_iostream_from_file_handle
                                                            (raptor_world *world,
                                                             FILE *handle);

Constructor - create a new iostream reading from a file_handle.

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

`world` : | raptor world
`handle` : | Input file_handle to open and read from
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_from_string ()

    raptor_iostream *   raptor_new_iostream_from_string     (raptor_world *world,
                                                             void *string,
                                                             size_t length);

Constructor - create a new iostream reading from a string.

`world` : | raptor world
`string` : | pointer to string
`length` : | length of string
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_to_sink ()

    raptor_iostream *   raptor_new_iostream_to_sink         (raptor_world *world);

Create a new write iostream to a sink, throwing away all data.

Provides an that throw away all writes and returns end of input immediately on reads. Same as `raptor_new_iostream_from_sink()`

`world` : | raptor_world object
Returns : | new raptor_iostream object or NULL on failure

### raptor_new_iostream_to_filename ()

    raptor_iostream *   raptor_new_iostream_to_filename     (raptor_world *world,
                                                             const char *filename);

Constructor - create a new iostream writing to a filename.

`world` : | raptor world
`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  (raptor_world *world,
                                                             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.

`world` : | raptor world
`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       (raptor_world *world,
                                                             void **string_p,
                                                             size_t *length_p,
                                                             raptor_data_malloc_handler const malloc_handler);

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

`world` : | raptor world
`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_hexadecimal_write ()

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

Write an integer in hexadecimal to the iostream.

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

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

### raptor_iostream_read_bytes ()

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

Read bytes to the iostream.

`ptr` : | start of buffer to read objects into
`size` : | size of object
`nmemb` : | number of objects to read
`iostr` : | raptor iostream
Returns : | number of objects read, 0 or less than nmemb on EOF, <0 on failure

### raptor_iostream_read_eof ()

    int                 raptor_iostream_read_eof            (raptor_iostream *iostr);

Check if an read iostream has ended

`iostr` : | raptor read iostream
Returns : | non-0 if EOF (or not a read iostream)

### raptor_iostream_tell ()

    unsigned long       raptor_iostream_tell                (raptor_iostream *iostr);

Get the offset in the iostream.

`iostr` : | raptor iostream
Returns : | offset in iostream

### raptor_iostream_counted_string_write ()

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

Write a counted string to the iostream.

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

### raptor_iostream_decimal_write ()

    int                 raptor_iostream_decimal_write       (int integer,
                                                             raptor_iostream *iostr);

Write an integer in decimal to the iostream.

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

### raptor_iostream_string_write ()

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

Write a NULL-terminated string to the iostream.

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

### raptor_iostream_write_byte ()

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

Write a byte to the iostream.

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

### raptor_iostream_write_bytes ()

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

Write bytes to the iostream.

`ptr` : | start of objects to write
`size` : | size of object
`nmemb` : | number of objects
`iostr` : | raptor iostream
Returns : | number of objects actually written, which may be less than nmemb. <0 on failure

### raptor_iostream_write_end ()

    int                 raptor_iostream_write_end           (raptor_iostream *iostr);

End writing to the iostream.

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

### raptor_bnodeid_ntriples_write ()

    int                 raptor_bnodeid_ntriples_write       (const unsigned char *bnodeid,
                                                             size_t len,
                                                             raptor_iostream *iostr);

Write a blank node ID in a form legal for N-Triples with _: prefix

`bnodeid` : | bnode ID to write
`len` : | length of bnode ID
`iostr` : | raptor_iostream to write to
Returns : | non-0 on failure

### enum raptor_escaped_write_bitflags

    typedef enum {
      RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF      = 1,
      RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU    = 2,
      RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8               = 4,
      RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES = 8,

      /* N-Triples - favour writing \u, \U over UTF8 */
      RAPTOR_ESCAPED_WRITE_NTRIPLES_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU | RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF,
      RAPTOR_ESCAPED_WRITE_NTRIPLES_URI     = RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES,

      /* SPARQL literal: allows raw UTF8 for printable literals */
      RAPTOR_ESCAPED_WRITE_SPARQL_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8,

      /* SPARQL long literal: no BS-escapes allowed */
      RAPTOR_ESCAPED_WRITE_SPARQL_LONG_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8,

      /* SPARQL uri: have to escape certain characters */
      RAPTOR_ESCAPED_WRITE_SPARQL_URI     = RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8 | RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES,

      /* Turtle (2013) escapes are like SPARQL */
      RAPTOR_ESCAPED_WRITE_TURTLE_URI     = RAPTOR_ESCAPED_WRITE_SPARQL_URI,
      RAPTOR_ESCAPED_WRITE_TURTLE_LITERAL = RAPTOR_ESCAPED_WRITE_SPARQL_LITERAL,
      RAPTOR_ESCAPED_WRITE_TURTLE_LONG_LITERAL = RAPTOR_ESCAPED_WRITE_SPARQL_LONG_LITERAL,

      /* JSON literals: \b \f \t \r \n and \u \U */
      RAPTOR_ESCAPED_WRITE_JSON_LITERAL = RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU | RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF
    } raptor_escaped_write_bitflags;

Bit flags for `raptor_string_escaped_write()` and friends.

`RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF` | Allow \b \f,
`RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU` | ALlow \t \n \r \u
`RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8` | Allow UTF-8 for printable U *
`RAPTOR_ESCAPED_WRITE_BITFLAG_SPARQL_URI_ESCAPES` | Must escape x00-x20<>\"{}|^` in URIs
`RAPTOR_ESCAPED_WRITE_NTRIPLES_LITERAL` | N-Triples literal
`RAPTOR_ESCAPED_WRITE_NTRIPLES_URI` | N-Triples URI
`RAPTOR_ESCAPED_WRITE_SPARQL_LITERAL` | SPARQL literal: allows raw UTF8 for printable literals
`RAPTOR_ESCAPED_WRITE_SPARQL_LONG_LITERAL` | SPARQL long literal: no BS-escapes allowed
`RAPTOR_ESCAPED_WRITE_SPARQL_URI` | SPARQL uri: have to escape certain characters
`RAPTOR_ESCAPED_WRITE_TURTLE_URI` | Turtle 2013 URIs (like SPARQL)
`RAPTOR_ESCAPED_WRITE_TURTLE_LITERAL` | Turtle 2013 literals (like SPARQL)
`RAPTOR_ESCAPED_WRITE_TURTLE_LONG_LITERAL` | Turtle 2013 long literals (like SPARQL)
`RAPTOR_ESCAPED_WRITE_JSON_LITERAL` | JSON literals: \b \f \t \r \n and \u \U

### raptor_string_escaped_write ()

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

Write a UTF-8 string formatted using different escapes to a raptor_iostream

Supports writing escapes in the Python, N-Triples, Turtle, JSON, SPARQL styles to an iostream.

`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.
`flags` : | bit flags - see raptor_escaped_write_bitflags
`iostr` : | raptor_iostream to write to
Returns : | non-0 on failure such as bad UTF-8 encoding.

### raptor_term_escaped_write ()

    int                 raptor_term_escaped_write           (const raptor_term *term,
                                                             unsigned int flags,
                                                             raptor_iostream *iostr);

Write a raptor_term formatted with escapes to a raptor_iostream

`term` : | term to write
`flags` : | bit flags - see raptor_escaped_write_bitflags
`iostr` : | raptor iostream
Returns : | non-0 on failure

### raptor_uri_escaped_write ()

    int                 raptor_uri_escaped_write            (raptor_uri *uri,
                                                             raptor_uri *base_uri,
                                                             unsigned int flags,
                                                             raptor_iostream *iostr);

Write a raptor_uri formatted with escapes to a raptor_iostream

`uri` : | uri to write
`base_uri` : | base uri to write relative to (or NULL)
`flags` : | bit flags - see raptor_escaped_write_bitflags
`iostr` : | raptor iostream
Returns : | non-0 on failure

### raptor_string_ntriples_write ()

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

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

`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.
`iostr` : | raptor_iostream to write to
Returns : | non-0 on failure such as bad UTF-8 encoding.

### raptor_string_python_write ()

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

Write a UTF-8 string using Python-style escapes (N-Triples, Turtle, JSON) to a raptor_iostream

`Deprecated`: use `raptor_string_escaped_write()` where the features requested are bits that can be individually chosen.

`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.
`mode` : | mode 0=N-Triples mode, 1=Turtle (allow raw UTF-8), 2=Turtle long string (allow raw UTF-8), 3=JSON
`iostr` : | raptor_iostream to write to
Returns : | non-0 on failure such as bad UTF-8 encoding.