diff --git a/lib/node_modules/@stdlib/dstructs/fifo/README.md b/lib/node_modules/@stdlib/dstructs/fifo/README.md index 380fd643f663..afca5860285c 100644 --- a/lib/node_modules/@stdlib/dstructs/fifo/README.md +++ b/lib/node_modules/@stdlib/dstructs/fifo/README.md @@ -80,6 +80,59 @@ len = queue.length; // returns 0 ``` +##### queue.every( predicate\[, thisArg] ) + +Tests whether all elements in a queue pass a test implemented by a predicate function. + +```javascript +// Test whether all elements are greater than 0: +function predicate( v ) { + return v > 0; +} + +var queue = fifo(); +// returns + +// Add values to the queue: +queue.push( 1 ).push( 2 ).push( 3 ); + +var bool = queue.every( predicate ); +// returns true +``` + +The `predicate` function is provided three arguments: + +- **value**: current queue element. +- **index**: current queue element index. +- **q**: the queue on which the method was called. + +To set the function execution context, provide a `thisArg`. + +```javascript +function predicate( v ) { + this.count += 1; + return v > 0; +} + +// Create a queue: +var queue = fifo(); + +// Add values to the queue: +queue.push( 1 ).push( 2 ).push( 3 ); + +// Define an execution context: +var ctx = { + 'count': 0 +}; + +// Test whether all elements are greater than 0: +var bool = queue.every( predicate, ctx ); +// returns true + +var n = ctx.count; +// returns 3 +``` + ##### queue.first() Returns the "oldest" queue value (i.e., the value which is "first-out"). If the queue is currently empty, the returned value is `undefined`. @@ -96,6 +149,37 @@ var v = queue.first(); // returns 'foo' ``` +##### queue.get( index ) + +Returns a queue element located at a nonnegative integer position (index) `i`. + +```javascript +var queue = fifo(); + +// Add values to the queue: +queue.push( 'foo' ).push( 'bar' ).push( 'baz' ); + +// Access elements by index via the accessor protocol: +var v = queue.get( 0 ); +// returns 'foo' + +v = queue.get( 1 ); +// returns 'bar' + +v = queue.get( 2 ); +// returns 'baz' +``` + +If provided an out-of-bounds index, the method returns `undefined`. + +```javascript +var queue = fifo(); + +// Out-of-bounds indices return undefined: +var v = queue.get( 10 ); +// returns undefined +``` + ##### queue.iterator() Returns an iterator for iterating over a queue. If an environment supports `Symbol.iterator`, the returned iterator is iterable. @@ -201,6 +285,48 @@ v = queue.pop(); // returns 'bar' ``` +##### queue.set( value, index ) + +Sets a queue element at a specified index. + +```javascript +var queue = fifo(); +// returns + +// Add values to the queue: +queue.push( 'foo' ).push( 'bar' ).push( 'baz' ); + +// Set elements by index: +queue.set( 'beep', 0 ); +var v = queue.get( 0 ); +// returns 'beep' + +queue.set( 'boop', 1 ); +v = queue.get( 1 ); +// returns 'boop' +``` + +By default, the method sets queue elements starting at position (index) `i = 0`. To set elements starting elsewhere in the queue, provide an index argument `i`. + +```javascript +var queue = fifo(); +// returns + +// Add values to the queue: +queue.push( 'foo' ).push( 'bar' ).push( 'baz' ); + +// By default, sets element at index 0: +queue.set( 'beep' ); +var v = queue.get( 0 ); +// returns 'beep' + +// Set element at a specified index: +queue.set( 'boop', 1 ); + +v = queue.get( 1 ); +// returns 'boop' +``` + ##### queue.toArray() Returns an array of queue values. diff --git a/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.every.js b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.every.js new file mode 100644 index 000000000000..e433d2e77244 --- /dev/null +++ b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.every.js @@ -0,0 +1,56 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var FIFO = require( './../lib' ); + + +// MAIN // + +bench( format( '%s:every', pkg ), function benchmark( b ) { + var bool; + var q; + var i; + + q = new FIFO(); + for ( i = 1; i <= 4; i++ ) { + q.push( i ); + } + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + bool = q.every( function predicate( v ) { + return v > 0; + }); + if ( typeof bool !== 'boolean' ) { + b.fail( 'should return a boolean' ); + } + } + b.toc(); + if ( typeof bool !== 'boolean' ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.every.length.js b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.every.length.js new file mode 100644 index 000000000000..e17ed102f58d --- /dev/null +++ b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.every.length.js @@ -0,0 +1,115 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; +var pow = require( '@stdlib/math/base/special/pow' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var FIFO = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Predicate function. +* +* @private +* @param {boolean} value - array element +* @param {NonNegativeInteger} idx - array element index +* @param {FIFO} q - queue instance +* @returns {boolean} boolean indicating whether a value passes a test +*/ +function predicate( value ) { + return value > 0; +} + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - queue length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var q; + var i; + + q = new FIFO(); + for ( i = 0; i < len; i++ ) { + q.push( i ); + } + + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var bool; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + bool = q.every( predicate ); + if ( typeof bool !== 'boolean' ) { + b.fail( 'should return a boolean' ); + } + } + b.toc(); + if ( !isBoolean( bool ) ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( format( '%s:every:len=%d', pkg, len ), f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.get.js b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.get.js new file mode 100644 index 000000000000..aeb16a1d9298 --- /dev/null +++ b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.get.js @@ -0,0 +1,54 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var FIFO = require( './../lib' ); + + +// MAIN // + +bench( format( '%s:get', pkg ), function benchmark( b ) { + var q; + var v; + var i; + + q = new FIFO(); + for ( i = 1; i <= 4; i++ ) { + q.push( i ); + } + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = q.get( i%4 ); + if ( typeof v === 'undefined' ) { + b.fail( 'should return a value' ); + } + } + b.toc(); + if ( typeof v === 'undefined' ) { + b.fail( 'should return a value' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.set.js b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.set.js new file mode 100644 index 000000000000..b3359ec9a610 --- /dev/null +++ b/lib/node_modules/@stdlib/dstructs/fifo/benchmark/benchmark.set.js @@ -0,0 +1,54 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var FIFO = require( './../lib' ); + + +// MAIN // + +bench( format( '%s:set', pkg ), function benchmark( b ) { + var q; + var v; + var i; + + q = new FIFO(); + for ( i = 1; i <= 4; i++ ) { + q.push( i ); + } + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = q.set( i%4, i%4 ); // value, index + if ( typeof v !== 'undefined' ) { + b.fail( 'should return undefined' ); + } + } + b.toc(); + if ( typeof v !== 'undefined' ) { + b.fail( 'should return undefined' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/dstructs/fifo/docs/repl.txt b/lib/node_modules/@stdlib/dstructs/fifo/docs/repl.txt index 5ec306f898d5..0993577a8179 100644 --- a/lib/node_modules/@stdlib/dstructs/fifo/docs/repl.txt +++ b/lib/node_modules/@stdlib/dstructs/fifo/docs/repl.txt @@ -10,10 +10,17 @@ queue.clear: Function Clears the queue. + queue.every: Function + Returns a boolean indicating whether all elements in the queue + pass a test. + queue.first: Function Returns the "oldest" queue value (i.e., the value which is "first-out"). If the queue is empty, the returned value is `undefined`. + queue.get: Function + Returns a queue element at a specified index. + queue.iterator: Function Returns an iterator for iterating over a queue. If an environment supports Symbol.iterator, the returned iterator is iterable. Note that, @@ -36,6 +43,9 @@ queue.push: Function Adds a value to the queue. + queue.set: Function + Sets a queue element at a specified index. + queue.toArray: Function Returns an array of queue values. @@ -45,18 +55,116 @@ Examples -------- > var q = {{alias}}(); - > q.push( 'foo' ).push( 'bar' ); + > q.push( 'foo' ).push( 'bar' ).push( 'baz' ); > q.length - 2 + 3 + > q.get( 0 ) + 'foo' + > q.get( 1 ) + 'bar' + > q.get( 2 ) + 'baz' > q.pop() 'foo' > q.length - 1 - > q.pop() + 2 + + +{{alias}}.prototype.every( predicate[, thisArg] ) + Returns a boolean indicating whether all elements in the queue pass a test. + + If the queue is empty, the method returns `true`. + + The predicate function is provided three arguments: + + - value: current queue element. + - index: current queue element index. + - q: the queue on which the method was called. + + Parameters + ---------- + predicate: Function + Predicate function to test queue elements. Should return a boolean + indicating whether an element passes the test. The function is provided + three arguments: value, index, and q. + + thisArg: Any (optional) + Execution context for the predicate function. + + Returns + ------- + bool: boolean + Boolean indicating whether all elements pass the test. + + Examples + -------- + > function predicate( v ) { return v > 0; }; + > var q = {{alias}}(); + > q.push( 1 ).push( 2 ).push( 3 ); + > q.every( predicate ) + true + + +{{alias}}.prototype.get( index ) + Returns a queue element located at a nonnegative integer + position (index) `i`. + + If provided an index outside the queue index range, the method returns + `undefined`. + + Parameters + ---------- + index: NonNegativeInteger + Queue element index. + + Returns + ------- + value: Any + Queue element. + + Examples + -------- + > var q = {{alias}}(); + > q.push( 'foo' ).push( 'bar' ).push( 'baz' ); + > q.get( 0 ) + 'foo' + > q.get( 1 ) 'bar' - > q.length - 0 + > q.get( 2 ) + 'baz' + > q.get( 10 ) + undefined - See Also + +{{alias}}.prototype.set( value[, index] ) + Sets one or more queue elements. + + If provided a single argument, the method sets array elements starting at + position (index) `i = 0`. To set elements starting elsewhere in the queue, + provide an index argument `i`. + + Parameters + ---------- + value: Any + Value to set. + + index: Integer (optional) + Queue element index. Default: 0. + + Examples -------- + > var q = {{alias}}(); + > q.push( 'foo' ).push( 'bar' ).push( 'baz' ); + > q.set( 'beep', 0 ); + > q.get( 0 ) + 'beep' + > q.set( 'boop', 1 ); + > q.get( 1 ) + 'boop' + > q.set( 'bop' ); + > q.get( 0 ) + 'bop' + + See Also + -------- diff --git a/lib/node_modules/@stdlib/dstructs/fifo/docs/types/index.d.ts b/lib/node_modules/@stdlib/dstructs/fifo/docs/types/index.d.ts index f8d54c6d8376..92ba979ba4db 100644 --- a/lib/node_modules/@stdlib/dstructs/fifo/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/dstructs/fifo/docs/types/index.d.ts @@ -22,16 +22,67 @@ import { IterableIterator } from '@stdlib/types/iter'; +/** + * Checks whether an element in a queue passes a test. + * + * @param value - current queue element + * @param index - current queue element index + * @param q - queue on which the method was called + * @returns boolean indicating whether an element in a queue passes a test + */ +type NullaryPredicate = ( this: U ) => boolean; + +/** + * Checks whether an element in a queue passes a test. + * + * @param value - current queue element + * @returns boolean indicating whether an element in a queue passes a test + */ +type UnaryPredicate = ( this: U, value: T ) => boolean; + +/** + * Checks whether an element in a queue passes a test. + * + * @param value - current queue element + * @param index - current queue element index + * @returns boolean indicating whether an element in a queue passes a test + */ +type BinaryPredicate = ( this: U, value: T, index: number ) => boolean; + +/** + * Checks whether an element in a queue passes a test. + * + * @param value - current queue element + * @param index - current queue element index + * @param q - queue on which the method was called + * @returns boolean indicating whether an element in a queue passes a test + */ +type TernaryPredicate = ( this: U, value: T, index: number, q: FIFO ) => boolean; + +/** +* Checks whether an element in an queue passes a test. +* +* @param value - current queue element +* @param index - current queue element index +* @param q - queue on which the method was called +* @returns boolean indicating whether an element in a queue passes a test +*/ +type Predicate = NullaryPredicate | UnaryPredicate | BinaryPredicate | TernaryPredicate; + /** * First-in-first-out (FIFO) queue. +* +* @template T - queue element type */ -declare class FIFO { +declare class FIFO { /** * First-in-first-out queue constructor. * * @returns FIFO queue instance * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -56,6 +107,8 @@ declare class FIFO { * @returns queue instance * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -82,12 +135,42 @@ declare class FIFO { */ clear(): FIFO; + /** + * Tests whether all elements in a queue pass a test implemented by a predicate function. + * + * ## Notes + * + * - If the queue is empty, the method returns `true`. + * + * @param predicate - predicate function to test queue elements + * @param thisArg - execution context for the predicate function + * @throws first argument must be a function + * @returns boolean indicating whether all elements pass a test + * + * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * + * function predicate( v ) { + * return v > 0; + * } + * + * var queue = new FIFO(); + * + * queue.push( 1 ).push( 2 ).push( 3 ); + * + * var bool = queue.every( predicate ); + * // returns true + */ + every( predicate: Predicate, thisArg?: ThisParameterType> ): boolean; + /** * Returns the "oldest" queue value (i.e., the value which is "first-out"). * * @returns "oldest" queue value * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -97,7 +180,29 @@ declare class FIFO { * var v = queue.first(); * // returns 'foo' */ - first(): any; + first(): T | void; + + /** + * Returns a queue element located at a nonnegative integer position (index) `i`. + * + * @param i - element index + * @throws index argument must be a nonnegative integer + * @returns queue element + * + * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * + * var queue = new FIFO(); + * + * queue.push( 'foo' ).push( 'bar' ); + * + * var v = queue.get( 0 ); + * // returns 'foo' + * + * v = queue.get( 1 ); + * // returns 'bar' + */ + get( i: number ): T | void; /** * Returns an iterator for iterating over a queue. @@ -109,6 +214,8 @@ declare class FIFO { * @returns iterator * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -135,6 +242,8 @@ declare class FIFO { * @returns "newest" queue value * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -144,12 +253,14 @@ declare class FIFO { * var v = queue.last(); * // returns 'bar' */ - last(): any; + last(): T | void; /** * Queue length. * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Examine the initial queue length: @@ -171,6 +282,8 @@ declare class FIFO { * @returns removed value * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -187,7 +300,7 @@ declare class FIFO { * v = queue.pop(); * // returns 'bar' */ - pop(): any; + pop(): T | void; /** * Adds a value to the queue. @@ -195,6 +308,8 @@ declare class FIFO { * @returns queue instance * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -211,7 +326,42 @@ declare class FIFO { * v = queue.pop(); * // returns 'bar' */ - push(): FIFO; + push( value: T ): FIFO; + + /** + * Sets a queue element at a specified index. + * + * ## Notes + * + * - If an index argument is not provided, the method sets a value at index `0`. + * + * @param value - value to set + * @param i - element index (default: 0) + * @throws index argument must be a nonnegative integer + * @throws index argument is out-of-bounds + * @throws target queue lacks sufficient storage to accommodate source values + * + * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * + * var queue = new FIFO(); + * + * queue.push( 'foo' ).push( 'bar' ).set( 'beep', 0 ); + * + * var v = queue.get( 0 ); + * // returns 'beep' + * + * queue.set( 'boop', 1 ); + * + * v = queue.get( 1 ); + * // returns 'boop' + * + * queue.set( 'beep' ); + * + * v = queue.get( 0 ); + * // returns 'beep' + */ + set( value: T, i?: number ): void; /** * Returns an array of queue values. @@ -219,6 +369,8 @@ declare class FIFO { * @returns queue values * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -228,7 +380,7 @@ declare class FIFO { * var vals = queue.toArray(); * // returns [ 'foo', 'bar' ] */ - toArray(): Array; + toArray(): Array; /** * Serializes a queue as JSON. @@ -240,6 +392,8 @@ declare class FIFO { * @returns serialized queue * * @example + * var FIFO = require( '@stdlib/dstructs/fifo' ); + * * var queue = new FIFO(); * * // Add values to the queue: @@ -249,7 +403,7 @@ declare class FIFO { * var o = queue.toJSON(); * // returns { 'type': 'fifo', 'data': [ 'foo', 'bar' ] } */ - toJSON(): any; + toJSON(): { type: string; data: Array }; } diff --git a/lib/node_modules/@stdlib/dstructs/fifo/examples/index.js b/lib/node_modules/@stdlib/dstructs/fifo/examples/index.js index 5759d4a8bcc1..9c373b603857 100644 --- a/lib/node_modules/@stdlib/dstructs/fifo/examples/index.js +++ b/lib/node_modules/@stdlib/dstructs/fifo/examples/index.js @@ -36,6 +36,11 @@ console.log( 'First: %s', v ); v = queue.last(); console.log( 'Last: %s', v ); +// Inspect accessor-protocol implementation: +queue.set( 'bop', 3 ); +v = queue.get( 3 ); +console.log( 'Value: %s', v ); + // Inspect the queue length: var len = queue.length; console.log( 'Queue length: %d', len ); diff --git a/lib/node_modules/@stdlib/dstructs/fifo/lib/main.js b/lib/node_modules/@stdlib/dstructs/fifo/lib/main.js index 4acb43b20dfd..556dbaab0688 100644 --- a/lib/node_modules/@stdlib/dstructs/fifo/lib/main.js +++ b/lib/node_modules/@stdlib/dstructs/fifo/lib/main.js @@ -24,10 +24,31 @@ var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); var setReadOnlyAccessor = require( '@stdlib/utils/define-nonenumerable-read-only-accessor' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' ).isPrimitive; +var format = require( '@stdlib/string/format' ); var iteratorSymbol = require( '@stdlib/symbol/iterator' ); var Node = require( './node.js' ); // eslint-disable-line stdlib/no-redeclare +// FUNCTIONS // + +/** +* Returns a boolean indicating if a value is a `FIFO`. +* +* @private +* @param {*} value - value to test +* @returns {boolean} boolean indicating if a value is a `FIFO` +*/ +function isFIFO( value ) { + return ( + typeof value === 'object' && + value !== null && + value.constructor.name === 'FIFO' + ); +} + + // MAIN // /** @@ -103,6 +124,54 @@ setReadOnly( FIFO.prototype, 'clear', function clear() { return this; }); +/** +* Tests whether all elements in a queue pass a test implemented by a predicate function. +* +* ## Notes +* +* - If the queue is empty, the method returns `true`. +* +* @name every +* @memberof FIFO.prototype +* @type {Function} +* @param {Function} predicate - predicate function to test queue elements +* @param {*} [thisArg] - predicate function execution context +* @throws {TypeError} `this` must be a FIFO +* @throws {TypeError} first argument must be a function +* @returns {boolean} boolean indicating whether all elements pass a test +* +* @example +* function predicate( v ) { +* return v > 0; +* } +* +* var queue = new FIFO(); +* +* queue.push( 1 ).push( 2 ).push( 3 ); +* +* var bool = queue.every( predicate ); +* // returns true +*/ +setReadOnly( FIFO.prototype, 'every', function every( predicate, thisArg ) { + var node; + var i; + + if ( !isFIFO( this ) ) { + throw new TypeError( 'invalid invocation. `this` is not a FIFO.' ); + } + if ( !isFunction( predicate ) ) { + throw new TypeError( format( 'invalid argument. First argument must be a function. Value: `%s`.', predicate ) ); + } + node = this._first; + for ( i = 0; i < this._length; i++ ) { + if ( !predicate.call( thisArg, node.value, i, this ) ) { + return false; + } + node = node.next; + } + return true; +}); + /** * Returns the "oldest" queue value (i.e., the value which is "first-out"). * @@ -127,6 +196,51 @@ setReadOnly( FIFO.prototype, 'first', function first() { } }); +/** +* Returns a queue element located at a nonnegative integer position (index) `i`. +* +* @name get +* @memberof FIFO.prototype +* @type {Function} +* @param {NonNegativeInteger} idx - element index +* @throws {TypeError} `this` must be a FIFO +* @throws {TypeError} index argument must be a nonnegative integer +* @returns {(*|void)} queue element or undefined +* +* @example +* var queue = new FIFO(); +* +* queue.push( 'foo' ).push( 'bar' ).push( 'baz' ); +* +* var v = queue.get( 0 ); +* // returns 'foo' +* +* v = queue.get( 1 ); +* // returns 'bar' +* +* v = queue.get( 100 ); +* // returns undefined +*/ +setReadOnly( FIFO.prototype, 'get', function get( idx ) { + var node; + var i; + + if ( !isFIFO( this ) ) { + throw new TypeError( 'invalid invocation. `this` is not a FIFO.' ); + } + if ( !isNonNegativeInteger( idx ) ) { + throw new TypeError( format( 'invalid argument. Index argument must be a nonnegative integer. Value: `%s`.', idx ) ); + } + if ( idx >= this._length ) { + return; + } + node = this._first; + for ( i = 0; i < idx; i++ ) { + node = node.next; + } + return node.value; +}); + /** * Returns an iterator for iterating over a queue. * @@ -379,6 +493,58 @@ setReadOnly( FIFO.prototype, 'push', function push( value ) { return this; }); +/** +* Sets a queue element at a specified index. +* +* ## Notes +* +* - If an index argument is not provided, the method sets a value at index `0`. +* +* @name set +* @memberof FIFO.prototype +* @type {Function} +* @param {*} value - value to set +* @param {NonNegativeInteger} idx - element index (default: 0) +* @throws {TypeError} `this` must be a FIFO +* @throws {TypeError} index argument must be a nonnegative integer +* @throws {RangeError} index argument is out-of-bounds +* @returns {void} +* +* @example +* var queue = new FIFO(); +* +* queue.push( 'foo' ).push( 'bar' ).push( 'baz' ); +* +* queue.set( 'beep', 0 ); +* var v = queue.get( 0 ); +* // returns 'beep' +* +* queue.set( 'boop', 1 ); +* v = queue.get( 1 ); +* // returns 'boop' +*/ +setReadOnly( FIFO.prototype, 'set', function set( value ) { + var node; + var idx; + var i; + + if ( !isFIFO( this ) ) { + throw new TypeError( 'invalid invocation. `this` is not a FIFO.' ); + } + idx = ( arguments.length > 1 ) ? arguments[ 1 ] : 0; + if ( !isNonNegativeInteger( idx ) ) { + throw new TypeError( format( 'invalid argument. Index argument must be a nonnegative integer. Value: `%s`.', idx ) ); + } + if ( idx >= this._length ) { + throw new RangeError( format( 'invalid argument. Index argument is out-of-bounds. Value: `%u`.', idx ) ); + } + node = this._first; + for ( i = 0; i < idx; i++ ) { + node = node.next; + } + node.value = value; +}); + /** * Returns an array of queue values. * diff --git a/lib/node_modules/@stdlib/dstructs/fifo/test/test.every.js b/lib/node_modules/@stdlib/dstructs/fifo/test/test.every.js new file mode 100644 index 000000000000..9892ab0759be --- /dev/null +++ b/lib/node_modules/@stdlib/dstructs/fifo/test/test.every.js @@ -0,0 +1,280 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +// MODULES // + +var tape = require( 'tape' ); +var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var FIFO = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof FIFO, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the prototype of the main export is an `every` method for returning boolean indicating whether all elements pass a test', function test( t ) { + t.strictEqual( hasOwnProp( FIFO.prototype, 'every' ), true, 'has property' ); + t.strictEqual( isFunction( FIFO.prototype.every ), true, 'has method' ); + t.end(); +}); + +tape( 'the method throws an error if invoked with a `this` context which is not a FIFO instance', function test( t ) { + var values; + var q; + var i; + + q = new FIFO(); + q.push( 'foo' ); + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + {}, + [], + function noop() {} + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return q.every.call( value, predicate ); + }; + } + + function predicate( v ) { + return v === 'foo'; + } +}); + +tape( 'the method throws an error if provided a first argument which is not a function', function test( t ) { + var values; + var q; + var i; + + q = new FIFO(); + q.push( 'foo' ); + q.push( 'bar' ); + + values = [ + '5', + 3.14, + NaN, + true, + false, + null, + void 0, + {}, + [] + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return q.every( value ); + }; + } +}); + +tape( 'the method returns `true` if operating on an empty queue', function test( t ) { + var bool; + var q; + + q = new FIFO(); + bool = q.every( predicate ); + + t.strictEqual( bool, true, 'returns expected value' ); + t.end(); + + function predicate() { + t.fail( 'should not be invoked' ); + } +}); + +tape( 'the method returns `true` if all elements pass a test', function test( t ) { + var bool; + var q; + + q = new FIFO(); + q.push( 2 ); + q.push( 4 ); + q.push( 6 ); + q.push( 8 ); + + bool = q.every( predicate ); + + t.strictEqual( bool, true, 'returns expected value' ); + t.end(); + + function predicate( v ) { + return v > 0; + } +}); + +tape( 'the method returns `false` if one or more elements fail a test', function test( t ) { + var bool; + var q; + + q = new FIFO(); + q.push( 2 ); + q.push( 4 ); + q.push( 5 ); + q.push( 8 ); + + bool = q.every( predicate ); + + t.strictEqual( bool, false, 'returns expected value' ); + t.end(); + + function predicate( v ) { + return v % 2 === 0; + } +}); + +tape( 'the method returns `false` on first element that fails the test', function test( t ) { + var count; + var bool; + var q; + + q = new FIFO(); + q.push( 2 ); + q.push( 4 ); + q.push( 5 ); + q.push( 8 ); + q.push( 10 ); + + count = 0; + bool = q.every( predicate ); + + t.strictEqual( bool, false, 'returns expected value' ); + t.strictEqual( count, 3, 'invoked correct number of times (short-circuit)' ); + t.end(); + + function predicate( v ) { + count += 1; + return v % 2 === 0; + } +}); + +tape( 'the method supports providing an execution context', function test( t ) { + var bool; + var ctx; + var q; + + ctx = { + 'count': 0 + }; + q = new FIFO(); + q.push( 1 ); + q.push( 2 ); + q.push( 3 ); + q.push( 4 ); + bool = q.every( predicate, ctx ); + + t.strictEqual( bool, true, 'returns expected value' ); + t.strictEqual( ctx.count, 4, 'returns expected context count' ); + + t.end(); + + function predicate( v ) { + this.count += 1; // eslint-disable-line no-invalid-this + return v > 0; + } +}); + +tape( 'the method provides the element value, index, and queue as arguments to the predicate', function test( t ) { + var indices; + var values; + var q; + + q = new FIFO(); + q.push( 'a' ); + q.push( 'b' ); + q.push( 'c' ); + + values = []; + indices = []; + + q.every( predicate ); + + t.deepEqual( values, [ 'a', 'b', 'c' ], 'passes element values' ); + t.deepEqual( indices, [ 0, 1, 2 ], 'passes indices' ); + + t.end(); + + function predicate( v, i, q ) { + values.push( v ); + indices.push( i ); + t.strictEqual( q, q, 'passes queue as third argument' ); + return true; + } +}); + +tape( 'the method works with different data types', function test( t ) { + var bool; + var q; + + q = new FIFO(); + q.push( 0 ); + q.push( 1 ); + q.push( 2 ); + + bool = q.every( predicate ); + + t.strictEqual( bool, true, 'works with numbers' ); + + q = new FIFO(); + q.push( 'foo' ); + q.push( 'bar' ); + q.push( 'baz' ); + + bool = q.every( predicate ); + + t.strictEqual( bool, true, 'works with strings' ); + + q = new FIFO(); + q.push( true ); + q.push( false ); + q.push( true ); + + bool = q.every( predicate ); + + t.strictEqual( bool, true, 'works with booleans' ); + t.end(); + + function predicate( v ) { + return v !== void 0; + } +}); diff --git a/lib/node_modules/@stdlib/dstructs/fifo/test/test.get.js b/lib/node_modules/@stdlib/dstructs/fifo/test/test.get.js new file mode 100644 index 000000000000..d5a1ebfd87a2 --- /dev/null +++ b/lib/node_modules/@stdlib/dstructs/fifo/test/test.get.js @@ -0,0 +1,137 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +// MODULES // + +var tape = require( 'tape' ); +var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var FIFO = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof FIFO, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the prototype of the main export is a `get` method for returning a queue element', function test( t ) { + t.strictEqual( hasOwnProp( FIFO.prototype, 'get' ), true, 'has property' ); + t.strictEqual( isFunction( FIFO.prototype.get ), true, 'has method' ); + t.end(); +}); + +tape( 'the method throws an error if invoked with a `this` context which is not a FIFO instance', function test( t ) { + var values; + var q; + var i; + + q = new FIFO(); + q.push( 'foo' ); + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + {}, + [] + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return q.get.call( value, 0 ); + }; + } +}); + +tape( 'the method throws an error if provided an index argument which is not a nonnegative integer', function test( t ) { + var values; + var q; + var i; + + q = new FIFO(); + q.push( 1 ); + + values = [ + '5', + -5, + 3.14, + NaN, + true, + false, + null, + void 0, + {}, + [], + function noop() {} + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return q.get( value ); + }; + } +}); + +tape( 'the method returns `undefined` if provided an index which exceeds queue length', function test( t ) { + var q; + var v; + var i; + + q = new FIFO(); + q.push( 'a' ); + q.push( 'b' ); + for ( i = 0; i < q.length; i++ ) { + v = q.get( q.length + i ); + t.strictEqual( v, void 0, 'returns expected value for index '+(q.length+i) ); + } + t.end(); +}); + +tape( 'the method returns a queue element', function test( t ) { + var q; + var v; + var i; + + q = new FIFO(); + q.push( 1 ); + q.push( 2 ); + q.push( 3 ); + + for ( i = 0; i < q.length; i++ ) { + v = q.get( i ); + t.strictEqual( v, i+1, 'returns expected value for index '+i ); + } + t.end(); +}); diff --git a/lib/node_modules/@stdlib/dstructs/fifo/test/test.set.js b/lib/node_modules/@stdlib/dstructs/fifo/test/test.set.js new file mode 100644 index 000000000000..2d3387adacda --- /dev/null +++ b/lib/node_modules/@stdlib/dstructs/fifo/test/test.set.js @@ -0,0 +1,180 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 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'; + +// MODULES // + +var tape = require( 'tape' ); +var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var FIFO = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof FIFO, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the prototype of the main export is a `set` method for setting one or more queue elements', function test( t ) { + t.strictEqual( hasOwnProp( FIFO.prototype, 'set' ), true, 'has property' ); + t.strictEqual( isFunction( FIFO.prototype.set ), true, 'has method' ); + t.end(); +}); + +tape( 'the method throws an error if invoked with a `this` context which is not a FIFO instance', function test( t ) { + var values; + var q; + var i; + + q = new FIFO(); + q.push( 'foo' ); + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + {}, + [] + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return q.set.call( value, 'a', 0 ); + }; + } +}); + +tape( 'the method throws an error if provided an index argument which is not a nonnegative integer', function test( t ) { + var values; + var q; + var i; + + q = new FIFO(); + q.push( 'foo' ); + + values = [ + '5', + -5, + 3.14, + NaN, + true, + false, + null, + void 0, + {}, + [], + function noop() {} + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return q.set( 'x', value ); + }; + } +}); + +tape( 'the method throws a RangeError if provided an index argument which is out-of-bounds', function test( t ) { + var values; + var q; + var i; + + q = new FIFO(); + q.push( 1 ); + q.push( 2 ); + + values = [ + q.length, + q.length + 1, + q.length + 2 + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), RangeError, 'throws an error when provided '+values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return q.set( 'x', value ); + }; + } +}); + +tape( 'the method sets a queue element (default index)', function test( t ) { + var q; + var v; + + q = new FIFO(); + q.push( 'a' ); + q.push( 'b' ); + + q.set( 'z' ); + v = q.get( 0 ); + t.strictEqual( v, 'z', 'sets first element when no index provided' ); + t.end(); +}); + +tape( 'the method sets a queue element (specified index)', function test( t ) { + var q; + var v; + + q = new FIFO(); + q.push( 'a' ); + q.push( 'b' ); + q.push( 'c' ); + + q.set( 'x', 1 ); + v = q.get( 1 ); + t.strictEqual( v, 'x', 'sets element at index 1' ); + t.end(); +}); + +tape( 'queue instances support numeric indexing (read)', function test( t ) { + var q = new FIFO(); + q.push( 'a' ).push( 'b' ).push( 'c' ); + + t.strictEqual( q.get( 0 ), 'a', 'get(0) matches' ); + t.strictEqual( q.get( 1 ), 'b', 'get(1) matches' ); + t.strictEqual( q.get( 2 ), 'c', 'get(2) matches' ); + t.strictEqual( q.length, 3, 'length property accessible' ); + t.end(); +}); + +tape( 'queue instances support numeric indexing (write)', function test( t ) { + var q = new FIFO(); + q.push( 'a' ).push( 'b' ); + + q.set( 'x', 1 ); + t.strictEqual( q.get( 1 ), 'x', 'set(1) updated element' ); + t.end(); +});