section-iostream: Raptor RDF Syntax Library Manual

## section-iostream section-iostream |

## Functions

int | (*raptor_iostream_init_func) ()
void | (*raptor_iostream_finish_func) ()
int | (*raptor_iostream_write_byte_func) ()
int | (*raptor_iostream_write_bytes_func) ()
int | (*raptor_iostream_write_end_func) ()
int | (*raptor_iostream_read_bytes_func) ()
int | (*raptor_iostream_read_eof_func) ()
raptor_iostream * | raptor_new_iostream_from_handler ()
raptor_iostream * | raptor_new_iostream_from_sink ()
raptor_iostream * | raptor_new_iostream_from_filename ()
raptor_iostream * | raptor_new_iostream_from_file_handle ()
raptor_iostream * | raptor_new_iostream_from_string ()
raptor_iostream * | raptor_new_iostream_to_sink ()
raptor_iostream * | raptor_new_iostream_to_filename ()
raptor_iostream * | raptor_new_iostream_to_file_handle ()
raptor_iostream * | raptor_new_iostream_to_string ()
void | raptor_free_iostream ()
int | raptor_iostream_hexadecimal_write ()
int | raptor_iostream_read_bytes ()
int | raptor_iostream_read_eof ()
unsigned long | raptor_iostream_tell ()
int | raptor_iostream_counted_string_write ()
int | raptor_iostream_decimal_write ()
int | raptor_iostream_string_write ()
int | raptor_iostream_write_byte ()
int | raptor_iostream_write_bytes ()
int | raptor_iostream_write_end ()
int | raptor_bnodeid_ntriples_write ()
int | raptor_string_escaped_write ()
int | raptor_term_escaped_write ()
int | raptor_uri_escaped_write ()
int | raptor_string_ntriples_write ()
int | raptor_string_python_write ()

## Types and Values

typedef | raptor_iostream
| raptor_iostream_handler
enum | raptor_escaped_write_bitflags

## Description

## Functions

### raptor_iostream_init_func ()

    int
    (*raptor_iostream_init_func) (void *context);

Handler function for raptor_iostream initialising.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

context | stream context data |

#### Returns

non-0 if EOF

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

iostr | raptor iostream |

#### Returns

non-0 on failure

### raptor_bnodeid_ntriples_write ()

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

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

#### Parameters

bnodeid | bnode ID to write |
len | length of bnode ID |
iostr | raptor_iostream to write to |

#### Returns

non-0 on failure

### raptor_string_escaped_write ()

    int
    raptor_string_escaped_write (const 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, mKR, SPARQL styles to an iostream.

#### Parameters

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

#### Parameters

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

#### Parameters

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 char *string,
                                  size_t len,
                                  const char delim,
                                  raptor_iostream *iostr);

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

#### Parameters

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 char *string,
                                size_t len,
                                const char delim,
                                unsigned int mode,
                                raptor_iostream *iostr);

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

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

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

#### Parameters

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.

## Types and Values

### raptor_iostream

    raptor_iostream* raptor_iostream;

Raptor I/O Stream class

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

#### Members

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

### enum raptor_escaped_write_bitflags

Bit flags for `raptor_string_escaped_write()` and friends.

#### Members

RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_BF | Allow \b \f, |
RAPTOR_ESCAPED_WRITE_BITFLAG_BS_ESCAPES_TNRU | Allow \t \n \r \u \U |
RAPTOR_ESCAPED_WRITE_BITFLAG_UTF8 | Use UTF-8 instead of \u \U for U+0080 or larger (will always use \u for U+0000..U+001F and U+007F) |
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: UTF-8 plus \b \f \t \r \n, \uXXXX only, no \U |