Circular Buffer Reference

 In Arduino Libraries

CircularBuffer is a circular buffer template for Arduino. The template takes two parameters:

  1. the type of data to store
  2. the maximum number of items to store in the buffer

The buffer starts empty. Items are added to the end of the buffer and can be removed from the start of the buffer. If more items are added than there is room in the buffer, the oldest ones are overwritten.

Forward and reverse iterators are implemented to walk through all the items in the buffer. Forward iterators start with the oldest item in the buffer. Reverse iterators start with the newest item in the buffer. The iterators are children of the CircularBuffer class.

The circular buffer uses a fixed size array to store inserted items. It does no dynamic memory allocation.

Example

This example uses a circular buffer to monitor a switch between pin 3 and ground being closed. Most switches don’t turn on immediately but ‘bounce‘. The time of each bounce is stored in the circular buffer. The buffer is printed every few seconds.

Declaration

A circular buffer variable can be declared using:
CircularBuffer<unsigned long, 15> MyCircularBuffer

The first template parameter (between the < and >) sets the type of data that will be stored in the buffer. It can be a simple type (such as an int, float etc), or a complex type (class or struct).

The second parameter is the maximum number of items to store in the circular buffer.

Because the ForwardIterator and ReverseIterator are children of the CircularBuffer, it may be helpful to use a type definition to save repeating the template parameters every time you want an iterator. Define a type for your buffer as follows:
typedef CircularBuffer<unsigned long, 15> MyCircularBufferType.

Then create a buffer variable using:
MyCircularBufferType MyBuffer

and iterators as:
MyCircularBufferType::ForwardIterator MyIterator(MyBuffer);
MyCircularBufferType::ReverseIterator MyIterator(MyBuffer);

Circular Buffer Functions

ElementSize()

Returns the number of bytes used by each item stored in the buffer.

IsEmpty()

Returns true if the buffer contains no items, or false if it contains 1 or more items.

Add(data)

Adds the item data to the end of the circular buffer. If the buffer is full, the oldest item in the buffer will be overwritten.

Head()

Returns the last value (the one most recently added) in the buffer.

Tail()

Returns the oldest value that is still in the buffer. It might not be the first item added if the buffer has already wrapped.

PopTail()

Removes the oldest value from the buffer.

DropRecords(RecordCount)

Removes RecordCount items from the start of the buffer.

Clear()

Removes all items from the buffer.

MaxSize()

Returns the maximum number of items that can be stored in the buffer.

Dump(Destination)

Writes the content of the buffer to a print stream. For example, MyBuffer.Dump(Serial); will write the content of the buffer to the serial port.

Iterator Functions

These functions are available for both forward and reverse iterators. Iterators are child classes of the CircularBuffer. They are both created with a single parameter: the circular buffer to iterate over.

CurrentValue()

Returns the current iterator value. Undefined if AtEnd() is true.

CurrentIndex()

Returns the current item number.

CurrentIndex()

Returns the position of the current item in the internal buffer.

Next()/Previous()

Moves the iterator to the next (ForwardIterator) or previous (ReverseIterator) item in the buffer, if it isn’t already at the end. If it is at the end, the iterator doesn’t move.

AtEnd()

Returns true if the iterator is at the end of the buffer and there are no more items to read.

Recent Posts

Leave a Comment

Contact Us

Send us an email and we will get back to you shortly.

Not readable? Change text.

Start typing and press Enter to search