About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please consider financially supporting stdlib. We greatly appreciate your continued support!

Circular Buffer

Circular buffer constructor.

Installation

npm install @stdlib/utils-circular-buffer

Alternatively,

• To load the package in a website via a script tag without installation and bundlers, use the ES Module available on the esm branch (see README).
• If you are using Deno, visit the deno branch (see README for usage intructions).
• For use in Observable, or in browser/node environments, use the Universal Module Definition (UMD) build available on the umd branch (see README).

The branches.md file summarizes the available branches and displays a diagram illustrating their relationships.

To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.

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 );
}

---

See Also

• @stdlib/utils-fifo: first-in-first-out (FIFO) queue.
• @stdlib/utils-stack: stack.

---

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.

Copyright

Copyright © 2016-2024. The Stdlib Authors.