CBuffer

JavaScript Circular Buffer Utility

The end goal of this project is to implement the entire JavaScript Array.prototype, and some additional utility methods, as a circular buffer.

Note: This is called a circular buffer because of what this library accomplishes, but is implemented as an Array. This may be confusing for Node users, which may want to use a true Buffer.

As JavaScript is used for more and more computationally intensive tasks, it's important to reduce execution and garbage collection time. By using a circular buffer instead of a native array less extraneous data bits are generated that will need to be cleaned up later. So use of this library is two fold: First, if you need a circular buffer for the classical reasons (animation queue, video streaming) this library can help you out. Second, if you know the maximum size of an array you'll be working with, using CBuffer can drastically reduce the memory footprint of your application.

While the entire Array.prototype API is on the roadmap, it's not all quite here. Below is the currently implemented API.

Usage

It's simple. Just use it like you would use an Array.

new CBuffer(10);      // empty buffer with length of 10
new CBuffer(1,2,3,4); // buffer with length 4
CBuffer(5);           // For those who are really lazy, new is optional

Included are several non-standard niceties. Like if you want to catch when data is overwritten, just assign a function to the overflow variable and it will be called whenever a value is about to be overwritten and it will pass the value as the first argument:

var myBuff = CBuffer(4);
myBuff.overflow = function(data) {
    console.log(data);
};

myBuff.push(1,2,3,4); // nothing shows up yet
myBuff.push(5);       // log: 1

API

Mutator Methods

• pop - Removes the last element from a circular buffer and returns that element.
• push - Adds one or more elements to the end of a circular buffer and returns the new size.
• reverse - Reverses the order of the elements of a circular buffer.
• rotateLeft - Rotates all elements left 1, or n, times.
• rotateRight - Rotates all elements right 1, or n, times.
• shift - Removes the first element from a circular buffer and returns that element.
• sort - Sorts the elements of a circular buffer.
• unshift - Adds one or more elements to the front of a circular buffer and returns the new size.

Accessor Methods

• indexOf - Returns the first (least) index of an element within the circular buffer equal to the specified value, or -1 if none is found.
• lastIndexOf - Returns the last (greatest) index of an element within the circular buffer equal to the specified value, or -1 if none is found.

Iteration Methods

• every - Returns true if every element in the circular buffer satisfies the provided testing function.
• forEach - Calls a function for each element in the circular buffer.
• some - Returns true if at least one element in the circular buffer satisfies the provided testing function.

Utility Methods

• empty - Equivalent to setting Array.length = 0.
• fill - Fill all set values with passed argument. Also supports functions.
• first - Returns first value in circular buffer.
• last - Returns last value in circular buffer.
• get - Get value at specific index.
• set - Set value as specific index.
• toArray - Return clean ordered array of buffer.
• overflow - Set to function and will be called when data is about to be overwritten.