cu/buffer.h: Generic Self-Extending Buffer
[Data Sequences]

Data Structures
struct	cu_buffer
Defines
#define	cu_buffer_put(buf, data_t, data)   (*(data_t *)cu_buffer_produce(buf, sizeof(data_t)) = (data))
Functions
cu_buffer_t	cu_buffer_new (size_t init_cap)
void	cu_buffer_init (cu_buffer_t buf, size_t init_cap)
void	cu_buffer_clear (cu_buffer_t buf)
void	cu_buffer_init_drop (cu_buffer_t buf, cu_buffer_t buf_drop)
void	cu_buffer_swap (cu_buffer_t buf0, cu_buffer_t buf1)
void *	cu_buffer_storage_start (cu_buffer_t buf)
void *	cu_buffer_storage_end (cu_buffer_t buf)
size_t	cu_buffer_storage_size (cu_buffer_t buf)
size_t	cu_buffer_fullcap (cu_buffer_t buf)
void	cu_buffer_extend_fullcap (cu_buffer_t buf, size_t fullcap)
size_t	cu_buffer_freecap (cu_buffer_t buf)
void	cu_buffer_extend_freecap (cu_buffer_t buf, size_t freecap)
void	cu_buffer_force_realign (cu_buffer_t buf)
void	cu_buffer_maybe_realign (cu_buffer_t buf)
void *	cu_buffer_content_start (cu_buffer_t buf)
void *	cu_buffer_content_end (cu_buffer_t buf)
size_t	cu_buffer_content_size (cu_buffer_t buf)
void	cu_buffer_set_content_start (cu_buffer_t buf, void *start)
void	cu_buffer_incr_content_start (cu_buffer_t buf, size_t incr)
void	cu_buffer_set_content_end (cu_buffer_t buf, void *end)
void	cu_buffer_incr_content_end (cu_buffer_t buf, size_t incr)
void	cu_buffer_resize_content (cu_buffer_t buf, size_t size)
void *	cu_buffer_produce (cu_buffer_t buf, size_t incr)
void	cu_buffer_write (cu_buffer_t buf, void const *data, size_t size)

---

Detailed Description

The structure of a buffer, illustrating the terminology used in the function names.

This header defines a buffer for use with any data which can be moved around. It has a storage which is dynamically re-allocated as needed. Within the storage is a sub-region with the current content. The content can be resized and moved upwards within the storage by moving its start and end pointers. When the content region reaches the limit of the storage, it will be move to the start of the storage, possibly reallocating a bigger storage region first. To guarantee good time complexity, the storage is extended in geometric progression, and the storage is kept big enough that the content is moved at most once on the average.

---

Function Documentation

void cu_buffer_clear

(

cu_buffer_t

buf

)

Set the content of buf to the empty sequence aligned to the start of the storage.

void* cu_buffer_content_end

(

cu_buffer_t

buf

)

The address of the end of the content of buf.

size_t cu_buffer_content_size

(

cu_buffer_t

buf

)

The size in bytes of the buffer contents.

void* cu_buffer_content_start

(

cu_buffer_t

buf

)

The address of the start of the content of buf.

void cu_buffer_extend_freecap	(	cu_buffer_t	buf,
		size_t	freecap
	)

Makes sure there is at least freecap bytes allocated after the end of the buffer content.

void cu_buffer_extend_fullcap	(	cu_buffer_t	buf,
		size_t	fullcap
	)

Makes sure there is at least fullcap bytes allocated after the start of the buffer content. This is done either by moving the content to the start of the buffer or by allocating a bigger chunck of memory.

void cu_buffer_force_realign

(

cu_buffer_t

buf

)

Unconditionally realign the content to the start of the storage.

size_t cu_buffer_freecap

(

cu_buffer_t

buf

)

The number of bytes allocated after the current contents.

size_t cu_buffer_fullcap

(

cu_buffer_t

buf

)

The number of bytes from the start of the buffer contents to the end of the end of the current buffer storage.

void cu_buffer_incr_content_end	(	cu_buffer_t	buf,
		size_t	incr
	)

Inclement the end-of-content pointer by incr bytes, which in essence indicates that the corresponding content is produced. This function extends the buffer capacity if needed.

void cu_buffer_incr_content_start	(	cu_buffer_t	buf,
		size_t	incr
	)

Increment the start-of-content pointer by incr bytes, which in essence indicates that the corresponding content is consumed, so that the related buffer space can be re-used.

Precondition:

incr must be less than or equal to the content size.

void cu_buffer_init	(	cu_buffer_t	buf,
		size_t	init_cap
	)

Initialise buf to an empty buffer of with initial capacity init_cap.

void cu_buffer_init_drop	(	cu_buffer_t	buf,
		cu_buffer_t	buf_drop
	)

Initialise buf with the data of buf_drop, and invalidate buf_drop.

void cu_buffer_maybe_realign

(

cu_buffer_t

buf

)

Realign content to the start of storage if the displacement is larger than the content size.

cu_buffer_t cu_buffer_new

(

size_t

init_cap

)

Returns an empty buffer with initial capacity init_cap.

void* cu_buffer_produce	(	cu_buffer_t	buf,
		size_t	incr
	)

This is a shortcut to increment the end-of-content pointer by incr and return it's value befor the increment. It is useful for appending data to the buffer.

void cu_buffer_resize_content	(	cu_buffer_t	buf,
		size_t	size
	)

Sets the size of the content of buf. This function extends the buffer capacity if needed.

void cu_buffer_set_content_end	(	cu_buffer_t	buf,
		void *	end
	)

Sets the end-of-content pointer.

Precondition:

end must be within the buffer and after the content start.

void cu_buffer_set_content_start	(	cu_buffer_t	buf,
		void *	start
	)

Sets the start of content pointer.

Precondition:

start must be within the buffer, and less than the content end.

void* cu_buffer_storage_end

(

cu_buffer_t

buf

)

The end of the current buffer storage.

size_t cu_buffer_storage_size

(

cu_buffer_t

buf

)

The number of bytes stored in buf.

void* cu_buffer_storage_start

(

cu_buffer_t

buf

)

The start of the current buffer storage.

void cu_buffer_swap	(	cu_buffer_t	buf0,
		cu_buffer_t	buf1
	)

Swap the states of buf0 and buf1.

void cu_buffer_write	(	cu_buffer_t	buf,
		void const *	data,
		size_t	size
	)

Append the size bytes starting at data to the content of buf.