@stdlib/dstructs-circular-buffer 0.1.0

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../lib/main.js", "../lib/index.js"],
+  "sourcesContent": ["/**\n* @license Apache-2.0\n*\n* Copyright (c) 2018 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n*    http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n/* eslint-disable no-restricted-syntax, no-invalid-this */\n\n'use strict';\n\n// MODULES //\n\nvar isCollection = require( '@stdlib/assert-is-collection' );\nvar isPositiveInteger = require( '@stdlib/assert-is-positive-integer' ).isPrimitive;\nvar isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;\nvar setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );\nvar setReadOnlyAccessor = require( '@stdlib/utils-define-nonenumerable-read-only-accessor' );\nvar iteratorSymbol = require( '@stdlib/symbol-iterator' );\nvar MAX_ITERATIONS = require( '@stdlib/constants-float64-max' );\nvar arraylike2object = require( '@stdlib/array-base-arraylike2object' );\nvar format = require( '@stdlib/string-format' );\n\n\n// MAIN //\n\n/**\n* Circular buffer constructor.\n*\n* @constructor\n* @param {(PositiveInteger|Collection)} buffer - buffer size or an array-like object to use as the underlying buffer\n* @throws {TypeError} must provide either a valid buffer size or an array-like object\n* @returns {CircularBuffer} circular buffer instance\n*\n* @example\n* var b = new CircularBuffer( 3 );\n*\n* // Fill the buffer...\n* var v = b.push( 'foo' );\n* // returns undefined\n*\n* v = b.push( 'bar' );\n* // returns undefined\n*\n* v = b.push( 'beep' );\n* // returns undefined\n*\n* // Add another value to the buffer and return the removed element:\n* v = b.push( 'boop' );\n* // returns 'foo'\n*/\nfunction CircularBuffer( buffer ) {\n\tvar buf;\n\tvar i;\n\tif ( !(this instanceof CircularBuffer) ) {\n\t\treturn new CircularBuffer( buffer );\n\t}\n\tif ( isPositiveInteger( buffer ) ) {\n\t\tbuf = [];\n\t\tfor ( i = 0; i < buffer; i++ ) {\n\t\t\tbuf.push( 0.0 ); // initialize with zeros, but could be any value (we're just ensuring a contiguous block of memory)\n\t\t}\n\t} else if ( isCollection( buffer ) ) {\n\t\tbuf = buffer;\n\t} else {\n\t\tthrow new TypeError( format( 'invalid argument. Must provide either a valid buffer size (i.e., a positive integer) or an array-like object which can serve as the underlying buffer. Value: `%s`.', buffer ) );\n\t}\n\tthis._buffer = arraylike2object( buf );\n\tthis._length = buf.length;\n\tthis._count = 0;\n\tthis._i = -1;\n\treturn this;\n}\n\n/**\n* Clears the buffer.\n*\n* @name clear\n* @memberof CircularBuffer.prototype\n* @type {Function}\n* @returns {CircularBuffer} circular buffer instance\n*\n* @example\n* var b = new CircularBuffer( 2 );\n*\n* // Add values to the buffer:\n* b.push( 'foo' );\n* b.push( 'bar' );\n* b.push( 'beep' );\n* b.push( 'boop' );\n*\n* // Get the number of elements currently in the buffer:\n* var n = b.count;\n* // returns 2\n*\n* // Clear the buffer:\n* b.clear();\n*\n* // Get the number of buffer values:\n* n = b.count;\n* // returns 0\n*/\nsetReadOnly( CircularBuffer.prototype, 'clear', function clear() {\n\tthis._count = 0;\n\tthis._i = -1; // this ensures that we always fill the buffer starting at index `0`.\n\treturn this;\n});\n\n/**\n* Number of elements currently in the buffer.\n*\n* @name count\n* @memberof CircularBuffer.prototype\n* @readonly\n* @type {NonNegativeInteger}\n*\n* @example\n* var b = new CircularBuffer( 4 );\n*\n* // Get the value count:\n* var n = b.count;\n* // returns 0\n*\n* // Add values to the buffer:\n* b.push( 'foo' );\n* b.push( 'bar' );\n*\n* // Get the value count:\n* n = b.count;\n* // returns 2\n*/\nsetReadOnlyAccessor( CircularBuffer.prototype, 'count', function get() {\n\treturn this._count;\n});\n\n/**\n* Boolean indicating whether a circular buffer is full.\n*\n* @name full\n* @memberof CircularBuffer.prototype\n* @readonly\n* @type {boolean}\n*\n* @example\n* var b = new CircularBuffer( 3 );\n*\n* // Determine if the buffer is full:\n* var bool = b.full;\n* // returns false\n*\n* // Add values to the buffer:\n* b.push( 'foo' );\n* b.push( 'bar' );\n* b.push( 'beep' );\n* b.push( 'boop' );\n*\n* // Determine if the buffer is full:\n* bool = b.full;\n* // returns true\n*/\nsetReadOnlyAccessor( CircularBuffer.prototype, 'full', function get() {\n\treturn this._count === this._length;\n});\n\n/**\n* Returns an iterator for iterating over a circular buffer.\n*\n* ## Notes\n*\n* -   An iterator does not iterate over partially full buffers.\n*\n* @name iterator\n* @memberof CircularBuffer.prototype\n* @type {Function}\n* @param {NonNegativeInteger} [niters] - number of iterations\n* @throws {TypeError} must provide a nonnegative integer\n* @returns {Iterator} iterator\n*\n* @example\n* var b = new CircularBuffer( 3 );\n*\n* // Add values to the buffer:\n* b.push( 'foo' );\n* b.push( 'bar' );\n* b.push( 'beep' );\n* b.push( 'boop' );\n*\n* // Create an iterator:\n* var it = b.iterator( b.length );\n*\n* // Iterate over the buffer...\n* var v = it.next().value;\n* // returns 'bar'\n*\n* v = it.next().value;\n* // returns 'beep'\n*\n* v = it.next().value;\n* // returns 'boop'\n*\n* var bool = it.next().done;\n* // returns true\n*/\nsetReadOnly( CircularBuffer.prototype, 'iterator', function iterator( niters ) {\n\tvar iter;\n\tvar self;\n\tvar FLG;\n\tvar N;\n\tvar n;\n\tvar i;\n\n\tif ( arguments.length ) {\n\t\tif ( !isNonNegativeInteger( niters ) ) {\n\t\t\tthrow new TypeError( format( 'invalid argument. Must provide a nonnegative integer. Value: `%s`.', niters ) );\n\t\t}\n\t\tN = niters;\n\t} else {\n\t\tN = MAX_ITERATIONS;\n\t}\n\tself = this;\n\n\t// Initialize the iteration index and counter:\n\ti = this._i;\n\tn = 0;\n\n\t// Create an iterator protocol-compliant object:\n\titer = {};\n\tsetReadOnly( iter, 'next', next );\n\tsetReadOnly( iter, 'return', end );\n\tif ( iteratorSymbol ) {\n\t\tsetReadOnly( iter, iteratorSymbol, factory );\n\t}\n\treturn iter;\n\n\t/**\n\t* Returns an iterator protocol-compliant object containing the next iterated value.\n\t*\n\t* @private\n\t* @returns {Object} iterator protocol-compliant object\n\t*/\n\tfunction next() {\n\t\t/* eslint-disable no-underscore-dangle */\n\t\tn += 1;\n\t\tif ( FLG || n > N ) {\n\t\t\treturn {\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\t// If the buffer is only partially full, don't allow iteration over \"undefined\" elements (this ensures similar behavior with `toArray()`)...\n\t\tif ( self._count !== self._length ) {\n\t\t\tFLG = true;\n\t\t\treturn {\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\ti = (i+1) % self._length;\n\t\treturn {\n\t\t\t'value': self._buffer.accessors[ 0 ]( self._buffer.data, i ),\n\t\t\t'done': false\n\t\t};\n\n\t\t/* eslint-enable no-underscore-dangle */\n\t}\n\n\t/**\n\t* Finishes an iterator.\n\t*\n\t* @private\n\t* @param {*} [value] - value to return\n\t* @returns {Object} iterator protocol-compliant object\n\t*/\n\tfunction end( value ) {\n\t\tFLG = true;\n\t\tif ( arguments.length ) {\n\t\t\treturn {\n\t\t\t\t'value': value,\n\t\t\t\t'done': true\n\t\t\t};\n\t\t}\n\t\treturn {\n\t\t\t'done': true\n\t\t};\n\t}\n\n\t/**\n\t* Returns a new iterator.\n\t*\n\t* @private\n\t* @returns {Iterator} iterator\n\t*/\n\tfunction factory() {\n\t\treturn self.iterator( N );\n\t}\n});\n\n/**\n* Circular buffer length (i.e., capacity).\n*\n* @name length\n* @memberof CircularBuffer.prototype\n* @readonly\n* @type {NonNegativeInteger}\n*\n* @example\n* var b = new CircularBuffer( 4 );\n*\n* // Get the buffer capacity:\n* var len = b.length;\n* // returns 4\n*/\nsetReadOnlyAccessor( CircularBuffer.prototype, 'length', function get() {\n\treturn this._length;\n});\n\n/**\n* Adds a value to the circular buffer.\n*\n* @name push\n* @memberof CircularBuffer.prototype\n* @type {Function}\n* @param {*} value - value to add\n* @returns {(*|void)} removed element or undefined\n*\n* @example\n* var b = new CircularBuffer( 3 );\n*\n* // Fill the buffer:\n* var v = b.push( 'foo' );\n* // returns undefined\n*\n* v = b.push( 'bar' );\n* // returns undefined\n*\n* v = b.push( 'beep' );\n* // returns undefined\n*\n* // Add another value to the buffer and return the removed element:\n* v = b.push( 'boop' );\n* // returns 'foo'\n*/\nsetReadOnly( CircularBuffer.prototype, 'push', function push( value ) {\n\tvar set;\n\tvar get;\n\tvar buf;\n\tvar v;\n\n\tbuf = this._buffer.data;\n\tget = this._buffer.accessors[ 0 ];\n\tset = this._buffer.accessors[ 1 ];\n\n\t// Compute the next buffer index:\n\tthis._i = (this._i+1) % this._length;\n\n\t// Check if we are still filling the buffer...\n\tif ( this._count < this._length ) {\n\t\tset( buf, this._i, value );\n\t\tthis._count += 1;\n\t\treturn;\n\t}\n\t// Replace an existing buffer element...\n\tv = get( buf, this._i );\n\tset( buf, this._i, value );\n\treturn v;\n});\n\n/**\n* Returns an array of circular buffer values.\n*\n* @name toArray\n* @memberof CircularBuffer.prototype\n* @type {Function}\n* @returns {Array} circular buffer values\n*\n* @example\n* var b = new CircularBuffer( 3 );\n*\n* // Add values to the buffer:\n* b.push( 'foo' );\n* b.push( 'bar' );\n* b.push( 'beep' );\n* b.push( 'boop' );\n*\n* // Get an array of buffer values:\n* var vals = b.toArray();\n* // returns [ 'bar', 'beep', 'boop' ]\n*/\nsetReadOnly( CircularBuffer.prototype, 'toArray', function toArray() {\n\tvar buf;\n\tvar get;\n\tvar out;\n\tvar k;\n\tvar i;\n\n\tbuf = this._buffer.data;\n\tget = this._buffer.accessors[ 0 ];\n\n\tout = [];\n\tfor ( i = 1; i <= this._count; i++ ) {\n\t\t// Note: in a full buffer, `count == length`; in a partially full buffer, we need to ensure we always start at index `0`\n\t\tk = (this._i+i) % this._count;\n\t\tout.push( get( buf, k ) );\n\t}\n\treturn out;\n});\n\n/**\n* Serializes a circular buffer as JSON.\n*\n* ## Notes\n*\n* -   `JSON.stringify()` implicitly calls this method when stringifying a `CircularBuffer` instance.\n*\n* @name toJSON\n* @memberof CircularBuffer.prototype\n* @type {Function}\n* @returns {Object} serialized circular buffer\n*\n* @example\n* var b = new CircularBuffer( 3 );\n*\n* // Add values to the buffer:\n* b.push( 'foo' );\n* b.push( 'bar' );\n* b.push( 'beep' );\n* b.push( 'boop' );\n*\n* // Serialize to JSON:\n* var o = b.toJSON();\n* // returns { 'type': 'circular-buffer', 'length': 3, 'data': [ 'bar', 'beep', 'boop' ] }\n*/\nsetReadOnly( CircularBuffer.prototype, 'toJSON', function toJSON() {\n\tvar out = {};\n\tout.type = 'circular-buffer';\n\tout.length = this._length;\n\tout.data = this.toArray();\n\treturn out;\n});\n\n\n// EXPORTS //\n\nmodule.exports = CircularBuffer;\n", "/**\n* @license Apache-2.0\n*\n* Copyright (c) 2018 The Stdlib Authors.\n*\n* Licensed under the Apache License, Version 2.0 (the \"License\");\n* you may not use this file except in compliance with the License.\n* You may obtain a copy of the License at\n*\n*    http://www.apache.org/licenses/LICENSE-2.0\n*\n* Unless required by applicable law or agreed to in writing, software\n* distributed under the License is distributed on an \"AS IS\" BASIS,\n* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n* See the License for the specific language governing permissions and\n* limitations under the License.\n*/\n\n'use strict';\n\n/**\n* Circular buffer.\n*\n* @module @stdlib/dstructs-circular-buffer\n*\n* @example\n* var CircularBuffer = require( '@stdlib/dstructs-circular-buffer' );\n*\n* var b = new CircularBuffer( 3 );\n*\n* // Fill the buffer...\n* var v = b.push( 'foo' );\n* // returns undefined\n*\n* v = b.push( 'bar' );\n* // returns undefined\n*\n* v = b.push( 'beep' );\n* // returns undefined\n*\n* // Add another value to the buffer and return the removed element:\n* v = b.push( 'boop' );\n* // returns 'foo'\n*/\n\n// MODULES //\n\nvar main = require( './main.js' );\n\n\n// EXPORTS //\n\nmodule.exports = main;\n"],
+  "mappings": "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",
+  "names": ["require_main", "__commonJSMin", "exports", "module", "isCollection", "isPositiveInteger", "isNonNegativeInteger", "setReadOnly", "setReadOnlyAccessor", "iteratorSymbol", "MAX_ITERATIONS", "arraylike2object", "format", "CircularBuffer", "buffer", "buf", "i", "niters", "iter", "self", "FLG", "N", "n", "next", "end", "factory", "value", "set", "get", "v", "out", "k", "main"]
+}

package/docs/types/index.d.ts

@@ -0,0 +1,268 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2021 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 4.1
+
+/// <reference types="@stdlib/types"/>
+
+import { TypedIterableIterator } from '@stdlib/types/iter';
+import { Collection } from '@stdlib/types/array';
+
+/**
+* Interface describing a JSON-serialized circular buffer.
+*/
+interface JSON<T> {
+	/**
+	* Object type.
+	*/
+	type: 'circular-buffer';
+
+	/**
+	* Number of elements.
+	*/
+	length: number;
+
+	/**
+	* Buffer elements.
+	*/
+	data: Array<T>;
+}
+
+/**
+* Circular buffer.
+*/
+declare class CircularBuffer<T> {
+	/**
+	* Circular buffer constructor.
+	*
+	* @param buffer - buffer size or an array-like object to use as the underlying buffer
+	* @throws must provide either a valid buffer size or an array-like object
+	* @returns circular buffer instance
+	*
+	* @example
+	* var b = new CircularBuffer( 3 );
+	*
+	* // Fill the buffer...
+	* var v = b.push( 'foo' );
+	* // returns undefined
+	*
+	* v = b.push( 'bar' );
+	* // returns undefined
+	*
+	* v = b.push( 'beep' );
+	* // returns undefined
+	*
+	* // Add another value to the buffer and return the removed element:
+	* v = b.push( 'boop' );
+	* // returns 'foo'
+	*/
+	constructor( buffer: number | Collection<T> );
+
+	/**
+	* Clears the buffer.
+	*
+	* @returns circular buffer instance
+	*
+	* @example
+	* var b = new CircularBuffer( 2 );
+	*
+	* // Add values to the buffer:
+	* b.push( 'foo' );
+	* b.push( 'bar' );
+	* b.push( 'beep' );
+	* b.push( 'boop' );
+	*
+	* // Get the number of elements currently in the buffer:
+	* var n = b.count;
+	* // returns 2
+	*
+	* // Clear the buffer:
+	* b.clear();
+	*
+	* // Get the number of buffer values:
+	* n = b.count;
+	* // returns 0
+	*/
+	clear(): CircularBuffer<T>;
+
+	/**
+	* Number of elements currently in the buffer.
+	*
+	* @example
+	* var b = new CircularBuffer( 4 );
+	*
+	* // Get the value count:
+	* var n = b.count;
+	* // returns 0
+	*
+	* // Add values to the buffer:
+	* b.push( 'foo' );
+	* b.push( 'bar' );
+	*
+	* // Get the value count:
+	* n = b.count;
+	* // returns 2
+	*/
+	readonly count: number;
+
+	/**
+	* Boolean indicating whether a circular buffer is full.
+	*
+	* @example
+	* var b = new CircularBuffer( 3 );
+	*
+	* // Determine if the buffer is full:
+	* var bool = b.full;
+	* // returns false
+	*
+	* // Add values to the buffer:
+	* b.push( 'foo' );
+	* b.push( 'bar' );
+	* b.push( 'beep' );
+	* b.push( 'boop' );
+	*
+	* // Determine if the buffer is full:
+	* bool = b.full;
+	* // returns true
+	*/
+	readonly full: boolean;
+
+	/**
+	* Returns an iterator for iterating over a circular buffer.
+	*
+	* ## Notes
+	*
+	* -   An iterator does not iterate over partially full buffers.
+	*
+	* @param niters - number of iterations
+	* @throws must provide a nonnegative integer
+	* @returns iterator
+	*
+	* @example
+	* var b = new CircularBuffer( 3 );
+	*
+	* // Add values to the buffer:
+	* b.push( 'foo' );
+	* b.push( 'bar' );
+	* b.push( 'beep' );
+	* b.push( 'boop' );
+	*
+	* // Create an iterator:
+	* var it = b.iterator( b.length );
+	*
+	* // Iterate over the buffer...
+	* var v = it.next().value;
+	* // returns 'bar'
+	*
+	* v = it.next().value;
+	* // returns 'beep'
+	*
+	* v = it.next().value;
+	* // returns 'boop'
+	*
+	* var bool = it.next().done;
+	* // returns true
+	*/
+	iterator( niters?: number ): TypedIterableIterator<T>;
+
+	/**
+	* Circular buffer length (i.e., capacity).
+	*
+	* @example
+	* var b = new CircularBuffer( 4 );
+	*
+	* // Get the buffer capacity:
+	* var len = b.length;
+	* // returns 4
+	*/
+	readonly length: number;
+
+	/**
+	* Adds a value to the circular buffer.
+	*
+	* @param value - value to add
+	* @returns removed element or undefined
+	*
+	* @example
+	* var b = new CircularBuffer( 3 );
+	*
+	* // Fill the buffer:
+	* var v = b.push( 'foo' );
+	* // returns undefined
+	*
+	* v = b.push( 'bar' );
+	* // returns undefined
+	*
+	* v = b.push( 'beep' );
+	* // returns undefined
+	*
+	* // Add another value to the buffer and return the removed element:
+	* v = b.push( 'boop' );
+	* // returns 'foo'
+	*/
+	push( value: T ): T;
+
+	/**
+	* Returns an array of circular buffer values.
+	*
+	* @returns circular buffer values
+	*
+	* @example
+	* var b = new CircularBuffer( 3 );
+	*
+	* // Add values to the buffer:
+	* b.push( 'foo' );
+	* b.push( 'bar' );
+	* b.push( 'beep' );
+	* b.push( 'boop' );
+	*
+	* // Get an array of buffer values:
+	* var vals = b.toArray();
+	* // returns [ 'bar', 'beep', 'boop' ]
+	*/
+	toArray(): Array<T>;
+
+	/**
+	* Serializes a circular buffer as JSON.
+	*
+	* ## Notes
+	*
+	* -   `JSON.stringify()` implicitly calls this method when stringifying a `CircularBuffer` instance.
+	*
+	* @returns serialized circular buffer
+	*
+	* @example
+	* var b = new CircularBuffer( 3 );
+	*
+	* // Add values to the buffer:
+	* b.push( 'foo' );
+	* b.push( 'bar' );
+	* b.push( 'beep' );
+	* b.push( 'boop' );
+	*
+	* // Serialize to JSON:
+	* var o = b.toJSON();
+	* // returns { 'type': 'circular-buffer', 'length': 3, 'data': [ 'bar', 'beep', 'boop' ] }
+	*/
+	toJSON(): JSON<T>;
+}
+
+
+// EXPORTS //
+
+export = CircularBuffer;

package/lib/index.js

@@ -0,0 +1,53 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2018 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* Circular buffer.
+*
+* @module @stdlib/dstructs-circular-buffer
+*
+* @example
+* var CircularBuffer = require( '@stdlib/dstructs-circular-buffer' );
+*
+* var b = new CircularBuffer( 3 );
+*
+* // Fill the buffer...
+* var v = b.push( 'foo' );
+* // returns undefined
+*
+* v = b.push( 'bar' );
+* // returns undefined
+*
+* v = b.push( 'beep' );
+* // returns undefined
+*
+* // Add another value to the buffer and return the removed element:
+* v = b.push( 'boop' );
+* // returns 'foo'
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;