Add utility to test if all elements in a collection are falsy

Author: kgryte

lib/node_modules/@stdlib/utils/none/README.md

@@ -0,0 +1,104 @@
+# none
+
+> Test whether all elements in a collection are falsy.
+
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="usage">
+
+## Usage
+
+``` javascript
+var none = require( '@stdlib/utils/none' );
+```
+
+#### none( collection )
+
+Tests whether all elements in a `collection` are falsy.
+
+``` javascript
+var arr = [ 0, 0, 0, 0, 0 ];
+
+var bool = none( arr );
+// returns true
+```
+
+If provided an empty `collection`, the function returns `true`.
+
+``` javascript
+var bool = none( [] );
+// returns true
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+* A `collection` may be either an [`Array`][mdn-array], [`Typed Array`][mdn-typed-array], or an array-like [`Object`][mdn-object] (excluding `strings` and `functions`).
+* The function does __not__ skip `undefined` elements and is thus not optimized for sparse collections.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+``` javascript
+var randu = require( '@stdlib/math/base/random/randu' );
+var none = require( '@stdlib/utils/none' );
+
+var bool;
+var arr;
+var i;
+
+arr = new Array( 100 );
+for ( i = 0; i < arr.length; i++ ) {
+    arr[ i ] = ( randu() > 0.95 );
+}
+
+bool = none( arr );
+// returns <boolean>
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
+[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
+[mdn-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/utils/none/benchmark/benchmark.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
+var pkg = require( './../package.json' ).name;
+var none = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var bool;
+	var arr;
+	var i;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		arr = [ 0, 0, 0, 0, 0, i+1 ];
+		bool = none( arr );
+		if ( !isBoolean( bool ) ) {
+			b.fail( 'should return a boolean' );
+		}
+	}
+	b.toc();
+	if ( !isBoolean( bool ) ) {
+		b.fail( 'should return a boolean' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+'::built-in', function benchmark( b ) {
+	var bool;
+	var arr;
+	var i;
+
+	function predicate( v ) {
+		return ( v === 0 );
+	}
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		arr = [ 0, 0, 0, 0, 0, i+1 ];
+		bool = arr.every( predicate );
+		if ( !isBoolean( bool ) ) {
+			b.fail( 'should return a boolean' );
+		}
+	}
+	b.toc();
+	if ( !isBoolean( bool ) ) {
+		b.fail( 'should return a boolean' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+'::loop', function benchmark( b ) {
+	var bool;
+	var arr;
+	var i;
+	var j;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		arr = [ 0, 0, 0, 0, 0, i+1 ];
+		bool = true;
+		for ( j = 0; j < arr.length; j++ ) {
+			if ( arr[ j ] !== 0 ) {
+				bool = false;
+				break;
+			}
+		}
+		if ( !isBoolean( bool ) ) {
+			b.fail( 'should be a boolean' );
+		}
+	}
+	b.toc();
+	if ( !isBoolean( bool ) ) {
+		b.fail( 'should be a boolean' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/utils/none/benchmark/julia/REQUIRE

@@ -0,0 +1,2 @@
+julia 0.5
+BenchmarkTools 0.0.8

lib/node_modules/@stdlib/utils/none/benchmark/julia/benchmark.jl

@@ -0,0 +1,128 @@
+#!/usr/bin/env julia
+
+import BenchmarkTools
+
+# Benchmark variables:
+name = "none";
+repeats = 3;
+
+"""
+	print_version()
+
+Prints the TAP version.
+
+# Examples
+
+``` julia
+julia> print_version()
+```
+"""
+function print_version()
+	@printf( "TAP version 13\n" );
+end
+
+"""
+	print_summary( total, passing )
+
+Print the benchmark summary.
+
+# Arguments
+
+* `total`: total number of tests
+* `passing`: number of passing tests
+
+# Examples
+
+``` julia
+julia> print_summary( 3, 3 )
+```
+"""
+function print_summary( total, passing )
+	@printf( "#\n" );
+	@printf( "1..%d\n", total ); # TAP plan
+	@printf( "# total %d\n", total );
+	@printf( "# pass  %d\n", passing );
+	@printf( "#\n" );
+	@printf( "# ok\n" );
+end
+
+"""
+	print_results( iterations, elapsed )
+
+Print benchmark results.
+
+# Arguments
+
+* `iterations`: number of iterations
+* `elapsed`: elapsed time (in seconds)
+
+# Examples
+
+``` julia
+julia> print_results( 1000000, 0.131009101868 )
+```
+"""
+function print_results( iterations, elapsed )
+	rate = iterations / elapsed
+
+	@printf( "  ---\n" );
+	@printf( "  iterations: %d\n", iterations );
+	@printf( "  elapsed: %0.9f\n", elapsed );
+	@printf( "  rate: %0.9f\n", rate );
+	@printf( "  ...\n" );
+end
+
+"""
+	benchmark()
+
+Run a benchmark.
+
+# Notes
+
+* Benchmark results are returned as a two-element array: [ iterations, elapsed ].
+* The number of iterations is not the true number of iterations. Instead, an 'iteration' is defined as a 'sample', which is a computed estimate for a single evaluation.
+* The elapsed time is in seconds.
+
+# Examples
+
+``` julia
+julia> benchmark();
+```
+"""
+function benchmark()
+	# We benchmark `all` as a proxy for `none`:
+	t = BenchmarkTools.@benchmark all( [ true, true, true, true, true, true ] ) samples=1e6
+
+	# Compute the total "elapsed" time and convert from nanoseconds to seconds:
+	s = sum( t.times ) / 1.0e9;
+
+	# Determine the number of "iterations":
+	iter = length( t.times );
+
+	# Return the results:
+	[ iter, s ];
+end
+
+"""
+	main()
+
+Run benchmarks.
+
+# Examples
+
+``` julia
+julia> main();
+```
+"""
+function main()
+	print_version();
+	for i in 1:3
+		@printf( "# julia::%s\n", name );
+		results = benchmark();
+		print_results( results[ 1 ], results[ 2 ] );
+        @printf( "ok %d benchmark finished\n", i );
+	end
+	print_summary( repeats, repeats );
+end
+
+main();

lib/node_modules/@stdlib/utils/none/docs/repl.txt

@@ -0,0 +1,29 @@
+
+{{alias}}( collection )
+    Tests whether all elements in a collection are falsy.
+
+    The function immediately returns upon encountering a truthy value.
+
+    If provided an empty collection, the function returns `true`.
+
+    Parameters
+    ----------
+    collection: Array|TypedArray|Object
+        Input collection over which to iterate. If provided an object, the
+        object must be array-like (excluding strings and functions).
+
+    Returns
+    -------
+    bool: boolean
+        The function returns `true` if all elements are falsy; otherwise, the
+        function returns `false`.
+
+    Examples
+    --------
+    > var arr = [ 0, 0, 0, 0, 0 ];
+    > var bool = {{alias}}( arr )
+    true
+
+    See Also
+    --------
+

lib/node_modules/@stdlib/utils/none/examples/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+var randu = require( '@stdlib/math/base/random/randu' );
+var none = require( './../lib' );
+
+var bool;
+var arr;
+var i;
+
+arr = new Array( 100 );
+for ( i = 0; i < arr.length; i++ ) {
+	arr[ i ] = ( randu() > 0.95 );
+}
+
+bool = none( arr );
+console.log( bool );

lib/node_modules/@stdlib/utils/none/lib/index.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+* Test whether all elements in a collection are falsy.
+*
+* @module @stdlib/utils/none
+*
+* @example
+* var none = require( '@stdlib/utils/none' );
+*
+* var arr = [ 0, 0, 0, 0, 0 ];
+*
+* var bool = none( arr );
+* // returns true
+*/
+
+// MODULES //
+
+var none = require( './none.js' );
+
+
+// EXPORTS //
+
+module.exports = none;