Table of Contents

Class CircularBuffer<T>

Namespace
VisioForge.Core.Helpers
Assembly
VisioForge.Core.dll

A generic circular buffer implementation that allows efficient insertion and removal of elements at both ends of the buffer. When the buffer reaches full capacity, adding new elements will automatically remove elements from the opposite end.

public class CircularBuffer<T> : IEnumerable<T>, IEnumerable

Type Parameters

T

The type of elements stored in the circular buffer.

Inheritance

Implements

Inherited Members

Remarks

When writing to a full buffer:

  • PushBack() removes the element at Front() (this[0])
  • PushFront() removes the element at Back() (this[Size-1])

This implementation is inspired by the Boost circular_buffer library: http://www.boost.org/doc/libs/1_53_0/libs/circular_buffer/doc/circular_buffer.html

Constructors

CircularBuffer(int)

Initializes a new instance of the VisioForge.Core.Helpers.CircularBuffer`1 class with the specified capacity.

public CircularBuffer(int capacity)

Parameters

capacity int

The maximum number of elements that the buffer can hold. Must be positive.

Exceptions

ArgumentException

Thrown when capacity is less than 1.

CircularBuffer(int, T[])

Initializes a new instance of the VisioForge.Core.Helpers.CircularBuffer`1 class with the specified capacity and pre-fills it with the provided items.

public CircularBuffer(int capacity, T[] items)

Parameters

capacity int

The maximum number of elements that the buffer can hold. Must be positive.

items T[]

Initial items to fill the buffer with. The length must not exceed the capacity. Tip: Use Skip(x).Take(y).ToArray() to build this parameter from any enumerable.

Exceptions

ArgumentException

Thrown when capacity is less than 1 or when items length exceeds capacity.

ArgumentNullException

Thrown when items is null.

Properties

Capacity

Gets the maximum capacity of the circular buffer.

public int Capacity { get; }

Property Value

int

Remarks

When the buffer reaches maximum capacity (IsFull = true), pushing new elements will automatically remove elements from the opposite end to maintain the capacity limit.

IsEmpty

Gets a value indicating whether the circular buffer is empty.

public bool IsEmpty { get; }

Property Value

bool

IsFull

Gets a value indicating whether the circular buffer is at full capacity.

public bool IsFull { get; }

Property Value

bool

Remarks

When the buffer is full, adding new elements will cause elements to be removed from the opposite end of the buffer to maintain the capacity constraint.

Size

Gets the current number of elements contained in the circular buffer.

public int Size { get; }

Property Value

int

this[int]

Gets or sets the element at the specified index in the buffer.

public T this[int index] { get; set; }

Property Value

T

Remarks

The index does not wrap around; valid indices are in the range [0, Size).

Exceptions

IndexOutOfRangeException

Thrown when index is negative, greater than or equal to Size, or when the buffer is empty.

Methods

Back()

Returns the element at the back of the buffer without removing it.

public T Back()

Returns

T

The element at the back of the buffer (equivalent to this[Size - 1]).

Exceptions

InvalidOperationException

Thrown when the buffer is empty.

Clear()

Removes all elements from the circular buffer.

public void Clear()

Remarks

After this operation, Size will be 0 but Capacity remains unchanged. All elements in the internal buffer are set to their default values.

Front()

Returns the element at the front of the buffer without removing it.

public T Front()

Returns

T

The element at the front of the buffer (equivalent to this[0]).

Exceptions

InvalidOperationException

Thrown when the buffer is empty.

GetEnumerator()

Returns an enumerator that iterates through the circular buffer.

public IEnumerator<T> GetEnumerator()

Returns

IEnumerator<T>

An enumerator that can be used to iterate through the buffer from front to back.

Remarks

The enumeration preserves the logical order of elements regardless of their physical arrangement in the internal buffer.

PopBack()

Removes and discards the element at the back of the circular buffer.

public void PopBack()

Remarks

This operation decreases the buffer size by 1.

Exceptions

InvalidOperationException

Thrown when the buffer is empty.

PopFront()

Removes and discards the element at the front of the circular buffer.

public void PopFront()

Remarks

This operation decreases the buffer size by 1.

Exceptions

InvalidOperationException

Thrown when the buffer is empty.

PushBack(T)

Adds an element to the back of the circular buffer.

public void PushBack(T item)

Parameters

item T

The element to add to the back of the buffer.

Remarks

After this operation, Back() and this[Size-1] will return the newly added element. If the buffer is full, the element at the front (Front()/this[0]) will be removed to make room for the new element.

PushFront(T)

Adds an element to the front of the circular buffer.

public void PushFront(T item)

Parameters

item T

The element to add to the front of the buffer.

Remarks

After this operation, Front() and this[0] will return the newly added element. If the buffer is full, the element at the back (Back()/this[Size-1]) will be removed to make room for the new element.

IEnumerable.GetEnumerator()

Returns a non-generic enumerator that iterates through the circular buffer.

IEnumerator IEnumerable.GetEnumerator()

Returns

IEnumerator

An IEnumerator that can be used to iterate through the buffer.

ToArray()

Copies all elements from the circular buffer to a new array.

public T[] ToArray()

Returns

T[]

A new array containing copies of the elements in the buffer, ordered from front to back.

Remarks

The returned array preserves the logical order of elements (from front to back), regardless of their physical arrangement in the internal buffer.

ToArraySegments()

Gets the contents of the buffer as two ArraySegment instances without copying the elements.

public IList<ArraySegment<T>> ToArraySegments()

Returns

IList<ArraySegment<T>>

An IList containing two ArraySegment instances that represent the buffer contents.

Remarks

This method provides a zero-copy view of the buffer contents, which is useful for performance-critical scenarios such as network operations (e.g., Send(IList<ArraySegment<byte>>)).

The segments preserve the logical order of elements from front to back. Either or both segments may be empty depending on the buffer state.