@stdlib/utils-circular-buffer

v0.2.1

Published

3 months ago

Circular buffer.

Downloads

106

Circular Buffer

Circular buffer constructor.

Installation

npm install @stdlib/utils-circular-buffer

Usage

var circularBuffer = require( '@stdlib/utils-circular-buffer' );

circularBuffer( buffer )

Returns a new circular buffer instance.

var buf = circularBuffer( 3 );
// returns <CircularBuffer>

The buffer argument may either be a integer which specifies the buffer size or an array-like object to use as the underlying buffer.

var Float64Array = require( '@stdlib/array-float64' );

// Use a typed array as the underlying buffer:
var buf = circularBuffer( new Float64Array( 3 ) );
// returns <CircularBuffer>

circularBuffer.prototype.clear()

Clears a buffer.

var buf = circularBuffer( 3 );
// returns <CircularBuffer>

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );

// Get the number of elements currently in the buffer:
var n = buf.count;
// returns 3

// Clear all buffer items:
buf.clear();

// Get the number of elements in the buffer:
n = buf.count;
// returns 0

circularBuffer.prototype.count

Read-only property which returns the number of elements currently in the buffer.

var buf = circularBuffer( 3 );
// returns <CircularBuffer>

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );

// Determine how many elements are in the buffer:
var n = buf.count;
// returns 2

circularBuffer.prototype.full

Read-only property which returns a boolean indicating if a buffer is full.

var buf = circularBuffer( 3 );
// returns <CircularBuffer>

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );

// Determine if the buffer is full:
var bool = buf.full;
// returns false

// Add another value to the buffer:
buf.push( 'beep' );

// Determine if the buffer is full:
bool = buf.full;
// returns true

circularBuffer.prototype.iterator( [niters] )

Returns an iterator for iterating over a buffer. If an environment supports Symbol.iterator, the returned iterator is iterable.

var buf = circularBuffer( 2 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Create an iterator:
var it = buf.iterator();

// Iterate over the buffer...
var v = it.next().value;
// returns 'beep'

v = it.next().value;
// returns 'boop'

v = it.next().value;
// returns 'beep'

v = it.next().value;
// returns 'boop'

v = it.next().value;
// returns 'beep'

By default, provided a buffer is full, the method returns an infinite iterator. To limit the number of iterations, provide an niters argument.

var buf = circularBuffer( 2 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Create an iterator:
var it = buf.iterator( buf.length );

// Iterate over the buffer...
var v = it.next().value;
// returns 'beep'

v = it.next().value;
// returns 'boop'

var bool = it.next().done;
// returns true

A returned iterator does not iterate over partially full circular buffers.

var buf = circularBuffer( 5 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );

// Create an iterator:
var it = buf.iterator();

// Determine if the buffer is full:
var bool = buf.full;
// returns false

// Iterate over the buffer...
bool = it.next().done;
// returns true

If iterating over a partially full circular buffer is necessary, use buf.toArray() and iterate over the returned array.

circularBuffer.prototype.length

Read-only property returning the buffer length (i.e., capacity).

var buf = circularBuffer( [ 0, 0, 0 ] );

// Get the buffer length:
var len = buf.length;
// returns 3

circularBuffer.prototype.push( value )

Adds a value to the buffer.

var buf = circularBuffer( 3 );

// Fill the buffer...
var v = buf.push( 'foo' );
// returns undefined

v = buf.push( 'bar' );
// returns undefined

v = buf.push( 'beep' );
// returns undefined

// Now that the buffer is full, each push will cause a value to be removed:
v = buf.push( 'boop' );
// returns 'foo'

When a circular buffer is empty or partially full, this method returns undefined. Once a circular buffer is full, the method returns removed values.

circularBuffer.prototype.toArray()

Returns an array of buffer values.

var buf = circularBuffer( 3 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Get an array of buffer values:
var vals = buf.toArray();
// returns [ 'bar', 'beep', 'boop' ]

circularBuffer.prototype.toJSON()

Serializes a circular buffer as JSON.

var buf = circularBuffer( 3 );

// Add values to the buffer:
buf.push( 'foo' );
buf.push( 'bar' );
buf.push( 'beep' );
buf.push( 'boop' );

// Serialize to JSON:
var o = buf.toJSON();
// returns { 'type': 'circular-buffer', 'length': 3, 'data': [ 'bar', 'beep', 'boop' ] }

Note: JSON.stringify() implicitly calls this method when stringifying a circular buffer instance.

Notes

The constructor supports array-like object buffer arguments which use getter and setter accessors for element access (e.g., Complex64Array, Complex128Array, etc).

Examples

var circularBuffer = require( '@stdlib/utils-circular-buffer' );

// Create a circular buffer capable of holding 5 elements:
var buf = circularBuffer( 5 );
console.log( 'Buffer length: %s', buf.length );

// Continuously add values to the buffer...
var v;
var i;
for ( i = 0; i < 100; i++ ) {
    v = buf.push( i );
    console.log( 'Count: %d. Added value: %s. Removed value: %s.', buf.count, i, ( v === void 0 ) ? '(none)' : v );
}

Notice

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

Community

License

See LICENSE.