circular_buffer.h File Reference

#include <inttypes.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>

Include dependency graph for circular_buffer.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	circular_buffer_uint8_struct
	circular buffer struct More...

Typedefs
typedef struct circular_buffer_uint8_struct	circular_buffer_uint8
	circular buffer struct

Functions
void	circular_buffer_init_uint8 (circular_buffer_uint8 *circ_buf, const size_t capacity, uint8_t *buffer)
	circular buffer init method
size_t	circular_buffer_get_size_uint8 (const circular_buffer_uint8 *circ_buf)
	circular buffer get number of elements
bool	circular_buffer_is_full_uint8 (const circular_buffer_uint8 *circ_buf)
	circular buffer get if full
bool	circular_buffer_is_empty_uint8 (const circular_buffer_uint8 *circ_buf)
	circular buffer get if empty
void	circular_buffer_print_uint8 (const circular_buffer_uint8 *circ_buf, FILE *outfile, uint8_t verbosity)
	circular buffer print contents
uint8_t	circular_buffer_get_element_uint8 (const circular_buffer_uint8 *circ_buf, const size_t iElement)
	circular buffer get element
void	circular_buffer_push_front_uint8 (circular_buffer_uint8 *circ_buf, const uint8_t element)
	circular buffer push front
void	circular_buffer_push_back_uint8 (circular_buffer_uint8 *circ_buf, const uint8_t element)
	circular buffer push back
uint8_t	circular_buffer_pop_front_uint8 (circular_buffer_uint8 *circ_buf)
	circular buffer pop front
uint8_t	circular_buffer_pop_back_uint8 (circular_buffer_uint8 *circ_buf)
	circular buffer pop back
void	circular_buffer_remove_front_to_uint8 (circular_buffer_uint8 *circ_buf, const uint8_t value, const bool inclusive)
	circular buffer remove elements from front until you find the given value
void	circular_buffer_remove_back_to_uint8 (circular_buffer_uint8 *circ_buf, const uint8_t value, const bool inclusive)
	circular buffer remove elements from back until you find the given value
size_t	circular_buffer_find_first_uint8 (const circular_buffer_uint8 *circ_buf, const uint8_t value)
	circular buffer find index of first occurance of value
size_t	circular_buffer_find_last_uint8 (const circular_buffer_uint8 *circ_buf, const uint8_t value)
	circular buffer find index of last occurance of value
size_t	circular_buffer_count_uint8 (const circular_buffer_uint8 *circ_buf, const uint8_t value)
	circular buffer count the number of a given value
size_t	circular_buffer_get_first_block_uint8 (const circular_buffer_uint8 *circ_buf, const uint8_t **outBlock)
	circular buffer get first block
size_t	circular_buffer_delete_first_block_uint8 (circular_buffer_uint8 *circ_buf)
	circular buffer delete first block
void	circular_buffer_push_back_block_uint8 (circular_buffer_uint8 *circ_buf, const uint8_t *source, size_t source_size)
	circular buffer push a block of memory on back
size_t	circular_buffer_pop_front_block_uint8 (circular_buffer_uint8 *circ_buf, uint8_t *destination, size_t dest_size)
	circular buffer pop from front into a block of memory
size_t	circular_buffer_push_back_from_fd_uint8 (circular_buffer_uint8 *circ_buf, const int fd)
	circular buffer push back reading from file descriptor
size_t	circular_buffer_pop_front_to_fd_uint8 (circular_buffer_uint8 *circ_buf, const int fd)
	circular buffer pop front writing to file descriptor
void	circular_buffer_clear_uint8 (circular_buffer_uint8 *circ_buf)
	circular buffer clear
size_t	circular_buffer_push_back_string_uint8 (circular_buffer_uint8 *circ_buf, const char *string)
	circular buffer push back string (null terminated)
size_t	circular_buffer_remove_front_unfinished_frames_uint8 (circular_buffer_uint8 *circ_buf, const char startChar, const char endChar)
	circular buffer remove unfinished frames from front of buffer
size_t	circular_buffer_get_blocks_uint8 (circular_buffer_uint8 *circ_buf, size_t iStart, size_t nElem, uint8_t **blocks, size_t *blocks_sizes)
	circular buffer access raw blocks of data for a given range of elements

Typedef Documentation

circular_buffer_uint8

typedef struct circular_buffer_uint8_struct circular_buffer_uint8

circular buffer struct

Keeps track of the state of the circular buffer Use this for a buffer of unit8's.

Function Documentation

circular_buffer_clear_uint8()

void circular_buffer_clear_uint8

(

circular_buffer_uint8 *

circ_buf

)

circular buffer clear

Resets the circular buffer to empty and starting from the beginning of the memory buffer

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Definition at line 364 of file circular_buffer.c.

References circular_buffer_uint8_struct::iStart, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

Referenced by circular_buffer_remove_front_unfinished_frames_uint8().

circular_buffer_count_uint8()

size_t circular_buffer_count_uint8	(	const circular_buffer_uint8 *	circ_buf,
		const uint8_t	value )

circular buffer count the number of a given value

Counts the number of elements in the buffer that match the given value

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
value	is the value you want to find

Returns

the number of matches found

Definition at line 237 of file circular_buffer.c.

References circular_buffer_get_element_uint8(), and circular_buffer_uint8_struct::size.

circular_buffer_delete_first_block_uint8()

size_t circular_buffer_delete_first_block_uint8

(

circular_buffer_uint8 *

circ_buf

)

circular buffer delete first block

Internally, the data may wrap around the end of the block of memory. This function deletes the memory block from the current start of the circular buffer up to the end of the memory block, or if the data doesn't wrap, up to the end of the data.

This can be used after circular_buffer_get_first_block_uint8 to "pop_front" a whole block of data at once.

See also

circular_buffer_get_first_block_uint8

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

size of the block deleted

Definition at line 261 of file circular_buffer.c.

References circular_buffer_uint8_struct::capacity, circular_buffer_pop_front_uint8(), circular_buffer_uint8_struct::iStart, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

circular_buffer_find_first_uint8()

size_t circular_buffer_find_first_uint8	(	const circular_buffer_uint8 *	circ_buf,
		const uint8_t	value )

circular buffer find index of first occurance of value

Finds the index of the first element with value equal to the given value. If the value is not found in the buffer, the return value will be >= the size of the buffer.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
value	is the value you want to find

Returns

the index where the value can be found using circular_buffer_get_element_uint8, will be >= size if not found

See also

circular_buffer_get_element_uint8

Definition at line 212 of file circular_buffer.c.

References circular_buffer_get_element_uint8(), and circular_buffer_uint8_struct::size.

Referenced by ascii_serial_com_compute_checksum(), ascii_serial_com_get_message_from_input_buffer(), and circular_buffer_remove_front_unfinished_frames_uint8().

circular_buffer_find_last_uint8()

size_t circular_buffer_find_last_uint8	(	const circular_buffer_uint8 *	circ_buf,
		const uint8_t	value )

circular buffer find index of last occurance of value

Finds the index of the last element with value equal to the given value. If the value is not found in the buffer, the return value will be >= the size of the buffer.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
value	is the value you want to find

Returns

the index where the value can be found using circular_buffer_get_element_uint8, will be >= size if not found

See also

circular_buffer_get_element_uint8

Definition at line 224 of file circular_buffer.c.

References circular_buffer_get_element_uint8(), and circular_buffer_uint8_struct::size.

Referenced by ascii_serial_com_compute_checksum(), and circular_buffer_remove_front_unfinished_frames_uint8().

circular_buffer_get_blocks_uint8()

size_t circular_buffer_get_blocks_uint8	(	circular_buffer_uint8 *	circ_buf,
		size_t	iStart,
		size_t	nElem,
		uint8_t **	blocks,
		size_t *	blocks_sizes )

circular buffer access raw blocks of data for a given range of elements

Given a start element iStart, and a number of elements to access nElem, gives access to the raw memory block(s) that contain the elements. This may be a single block of memory or two, since the elements may wrap around the end of the underlying memory.

Example use:

uint8_t* blocks[2]; size_t blocks_sizes[2];

size_t nBlocks = circular_buffer_get_blocks_uint8(cb, 3, 5, blocks, blocks_sizes);

for(size_t iBlock=0; iBlock < nBlocks; iBlock++) { for(size_t iElem=0; iElem < blocks_sizes[iBlock]; iElem++) { uint8_t elem = blocks[iBlock][iElem]; } }

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
iStart	the first element of the block requested
nElem	the size of the block requested
blocks	output array of pointers to blocks. User should allocate uint8_t* blocks[2];
blocks_sizes	output array of size of blocks. User should allocate size_t blocks_sizes[2];

Returns

the number of memory blocks

Throws ASC_ERROR_CB_OOB if iStart + nElem is > size of buffer

Definition at line 428 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_get_size_uint8(), and circular_buffer_uint8_struct::iStart.

Referenced by ascii_serial_com_compute_checksum().

circular_buffer_get_element_uint8()

uint8_t circular_buffer_get_element_uint8	(	const circular_buffer_uint8 *	circ_buf,
		const size_t	iElement )

circular buffer get element

Use this for a buffer of unit8's.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
iElement	indexes the circular buffer. The element will be iElements back from the front of the circular buffer

Returns

the entry at iElement

May throw an asc_exception

Definition at line 126 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_get_size_uint8(), and circular_buffer_uint8_struct::iStart.

Referenced by ascii_serial_com_get_message_from_input_buffer(), circular_buffer_count_uint8(), circular_buffer_find_first_uint8(), circular_buffer_find_last_uint8(), circular_buffer_print_uint8(), circular_buffer_remove_back_to_uint8(), circular_buffer_remove_front_to_uint8(), and circular_buffer_remove_front_unfinished_frames_uint8().

circular_buffer_get_first_block_uint8()

size_t circular_buffer_get_first_block_uint8	(	const circular_buffer_uint8 *	circ_buf,
		const uint8_t **	outBlock )

circular buffer get first block

Internally, the data may wrap around the end of the block of memory. This function gives you access to the memory block up to the end of the memory block, or if the data doesn't wrap, up to the end of the data.

This can be used followed by circular_buffer_delete_first_block_uint8 to "pop_front" a whole block of data at once.

See also

circular_buffer_delete_first_block_uint8

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
outBlock	is a pointer to the start of the block of memory

Returns

size of the block pointed to by outBlock

Definition at line 250 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_uint8_struct::iStart, and circular_buffer_uint8_struct::size.

circular_buffer_get_size_uint8()

size_t circular_buffer_get_size_uint8

(

const circular_buffer_uint8 *

circ_buf

)

circular buffer get number of elements

circular buffer get number of elements Use this for a buffer of unit8's.

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

the number of elements in the buffer

Definition at line 60 of file circular_buffer.c.

References circular_buffer_uint8_struct::size.

Referenced by ascii_serial_com_compute_checksum(), ascii_serial_com_get_message_from_input_buffer(), circular_buffer_get_blocks_uint8(), circular_buffer_get_element_uint8(), circular_buffer_is_empty_uint8(), and circular_buffer_is_full_uint8().

circular_buffer_init_uint8()

void circular_buffer_init_uint8	(	circular_buffer_uint8 *	circ_buf,
		const size_t	capacity,
		uint8_t *	buffer )

circular buffer init method

Initialize circular buffer THE BUFFER MUST BE SMALLER THAN (< not <=) SIZE_T ON THE PLATFORM Use this for a buffer of unit8's.

May throw an asc_exception

Parameters

circ_buf	is a pointer to an uninitialized circular buffer struct
capacity	is the length of buffer (uint8_t array). It must be a power of 2! If it's not, a asc_exception ASC_ERROR_CB_BAD_CAPACITY will be raised.
buffer	is a pointer to the buffer (uint8_t array), which must be pre-allocated

Definition at line 45 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_uint8_struct::iStart, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

Referenced by ascii_serial_com_init().

circular_buffer_is_empty_uint8()

bool circular_buffer_is_empty_uint8

(

const circular_buffer_uint8 *

circ_buf

)

circular buffer get if empty

Use this for a buffer of unit8's.

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

true if the buffer is empty

Definition at line 68 of file circular_buffer.c.

References circular_buffer_get_size_uint8().

Referenced by circular_buffer_io_fd_poll_do_poll().

circular_buffer_is_full_uint8()

bool circular_buffer_is_full_uint8

(

const circular_buffer_uint8 *

circ_buf

)

circular buffer get if full

Use this for a buffer of unit8's.

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

true true if the buffer is full

Definition at line 64 of file circular_buffer.c.

References circular_buffer_uint8_struct::capacity, and circular_buffer_get_size_uint8().

circular_buffer_pop_back_uint8()

uint8_t circular_buffer_pop_back_uint8

(

circular_buffer_uint8 *

circ_buf

)

circular buffer pop back

Pops an element off of the back of the buffer, both removing it and returning it. User's responsibility to first check if the buffer is empty. Use this for a buffer of unit8's.

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

the element to be popped off the back of the buffer

Definition at line 169 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

Referenced by circular_buffer_remove_back_to_uint8().

circular_buffer_pop_front_block_uint8()

size_t circular_buffer_pop_front_block_uint8	(	circular_buffer_uint8 *	circ_buf,
		uint8_t *	destination,
		size_t	dest_size )

circular buffer pop from front into a block of memory

Pops elements from front into a block of memory

Won't pop all elements if circular buffer wraps around it's internal memory or there isn't enough source size

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
destination	is the start of the destination memory block
source_size	is the size of the destination memory block

Returns

total number of elements popped from buffer (and written to block)

Definition at line 285 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_uint8_struct::iStart, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

circular_buffer_pop_front_to_fd_uint8()

size_t circular_buffer_pop_front_to_fd_uint8	(	circular_buffer_uint8 *	circ_buf,
		const int	fd )

circular buffer pop front writing to file descriptor

Calls POSIX write once from the circular buffer

Won't necessarily empty the buffer, even if the file is available for writing

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

total number of elements popped from buffer (and written to file)

Definition at line 338 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_uint8_struct::iStart, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

Referenced by circular_buffer_io_fd_poll_do_output().

circular_buffer_pop_front_uint8()

uint8_t circular_buffer_pop_front_uint8

(

circular_buffer_uint8 *

circ_buf

)

circular buffer pop front

Pops an element off of the front of the buffer, both removing it and returning it. User's responsibility to first check if the buffer is empty. Use this for a buffer of unit8's.

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

element the element popped off the front of the buffer

Definition at line 159 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::iStart, and circular_buffer_uint8_struct::size.

Referenced by ascii_serial_com_get_message_from_input_buffer(), circular_buffer_delete_first_block_uint8(), circular_buffer_remove_front_to_uint8(), and circular_buffer_remove_front_unfinished_frames_uint8().

circular_buffer_print_uint8()

void circular_buffer_print_uint8	(	const circular_buffer_uint8 *	circ_buf,
		FILE *	outfile,
		uint8_t	verbosity )

circular buffer print contents

Use this for debugging

outfile is usually stderr or stdout

verbosity is from 0 to 4 with greater increasing verbosity

Definition at line 73 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_get_element_uint8(), circular_buffer_uint8_struct::iStart, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

circular_buffer_push_back_block_uint8()

void circular_buffer_push_back_block_uint8	(	circular_buffer_uint8 *	circ_buf,
		const uint8_t *	source,
		size_t	source_size )

circular buffer push a block of memory on back

Pushes a block of memory onto back

Will wrap around and overrite front if buffer gets full

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
source	is the start of the source memory block
source_size	is the size of the source memory block

Definition at line 277 of file circular_buffer.c.

References circular_buffer_push_back_uint8().

circular_buffer_push_back_from_fd_uint8()

size_t circular_buffer_push_back_from_fd_uint8	(	circular_buffer_uint8 *	circ_buf,
		const int	fd )

circular buffer push back reading from file descriptor

Calls POSIX read once into the circular buffer

Doesn't overwrite the front of the buffer like the normal push_back does. Stops when full.

Won't necessarily fill up the buffer, even if there are bytes to read

Parameters

circ_buf

is a pointer to an initialized circular buffer struct

Returns

total number of elements pushed onto buffer (and read from file)

Definition at line 310 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_uint8_struct::iStart, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

Referenced by circular_buffer_io_fd_poll_do_input().

circular_buffer_push_back_string_uint8()

size_t circular_buffer_push_back_string_uint8	(	circular_buffer_uint8 *	circ_buf,
		const char *	string )

circular buffer push back string (null terminated)

Pushes null terminated string onto buffer (without pushing the null)

For testing, NOT RECOMMENDED FOR MICROCONTROLLER USE

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
string	null terminated string like a string literal

Returns

total number of elements pushed onto buffer

Definition at line 370 of file circular_buffer.c.

References circular_buffer_push_back_uint8().

circular_buffer_push_back_uint8()

void circular_buffer_push_back_uint8	(	circular_buffer_uint8 *	circ_buf,
		const uint8_t	element )

circular buffer push back

Pushes the given element onto the back of the buffer, making it the new back element. Use this for a buffer of unit8's.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
element	the element to be pushed onto the back of the buffer

Definition at line 148 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_uint8_struct::iStop, and circular_buffer_uint8_struct::size.

Referenced by ascii_serial_com_put_message_in_output_buffer(), circular_buffer_push_back_block_uint8(), and circular_buffer_push_back_string_uint8().

circular_buffer_push_front_uint8()

void circular_buffer_push_front_uint8	(	circular_buffer_uint8 *	circ_buf,
		const uint8_t	element )

circular buffer push front

Pushes the given element onto the front of the buffer, making it the new front element. Use this for a buffer of unit8's.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
element	the element to be pushed onto the front of the buffer

Definition at line 137 of file circular_buffer.c.

References circular_buffer_uint8_struct::buffer, circular_buffer_uint8_struct::capacity, circular_buffer_uint8_struct::iStart, and circular_buffer_uint8_struct::size.

circular_buffer_remove_back_to_uint8()

void circular_buffer_remove_back_to_uint8	(	circular_buffer_uint8 *	circ_buf,
		const uint8_t	value,
		const bool	inclusive )

circular buffer remove elements from back until you find the given value

Remove elements from the back of the buffer until the given value is found. If the value isn't in the buffer, will empty the buffer.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
value	is the value you want to remove the back of the buffer up to.
inclusive	if true, then remove the given value, otherwise all after the given value

Definition at line 195 of file circular_buffer.c.

References circular_buffer_get_element_uint8(), circular_buffer_pop_back_uint8(), and circular_buffer_uint8_struct::size.

circular_buffer_remove_front_to_uint8()

void circular_buffer_remove_front_to_uint8	(	circular_buffer_uint8 *	circ_buf,
		const uint8_t	value,
		const bool	inclusive )

circular buffer remove elements from front until you find the given value

Remove elements from the front of the buffer until the given value is found. If the value isn't in the buffer, will empty the buffer.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
value	is the value you want to remove the front of the buffer up to.
inclusive	if true, then remove the given value, otherwise all before the given value

Definition at line 179 of file circular_buffer.c.

References circular_buffer_get_element_uint8(), circular_buffer_pop_front_uint8(), and circular_buffer_uint8_struct::size.

circular_buffer_remove_front_unfinished_frames_uint8()

size_t circular_buffer_remove_front_unfinished_frames_uint8	(	circular_buffer_uint8 *	circ_buf,
		const char	startChar,
		const char	endChar )

circular buffer remove unfinished frames from front of buffer

Removes from the front of the buffer any frames that haven't ended before an ended frame. If the buffer just contains an unfinished frame (e.g. that hasn't finished reading in yet), that isn't removed.

More concretely: The first endChar is found. Any elements before the startChar preceding endChar are removed. If the endChar isn't found, any elements before the last startChar are removed. If no startChar is found either, the buffer is cleared.

Additionally, if endChar is front or there is no startChar before the first endChar, everything up to and including endChar is deleted and the function is recursed.

Parameters

circ_buf	is a pointer to an initialized circular buffer struct
startChar	designates the start of frames
endChar	designates the end of frames

Returns

the number of elements removed

Definition at line 385 of file circular_buffer.c.

References circular_buffer_clear_uint8(), circular_buffer_find_first_uint8(), circular_buffer_find_last_uint8(), circular_buffer_get_element_uint8(), circular_buffer_pop_front_uint8(), circular_buffer_remove_front_unfinished_frames_uint8(), and circular_buffer_uint8_struct::size.

Referenced by ascii_serial_com_get_message_from_input_buffer(), and circular_buffer_remove_front_unfinished_frames_uint8().