# Mnemonist

## Circular Buffer

The `CircularBuffer` is a buffer with a fixed capacity that can be used both as a LIFO or FIFO list very efficiently.

As such, it is mainly used as a fixed capacity `Queue`.

For more information about the circular buffer, you can head here.

Note, that contrary to the `FixedDeque`, the `CircularBuffer` will overwrite old values when overflowing capacity.

``````const CircularBuffer = require('mnemonist/circular-buffer');
``````

## Constructor

The `CircularBuffer` takes two arguments: a array class to use, and the desired capacity.

``````const buffer = new CircularBuffer(Array, 10);
``````
``````// Using byte arrays
const buffer = new CircularBuffer(Int8Array, 10);
``````

### Static #.from

Alternatively, one can build a `CircularBuffer` from an arbitrary JavaScript iterable likewise:

``````// Attempting the guess the given iterable's length/size
const buffer = CircularBuffer.from([1, 2, 3], Int8Array);
``````
``````// Providing the desired capacity
const buffer = CircularBuffer.from([1, 2, 3], Int8Array, 10);
``````

## Methods

Mutation

Read

Iteration

### #.capacity

Maximum number of items the buffer is able to store.

``````const buffer = new CircularBuffer(Array, 10);
buffer.capacity
>>> 10
``````

### #.size

Number of items in the buffer.

``````const buffer = new CircularBuffer(Array, 10);
buffer.size
>>> 0
``````

### #.push

Append an item at the end of the buffer.

Will overwrite first value when the buffer’s capacity is exceeded.

`O(1)`

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
``````

### #.unshift

Prepend an item at the beginning of the buffer.

Will overwrite the last value when the buffer’s capacity is exceeded.

`O(1)`

``````const buffer = new CircularBuffer(Array, 10);

buffer.unshift(1);
``````

### #.pop

Retrieve & remove the last item of the buffer.

`O(1)`

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
buffer.push(2);
buffer.pop();
>>> 2
``````

### #.shift

Retrieve & remove the first item of the buffer.

`O(1)`

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
buffer.push(2);
buffer.shift();
>>> 1
``````

Completely clears the buffer.

`O(1)`

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
buffer.clear();
buffer.toArray();
>>> []
``````

### #.peekFirst

Retrieves the first item of the buffer.

`O(1)`

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
buffer.push(2);
buffer.peekFirst();
>>> 1
``````

### #.peekLast

Retrieves the last item of the buffer.

`O(1)`

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
buffer.push(2);
buffer.peekLast();
>>> 2
``````

### #.forEach

Iterates over the buffer’s values.

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
buffer.push(2);

buffer.forEach((item, index, buffer) => {
console.log(index, item);
});
``````

### #.toArray

Converts the buffer into a JavaScript array.

Note that the resulting array will be instantiated using the provided class.

``````const buffer = new CircularBuffer(Array, 10);

buffer.push(1);
buffer.push(2);

buffer.toArray();
>>> [1, 2]
``````

### #.values

Returns an iterator over the buffer’s values.

``````const buffer = CircularBuffer.from([1, 2, 3], Array);

const iterator = buffer.values();

iterator.next().value
>>> 1
``````

### #.entries

Returns an iterator over the buffer’s entries.

``````const buffer = CircularBuffer.from([1, 2, 3], Array);

const iterator = buffer.entries();

iterator.next().value
>>> [0, 1]
``````

### Iterable

Alternatively, you can iterate over a buffer’s values using ES2015 `for...of` protocol:

``````const buffer = CircularBuffer.from([1, 2, 3], Array);

for (const item of buffer) {
console.log(item);
}
``````