Data Stream

Collaboration diagram for Data Stream:

Detailed Description

Macros
#define	bj_stream_read_t(stream, type, buffer)
	Reads data of a specified type from the stream into a buffer.
#define	bj_stream_skip_t(stream, type)
	Skips reading data of a specified type from the stream.

Typedefs
typedef struct bj_stream_t	bj_stream
	Structure representing a stream of data.

Enumerations
enum	bj_seek_origin { BJ_SEEK_BEGIN = 0x00 , BJ_SEEK_CURRENT = 0x01 , BJ_SEEK_END = 0x02 }
	Position in a bj_stream to use for origin. More...

Functions
bj_stream *	bj_stream_alloc (void)
	Allocate a new bj_stream object.
bj_stream *	bj_stream_new_read (const void *p_data, size_t length)
	Creates a new bj_stream for reading from a memory buffer.
bj_stream *	bj_stream_new_read_from_file (const char *p_path, bj_error **p_error)
	Creates a new bj_stream for reading from a file.
void	bj_stream_del (bj_stream *p_stream)
	Deletes a bj_stream object and releases associated memory.
size_t	bj_stream_read (bj_stream *p_stream, void *p_dest, size_t count)
	Reads data from the stream into a destination buffer.
size_t	bj_stream_len (bj_stream *p_stream)
	Get the size of the stream.
size_t	bj_stream_seek (bj_stream *p_stream, ptrdiff_t position, bj_seek_origin from)
	Seeks to a new position in the stream relative to a specified origin.
size_t	bj_stream_tell (bj_stream *p_stream)
	Returns the current position of the cursor in the stream.

Macro Definition Documentation

bj_stream_read_t

#define bj_stream_read_t	(		stream,
			type,
			buffer )

Value:

bj_stream_read(stream, buffer, sizeof(type))

Parameters

stream	Pointer to the stream instance.
type	Data type to read.
buffer	Pointer to the buffer to store the read data.

bj_stream_skip_t

#define bj_stream_skip_t	(		stream,
			type )

Value:

bj_stream_read(stream, 0, sizeof(type))

Parameters

stream	Pointer to the stream instance.
type	Data type to skip.

Typedef Documentation

bj_stream

typedef struct bj_stream_t bj_stream

Typedef for the bj_stream_t struct

Enumeration Type Documentation

bj_seek_origin

enum bj_seek_origin

Enumerator
BJ_SEEK_BEGIN	The beginning of the stream.
BJ_SEEK_CURRENT	The current position of the stream.
BJ_SEEK_END	The end of the stream.

Function Documentation

bj_stream_alloc()

bj_stream * bj_stream_alloc

(

void

)

Returns

A pointer to a new bj_stream

Memory Management

The object pointed by the returned value must be deleted using bj_free.

bj_stream_del()

void bj_stream_del

(

bj_stream *

p_stream

)

Parameters

p_stream

Pointer to the bj_stream object to delete.

bj_stream_len()

size_t bj_stream_len

(

bj_stream *

p_stream

)

Parameters

p_stream

Pointer to the stream instance.

Returns

The size of the stream, in bytes

bj_stream_new_read()

bj_stream * bj_stream_new_read	(	const void *	p_data,
		size_t	length )

Parameters

p_data	Pointer to the data buffer.
length	Length of the data buffer in bytes.

Returns

A pointer to the newly created bj_stream object.

bj_stream_new_read_from_file()

bj_stream * bj_stream_new_read_from_file	(	const char *	p_path,
		bj_error **	p_error )

Parameters

p_path	The file path to open
p_error	Optional error object

Returns

A pointer to an error object

The file memory is entirely copied to internal memory buffer.

bj_stream_read()

size_t bj_stream_read	(	bj_stream *	p_stream,
		void *	p_dest,
		size_t	count )

Parameters

p_stream	Pointer to the stream instance.
p_dest	Pointer to the destination buffer.
count	Number of bytes to read.

Returns

Number of bytes actually read.

The function advances the stream position by count bytes. If fewer bytes than count are read, the end of the stream is reached.

Memory Safety

This function does not perform any memory bounds checking. It is the caller's responsibility to ensure p_dest has enough space to hold count bytes.

bj_stream_seek()

size_t bj_stream_seek	(	bj_stream *	p_stream,
		ptrdiff_t	position,
		bj_seek_origin	from )

Parameters

p_stream	Pointer to the stream instance.
position	Offset for the new position.
from	Origin relative to which the position should be calculated.

Returns

The new position within the stream after seeking.

The function clamps the new position to stay within the valid range of the stream, from 0 to the length of the stream.

bj_stream_tell()

size_t bj_stream_tell

(

bj_stream *

p_stream

)

Parameters

p_stream

Pointer to the stream instance.

Returns

The current position within the stream.