Stream I/O

A sys_iostream_t is a small, fixed set of primitives - peek, read, write, seek, close - implemented differently per backend. More...

Collaboration diagram for Stream I/O:

Macros
#define	SYS_IOSTREAM_CAPACITY   8
	Maximum number of open streams.
#define	SYS_IOSTREAM_EOF   (-1)
	Sentinel returned by sys_iostream_peek() at the end of a stream.

Typedefs
typedef struct sys_iostream_t	sys_iostream_t
	An opaque byte stream. More...

Functions
void	sys_iostream_close (sys_iostream_t *s)
	Release a stream back to the pool. More...
int	sys_iostream_peek (sys_iostream_t *s)
	Look at the next byte without consuming it. More...
size_t	sys_iostream_read (sys_iostream_t *s, char *buf, size_t n)
	Read bytes from a stream. More...
size_t	sys_iostream_write (sys_iostream_t *s, const char *buf, size_t n)
	Write bytes to a stream. More...
ptrdiff_t	sys_iostream_seek (sys_iostream_t *s, ptrdiff_t offset, bool abs)
	Move a stream's read/write position. More...

Detailed Description

A sys_iostream_t is a small, fixed set of primitives - peek, read, write, seek, close - implemented differently per backend.

Instances come from a static pool (SYS_IOSTREAM_CAPACITY), never the heap, and are constructed by a source-specific function rather than directly; sys_string_read() (sys/string.h) is the only backend today, wrapping an existing string with no copy of its bytes. sys/rune.h's tokenizer and sys/scanner.h's scanner are both built entirely on this interface, so a future backend (a file, say) would work with them unchanged.

Example - read a stream in two passes by seeking back to the start:

sys_iostream_t *s = sys_string_read("hello");

char buf[6] = {0};
sys_iostream_read(s, buf, 5); // buf == "hello"

sys_iostream_seek(s, 0, true); // back to the start
sys_iostream_read(s, buf, 5); // buf == "hello" again

sys_iostream_close(s);

Typedef Documentation

sys_iostream_t

typedef struct sys_iostream_t sys_iostream_t

An opaque byte stream.

Instances come from a static pool (SYS_IOSTREAM_CAPACITY) - no heap allocation. Constructed by a source-specific function (e.g. sys_string_read() in sys/string.h) and released with sys_iostream_close().

Definition at line 68 of file io.h.

Function Documentation

sys_iostream_close()

void sys_iostream_close

(

sys_iostream_t *

s

)

Release a stream back to the pool.

Parameters

s	The stream to close, or NULL (a no-op).

Releases any resources the stream's source holds (nothing, for a string-backed stream) and frees its pool slot for reuse.

sys_iostream_peek()

int sys_iostream_peek

(

sys_iostream_t *

s

)

Look at the next byte without consuming it.

Parameters

s	The stream to peek at.

Returns

The next unread byte, as an unsigned value 0-255, or SYS_IOSTREAM_EOF if the stream is at its end. Calling this repeatedly without an intervening sys_iostream_read() returns the same byte every time.

sys_iostream_read()

size_t sys_iostream_read	(	sys_iostream_t *	s,
		char *	buf,
		size_t	n
	)

Read bytes from a stream.

Parameters

s	The stream to read from.
buf	Destination buffer.
n	Maximum number of bytes to read.

Returns

The number of bytes actually read into buf, which may be less than n. 0 means the stream is at its end - it is not an error.

sys_iostream_seek()

ptrdiff_t sys_iostream_seek	(	sys_iostream_t *	s,
		ptrdiff_t	offset,
		bool	abs
	)

Move a stream's read/write position.

Parameters

s	The stream to seek.
offset	Byte offset - absolute from the start when abs is true (must be >= 0), otherwise relative to the current position (negative moves backward).
abs	true for an absolute seek, false for relative.

Returns

The resulting absolute position (>= 0) on success, or -1 if the seek would go out of bounds - the position is left unchanged in that case.

sys_iostream_write()

size_t sys_iostream_write	(	sys_iostream_t *	s,
		const char *	buf,
		size_t	n
	)

Write bytes to a stream.

Parameters

s	The stream to write to.
buf	Source buffer.
n	Number of bytes to write.

Returns

The number of bytes actually written, which may be less than n (for example if the destination is full). 0 means nothing could be written - for a read-only stream (such as one from sys_string_read()), this is always the case.