Streams

Input stream

struct UIStream

Models an input stream.

Public Members

ustream_ret state: Stream state.

size_t read_bytes: Bytes read since the last reset call.

void *ctx: Stream context, can be anything.

ustream_ret (*read)(void *ctx, void *buf, size_t count, size_t *read)

Pointer to a function that reads count bytes from the stream and writes them into buf.

Param ctx:: Stream context.
Param buf:: Buffer to write into.
Param count:: Number of bytes to read.
Param read:: [out] Number of bytes actually read.
Return:: Return code.

ustream_ret (*reset)(void *ctx)

Pointer to a function that resets the stream.

Note

Can be NULL if the stream cannot be reset.

Param ctx:: Stream context.
Return:: Return code.

ustream_ret (*free)(void *ctx)

Pointer to a function that releases any resource reserved by the stream.

The provided function is invoked when uistream_deinit() is called.

Note

Can be NULL if the stream does not need to release resources.

Param ctx:: Stream context.
Return:: Return code.

UIStream uistream(void *ctx, ustream_ret (*read_func)(void*, void*, size_t, size_t*), ustream_ret (*reset_func)(void*), ustream_ret (*free_func)(void*))

Initializes an input stream.

Note

The returned object must be destroyed by calling uistream_deinit().

Parameters:

ctx – Stream context.
read_func – read function pointer.
reset_func – reset function pointer.
free_func – free function pointer.

Returns:

Stream instance.

ustream_ret uistream_deinit(UIStream *stream)

Deinitializes the stream, releasing any reserved resource.

Parameters:

stream – Input stream.

Returns:

Return code.

ustream_ret uistream_reset(UIStream *stream)

Resets the stream.

Parameters:

stream – Input stream.

Returns:

Return code.

ustream_ret uistream_read(UIStream *stream, void *buf, size_t count, size_t *read)

Reads count bytes from the stream and writes them into buf.

Parameters:

stream – Input stream.
buf – Input buffer.
count – Maximum number of bytes to read.
read – [out] Number of bytes read.

Returns:

Return code.

UIStream *uistream_std(void)

Returns a stream that reads from the standard input.

Returns:: Standard input stream.

ustream_ret uistream_from_path(UIStream *stream, char const *path)

Initializes a stream that reads from the file at the specified path.

Note

The returned object must be destroyed by calling uistream_deinit().

Parameters:

stream – Input stream.
path – Path to the file to read from.

Returns:

Return code.

ustream_ret uistream_from_file(UIStream *stream, FILE *file)

Initializes a stream that reads from the specified file.

Note

The returned object must be destroyed by calling uistream_deinit().

Parameters:

stream – Input stream.
file – The input file.

Returns:

Return code.

ustream_ret uistream_from_buf(UIStream *stream, void const *buf, size_t size)

Initializes a stream that reads from the specified buffer.

Note

The returned object must be destroyed by calling uistream_deinit().

Parameters:

stream – Input stream.
buf – The input buffer.
size – Size of the input buffer.

Returns:

Return code.

ustream_ret uistream_from_strbuf(UIStream *stream, UStrBuf const *buf)

Initializes a stream that reads from the specified string buffer.

Note

The returned object must be destroyed by calling uistream_deinit().

Parameters:

stream – Input stream.
buf – String buffer.

Returns:

Return code.

ustream_ret uistream_from_string(UIStream *stream, char const *string)

Initializes a stream that reads from the specified null-terminated string.

Note

The returned object must be destroyed by calling uistream_deinit().

Parameters:

stream – Input stream.
string – String.

Returns:

Return code.

ustream_ret uistream_from_ustring(UIStream *stream, UString const *string)

Initializes a stream that reads from the specified string.

Note

The returned object must be destroyed by calling uistream_deinit().

Parameters:

stream – Input stream.
string – String.

Returns:

Return code.

Output stream

struct UOStream

Models an output stream.

Public Members

ustream_ret state: Stream state.

size_t written_bytes: Bytes written since the last flush call.

void *ctx: Stream context, can be anything.

ustream_ret (*write)(void *ctx, void const *buf, size_t count, size_t *written)

Pointer to a function that reads count bytes from buf and writes them into the stream.

Param ctx:: Stream context.
Param buf:: Buffer to read from.
Param count:: Number of bytes to write.
Param rcount:: [out] Number of bytes actually written.
Return:: Return code.

ustream_ret (*writef)(void *ctx, size_t *written, char const *format, va_list args)

Pointer to a function that writes a formatted string into the stream.

Note

Can be NULL, in which case the stream will fallback to write.

Param ctx:: Stream context.
Param written:: [out] Number of bytes written.
Param format:: Format string.
Param args:: Format arguments.
Return:: Return code.

ustream_ret (*flush)(void *ctx)

Pointer to a function that flushes the stream, writing any buffered data.

Note

Can be NULL if the stream cannot be flushed.

Param ctx:: Stream context.
Return:: Return code.

ustream_ret (*free)(void *ctx)

Pointer to a function that releases any resource reserved by the stream.

The provided function is invoked when uostream_deinit() is called.

Note

Can be NULL if the stream does not need to release resources.

Param ctx:: Stream context.
Return:: Return code.

UOStream uostream(void *ctx, ustream_ret (*write_func)(void*, void const*, size_t, size_t*), ustream_ret (*writef_func)(void*, size_t*, char const*, va_list), ustream_ret (*flush_func)(void*), ustream_ret (*free_func)(void*))

Initializes an output stream.

Note

The returned object must be destroyed by calling uostream_deinit().

Parameters:

ctx – Stream context.
write_func – write function pointer.
writef_func – writef function pointer.
flush_func – flush function pointer.
free_func – free function pointer.

Returns:

Stream instance.

ustream_ret uostream_deinit(UOStream *stream)

Deinitializes the stream, releasing any reserved resource.

Parameters:

stream – Output stream.

Returns:

Return code.

ustream_ret uostream_flush(UOStream *stream)

Flushes the stream, writing any buffered data.

Parameters:

stream – Output stream.

Returns:

Return code.

ustream_ret uostream_write(UOStream *stream, void const *buf, size_t count, size_t *written)

Writes count bytes from buf into the specified output stream.

Parameters:

stream – Output stream.
buf – Buffer.
count – Number of bytes to write.
written – [out] Number of bytes written.

Returns:

Return code.

ustream_ret uostream_writef(UOStream *stream, size_t *written, char const *format, ...)

Writes a formatted string into the stream.

Parameters:

stream – Output stream.
written – [out] Number of bytes written.
format – Format string.
... – Format arguments.

Returns:

Return code.

ustream_ret uostream_writef_list(UOStream *stream, size_t *written, char const *format, va_list args)

Writes a formatted string into the stream.

Parameters:

stream – Output stream.
written – [out] Number of bytes written.
format – Format string.
args – Format arguments.

Returns:

Return code.

ustream_ret uostream_write_string(UOStream *stream, UString const *string, size_t *written)

Writes a string into the stream.

Parameters:

stream – Output stream.
string – String.
written – [out] Number of bytes written.

Returns:

Return code.

ustream_ret uostream_write_time(UOStream *stream, UTime const *time, size_t *written)

Writes the specified date and time into the stream.

Parameters:

stream – Output stream.
time – Date and time.
written – [out] Number of bytes written.

Returns:

Return code.

ustream_ret uostream_write_time_interval(UOStream *stream, utime_ns interval, utime_unit unit, unsigned decimal_digits, size_t *written)

Writes the specified time interval into the stream.

Parameters:

stream – Output stream.
interval – Time interval.
unit – Time unit.
decimal_digits – Number of decimal digits to write.
written – [out] Number of bytes written.

Returns:

Return code.

ustream_ret uostream_write_version(UOStream *stream, UVersion const *version, size_t *written)

Writes the specified version into the stream.

Parameters:

stream – Output stream.
version – Version.
written – [out] Number of bytes written.

Returns:

Return code.

UOStream *uostream_std(void)

Returns a stream that writes to the standard output.

Returns:: Standard output stream.

UOStream *uostream_stderr(void)

Returns a stream that writes to the standard error.

Returns:: Standard error stream.

UOStream *uostream_null(void)

Returns a stream that discards its output.

Returns:: Null output stream.

ustream_ret uostream_to_path(UOStream *stream, char const *path)

Initializes a stream that writes to the file at the specified path.

Note

The returned object must be destroyed by calling uostream_deinit().

Parameters:

stream – Output stream.
path – Path to the file to write to.

Returns:

Return code.

ustream_ret uostream_to_file(UOStream *stream, FILE *file)

Initializes a stream that writes to the specified file.

Note

The returned object must be destroyed by calling uostream_deinit().

Note

You are responsible for closing the file.

Parameters:

stream – Output stream.
file – The output file.

Returns:

Return code.

ustream_ret uostream_to_buf(UOStream *stream, void *buf, size_t size)

Initializes a stream that writes to the specified buffer.

Note

The returned object must be destroyed by calling uostream_deinit().

Parameters:

stream – Output stream.
buf – The output buffer.
size – Size of the output buffer.

Returns:

Return code.

ustream_ret uostream_to_strbuf(UOStream *stream, UStrBuf *buf)

Initializes a stream that writes to the specified string buffer.

Note

The returned object must be destroyed by calling uostream_deinit().

Note

If buf is NULL, the stream will allocate a new string buffer and set it as its context. In this case, the string buffer will be deinitialized when calling uostream_deinit().

Parameters:

stream – Output stream.
buf – The output buffer.

Returns:

Return code.

ustream_ret uostream_to_multi(UOStream *stream)

Initializes a stream that writes to multiple substreams.

Note

The returned object must be destroyed by calling uostream_deinit().

Note

Multi-streams behave as follows:

In case of error of any of the substreams, only the first detected error code is returned. It is your responsibility to check the state of each individual substream if that is important for your use case.
The reported written bytes are the maximum bytes written by any of the underlying substreams.
Calling uostream_deinit() deinitializes all substreams.

Parameters:

stream – Output stream.

Returns:

Return code.

ustream_ret uostream_add_substream(UOStream *stream, UOStream const *other)

Adds a new output stream to the specified multi-stream.

Note

Both streams must have been initialized beforehand, and stream must have been initialized via uostream_to_multi().

Parameters:

stream – Output stream.
other – Stream to add.

Returns:

Return code.

uostream_write_literal(stream, literal, written)

Writes the specified string literal into the stream.

Parameters:

stream – UOStream * Output stream.
literal – char const [] String literal.
written – [out] size_t * Number of bytes written.

Returns:

Return code.

Return codes

enum ustream_ret

Return codes for IO streams.

Values:

enumerator USTREAM_OK: Success.

enumerator USTREAM_ERR_BOUNDS: Buffer bounds exceeded, usually when writing to a stream backed by a fixed memory buffer.

enumerator USTREAM_ERR_MEM: Memory error, usually caused by failed allocations.

enumerator USTREAM_ERR_IO: Input/output error, usually returned when a file or stream operation fails.

Note

When this happens, errno is sometimes set to a more meaningful value.

enumerator USTREAM_ERR: Generic error.