I/O Stream
3
RAPTOR Library

# 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);
    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_handler2;
    raptor_iostream*    raptor_new_iostream_from_handler2   (void *user_data,
                                                             const raptor_iostream_handler2 * const handler2);
    raptor_iostream*    raptor_new_iostream_from_handler    (void *context,
                                                             const raptor_iostream_handler *handler);
    raptor_iostream*    raptor_new_iostream_from_sink       (void);
    raptor_iostream*    raptor_new_iostream_from_filename   (const char *filename);
    raptor_iostream*    raptor_new_iostream_from_file_handle
                                                            (FILE *handle);
    raptor_iostream*    raptor_new_iostream_from_string     (void *string,
                                                             size_t length);
    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_handlersize_t size) ());
    void                raptor_free_iostream                (raptor_iostream *iostr);
    int                 raptor_iostream_format_hexadecimal  (raptor_iostream *iostr,
                                                             unsigned int integer,
                                                             int width);
    size_t              raptor_iostream_get_bytes_written_count
                                                            (raptor_iostream *iostr);
    int                 raptor_iostream_read_bytes          (raptor_iostream *iostr,
                                                             void *ptr,
                                                             size_t size,
                                                             size_t nmemb);
    int                 raptor_iostream_read_eof            (raptor_iostream *iostr);
    unsigned long       raptor_iostream_tell                (raptor_iostream *iostr);
    int                 raptor_iostream_write_byte          (raptor_iostream *iostr,
                                                             const int byte);
    int                 raptor_iostream_write_bytes         (raptor_iostream *iostr,
                                                             const void *ptr,
                                                             size_t size,
                                                             size_t nmemb);
    int                 raptor_iostream_write_counted_string
                                                            (raptor_iostream *iostr,
                                                             const void *string,
                                                             size_t len);
    int                 raptor_iostream_write_decimal       (raptor_iostream *iostr,
                                                             int integer);
    void                raptor_iostream_write_end           (raptor_iostream *iostr);
    void                raptor_iostream_write_statement_ntriples
                                                            (raptor_iostream *iostr,
                                                             const raptor_statement *statement);
    int                 raptor_iostream_write_string        (raptor_iostream *iostr,
                                                             const void *string);
    int                 raptor_iostream_write_string_ntriples
                                                            (raptor_iostream *iostr,
                                                             unsigned char *string,
                                                             size_t len,
                                                             const char delim);
    int                 raptor_iostream_write_string_python (raptor_iostream *iostr,
                                                             unsigned char *string,
                                                             size_t len,
                                                             const char delim,
                                                             int flags);
    void                raptor_iostream_write_string_turtle (raptor_iostream *iostr,
                                                             unsigned char *string,
                                                             size_t len);
    int                 raptor_iostream_write_stringbuffer  (raptor_iostream *iostr,
                                                             raptor_stringbuffer *sb);

## 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_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 {
      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;

`raptor_iostream_handler` is deprecated and should not be used in newly-written code. Use raptor_iostream_handler2

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 (for writing)

raptor_iostream_write_bytes_func write_bytes;

  write bytes handler - required (for writing)

raptor_iostream_write_end_func write_end;

  write end handler - optional (for writing), called at most once

### raptor_iostream_handler2

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

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

    raptor_iostream*    raptor_new_iostream_from_handler2   (void *user_data,
                                                             const raptor_iostream_handler2 * const handler2);

Create a new iostream over a user-defined handler

`user_data` :

  pointer to context information to pass in to calls

`handler2` :

  pointer to handler methods

Returns :

  new raptor_iostream object or NULL on failure

### raptor_new_iostream_from_handler ()

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

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

Create a new iostream over a user-defined handler.

`deprecated`: Use `raptor_new_iostream_from_handler2()` instead

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

    raptor_iostream*    raptor_new_iostream_from_sink       (void);

Create a new read iostream from a sink.

Returns :

  new raptor_iostream object or NULL on failure

### raptor_new_iostream_from_filename ()

    raptor_iostream*    raptor_new_iostream_from_filename   (const char *filename);

Constructor - create a new iostream reading from a filename.

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

`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     (void *string,
                                                             size_t length);

Constructor - create a new iostream reading from a string.

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

Create a new write 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_handlersize_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_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_get_bytes_written_count ()

    size_t              raptor_iostream_get_bytes_written_count
                                                            (raptor_iostream *iostr);

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

Get the number of bytes written to the iostream.

`deprecated`: Use `raptor_iostream_tell()` instead

`iostr` :

  raptor iostream

Returns :

  number of bytes written or 0 if none written so far

### raptor_iostream_read_bytes ()

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

Read bytes to the iostream.

`iostr` :

  raptor iostream

`ptr` :

  start of buffer to read objects into

`size` :

  size of object

`nmemb` :

  number of objects to read

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_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_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_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_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_write_end ()

    void                raptor_iostream_write_end           (raptor_iostream *iostr);

End writing to the iostream.

`iostr` :

  raptor iostream

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

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

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

Write a UTF-8 string using Python-style escapes (N-Triples, Turtle, JSON) 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.

`flags` :

  flags 0=N-Triples mode, 1=Turtle (allow raw UTF-8), 2=Turtle long string (allow raw UTF-8), 3=JSON

Returns :

  non-0 on failure such as bad UTF-8 encoding.

### raptor_iostream_write_string_turtle ()

    void                raptor_iostream_write_string_turtle (raptor_iostream *iostr,
                                                             unsigned char *string,
                                                             size_t len);

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

Write an UTF-8 string using Turtle "longString" triple quoting to an iostream.

`deprecated`: use `raptor_iostream_write_string_python()` instead

`iostr` :

  raptor_iostream to write to

`string` :

  UTF-8 string to write

`len` :

  length of UTF-8 string

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