Streams

Input stream

struct UIStream

Models an input stream.

Public Functions

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.

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.

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.

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.

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.

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.

Parameters

stream – Input stream.
string – String.

Returns

Return code.

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.

Public Static Functions

static inline 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.

Parameters

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

Returns

Stream instance.

Output stream

struct UOStream

Models an output stream.

Public Functions

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.

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

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.

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

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

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.

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.

Public Static Functions

static inline 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.

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.

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.