I/O Stream

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

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.

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

 


Navigation: Redland Home Page

Copyright 2000-2023 Dave Beckett