A universal ringbuffer library. More...

#include <stdint.h>

Include dependency graph for kBuffer.h:

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

Data Structures
struct	buffer_t
	Struct for buffer handling. If you need a ringbuffer in your software, you should instantiate a buffer_t, and run the neccessary functions with a pointer to your instance. More...

Macros
#define	bufferDatatype uint16_t
	The datatype of one buffer element. As default, it is an 16 bit unsigned integer. Feel free to change it to your needs.

#define	BUFFER_ENABLE_MEAN
	Enables mean/ averaging functions. If you uncomment this define, the following functions will be compiled. Only enable it, if bufferDatatype is some sort of numeric datatype (integer, float, ...) bufferMean(); bufferMeanRMS();

Enumerations
enum	bufferStatus_t { bufferOK = 0, bufferMemoryAllocationFailed, bufferEmpty, bufferFull, bufferNotInitialized, bufferError }
	buffer function return codes More...

Functions
bufferStatus_t	bufferInit (buffer_t *buffer, uint16_t bufferSize)
	init a new buffer This function inits a new buffer_t. More...

bufferStatus_t	bufferInitStatic (buffer_t buffer, uint16_t bufferSize, bufferDatatype bufferArray)
	init a new buffer This function inits a new buffer_t, but doesn't allocate the memory dynamically You've to provide an array of the datatype and the required length when calling this function. This function might be useful, if you want to save the overhead of the malloc() function More...

bufferStatus_t	bufferWriteToIndex (buffer_t *buffer, uint16_t index, bufferDatatype data)
	write data to a specific index of the buffer. WARNING: Take care when using this function, it is against the main concept of a ringbuffer More...

bufferStatus_t	bufferReadFromIndex (buffer_t buffer, uint16_t index, bufferDatatype data)
	read data from a specifig index of the buffer WARNING: Take care when using this function, it is against the main concept of a ringbuffer More...

uint8_t	bufferIsEmpty (buffer_t *buffer)
	Checks, wheter the buffer is empty. More...

uint8_t	bufferIsFull (buffer_t *buffer)
	Checks, wheter the buffer is full. More...

bufferStatus_t	bufferWrite (buffer_t *buffer, bufferDatatype data)
	add data to the end of the ringbuffer More...

bufferStatus_t	bufferWriteOverwrite (buffer_t *buffer, bufferDatatype data)
	Add data to the end of the ringbuffer. If the buffer is full, overwrite the first data. More...

bufferStatus_t	bufferRead (buffer_t buffer, bufferDatatype data)
	read data from the beginning of the buffer More...

bufferStatus_t	bufferPeek (buffer_t buffer, bufferDatatype data)
	have a look at the next element in the buffer, but do not increase the read pointer More...

bufferStatus_t	bufferFill (buffer_t *buffer, bufferDatatype data, uint8_t silent)
	fill the whole buffer with given dummy data. More...

bufferStatus_t	bufferAvailable (buffer_t buffer, uint16_t available)
	return, how many elements are stored and available in the buffer More...

bufferStatus_t	bufferMean (buffer_t buffer, bufferDatatype meanOut)
	take the average of the whole buffer More...

bufferStatus_t	bufferMeanRMS (buffer_t buffer, bufferDatatype meanOut)
	take the root mean square of the whole buffer More...

Detailed Description

A universal ringbuffer library.

Author: Peter Kappelt

See also: https://github.com/peterkappelt/kBuffer

Copyright: Peter Kappelt 2016; MIT License (see LICENSE.txt in the root of this repository)

Enumeration Type Documentation

enum bufferStatus_t

buffer function return codes

Enumerator
bufferOK	it seems, as everything worked as expected
bufferMemoryAllocationFailed	happens while allocating memory, there is not enough free memory (->malloc failed)
bufferEmpty	happens at reading data, buffer is empty and there is no more data to read
bufferFull	happens at writing data, buffer is full, no more data can be written
bufferNotInitialized	The buffer is not initialized
bufferError	an error occured, which isn't explained nearer. Have a look at the according function

Function Documentation

bufferStatus_t bufferAvailable	(	buffer_t *	buffer,
		uint16_t *	available
	)

return, how many elements are stored and available in the buffer

Parameters

buffer	pointer to a buffer_t instance
available	pointer to a variable where the number of available elements should be stored

Returns: an element of bufferStatus_t

Return values

bufferOK	it worked as expected
bufferNotInitialized	the buffer wasn't initialized

bufferStatus_t bufferFill	(	buffer_t *	buffer,
		bufferDatatype	data,
		uint8_t	silent
	)

fill the whole buffer with given dummy data.

Parameters

buffer	pointer buffer_t instance
data	data to fill the buffer with
silent	if this parameter is 1, the buffer will be filled with data, but the write pointer stays at its current position (usefull, if you take the mean but the buffer is not full yet. You can just prefill it, the mean will be taken with the prefilled values)

Returns: an element of bufferStatus_t

Return values

bufferOK	it worked as expected
bufferNotInitialized	the buffer wasn't initialized

bufferStatus_t bufferInit	(	buffer_t *	buffer,
		uint16_t	bufferSize
	)

init a new buffer This function inits a new buffer_t.

Parameters

buffer	Pointer (&) to a buffer_t object.
bufferSize	desired size of the buffer, the total buffer size (e.g. length-of-datatype * bufferSize) may not exceed 2^16 bytes

Returns: an element of bufferStatus_t

Return values

bufferMemoryAllocationFailed	The memory allocation with malloc failed. Make sure, you have enough memory available
bufferOK	It seems, like everything went well

bufferStatus_t bufferInitStatic	(	buffer_t *	buffer,
		uint16_t	bufferSize,
		bufferDatatype *	bufferArray
	)

init a new buffer This function inits a new buffer_t, but doesn't allocate the memory dynamically
You've to provide an array of the datatype and the required length when calling this function.
This function might be useful, if you want to save the overhead of the malloc() function

Parameters

buffer	Pointer (&) to a buffer_t object.
bufferSize	desired size of the buffer, the total buffer size (e.g. length-of-datatype * bufferSize) may not exceed 2^16 bytes
bufferArray	pointer to a array of the type bufferDatatype, which is bufferSize elements long

Returns: an element of bufferStatus_t

Return values

bufferOK It seems, like everything went well

uint8_t bufferIsEmpty ( buffer_t * buffer )

Checks, wheter the buffer is empty.

Parameters

buffer Pointer to a buffer_t instance

Return values

1	buffer is empty
0	buffer is not empty

uint8_t bufferIsFull ( buffer_t * buffer )

Checks, wheter the buffer is full.

Parameters

buffer Pointer to a buffer_t instance

Return values

1	buffer is full
0	buffer is not full

bufferStatus_t bufferMean	(	buffer_t *	buffer,
		bufferDatatype *	meanOut
	)

take the average of the whole buffer

Parameters

buffer	pointer to a buffer_t instance
meanOut	pointer to a variable, where the mean will be stored

Returns: a element of bufferStatus_t

Return values

bufferOK	it worked as expected, the mean is stored at the given variable
bufferNotInitialized	the buffer is not initialized

Bug:: The sum of the buffer is taken. Take precautions, that this variable won't overflow

bufferStatus_t bufferMeanRMS	(	buffer_t *	buffer,
		bufferDatatype *	meanOut
	)

take the root mean square of the whole buffer

Parameters

buffer	pointer to a buffer_t instance
meanOut	pointer to a variable, where the mean will be stored

Returns: a element of bufferStatus_t

Return values

bufferOK	it worked as expected, the mean is stored at the given variable
bufferNotInitialized	the buffer is not initialized

Bug:: The sum of squared buffer elements is taken. Take precautions, that this variable won't overflow

bufferStatus_t bufferPeek	(	buffer_t *	buffer,
		bufferDatatype *	data
	)

have a look at the next element in the buffer, but do not increase the read pointer

Parameters

buffer	pointer to a buffer_t instance
data	pointer to a variable where data should be stored

Returns: a element of bufferStatus_t

Return values

bufferOK	it worked as expected
bufferNotInitialized	the bufferInit() method hasn't been called or failed before
bufferEmpty	the buffer is empty an no more data can be read

bufferStatus_t bufferRead	(	buffer_t *	buffer,
		bufferDatatype *	data
	)

read data from the beginning of the buffer

Parameters

buffer	pointer to a buffer_t instance
data	pointer to a variable where data should be stored

Returns: a element of bufferStatus_t

Return values

bufferOK	it worked as expected
bufferNotInitialized	the bufferInit() method hasn't been called or failed before
bufferEmpty	the buffer is empty an no more data can be read

bufferStatus_t bufferReadFromIndex	(	buffer_t *	buffer,
		uint16_t	index,
		bufferDatatype *	data
	)

read data from a specifig index of the buffer WARNING: Take care when using this function, it is against the main concept of a ringbuffer

Parameters

buffer	Pointer to a buffer_t instance
index	The index, where data should be written. It can be in range 0 to length - 1
data	Pointer to a variable where the read data should be written to.

Returns: an element of bufferStatus_t

Return values

bufferOK	It went successfull
bufferNotInitialized	The buffer is not initialized. You have to call bufferInit before (or the init failed before)
bufferError	The desired data index is out of range

bufferStatus_t bufferWrite	(	buffer_t *	buffer,
		bufferDatatype	data
	)

add data to the end of the ringbuffer

Parameters

buffer	pointer to a buffer_t instance
data	data which should be written

Returns: a element of bufferStatus_t

Return values

bufferOK	it worked as expected
bufferNotInitialized	the bufferInit() method hasn't been called or failed before
bufferFull	the buffer is full an no more data can be written

bufferStatus_t bufferWriteOverwrite	(	buffer_t *	buffer,
		bufferDatatype	data
	)

Add data to the end of the ringbuffer. If the buffer is full, overwrite the first data.

Parameters

buffer	pointer to a buffer_t instance
data	data which should be written

Returns: a element of bufferStatus_t

Return values

bufferOK	it worked as expected
bufferNotInitialized	the bufferInit() method hasn't been called or failed before

bufferStatus_t bufferWriteToIndex	(	buffer_t *	buffer,
		uint16_t	index,
		bufferDatatype	data
	)

write data to a specific index of the buffer. WARNING: Take care when using this function, it is against the main concept of a ringbuffer

Parameters

buffer	Pointer to a buffer_t instance
index	The index, where data should be written. It can be in range 0 to length - 1
data	The actual data which should be written

Returns: an element of bufferStatus_t

Return values

bufferOK	It went successfull
bufferNotInitialized	The buffer is not initialized. You have to call bufferInit before (or the init failed before)
bufferError	The desired data index is out of range

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation