feat: add iter/cuevery

lib/node_modules/@stdlib/_tools/repl-txt/rules/interface-spacing/lib/main.js

@@ -1,6 +1,7 @@
 /**
 * @license Apache-2.0
 *
+*
 * Copyright (c) 2021 The Stdlib Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");

lib/node_modules/@stdlib/iter/cuevery/benchmark/benchmark.js

@@ -0,0 +1,105 @@
+/**
+* @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 isBoolean = require( '@stdlib/assert-is-boolean' ).isPrimitive;
+var isIteratorLike = require( '@stdlib/assert-is-iterator-like' );
+var pkg = require( './../package.json' ).name;
+var iterCuEvery = 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 };
+        }
+        return { 'done': true };
+    }
+
+    function reset() {
+        i = -1;
+    }
+}
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+    var iter;
+    var arr;
+    var i;
+
+    arr = [ true, true, true, false, true ];
+
+    b.tic();
+    for ( i = 0; i < b.iterations; i++ ) {
+        iter = iterCuEvery( createIterator( arr ) );
+        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();
+});
+
+bench( pkg+'::iteration', function benchmark( b ) {
+    var iter;
+    var arr;
+    var i;
+    var v;
+
+    arr = [ true, true, true, false, true ];
+    iter = iterCuEvery( createIterator( arr ) );
+
+    b.tic();
+    for ( i = 0; i < b.iterations; i++ ) {
+        v = iter.next().value;
+        if ( typeof v !== 'boolean' ) {
+            b.fail( 'should return a boolean' );
+        }
+    }
+    b.toc();
+
+    if ( !isBoolean( v ) ) {
+        b.fail( 'should return a boolean' );
+    }
+    b.pass( 'benchmark finished' );
+    b.end();
+});
+

lib/node_modules/@stdlib/iter/cuevery/docs/repl.txt

@@ -0,0 +1,53 @@
+{{alias}}( iterator )
+Returns an iterator which cumulatively tests whether every iterated value is
+falsy.
+
+The returned iterator immediately returns `false` upon encountering a truthy
+value, for all subsequent iterations.
+
+If provided an iterator which does not return any iterated values, the
+returned iterator returns `true`.
+
+Parameters
+----------
+iterator: Object
+Input iterator over which to iterate.
+
+Returns
+-------
+iterator: Object
+Iterator.
+
+Iterator Protocol
+-----------------
+The returned iterator protocol-compliant object has the following properties:
+
+next: Function
+Returns an iterator 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
+is finished.
+
+return: Function
+Finishes an iterator and returns a single (optional) argument in an
+iterator protocol-compliant object.
+
+Examples
+--------
+> var arr = {{alias:@stdlib/array/to-iterator}}( [ 0, 0, 0, 0, 1 ] ) ;
+> var it = {{alias}}( arr )
+> var v = it.next().value
+true
+> v = it.next().value
+true
+> v = it.next().value
+true
+> v = it.next().value
+true
+> v = it.next().value
+false
+> var bool = it.next().done
+true
+
+See Also
+--------

lib/node_modules/@stdlib/iter/cuevery/docs/types/index.d.ts

@@ -0,0 +1,43 @@
+// TypeScript Version: 4.1
+
+/// <reference types="@stdlib/types"/>
+
+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 cumulatively tests whether every iterated value is truthy.
+*
+* @param iterator - input iterator
+* @returns iterator
+*
+* @example
+* var array2iterator = require( '@stdlib/array-to-iterator' );
+*
+* var it = iterCuEvery( array2iterator( [ true, true, true, false, true ] ) );
+* // returns <Object>
+*
+* var v = it.next().value;
+* // returns true
+*
+* v = it.next().value;
+* // returns true
+*
+* v = it.next().value;
+* // returns true
+*
+* v = it.next().value;
+* // returns false
+*
+* v = it.next().value;
+* // returns false
+*
+* v = it.next().done;
+* // returns true
+*/
+declare function iterCuEvery( iterator: Iterator ): Iterator;
+
+// EXPORTS //
+export = iterCuEvery;

lib/node_modules/@stdlib/iter/cuevery/docs/types/test.ts

@@ -0,0 +1,63 @@
+/**
+* @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 iterCuEvery from './index';
+//import isIteratorLike from '@stdlib/assert/is-iterator-like';
+
+// Define a proper iterator for testing
+function iterator() {
+    let count = 0;
+    const data = [true, true, true, false, true, false, 1, 2, 3];
+    return {
+        next: () => {
+            if (count < data.length) {
+                return { value: Boolean(data[count++]), done: false };
+            }
+            return { value: true, done: true };
+        },
+        return: (value?: any) => {
+            return { value: value ?? true, done: true };
+        }
+    };
+}
+
+// TESTS //
+
+// The function returns an iterator...
+{
+    iterCuEvery(iterator()); // $ExpectType Iterator
+}
+
+// The compiler throws an error if the function is provided a value other than an iterator protocol-compliant object...
+{
+    iterCuEvery(5 as any); // $ExpectError
+    iterCuEvery(true as any); // $ExpectError
+    iterCuEvery(null as any); // $ExpectError
+    iterCuEvery(undefined as any); // $ExpectError
+    iterCuEvery([] as any); // $ExpectError
+    iterCuEvery({} as any); // $ExpectError
+    //iterCuEvery((x: number): number => x as any as Iterator); // $ExpectError
+}
+
+// Test iterator with Symbol.iterator if supported
+{
+    const it = iterator();
+    if (Symbol.iterator in it) {
+        iterCuEvery(it); // $ExpectType Iterator
+    }
+}

lib/node_modules/@stdlib/iter/cuevery/examples/index.js

@@ -0,0 +1,46 @@
+/**
+* @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 iterCuEvery = require( './../lib' );
+
+// Create an iterator which generates uniformly distributed pseudorandom numbers:
+var rand = randu({
+    'iter': 100
+});
+
+// Create an iterator which applies a threshold to generated numbers:
+var it = iterMap( rand, function threshold( r ) {
+    return ( r > 0.05 );
+});
+
+// Create an iterator which cumulatively tests whether all values are "truthy":
+var result = iterCuEvery( it );
+
+// Perform manual iteration...
+var v;
+while ( true ) {
+    v = result.next();
+    if ( v.done ) {
+        break;
+    }
+    console.log( v.value );
+}

lib/node_modules/@stdlib/iter/cuevery/lib/index.js

@@ -0,0 +1,59 @@
+/**
+* @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 cumulatively tests whether every iterated value is truthy.
+*
+* @module @stdlib/iter-cuevery
+*
+* @example
+* var array2iterator = require( '@stdlib/array-to-iterator' );
+* var iterCuEvery = require( '@stdlib/iter-cuevery' );
+*
+* var it = iterCuEvery( array2iterator( [ true, true, true, false, true ] ) );
+* // returns <Object>
+*
+* var v = it.next().value;
+* // returns true
+*
+* v = it.next().value;
+* // returns true
+*
+* v = it.next().value;
+* // returns true
+*
+* v = it.next().value;
+* // returns false
+*
+* v = it.next().value;
+* // returns false
+*
+* var bool = it.next().done;
+* // returns true
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;