From b1324d60ebb417904fa3565723aa2f51a437c6e2 Mon Sep 17 00:00:00 2001 From: Nourhan Hasan Date: Thu, 11 Jul 2024 13:29:06 +0300 Subject: [PATCH 01/16] feat: add JavaScript implementation for iter/cusome --- .../@stdlib/iter/cusome/README.md | 167 ++++++++++++++++++ .../iter/cusome/benchmark/benchmark.js | 51 ++++++ .../@stdlib/iter/cusome/docs/repl.txt | 46 +++++ .../@stdlib/iter/cusome/docs/types/index.d.ts | 62 +++++++ .../@stdlib/iter/cusome/docs/types/test.ts | 55 ++++++ .../@stdlib/iter/cusome/lib/index.js | 55 ++++++ .../@stdlib/iter/cusome/lib/main.js | 110 ++++++++++++ .../@stdlib/iter/cusome/package.json | 68 +++++++ .../@stdlib/iter/cusome/test/test.js | 126 +++++++++++++ 9 files changed, 740 insertions(+) create mode 100644 lib/node_modules/@stdlib/iter/cusome/README.md create mode 100644 lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js create mode 100644 lib/node_modules/@stdlib/iter/cusome/docs/repl.txt create mode 100644 lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts create mode 100644 lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts create mode 100644 lib/node_modules/@stdlib/iter/cusome/lib/index.js create mode 100644 lib/node_modules/@stdlib/iter/cusome/lib/main.js create mode 100644 lib/node_modules/@stdlib/iter/cusome/package.json create mode 100644 lib/node_modules/@stdlib/iter/cusome/test/test.js diff --git a/lib/node_modules/@stdlib/iter/cusome/README.md b/lib/node_modules/@stdlib/iter/cusome/README.md new file mode 100644 index 000000000000..24972b16709b --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/README.md @@ -0,0 +1,167 @@ + + +# iterCuSome + +> Create an iterator which cumulatively tests whether at least `n` iterated values are truthy. + + + +
+ +This module provides an iterator function `iterCuSome` that creates an iterator to iteratively test whether at least `n` truthy values have been encountered from a source iterator. It continues iterating as long as there are values available from the source iterator. + +
+ + + + + +
+ +## Usage + +```javascript +var iterCuSome = require( '@stdlib/iter/cusome' ); +``` + +#### iterCuSome( array2iterator, n ) + +Returns an iterator which cumulatively tests whether at least `n` iterated values are truthy. + +```javascript +var array2iterator = require( '@stdlib/array/to-iterator' ); + +var arr = array2iterator( [ false, false, false, true, true ] ); + +iterator = iterCuSome( arr, 2 ); + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns false + +// .. +``` + +
+ + + + + +
+ +## Notes + +- The iterCuSome function returns an iterator which continues to iterate over values from the source iterator until at least n truthy values are encountered. +- If fewer than n truthy values are encountered, it returns false. Once n truthy values are encountered, it returns true and stops further iteration. + +
+ + + + + +
+ +## Examples + + + +```javascript +// Example 1: Testing an iterator with n = 3 + +var array2iterator = require( '@stdlib/array/to-iterator' ); + +var arr = array2iterator( [ 0, 0, 1, 1, 1 ] ); +var iterator = iterCuSome( arr, 3 ); + +var v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns true + +var done = iterator.next().done; +// returns true + +// Example 2: Testing an iterator with n = 2 + +arr = array2iterator( [ false, false, false, true, true ] ); + +iterator = iterCuSome( arr, 2 ); + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns false + +v = iterator.next().value; +// returns true + +done = iterator.next().done; +// returns true +``` + +
+ + + + + +
+ +
+ + + + + +
+ +
+ + + + + +
+ +
+ + diff --git a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js new file mode 100644 index 000000000000..5f71ede211d0 --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js @@ -0,0 +1,51 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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 isIteratorLike = require( '@stdlib/assert/is-iterator-like' ); +var array2iterator = require( '@stdlib/array/to-iterator' ); +var pkg = require( './../package.json' ).name; +var iterCuSome = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var iter; + var arr; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + arr = array2iterator( [ false, false, false, true, true ] ); + iter = iterCuSome( arr, 2 ); + if ( typeof iter !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isIteratorLike( iter ) ) { + b.fail( 'should return an iterator protocol-compliant object' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/iter/cusome/docs/repl.txt b/lib/node_modules/@stdlib/iter/cusome/docs/repl.txt new file mode 100644 index 000000000000..933b5abfea13 --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/docs/repl.txt @@ -0,0 +1,46 @@ +{{alias}}( iterator, n ) + Returns an iterator which returns `true` once at least `n` iterated + values are truthy. + + If an environment supports Symbol.iterator, the returned iterator + is iterable. + + Parameters + ---------- + iterator: Object + Source iterator. + + n: integer + Number of truthy values required to return `true`. + + Returns + ------- + iterator: Object + Iterator. + + iterator.next(): Function + Returns an iterator protocol-compliant object containing the next + iterated value (`false` or `true`) and a boolean flag indicating + whether the iterator is finished. + + iterator.return( [value] ): Function + Finishes an iterator and returns a provided value. + + Examples + -------- + > var array2iterator = require( '@stdlib/array/to-iterator' ); + > arr = array2iterator( [ false, false, false, true, true ] ); + > var it = {{alias}}( arr, 2 ); + > var v = it.next().value + false + > v = it.next().value + false + > v = it.next().value + false + > v = it.next().value + false + > v = it.next().value + true + + See Also + -------- diff --git a/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts b/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts new file mode 100644 index 000000000000..7e8a9e0572bc --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts @@ -0,0 +1,62 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2024 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 + +/// + +import { Iterator as Iter, IterableIterator } from '@stdlib/types/iter'; + +// Define a union type representing both iterable and non-iterable iterators: +type Iterator = Iter | IterableIterator; + +/** +* Returns an iterator which returns `true` once at least `n` iterated values are truthy. +* +* ## Notes +* +* - If an environment supports `Symbol.iterator`, the returned iterator is iterable. +* +* @param iterator - source iterator +* @param n - number of truthy values required to return `true` +* @throws `n` must be a nonnegative integer +* @returns iterator +* +* @example +* var array2iterator = require( '@stdlib/array/to-iterator' ); +* var iterCuSome = require( '@stdlib/iter/cusome' ); +* +* var it = iterCuSome( array2iterator( [ false, false, false, true, true ] ), 2 ); +* +* var v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns false +* +* // .. +*/ +declare function iterCuSome( iterator: Iterator, n: number ): Iterator; + + +// EXPORTS // + +export = iterCuSome; diff --git a/lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts b/lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts new file mode 100644 index 000000000000..197a9144694f --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts @@ -0,0 +1,55 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2024 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. +*/ + +import array2iterator = require( '@stdlib/array/to-iterator' ); +import iterCuSome = require( './index' ); + + +// TESTS // + +// The function returns an iterator... +{ + iterCuSome( array2iterator( [ false, false, false, true, true ] ), 2 ); // $ExpectType Iterator +} + +// The compiler throws an error if the function is provided a first argument which is not an iterator... +{ + iterCuSome( 'abc', 2 ); // $ExpectError + iterCuSome( 123, 2 ); // $ExpectError + iterCuSome( true, 2 ); // $ExpectError + iterCuSome( false, 2 ); // $ExpectError + iterCuSome( [], 2 ); // $ExpectError + iterCuSome( {}, 2 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not a number... +{ + iterCuSome( array2iterator( [ false, false, false, true, true ] ), '2' ); // $ExpectError + iterCuSome( array2iterator( [ false, false, false, true, true ] ), true ); // $ExpectError + iterCuSome( array2iterator( [ false, false, false, true, true ] ), false ); // $ExpectError + iterCuSome( array2iterator( [ false, false, false, true, true ] ), null ); // $ExpectError + iterCuSome( array2iterator( [ false, false, false, true, true ] ), [] ); // $ExpectError + iterCuSome( array2iterator( [ false, false, false, true, true ] ), {} ); // $ExpectError + iterCuSome( array2iterator( [ false, false, false, true, true ] ), ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided insufficient arguments... +{ + iterCuSome(); // $ExpectError + iterCuSome( array2iterator( [ false, false, false, true, true ] ) ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/iter/cusome/lib/index.js b/lib/node_modules/@stdlib/iter/cusome/lib/index.js new file mode 100644 index 000000000000..578396eefd04 --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/lib/index.js @@ -0,0 +1,55 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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'; + +/** +* Create an iterator which tests whether at least `n` iterated values are truthy. +* +* @module @stdlib/iter/cusome +* +* @example +* +* var array2iterator = require( '@stdlib/array/to-iterator' ); +* +* var iterCuSome = require( '@stdlib/iter/cusome' ); +* +* var arr = array2iterator( [ false, false, false, true, true ] ); +* +* var it = iterCuSome( arr, 2 ); +* +* var v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns false +* +* // .. +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/iter/cusome/lib/main.js b/lib/node_modules/@stdlib/iter/cusome/lib/main.js new file mode 100644 index 000000000000..f85ab9a17881 --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/lib/main.js @@ -0,0 +1,110 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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'; + +// MAIN // + +/** +* Returns an iterator which tests whether at least `n` iterated values are truthy. +* +* @param {Iterator} iterator - source iterator +* @param {number} n - number of truthy values to test +* @returns {Iterator} iterator +* +* @example +* var array2iterator = require( '@stdlib/array/to-iterator' ); +* +* var arr = array2iterator( [ false, false, false, true, true ] ); +* +* var it = iterCuSome( arr, 2 ); +* +* var v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns true +* +* var bool = it.next().done; +* // returns true +*/ +function iterCuSome( iterator, n ) { + var count; + var done; + var obj; + + count = 0; + done = false; + /** + * Advances the iterator and checks if the condition is met. + * + * @returns {Object} - Object with `value` and `done` properties. + */ + function next() { + var v; + + if ( done ) { + return { + 'done': true + }; + } + v = iterator.next(); + if ( v.done ) { + done = true; + return { + 'value': count >= n, + 'done': true + }; + } + if ( v.value ) { + count += 1; + } + if ( count >= n ) { + done = true; + return { + 'value': true, + 'done': false + }; + } + return { + 'value': false, + 'done': false + }; + } + + // Define the iterator protocol + obj = {}; + obj.next = next; + obj[Symbol.iterator] = obj; + + return obj; +} + + +// EXPORTS // + +module.exports = iterCuSome; diff --git a/lib/node_modules/@stdlib/iter/cusome/package.json b/lib/node_modules/@stdlib/iter/cusome/package.json new file mode 100644 index 000000000000..24c97b5f9d3a --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/package.json @@ -0,0 +1,68 @@ +{ + "name": "@stdlib/iter/cusome", + "version": "0.0.0", + "description": "Create an iterator which tests whether at least `n` iterated values are truthy.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdutils", + "stdutil", + "utilities", + "utility", + "utils", + "util", + "cartesian", + "combination", + "permutation", + "iterator", + "iterate", + "iteration", + "iter" + ] + } + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/iter/cusome/test/test.js b/lib/node_modules/@stdlib/iter/cusome/test/test.js new file mode 100644 index 000000000000..922f1020f950 --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/test/test.js @@ -0,0 +1,126 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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 array2iterator = require( '@stdlib/array/to-iterator' ); +var iterCuSome = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof iterCuSome, 'function', 'main export is a function' ); + t.end(); +} ); + +tape( 'the function returns an iterator which tests whether at least `n` iterated values are truthy', function test( t ) { + var expected; + var iterator; + var actual; + var arr; + var v; + + arr = array2iterator( [ false, false, false, true, true ] ); + iterator = iterCuSome( arr, 2 ); + expected = [ false, false, false, false, true ]; + actual = []; + + while ( true ) { + v = iterator.next(); + if ( v.done ) { + break; + } + actual.push( v.value ); + } + t.deepEqual( actual, expected, 'returns expected values' ); + t.end(); +} ); + +tape( 'the function returns an iterator which returns `true` once at least `n` truthy values have been iterated', function test( t ) { + var iterator; + var expected; + var actual; + var arr; + var v; + + arr = array2iterator( [ 0, 0, 1, 1, 1 ] ); + iterator = iterCuSome( arr, 3 ); + expected = [ false, false, false, false, true ]; + actual = []; + + while ( true ) { + v = iterator.next(); + if ( v.done ) { + break; + } + actual.push( v.value ); + } + t.deepEqual( actual, expected, 'returns expected values' ); + t.end(); +} ); + +tape( 'the function returns an iterator which returns `false` if fewer than `n` truthy values are iterated', function test( t ) { + var iterator; + var expected; + var actual; + var arr; + var v; + + arr = array2iterator( [ 0, 0, 0, 1, 1 ] ); + iterator = iterCuSome( arr, 3 ); + expected = [ false, false, false, false, false ]; + actual = []; + + while ( true ) { + v = iterator.next(); + if ( v.done ) { + break; + } + actual.push( v.value ); + } + t.deepEqual( actual, expected, 'returns expected values' ); + t.end(); +} ); + +tape( 'the function returns `true` immediately if the first `n` values are truthy', function test( t ) { + var iterator; + var expected; + var actual; + var arr; + var v; + + arr = array2iterator( [ 1, 1, 0, 0, 0 ] ); + iterator = iterCuSome( arr, 2 ); + expected = [ false, true ]; + actual = []; + + while ( true ) { + v = iterator.next(); + if ( v.done ) { + break; + } + actual.push( v.value ); + } + t.deepEqual( actual, expected, 'returns expected values' ); + t.end(); +} ); From cc8a093b7af1bdb821b1ab970715ee50420857b6 Mon Sep 17 00:00:00 2001 From: Nourhan Hasan Date: Fri, 12 Jul 2024 13:24:47 +0300 Subject: [PATCH 02/16] feat: add JavaScript implementation for iter/cusome --- .../@stdlib/iter/cusome/README.md | 6 +- .../@stdlib/iter/cusome/lib/main.js | 64 ++++----- .../@stdlib/iter/cusome/package.json | 92 +++++++------ .../@stdlib/iter/cusome/test/test.js | 129 +++++++++++------- 4 files changed, 165 insertions(+), 126 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/README.md b/lib/node_modules/@stdlib/iter/cusome/README.md index 24972b16709b..828fbac8df8c 100644 --- a/lib/node_modules/@stdlib/iter/cusome/README.md +++ b/lib/node_modules/@stdlib/iter/cusome/README.md @@ -115,7 +115,7 @@ var done = iterator.next().done; // Example 2: Testing an iterator with n = 2 -arr = array2iterator( [ false, false, false, true, true ] ); +arr = array2iterator( [ false, true, true, false, false ] ); iterator = iterCuSome( arr, 2 ); @@ -126,10 +126,10 @@ v = iterator.next().value; // returns false v = iterator.next().value; -// returns false +// returns true v = iterator.next().value; -// returns false +// returns true v = iterator.next().value; // returns true diff --git a/lib/node_modules/@stdlib/iter/cusome/lib/main.js b/lib/node_modules/@stdlib/iter/cusome/lib/main.js index f85ab9a17881..c0092226b008 100644 --- a/lib/node_modules/@stdlib/iter/cusome/lib/main.js +++ b/lib/node_modules/@stdlib/iter/cusome/lib/main.js @@ -18,13 +18,23 @@ 'use strict'; +// MODULES // + +var setReadOnly = require('@stdlib/utils/define-nonenumerable-read-only-property'); +var isIteratorLike = require( '@stdlib/assert-is-iterator-like' ); +var isPositiveInteger = require( '@stdlib/assert-is-positive-integer' ).isPrimitive; +var format = require( '@stdlib/string-format' ); + + // MAIN // /** * Returns an iterator which tests whether at least `n` iterated values are truthy. * -* @param {Iterator} iterator - source iterator -* @param {number} n - number of truthy values to test +* @param {Iterator} iterator - input iterator +* @param {PositiveInteger} n - minimum number of truthy elements +* @throws {TypeError} first argument must be an iterator +* @throws {TypeError} second argument must be a positive integer * @returns {Iterator} iterator * * @example @@ -54,54 +64,46 @@ */ function iterCuSome( iterator, n ) { var count; - var done; - var obj; + var iter; + + if ( !isIteratorLike( iterator ) ) { + throw new TypeError( format( 'invalid argument. First argument must be an iterator. Value: `%s`.', iterator ) ); + } + if ( !isPositiveInteger( n ) ) { + throw new TypeError( format( 'invalid argument. Second argument must be a positive integer. Value: `%s`.', n ) ); + } + // Create an iterator protocol-compliant object: + iter = {}; count = 0; - done = false; + setReadOnly(iter, 'next', next); + + return iter; + /** - * Advances the iterator and checks if the condition is met. - * - * @returns {Object} - Object with `value` and `done` properties. - */ +* Returns an iterator protocol-compliant object containing the next iterated value. +* +* @private +* @returns {Object} iterator protocol-compliant object +*/ function next() { var v; - if ( done ) { - return { - 'done': true - }; - } v = iterator.next(); if ( v.done ) { - done = true; return { - 'value': count >= n, + 'value': false, 'done': true }; } if ( v.value ) { count += 1; } - if ( count >= n ) { - done = true; - return { - 'value': true, - 'done': false - }; - } return { - 'value': false, + 'value': count >= n, 'done': false }; } - - // Define the iterator protocol - obj = {}; - obj.next = next; - obj[Symbol.iterator] = obj; - - return obj; } diff --git a/lib/node_modules/@stdlib/iter/cusome/package.json b/lib/node_modules/@stdlib/iter/cusome/package.json index 24c97b5f9d3a..32cd5f24f503 100644 --- a/lib/node_modules/@stdlib/iter/cusome/package.json +++ b/lib/node_modules/@stdlib/iter/cusome/package.json @@ -4,65 +4,69 @@ "description": "Create an iterator which tests whether at least `n` iterated values are truthy.", "license": "Apache-2.0", "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { "name": "The Stdlib Authors", "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } ], "main": "./lib", "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" }, "types": "./docs/types", "scripts": {}, "homepage": "https://github.com/stdlib-js/stdlib", "repository": { - "type": "git", - "url": "git://github.com/stdlib-js/stdlib.git" + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" }, "bugs": { - "url": "https://github.com/stdlib-js/stdlib/issues" + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": { + "@stdlib/assert-is-iterator-like": "^0.2.1", + "@stdlib/assert-is-positive-integer": "^0.2.1" }, - "dependencies": {}, - "devDependencies": {}, "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" + "node": ">=0.10.0", + "npm": ">2.7.0" }, "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" ], "keywords": [ - "stdlib", - "stdutils", - "stdutil", - "utilities", - "utility", - "utils", - "util", - "cartesian", - "combination", - "permutation", - "iterator", - "iterate", - "iteration", - "iter" - ] - } - \ No newline at end of file + "stdlib", + "stdutils", + "stdutil", + "utilities", + "utility", + "utils", + "util", + "cartesian", + "combination", + "permutation", + "iterator", + "iterate", + "iteration", + "iter" + ], + "devDependencies": { + "@stdlib/assert-is-boolean": "^0.2.1" + } +} diff --git a/lib/node_modules/@stdlib/iter/cusome/test/test.js b/lib/node_modules/@stdlib/iter/cusome/test/test.js index 922f1020f950..bb2db0e6544b 100644 --- a/lib/node_modules/@stdlib/iter/cusome/test/test.js +++ b/lib/node_modules/@stdlib/iter/cusome/test/test.js @@ -31,64 +31,94 @@ tape( 'main export is a function', function test( t ) { t.ok( true, __filename ); t.strictEqual( typeof iterCuSome, 'function', 'main export is a function' ); t.end(); -} ); - -tape( 'the function returns an iterator which tests whether at least `n` iterated values are truthy', function test( t ) { - var expected; - var iterator; - var actual; - var arr; - var v; - - arr = array2iterator( [ false, false, false, true, true ] ); - iterator = iterCuSome( arr, 2 ); - expected = [ false, false, false, false, true ]; - actual = []; +}); + +tape( 'the function throws an error if not provided an iterator as a first argument', function test( t ) { + var values; + var i; + + 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 a type error when provided '+values[i] ); + } + t.end(); - while ( true ) { - v = iterator.next(); - if ( v.done ) { - break; - } - actual.push( v.value ); + function badValue( value ) { + return function badValue() { + iterCuSome( value, 2 ); + }; + } +}); + +tape( 'the function throws an error if provided a second argument which is not a positive integer', function test( t ) { + var values; + var i; + + values = [ + '5', + -5, + 0, + 3.14, + NaN, + true, + false, + null, + void 0, + {}, + [], + function noop() {} + ]; + + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws a type error when provided '+values[i] ); } - t.deepEqual( actual, expected, 'returns expected values' ); t.end(); -} ); -tape( 'the function returns an iterator which returns `true` once at least `n` truthy values have been iterated', function test( t ) { - var iterator; - var expected; - var actual; + function badValue( value ) { + return function badValue() { + iterCuSome( array2iterator( [ 1, 2, 3 ] ), value ); + }; + } +}); + +tape( 'if provided an "empty" iterator, the function returns an iterator yielding `false` values', function test( t ) { var arr; + var it; var v; - arr = array2iterator( [ 0, 0, 1, 1, 1 ] ); - iterator = iterCuSome( arr, 3 ); - expected = [ false, false, false, false, true ]; - actual = []; + arr = array2iterator( [] ); + it = iterCuSome( arr, 1 ); + + v = it.next(); + t.strictEqual( v.value, false, 'returns false' ); + t.strictEqual( v.done, true, 'returns done as true' ); - while ( true ) { - v = iterator.next(); - if ( v.done ) { - break; - } - actual.push( v.value ); - } - t.deepEqual( actual, expected, 'returns expected values' ); t.end(); -} ); +}); -tape( 'the function returns an iterator which returns `false` if fewer than `n` truthy values are iterated', function test( t ) { - var iterator; +tape( 'the function returns an iterator which cumulatively tests whether at least `n` iterated values are truthy (example 1)', function test( t ) { var expected; + var iterator; var actual; var arr; var v; - arr = array2iterator( [ 0, 0, 0, 1, 1 ] ); - iterator = iterCuSome( arr, 3 ); - expected = [ false, false, false, false, false ]; + arr = array2iterator( [ false, false, false, true, true ] ); + iterator = iterCuSome( arr, 2 ); + + expected = [ false, false, false, false, true ]; actual = []; while ( true ) { @@ -98,20 +128,22 @@ tape( 'the function returns an iterator which returns `false` if fewer than `n` } actual.push( v.value ); } + t.deepEqual( actual, expected, 'returns expected values' ); t.end(); -} ); +}); -tape( 'the function returns `true` immediately if the first `n` values are truthy', function test( t ) { - var iterator; +tape( 'the function returns an iterator which cumulatively tests whether at least `n` iterated values are truthy (example 2)', function test( t ) { var expected; + var iterator; var actual; var arr; var v; arr = array2iterator( [ 1, 1, 0, 0, 0 ] ); iterator = iterCuSome( arr, 2 ); - expected = [ false, true ]; + + expected = [ false, true, true, true, true ]; actual = []; while ( true ) { @@ -121,6 +153,7 @@ tape( 'the function returns `true` immediately if the first `n` values are truth } actual.push( v.value ); } + t.deepEqual( actual, expected, 'returns expected values' ); t.end(); -} ); +}); From cf3abd0b2f527bdad3553cff22457089339912d4 Mon Sep 17 00:00:00 2001 From: Nourhan Hasan Date: Fri, 12 Jul 2024 18:25:57 +0300 Subject: [PATCH 03/16] feat: update javascript cusome benchmark --- .../iter/cusome/benchmark/benchmark.js | 100 ++++++++++++++++++ .../@stdlib/iter/cusome/lib/main.js | 10 +- 2 files changed, 105 insertions(+), 5 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js index 5f71ede211d0..34a32710f6d8 100644 --- a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js @@ -21,14 +21,74 @@ // MODULES // var bench = require( '@stdlib/bench' ); +var isBoolean = require( '@stdlib/assert-is-boolean' ).isPrimitive; var isIteratorLike = require( '@stdlib/assert/is-iterator-like' ); var array2iterator = require( '@stdlib/array/to-iterator' ); var pkg = require( './../package.json' ).name; var iterCuSome = require( './../lib' ); +// FUNCTIONS // + +function createIterator( arr ) { + var len; + var it; + var i; + + len = arr.length; + i = -1; + + it = {}; + it.next = next; + it.reset = reset; + + return it; + + function next() { + i += 1; + if ( i < len ) { + return { + 'value': arr[ i ], + 'done': false + }; + } + i = -1; // reset index + return { + 'done': true + }; + } + + function reset() { + i = -1; + } +} + + // MAIN // +bench( pkg, function benchmark( b ) { + var bool; + var arr; + var i; + + arr = createIterator( [ 0, 0, 1, 1, 1, 1 ] ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + bool = iterCuSome( arr, 4 ); + if ( typeof bool.next().value !== 'boolean' ) { + b.fail( 'should return a boolean' ); + } + arr.reset(); + } + b.toc(); + if ( !isBoolean( bool.next().done ) ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + bench( pkg, function benchmark( b ) { var iter; var arr; @@ -49,3 +109,43 @@ bench( pkg, function benchmark( b ) { b.pass( 'benchmark finished' ); b.end(); }); + +bench( pkg+'::loop', function benchmark( b ) { + var values; + var total; + var count; + var bool; + var arr; + var i; + var j; + + total = 4; + + values = [ 0, 0, 1, 1, 1, 1 ]; + arr = createIterator( values ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + bool = false; + count = 0; + for ( j = 0; j < values.length; j++ ) { + if ( arr.next().value ) { + count += 1; + if ( count === total ) { + bool = true; + break; + } + } + } + if ( typeof bool !== 'boolean' ) { + b.fail( 'should return a boolean' ); + } + arr.reset(); + } + b.toc(); + if ( !isBoolean( bool ) ) { + b.fail( 'should be a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/iter/cusome/lib/main.js b/lib/node_modules/@stdlib/iter/cusome/lib/main.js index c0092226b008..b8e539bd9f55 100644 --- a/lib/node_modules/@stdlib/iter/cusome/lib/main.js +++ b/lib/node_modules/@stdlib/iter/cusome/lib/main.js @@ -81,11 +81,11 @@ function iterCuSome( iterator, n ) { return iter; /** -* Returns an iterator protocol-compliant object containing the next iterated value. -* -* @private -* @returns {Object} iterator protocol-compliant object -*/ + * Returns an iterator protocol-compliant object containing the next iterated value. + * + * @private + * @returns {Object} iterator protocol-compliant object + */ function next() { var v; From bbbc845cf0f8ddb0cb9b270205f550b96bdac774 Mon Sep 17 00:00:00 2001 From: Nourhan Hasan Date: Tue, 16 Jul 2024 21:18:27 +0300 Subject: [PATCH 04/16] feat: update javascript main func, usit tests and fix CL errors --- .../iter/cusome/benchmark/benchmark.js | 2 +- .../@stdlib/iter/cusome/lib/main.js | 52 +++++++- .../@stdlib/iter/cusome/package.json | 16 +-- .../@stdlib/iter/cusome/test/test.js | 122 ++++++++++++++++++ 4 files changed, 176 insertions(+), 16 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js index 34a32710f6d8..4b50072e7950 100644 --- a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js @@ -21,7 +21,7 @@ // MODULES // var bench = require( '@stdlib/bench' ); -var isBoolean = require( '@stdlib/assert-is-boolean' ).isPrimitive; +var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; var isIteratorLike = require( '@stdlib/assert/is-iterator-like' ); var array2iterator = require( '@stdlib/array/to-iterator' ); var pkg = require( './../package.json' ).name; diff --git a/lib/node_modules/@stdlib/iter/cusome/lib/main.js b/lib/node_modules/@stdlib/iter/cusome/lib/main.js index b8e539bd9f55..a747ae6e9921 100644 --- a/lib/node_modules/@stdlib/iter/cusome/lib/main.js +++ b/lib/node_modules/@stdlib/iter/cusome/lib/main.js @@ -21,9 +21,11 @@ // MODULES // var setReadOnly = require('@stdlib/utils/define-nonenumerable-read-only-property'); -var isIteratorLike = require( '@stdlib/assert-is-iterator-like' ); -var isPositiveInteger = require( '@stdlib/assert-is-positive-integer' ).isPrimitive; -var format = require( '@stdlib/string-format' ); +var isIteratorLike = require('@stdlib/assert/is-iterator-like'); +var isPositiveInteger = require('@stdlib/assert/is-positive-integer').isPrimitive; +var format = require('@stdlib/string/format'); +var isFunction = require('@stdlib/assert/is-function'); +var iteratorSymbol = require('@stdlib/symbol/iterator'); // MAIN // @@ -65,6 +67,7 @@ var format = require( '@stdlib/string-format' ); function iterCuSome( iterator, n ) { var count; var iter; + var FLG; if ( !isIteratorLike( iterator ) ) { throw new TypeError( format( 'invalid argument. First argument must be an iterator. Value: `%s`.', iterator ) ); @@ -76,8 +79,13 @@ function iterCuSome( iterator, n ) { // Create an iterator protocol-compliant object: iter = {}; count = 0; - setReadOnly(iter, 'next', next); + setReadOnly( iter, 'next', next ); + setReadOnly( iter, 'return', end ); + // If an environment supports `Symbol.iterator` and the provided iterator is iterable, make the iterator iterable: + if ( iteratorSymbol && isFunction( iterator[ iteratorSymbol ] ) ) { + setReadOnly( iter, iteratorSymbol, factory ); + } return iter; /** @@ -89,8 +97,14 @@ function iterCuSome( iterator, n ) { function next() { var v; + if ( FLG ) { + return { + 'done': true + }; + } v = iterator.next(); if ( v.done ) { + FLG = true; return { 'value': false, 'done': true @@ -104,6 +118,36 @@ function iterCuSome( iterator, n ) { 'done': false }; } + + /** + * Finishes an iterator. + * + * @private + * @param {*} [value] - value to return + * @returns {Object} iterator protocol-compliant object + */ + function end( value ) { + FLG = true; + if ( arguments.length ) { + return { + 'value': value, + 'done': true + }; + } + return { + 'done': true + }; + } + + /** + * Returns a new iterator. + * + * @private + * @returns {Iterator} iterator + */ + function factory() { + return iterCuSome( iterator[ iteratorSymbol ](), n ); + } } diff --git a/lib/node_modules/@stdlib/iter/cusome/package.json b/lib/node_modules/@stdlib/iter/cusome/package.json index 32cd5f24f503..b39e5ac0757e 100644 --- a/lib/node_modules/@stdlib/iter/cusome/package.json +++ b/lib/node_modules/@stdlib/iter/cusome/package.json @@ -31,10 +31,8 @@ "bugs": { "url": "https://github.com/stdlib-js/stdlib/issues" }, - "dependencies": { - "@stdlib/assert-is-iterator-like": "^0.2.1", - "@stdlib/assert-is-positive-integer": "^0.2.1" - }, + "dependencies": {}, + "devDependencies": {}, "engines": { "node": ">=0.10.0", "npm": ">2.7.0" @@ -58,15 +56,11 @@ "utility", "utils", "util", - "cartesian", - "combination", - "permutation", + "some", + "cusome", "iterator", "iterate", "iteration", "iter" - ], - "devDependencies": { - "@stdlib/assert-is-boolean": "^0.2.1" - } + ] } diff --git a/lib/node_modules/@stdlib/iter/cusome/test/test.js b/lib/node_modules/@stdlib/iter/cusome/test/test.js index bb2db0e6544b..18d98f92d571 100644 --- a/lib/node_modules/@stdlib/iter/cusome/test/test.js +++ b/lib/node_modules/@stdlib/iter/cusome/test/test.js @@ -21,7 +21,10 @@ // MODULES // var tape = require( 'tape' ); +var proxyquire = require( 'proxyquire' ); var array2iterator = require( '@stdlib/array/to-iterator' ); +var randu = require( '@stdlib/random/iter/randu' ); +var iteratorSymbol = require( '@stdlib/symbol/iterator' ); var iterCuSome = require( './../lib' ); @@ -157,3 +160,122 @@ tape( 'the function returns an iterator which cumulatively tests whether at leas t.deepEqual( actual, expected, 'returns expected values' ); t.end(); }); + +tape( 'the returned iterator has a `return` method for closing an iterator (no argument)', function test( t ) { + var it; + var r; + + it = iterCuSome( randu(), 2 ); + + r = it.next(); + t.equal( typeof r.value, 'boolean', 'returns expected value' ); + t.equal( r.done, false, 'returns expected value' ); + + r = it.next(); + t.equal( typeof r.value, 'boolean', 'returns expected value' ); + t.equal( r.done, false, 'returns expected value' ); + + r = it.return(); + t.equal( r.value, void 0, 'returns expected value' ); + t.equal( r.done, true, 'returns expected value' ); + + r = it.next(); + t.equal( r.value, void 0, 'returns expected value' ); + t.equal( r.done, true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the returned iterator has a `return` method for closing an iterator (argument)', function test( t ) { + var it; + var r; + + it = iterCuSome( randu(), 2 ); + + r = it.next(); + t.equal( typeof r.value, 'boolean', 'returns expected value' ); + t.equal( r.done, false, 'returns expected value' ); + + r = it.next(); + t.equal( typeof r.value, 'boolean', 'returns expected value' ); + t.equal( r.done, false, 'returns expected value' ); + + r = it.return( 'finished' ); + t.equal( r.value, 'finished', 'returns expected value' ); + t.equal( r.done, true, 'returns expected value' ); + + r = it.next(); + t.equal( r.value, void 0, 'returns expected value' ); + t.equal( r.done, true, 'returns expected value' ); + + t.end(); +}); + +tape( 'if an environment supports `Symbol.iterator` and the provided iterator is iterable, the returned iterator is iterable', function test( t ) { + var iterCuSome; + var opts; + var rand; + var it1; + var it2; + var i; + + iterCuSome = proxyquire( './../lib/main.js', { + '@stdlib/symbol/iterator': '__ITERATOR_SYMBOL__' + }); + + opts = { + 'seed': 12345 + }; + rand = randu( opts ); + rand[ '__ITERATOR_SYMBOL__' ] = factory; + + it1 = iterCuSome( rand, 2 ); + t.equal( typeof it1[ '__ITERATOR_SYMBOL__' ], 'function', 'has method' ); + t.equal( it1[ '__ITERATOR_SYMBOL__' ].length, 0, 'has zero arity' ); + + it2 = it1[ '__ITERATOR_SYMBOL__' ](); + t.equal( typeof it2, 'object', 'returns an object' ); + t.equal( typeof it2.next, 'function', 'has method' ); + t.equal( typeof it2.return, 'function', 'has method' ); + + for ( i = 0; i < 100; i++ ) { + t.equal( it2.next().value, it1.next().value, 'returns expected value' ); + } + t.end(); + + function factory() { + return randu( opts ); + } +}); + +tape( 'if an environment does not support `Symbol.iterator`, the returned iterator is not "iterable"', function test( t ) { + var iterCuSome; + var it; + + iterCuSome = proxyquire( './../lib/main.js', { + '@stdlib/symbol/iterator': false + }); + + it = iterCuSome( randu(), 2 ); + t.equal( it[ iteratorSymbol ], void 0, 'does not have property' ); + + t.end(); +}); + +tape( 'if a provided iterator is not iterable, the returned iterator is not iterable', function test( t ) { + var iterCuSome; + var rand; + var it; + + iterCuSome = proxyquire( './../lib/main.js', { + '@stdlib/symbol/iterator': '__ITERATOR_SYMBOL__' + }); + + rand = randu(); + rand[ '__ITERATOR_SYMBOL__' ] = null; + + it = iterCuSome( rand, 2 ); + t.equal( it[ iteratorSymbol ], void 0, 'does not have property' ); + + t.end(); +}); From 20cb343209c08fea746055d81b0dfc01bb5c112c Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 14:38:32 -0700 Subject: [PATCH 05/16] bench: refactor benchmarks --- .../iter/cusome/benchmark/benchmark.js | 102 +++--------------- 1 file changed, 13 insertions(+), 89 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js index 4b50072e7950..19b398e7bdde 100644 --- a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js @@ -23,81 +23,23 @@ var bench = require( '@stdlib/bench' ); var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; var isIteratorLike = require( '@stdlib/assert/is-iterator-like' ); -var array2iterator = require( '@stdlib/array/to-iterator' ); +var iterConstant = require( '@stdlib/iter/constant' ); var pkg = require( './../package.json' ).name; var iterCuSome = require( './../lib' ); -// FUNCTIONS // - -function createIterator( arr ) { - var len; - var it; - var i; - - len = arr.length; - i = -1; - - it = {}; - it.next = next; - it.reset = reset; - - return it; - - function next() { - i += 1; - if ( i < len ) { - return { - 'value': arr[ i ], - 'done': false - }; - } - i = -1; // reset index - return { - 'done': true - }; - } - - function reset() { - i = -1; - } -} - - // MAIN // -bench( pkg, function benchmark( b ) { - var bool; - var arr; - var i; - - arr = createIterator( [ 0, 0, 1, 1, 1, 1 ] ); - - b.tic(); - for ( i = 0; i < b.iterations; i++ ) { - bool = iterCuSome( arr, 4 ); - if ( typeof bool.next().value !== 'boolean' ) { - b.fail( 'should return a boolean' ); - } - arr.reset(); - } - b.toc(); - if ( !isBoolean( bool.next().done ) ) { - b.fail( 'should return a boolean' ); - } - b.pass( 'benchmark finished' ); - b.end(); -}); - bench( pkg, function benchmark( b ) { var iter; - var arr; + var it; var i; + it = iterConstant( 3.14 ); + b.tic(); for ( i = 0; i < b.iterations; i++ ) { - arr = array2iterator( [ false, false, false, true, true ] ); - iter = iterCuSome( arr, 2 ); + iter = iterCuSome( it, 2 ); if ( typeof iter !== 'object' ) { b.fail( 'should return an object' ); } @@ -110,41 +52,23 @@ bench( pkg, function benchmark( b ) { b.end(); }); -bench( pkg+'::loop', function benchmark( b ) { - var values; - var total; - var count; - var bool; - var arr; +bench( pkg+'::iteration', function benchmark( b ) { + var iter; + var v; var i; - var j; - - total = 4; - values = [ 0, 0, 1, 1, 1, 1 ]; - arr = createIterator( values ); + iter = iterCuSome( iterConstant( 3.14 ), b.iterations-1 ); b.tic(); for ( i = 0; i < b.iterations; i++ ) { - bool = false; - count = 0; - for ( j = 0; j < values.length; j++ ) { - if ( arr.next().value ) { - count += 1; - if ( count === total ) { - bool = true; - break; - } - } - } - if ( typeof bool !== 'boolean' ) { + v = iter.next().value; + if ( !isBoolean( v ) ) { b.fail( 'should return a boolean' ); } - arr.reset(); } b.toc(); - if ( !isBoolean( bool ) ) { - b.fail( 'should be a boolean' ); + if ( !isBoolean( v ) ) { + b.fail( 'should return a boolean' ); } b.pass( 'benchmark finished' ); b.end(); From 5495ff1406a1f0e57c27e581fc460fdb0dc67683 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 14:43:02 -0700 Subject: [PATCH 06/16] docs: update examples --- .../@stdlib/iter/cusome/docs/types/index.d.ts | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts b/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts index 7e8a9e0572bc..a18ab5b9c840 100644 --- a/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts @@ -26,22 +26,17 @@ import { Iterator as Iter, IterableIterator } from '@stdlib/types/iter'; type Iterator = Iter | IterableIterator; /** -* Returns an iterator which returns `true` once at least `n` iterated values are truthy. -* -* ## Notes -* -* - If an environment supports `Symbol.iterator`, the returned iterator is iterable. +* Returns an iterator which cumulatively tests whether at least `n` iterated values are truthy. * * @param iterator - source iterator -* @param n - number of truthy values required to return `true` -* @throws `n` must be a nonnegative integer +* @param n - minimum number of truthy elements * @returns iterator * * @example * var array2iterator = require( '@stdlib/array/to-iterator' ); * var iterCuSome = require( '@stdlib/iter/cusome' ); * -* var it = iterCuSome( array2iterator( [ false, false, false, true, true ] ), 2 ); +* var it = iterCuSome( array2iterator( [ false, false, false, true, true, false ] ), 2 ); * * var v = it.next().value; * // returns false @@ -52,6 +47,15 @@ type Iterator = Iter | IterableIterator; * v = it.next().value; * // returns false * +* v = it.next().value; +* // returns false +* +* v = it.next().value; +* // returns true +* +* v = it.next().value; +* // returns true +* * // .. */ declare function iterCuSome( iterator: Iterator, n: number ): Iterator; From 4deb444faa74f34d37986d6bc3e79e6b4c4118c8 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 14:44:25 -0700 Subject: [PATCH 07/16] test: refactor tests --- .../@stdlib/iter/cusome/docs/types/test.ts | 23 +++++++++++-------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts b/lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts index 197a9144694f..6a172ffa04a9 100644 --- a/lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts +++ b/lib/node_modules/@stdlib/iter/cusome/docs/types/test.ts @@ -39,17 +39,22 @@ import iterCuSome = require( './index' ); // The compiler throws an error if the function is provided a second argument which is not a number... { - iterCuSome( array2iterator( [ false, false, false, true, true ] ), '2' ); // $ExpectError - iterCuSome( array2iterator( [ false, false, false, true, true ] ), true ); // $ExpectError - iterCuSome( array2iterator( [ false, false, false, true, true ] ), false ); // $ExpectError - iterCuSome( array2iterator( [ false, false, false, true, true ] ), null ); // $ExpectError - iterCuSome( array2iterator( [ false, false, false, true, true ] ), [] ); // $ExpectError - iterCuSome( array2iterator( [ false, false, false, true, true ] ), {} ); // $ExpectError - iterCuSome( array2iterator( [ false, false, false, true, true ] ), ( x: number ): number => x ); // $ExpectError + const it = array2iterator( [ false, false, false, true, true ] ); + + iterCuSome( it, '2' ); // $ExpectError + iterCuSome( it, true ); // $ExpectError + iterCuSome( it, false ); // $ExpectError + iterCuSome( it, null ); // $ExpectError + iterCuSome( it, [] ); // $ExpectError + iterCuSome( it, {} ); // $ExpectError + iterCuSome( it, ( x: number ): number => x ); // $ExpectError } -// The compiler throws an error if the function is provided insufficient arguments... +// The compiler throws an error if the function is provided an unsupported number of arguments... { + const it = array2iterator( [ false, false, false, true, true ] ); + iterCuSome(); // $ExpectError - iterCuSome( array2iterator( [ false, false, false, true, true ] ) ); // $ExpectError + iterCuSome( it ); // $ExpectError + iterCuSome( it, 2, {} ); // $ExpectError } From 2f57da9e08c9d780052bf26591c725bf9c892ac9 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 14:47:06 -0700 Subject: [PATCH 08/16] docs: update copy and fix examples --- .../@stdlib/iter/cusome/docs/repl.txt | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/docs/repl.txt b/lib/node_modules/@stdlib/iter/cusome/docs/repl.txt index 933b5abfea13..27e6e102133b 100644 --- a/lib/node_modules/@stdlib/iter/cusome/docs/repl.txt +++ b/lib/node_modules/@stdlib/iter/cusome/docs/repl.txt @@ -1,17 +1,18 @@ + {{alias}}( iterator, n ) - Returns an iterator which returns `true` once at least `n` iterated + Returns an iterator which cumulatively tests whether at least `n` iterated values are truthy. - - If an environment supports Symbol.iterator, the returned iterator - is iterable. + + If an environment supports Symbol.iterator and a provided iterator is + iterable, the returned iterator is iterable. Parameters ---------- iterator: Object - Source iterator. + Input iterator. n: integer - Number of truthy values required to return `true`. + Minimum number of truthy values. Returns ------- @@ -20,16 +21,15 @@ iterator.next(): Function Returns an iterator protocol-compliant object containing the next - iterated value (`false` or `true`) and a boolean flag indicating - whether the iterator is finished. + iterated value (if one exists) and a boolean flag indicating whether the + iterator is finished. iterator.return( [value] ): Function Finishes an iterator and returns a provided value. Examples -------- - > var array2iterator = require( '@stdlib/array/to-iterator' ); - > arr = array2iterator( [ false, false, false, true, true ] ); + > var arr = {{alias:@stdlib/array/to-iterator}}( [ 0, 0, 1, 1, 0 ] ); > var it = {{alias}}( arr, 2 ); > var v = it.next().value false @@ -38,9 +38,10 @@ > v = it.next().value false > v = it.next().value - false + true > v = it.next().value true See Also -------- + From 801c269dd5c4cdc3e696c96ba4fc1e4e273c9378 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 14:49:13 -0700 Subject: [PATCH 09/16] docs: add and update examples --- .../@stdlib/iter/cusome/README.md | 75 +++++++------------ .../@stdlib/iter/cusome/examples/index.js | 49 ++++++++++++ 2 files changed, 77 insertions(+), 47 deletions(-) create mode 100644 lib/node_modules/@stdlib/iter/cusome/examples/index.js diff --git a/lib/node_modules/@stdlib/iter/cusome/README.md b/lib/node_modules/@stdlib/iter/cusome/README.md index 828fbac8df8c..bf47ce3ce2ce 100644 --- a/lib/node_modules/@stdlib/iter/cusome/README.md +++ b/lib/node_modules/@stdlib/iter/cusome/README.md @@ -88,54 +88,35 @@ v = iterator.next().value; ```javascript -// Example 1: Testing an iterator with n = 3 - -var array2iterator = require( '@stdlib/array/to-iterator' ); - -var arr = array2iterator( [ 0, 0, 1, 1, 1 ] ); -var iterator = iterCuSome( arr, 3 ); - -var v = iterator.next().value; -// returns false - -v = iterator.next().value; -// returns false - -v = iterator.next().value; -// returns false - -v = iterator.next().value; -// returns false - -v = iterator.next().value; -// returns true - -var done = iterator.next().done; -// returns true - -// Example 2: Testing an iterator with n = 2 - -arr = array2iterator( [ false, true, true, false, false ] ); - -iterator = iterCuSome( arr, 2 ); - -v = iterator.next().value; -// returns false - -v = iterator.next().value; -// returns false - -v = iterator.next().value; -// returns true - -v = iterator.next().value; -// returns true - -v = iterator.next().value; -// returns true +var randu = require( '@stdlib/random/iter/randu' ); +var iterMap = require( '@stdlib/iter/map' ); +var iterCuSome = require( '@stdlib/iter/cusome' ); -done = iterator.next().done; -// returns true +function threshold( r ) { + return ( r > 0.95 ); +} + +// Create an iterator which generates uniformly distributed pseudorandom numbers: +var opts = { + 'iter': 100 +}; +var riter = randu( opts ); + +// Create an iterator which applies a threshold to generated numbers: +var miter = iterMap( riter, threshold ); + +// Create an iterator which cumulatively tests whether at least 5 iterated values are truthy: +var it = iterCuSome( miter, 5 ); + +// Perform manual iteration... +var r; +while ( true ) { + r = it.next(); + if ( r.done ) { + break; + } + console.log( r.value ); +} ``` diff --git a/lib/node_modules/@stdlib/iter/cusome/examples/index.js b/lib/node_modules/@stdlib/iter/cusome/examples/index.js new file mode 100644 index 000000000000..361d5c294b9c --- /dev/null +++ b/lib/node_modules/@stdlib/iter/cusome/examples/index.js @@ -0,0 +1,49 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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'; + +var randu = require( '@stdlib/random/iter/randu' ); +var iterMap = require( '@stdlib/iter/map' ); +var iterCuSome = require( './../lib' ); + +function threshold( r ) { + return ( r > 0.95 ); +} + +// Create an iterator which generates uniformly distributed pseudorandom numbers: +var opts = { + 'iter': 100 +}; +var riter = randu( opts ); + +// Create an iterator which applies a threshold to generated numbers: +var miter = iterMap( riter, threshold ); + +// Create an iterator which cumulatively tests whether at least 5 iterated values are truthy: +var it = iterCuSome( miter, 5 ); + +// Perform manual iteration... +var r; +while ( true ) { + r = it.next(); + if ( r.done ) { + break; + } + console.log( r.value ); +} From fd67e2e369c9eeec4b8db53d1fbe89a3653fc828 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 15:09:36 -0700 Subject: [PATCH 10/16] docs: update copy --- .../@stdlib/iter/cusome/lib/index.js | 15 +++++++---- .../@stdlib/iter/cusome/lib/main.js | 26 ++++++++----------- 2 files changed, 21 insertions(+), 20 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/lib/index.js b/lib/node_modules/@stdlib/iter/cusome/lib/index.js index 578396eefd04..40da491a1a20 100644 --- a/lib/node_modules/@stdlib/iter/cusome/lib/index.js +++ b/lib/node_modules/@stdlib/iter/cusome/lib/index.js @@ -19,17 +19,15 @@ 'use strict'; /** -* Create an iterator which tests whether at least `n` iterated values are truthy. +* Create an iterator which cumulatively tests whether at least `n` iterated values are truthy. * * @module @stdlib/iter/cusome * * @example -* * var array2iterator = require( '@stdlib/array/to-iterator' ); -* * var iterCuSome = require( '@stdlib/iter/cusome' ); * -* var arr = array2iterator( [ false, false, false, true, true ] ); +* var arr = array2iterator( [ 0, 0, 1, 1, 0 ] ); * * var it = iterCuSome( arr, 2 ); * @@ -42,7 +40,14 @@ * v = it.next().value; * // returns false * -* // .. +* v = it.next().value; +* // returns true +* +* v = it.next().value; +* // returns true +* +* var bool = it.next().done; +* // returns true */ // MODULES // diff --git a/lib/node_modules/@stdlib/iter/cusome/lib/main.js b/lib/node_modules/@stdlib/iter/cusome/lib/main.js index a747ae6e9921..dfd9df06dd29 100644 --- a/lib/node_modules/@stdlib/iter/cusome/lib/main.js +++ b/lib/node_modules/@stdlib/iter/cusome/lib/main.js @@ -20,18 +20,18 @@ // MODULES // -var setReadOnly = require('@stdlib/utils/define-nonenumerable-read-only-property'); -var isIteratorLike = require('@stdlib/assert/is-iterator-like'); -var isPositiveInteger = require('@stdlib/assert/is-positive-integer').isPrimitive; -var format = require('@stdlib/string/format'); -var isFunction = require('@stdlib/assert/is-function'); -var iteratorSymbol = require('@stdlib/symbol/iterator'); +var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var isIteratorLike = require( '@stdlib/assert/is-iterator-like' ); +var isPositiveInteger = require( '@stdlib/assert/is-positive-integer' ).isPrimitive; +var iteratorSymbol = require( '@stdlib/symbol/iterator' ); +var format = require( '@stdlib/string/format' ); // MAIN // /** -* Returns an iterator which tests whether at least `n` iterated values are truthy. +* Returns an iterator which cumulatively tests whether at least `n` iterated values are truthy. * * @param {Iterator} iterator - input iterator * @param {PositiveInteger} n - minimum number of truthy elements @@ -42,7 +42,7 @@ var iteratorSymbol = require('@stdlib/symbol/iterator'); * @example * var array2iterator = require( '@stdlib/array/to-iterator' ); * -* var arr = array2iterator( [ false, false, false, true, true ] ); +* var arr = array2iterator( [ 0, 0, 1, 1, 0 ] ); * * var it = iterCuSome( arr, 2 ); * @@ -56,7 +56,7 @@ var iteratorSymbol = require('@stdlib/symbol/iterator'); * // returns false * * v = it.next().value; -* // returns false +* // returns true * * v = it.next().value; * // returns true @@ -75,10 +75,10 @@ function iterCuSome( iterator, n ) { if ( !isPositiveInteger( n ) ) { throw new TypeError( format( 'invalid argument. Second argument must be a positive integer. Value: `%s`.', n ) ); } + count = 0; // Create an iterator protocol-compliant object: iter = {}; - count = 0; setReadOnly( iter, 'next', next ); setReadOnly( iter, 'return', end ); @@ -96,7 +96,6 @@ function iterCuSome( iterator, n ) { */ function next() { var v; - if ( FLG ) { return { 'done': true @@ -105,10 +104,7 @@ function iterCuSome( iterator, n ) { v = iterator.next(); if ( v.done ) { FLG = true; - return { - 'value': false, - 'done': true - }; + return v; } if ( v.value ) { count += 1; From 20b6a99b6dcfcb065b8a438079410f71bbf587bb Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 15:16:18 -0700 Subject: [PATCH 11/16] test: refactor tests --- .../@stdlib/iter/cusome/test/test.js | 131 +++++++++++++----- 1 file changed, 97 insertions(+), 34 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/test/test.js b/lib/node_modules/@stdlib/iter/cusome/test/test.js index 18d98f92d571..b45e2ac8ebd6 100644 --- a/lib/node_modules/@stdlib/iter/cusome/test/test.js +++ b/lib/node_modules/@stdlib/iter/cusome/test/test.js @@ -36,7 +36,7 @@ tape( 'main export is a function', function test( t ) { t.end(); }); -tape( 'the function throws an error if not provided an iterator as a first argument', function test( t ) { +tape( 'the function throws an error if provided a first argument which is not an iterator protocol-compliant object', function test( t ) { var values; var i; @@ -96,7 +96,24 @@ tape( 'the function throws an error if provided a second argument which is not a } }); -tape( 'if provided an "empty" iterator, the function returns an iterator yielding `false` values', function test( t ) { +tape( 'the function returns an iterator protocol-compliant object', function test( t ) { + var arr; + var it; + var r; + var i; + + arr = array2iterator( [ 0, 0, 1, 0, 1 ] ); + it = iterCuSome( arr, 1 ); + for ( i = 0; i < 5; i++ ) { + r = it.next(); + t.equal( typeof r.value, 'boolean', 'returns expected value' ); + t.equal( typeof r.done, 'boolean', 'returns expected value' ); + } + t.equal( typeof r.done, 'boolean', 'returns expected value' ); + t.end(); +}); + +tape( 'if provided an "empty" iterator, the function returns an iterator which is also empty', function test( t ) { var arr; var it; var v; @@ -105,58 +122,104 @@ tape( 'if provided an "empty" iterator, the function returns an iterator yieldin it = iterCuSome( arr, 1 ); v = it.next(); - t.strictEqual( v.value, false, 'returns false' ); - t.strictEqual( v.done, true, 'returns done as true' ); + t.strictEqual( v.value, false, 'returns expected value' ); + t.strictEqual( v.done, true, 'returns expected value' ); t.end(); }); -tape( 'the function returns an iterator which cumulatively tests whether at least `n` iterated values are truthy (example 1)', function test( t ) { +tape( 'the function returns an iterator which cumulatively tests whether at least `n` iterated values are truthy', function test( t ) { var expected; - var iterator; var actual; - var arr; - var v; + var values; + var it; + var i; + + values = [ 0, 0, 1, 1, 0, 0 ]; + expected = [ + { + 'value': false, + 'done': false + }, + { + 'value': false, + 'done': false + }, + { + 'value': false, + 'done': false + }, + { + 'value': true, + 'done': false + }, + { + 'value': true, + 'done': false + }, + { + 'value': true, + 'done': false + }, + { + 'done': true + } + ]; - arr = array2iterator( [ false, false, false, true, true ] ); - iterator = iterCuSome( arr, 2 ); + it = iterCuSome( array2iterator( values ), 2 ); - expected = [ false, false, false, false, true ]; actual = []; - - while ( true ) { - v = iterator.next(); - if ( v.done ) { - break; - } - actual.push( v.value ); + for ( i = 0; i < expected.length; i++ ) { + actual.push( it.next() ); } - t.deepEqual( actual, expected, 'returns expected values' ); t.end(); }); -tape( 'the function returns an iterator which cumulatively tests whether at least `n` iterated values are truthy (example 2)', function test( t ) { +tape( 'if an upstream iterator iterator does not return at least `n` truthy values, the function returns an iterator which returns all falsy values', function test( t ) { var expected; - var iterator; var actual; - var arr; - var v; + var values; + var it; + var i; + + values = [ 0, 0, 1, 1, 0, 0 ]; + expected = [ + { + 'value': false, + 'done': false + }, + { + 'value': false, + 'done': false + }, + { + 'value': false, + 'done': false + }, + { + 'value': false, + 'done': false + }, + { + 'value': false, + 'done': false + }, + { + 'value': false, + 'done': false + }, + { + 'done': true + } + ]; - arr = array2iterator( [ 1, 1, 0, 0, 0 ] ); - iterator = iterCuSome( arr, 2 ); + it = iterCuSome( array2iterator( values ), 3 ); - expected = [ false, true, true, true, true ]; actual = []; - - while ( true ) { - v = iterator.next(); - if ( v.done ) { - break; - } - actual.push( v.value ); + for ( i = 0; i < expected.length; i++ ) { + actual.push( it.next() ); } - t.deepEqual( actual, expected, 'returns expected values' ); t.end(); }); From c92555b2f87a5f59d8be2f826c49ed7ebaa08acf Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 15:17:26 -0700 Subject: [PATCH 12/16] style: fix indentation --- .../@stdlib/iter/cusome/package.json | 128 +++++++++--------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/package.json b/lib/node_modules/@stdlib/iter/cusome/package.json index b39e5ac0757e..055681e57fd9 100644 --- a/lib/node_modules/@stdlib/iter/cusome/package.json +++ b/lib/node_modules/@stdlib/iter/cusome/package.json @@ -1,66 +1,66 @@ { - "name": "@stdlib/iter/cusome", - "version": "0.0.0", - "description": "Create an iterator which tests whether at least `n` iterated values are truthy.", - "license": "Apache-2.0", - "author": { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - }, - "contributors": [ - { - "name": "The Stdlib Authors", - "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" - } - ], - "main": "./lib", - "directories": { - "benchmark": "./benchmark", - "doc": "./docs", - "example": "./examples", - "lib": "./lib", - "test": "./test" - }, - "types": "./docs/types", - "scripts": {}, - "homepage": "https://github.com/stdlib-js/stdlib", - "repository": { - "type": "git", - "url": "git://github.com/stdlib-js/stdlib.git" - }, - "bugs": { - "url": "https://github.com/stdlib-js/stdlib/issues" - }, - "dependencies": {}, - "devDependencies": {}, - "engines": { - "node": ">=0.10.0", - "npm": ">2.7.0" - }, - "os": [ - "aix", - "darwin", - "freebsd", - "linux", - "macos", - "openbsd", - "sunos", - "win32", - "windows" - ], - "keywords": [ - "stdlib", - "stdutils", - "stdutil", - "utilities", - "utility", - "utils", - "util", - "some", - "cusome", - "iterator", - "iterate", - "iteration", - "iter" - ] + "name": "@stdlib/iter/cusome", + "version": "0.0.0", + "description": "Create an iterator which cumulatively tests whether at least `n` iterated values are truthy.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdutils", + "stdutil", + "utilities", + "utility", + "utils", + "util", + "some", + "cusome", + "iterator", + "iterate", + "iteration", + "iter" + ] } From 70a54c22c96b656ca4ec8fcc671bc33f4e1e76ce Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 15:20:04 -0700 Subject: [PATCH 13/16] docs: update copy and fix examples --- .../@stdlib/iter/cusome/README.md | 38 ++++++++++++------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/README.md b/lib/node_modules/@stdlib/iter/cusome/README.md index bf47ce3ce2ce..3309743604c1 100644 --- a/lib/node_modules/@stdlib/iter/cusome/README.md +++ b/lib/node_modules/@stdlib/iter/cusome/README.md @@ -26,8 +26,6 @@ limitations under the License.
-This module provides an iterator function `iterCuSome` that creates an iterator to iteratively test whether at least `n` truthy values have been encountered from a source iterator. It continues iterating as long as there are values available from the source iterator. -
@@ -42,26 +40,41 @@ This module provides an iterator function `iterCuSome` that creates an iterator var iterCuSome = require( '@stdlib/iter/cusome' ); ``` -#### iterCuSome( array2iterator, n ) +#### iterCuSome( iterator, n ) -Returns an iterator which cumulatively tests whether at least `n` iterated values are truthy. +Returns an [iterator][mdn-iterator-protocol] which cumulatively tests whether at least `n` iterated values are truthy. ```javascript var array2iterator = require( '@stdlib/array/to-iterator' ); -var arr = array2iterator( [ false, false, false, true, true ] ); +var arr = array2iterator( [ 0, 0, 1, 1, 0 ] ); + +var it = iterCuSome( arr, 2 ); -iterator = iterCuSome( arr, 2 ); +var v = it.next().value; +// returns false -v = iterator.next().value; +v = it.next().value; // returns false -v = iterator.next().value; +v = it.next().value; // returns false -// .. +v = it.next().value; +// returns true + +v = it.next().value; +// returns true + +var bool = it.next().done; +// returns true ``` +The returned [iterator][mdn-iterator-protocol] protocol-compliant object has the following properties: + +- **next**: function which returns an [iterator][mdn-iterator-protocol] protocol-compliant object containing the next iterated value (if one exists) assigned to a `value` property and a `done` property having a `boolean` value indicating whether the [iterator][mdn-iterator-protocol] is finished. +- **return**: function which closes an [iterator][mdn-iterator-protocol] and returns a single (optional) argument in an [iterator][mdn-iterator-protocol] protocol-compliant object. + @@ -69,11 +82,6 @@ v = iterator.next().value;
- -## Notes - -- The iterCuSome function returns an iterator which continues to iterate over values from the source iterator until at least n truthy values are encountered. -- If fewer than n truthy values are encountered, it returns false. Once n truthy values are encountered, it returns true and stops further iteration.
@@ -143,6 +151,8 @@ while ( true ) {
+[mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol +
From 975384269dc09d31a857b660f6a66147c3b0eb45 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 15:22:03 -0700 Subject: [PATCH 14/16] docs: remove `require` statement --- lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts b/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts index a18ab5b9c840..dcbf612222b5 100644 --- a/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/iter/cusome/docs/types/index.d.ts @@ -34,7 +34,6 @@ type Iterator = Iter | IterableIterator; * * @example * var array2iterator = require( '@stdlib/array/to-iterator' ); -* var iterCuSome = require( '@stdlib/iter/cusome' ); * * var it = iterCuSome( array2iterator( [ false, false, false, true, true, false ] ), 2 ); * From f06409e8b0eba2ba2dfb6714a1c8eb361103b8b1 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 15:26:23 -0700 Subject: [PATCH 15/16] test: fix assertion --- lib/node_modules/@stdlib/iter/cusome/test/test.js | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/test/test.js b/lib/node_modules/@stdlib/iter/cusome/test/test.js index b45e2ac8ebd6..2b07b09db760 100644 --- a/lib/node_modules/@stdlib/iter/cusome/test/test.js +++ b/lib/node_modules/@stdlib/iter/cusome/test/test.js @@ -122,7 +122,6 @@ tape( 'if provided an "empty" iterator, the function returns an iterator which i it = iterCuSome( arr, 1 ); v = it.next(); - t.strictEqual( v.value, false, 'returns expected value' ); t.strictEqual( v.done, true, 'returns expected value' ); t.end(); From 2a4ee4b14632183e3321a640affa7e78e5f20e7d Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 22 Jul 2024 15:27:50 -0700 Subject: [PATCH 16/16] bench: fix input value --- lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js index 19b398e7bdde..e172ad932cdf 100644 --- a/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/iter/cusome/benchmark/benchmark.js @@ -57,7 +57,7 @@ bench( pkg+'::iteration', function benchmark( b ) { var v; var i; - iter = iterCuSome( iterConstant( 3.14 ), b.iterations-1 ); + iter = iterCuSome( iterConstant( 3.14 ), b.iterations ); b.tic(); for ( i = 0; i < b.iterations; i++ ) {