https://github.com/stdlib-js/dstructs-circular-buffer
Circular buffer.
https://github.com/stdlib-js/dstructs-circular-buffer
buffer circular collection cyclic data data-structure data-structures fifo first-in-first-out javascript node node-js nodejs queue ring stdlib structure
Last synced: about 1 year ago
JSON representation
Circular buffer.
- Host: GitHub
- URL: https://github.com/stdlib-js/dstructs-circular-buffer
- Owner: stdlib-js
- License: apache-2.0
- Created: 2025-02-24T09:19:34.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-17T02:22:55.000Z (about 1 year ago)
- Last Synced: 2025-03-17T02:42:03.837Z (about 1 year ago)
- Topics: buffer, circular, collection, cyclic, data, data-structure, data-structures, fifo, first-in-first-out, javascript, node, node-js, nodejs, queue, ring, stdlib, structure
- Language: JavaScript
- Homepage: https://github.com/stdlib-js/stdlib
- Size: 368 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Security: SECURITY.md
Awesome Lists containing this project
README
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
[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url]
> Circular buffer constructor.
## Installation
```bash
npm install @stdlib/dstructs-circular-buffer
```
Alternatively,
- To load the package in a website via a `script` tag without installation and bundlers, use the [ES Module][es-module] available on the [`esm`][esm-url] branch (see [README][esm-readme]).
- If you are using Deno, visit the [`deno`][deno-url] branch (see [README][deno-readme] for usage intructions).
- For use in Observable, or in browser/node environments, use the [Universal Module Definition (UMD)][umd] build available on the [`umd`][umd-url] branch (see [README][umd-readme]).
The [branches.md][branches-url] 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
```javascript
var circularBuffer = require( '@stdlib/dstructs-circular-buffer' );
```
#### circularBuffer( buffer )
Returns a new circular buffer instance.
```javascript
var buf = circularBuffer( 3 );
// returns
```
The `buffer` argument may either be a integer which specifies the buffer size or an array-like object to use as the underlying buffer.
```javascript
var Float64Array = require( '@stdlib/array-float64' );
// Use a typed array as the underlying buffer:
var buf = circularBuffer( new Float64Array( 3 ) );
// returns
```
##### circularBuffer.prototype.clear()
Clears a buffer.
```javascript
var buf = circularBuffer( 3 );
// returns
// 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.
```javascript
var buf = circularBuffer( 3 );
// returns
// 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.
```javascript
var buf = circularBuffer( 3 );
// returns
// 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.
```javascript
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.
```javascript
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.
```javascript
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).
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
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`][@stdlib/array/complex64], [`Complex128Array`][@stdlib/array/complex128], etc).
## Examples
```javascript
var circularBuffer = require( '@stdlib/dstructs-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/dstructs-fifo`][@stdlib/dstructs/fifo]: first-in-first-out (FIFO) queue.
- [`@stdlib/dstructs-stack`][@stdlib/dstructs/stack]: stack.
* * *
## Notice
This package is part of [stdlib][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][stdlib], see the main project [repository][stdlib].
#### Community
[![Chat][chat-image]][chat-url]
---
## License
See [LICENSE][stdlib-license].
## Copyright
Copyright © 2016-2025. The Stdlib [Authors][stdlib-authors].
[npm-image]: http://img.shields.io/npm/v/@stdlib/dstructs-circular-buffer.svg
[npm-url]: https://npmjs.org/package/@stdlib/dstructs-circular-buffer
[test-image]: https://github.com/stdlib-js/dstructs-circular-buffer/actions/workflows/test.yml/badge.svg?branch=main
[test-url]: https://github.com/stdlib-js/dstructs-circular-buffer/actions/workflows/test.yml?query=branch:main
[coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/dstructs-circular-buffer/main.svg
[coverage-url]: https://codecov.io/github/stdlib-js/dstructs-circular-buffer?branch=main
[chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg
[chat-url]: https://app.gitter.im/#/room/#stdlib-js_stdlib:gitter.im
[stdlib]: https://github.com/stdlib-js/stdlib
[stdlib-authors]: https://github.com/stdlib-js/stdlib/graphs/contributors
[umd]: https://github.com/umdjs/umd
[es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
[deno-url]: https://github.com/stdlib-js/dstructs-circular-buffer/tree/deno
[deno-readme]: https://github.com/stdlib-js/dstructs-circular-buffer/blob/deno/README.md
[umd-url]: https://github.com/stdlib-js/dstructs-circular-buffer/tree/umd
[umd-readme]: https://github.com/stdlib-js/dstructs-circular-buffer/blob/umd/README.md
[esm-url]: https://github.com/stdlib-js/dstructs-circular-buffer/tree/esm
[esm-readme]: https://github.com/stdlib-js/dstructs-circular-buffer/blob/esm/README.md
[branches-url]: https://github.com/stdlib-js/dstructs-circular-buffer/blob/main/branches.md
[stdlib-license]: https://raw.githubusercontent.com/stdlib-js/dstructs-circular-buffer/main/LICENSE
[@stdlib/array/complex64]: https://github.com/stdlib-js/array-complex64
[@stdlib/array/complex128]: https://github.com/stdlib-js/array-complex128
[@stdlib/dstructs/fifo]: https://github.com/stdlib-js/dstructs-fifo
[@stdlib/dstructs/stack]: https://github.com/stdlib-js/dstructs-stack