3.0.6 • Published 6 years ago
@unibtc/better-cbuffer v3.0.6
JavaScript Circular Buffer Utility
Forked from CBuffer with additional enhancements
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.
Below is the currently implemented API.
Installation
npm install better-cbuffer
oryarn add better-cbuffer
Usage
It's simple. Just use it like you would use an Array.
new CBuffer(10); // empty buffer with size of 10
new CBuffer(1,2,3,4); // buffer with size 4
new CBuffer([1,2,3,4,5]); // buffer with size 5
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 = new 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 length.
- 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. Unlike native
sort
, the default comparitor sorts bya > b
. - unshift - Adds one or more elements to the front of a circular buffer and returns the new length.
- filter - Removes the elements that does not pass the condition. Mutates the Buffer
- map - Iterate over each element and mutates them. Mutates the Buffer
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.
- sortedIndex - Returns the position some
value
would be inserted into a sorted circular buffer ranked by an optional comparitor. - from - Creates and returns a new Buffer instance using the arguments.
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
. - clear - Equivalent to
CBuffer.fill(undefined).empty()
- fill - Fill 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.
- slice - Return a slice of the buffer as an array.
Benchmark
- run
node speed/index
shift 1e4 - CBuffer x 80,594 ops/sec ±4.19% (82 runs sampled)
pop 1e5 - CBuffer x 8,424 ops/sec ±3.61% (88 runs sampled)
filter - CBuffer x 14,883,389 ops/sec ±2.06% (79 runs sampled)
reverse - CBuffer x 99,982,055 ops/sec ±2.24% (87 runs sampled)
push 1e5 - CBuffer x 377,083,872 ops/sec ±2.87% (86 runs sampled)
unshift 1e5 - CBuffer x 366,588,191 ops/sec ±3.29% (80 runs sampled)
shift 1e4 - Array x 64,866 ops/sec ±6.62% (80 runs sampled)
pop 1e5 - Array x 6,204 ops/sec ±6.85% (65 runs sampled)
filter - Array x 335 ops/sec ±5.64% (69 runs sampled)
reverse - Array x 9,094 ops/sec ±5.21% (82 runs sampled)
push 1e5 - Array x 6,327,845 ops/sec ±3.83% (77 runs sampled)
unshift 1e5 - Array x 6,876,578 ops/sec ±4.29% (79 runs sampled)
Fastest is pop 1e5 - CBuffer
Fastest is shift 1e4 - CBuffer
Fastest is filter - CBuffer
Fastest is reverse - CBuffer
Fastest is push 1e5 - CBuffer
Fastest is unshift 1e5 - CBuffer