Add a functional do-while utility

Author: kgryte

lib/node_modules/@stdlib/utils/do-while/README.md

@@ -0,0 +1,124 @@
+# doWhile
+
+> While a test condition is true, invoke a function.
+
+
+<!-- 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 doWhile = require( '@stdlib/utils/do-while' );
+```
+
+#### doWhile( predicate, fcn\[, thisArg \] )
+
+Invokes a `function` until a `predicate` function returns `false`.  Note that the `predicate` function is evaluated __after__ executing `fcn`; thus, `fcn` __always__ executes at least once.
+
+``` javascript
+function predicate( i ) {
+    return ( i < 5 );
+}
+
+function beep( i ) {
+    console.log( 'boop: %d', i );
+}
+
+doWhile( predicate, beep );
+/* =>
+    boop: 0
+    boop: 1
+    boop: 2
+    boop: 3
+    boop: 4
+*/
+```
+
+Both the `predicate` function and the `function` to invoke are provided a single argument:
+
+* `i`: iteration number (starting from zero)
+
+To set the function execution context for the invoked function, provide a `thisArg`.
+
+``` javascript
+function predicate( i ) {
+    return ( i < 5 );
+}
+
+function count() {
+    this.count += 1;
+}
+
+var context = {
+    'count': 0
+}; 
+
+doWhile( predicate, count, context );
+
+console.log( context.count );
+// => 5
+```
+
+
+</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">
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+``` javascript
+var randu = require( '@stdlib/math/base/random/randu' );
+var doWhile = require( '@stdlib/utils/do-while' );
+
+function predicate() {
+    return ( randu() > 0.05 );
+}
+
+function log( i ) {
+    console.log( i );
+}
+
+doWhile( predicate, log );
+```
+
+</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">
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/utils/do-while/benchmark/benchmark.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var pkg = require( './../package.json' ).name;
+var doWhile = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var sum;
+	var i;
+
+	function predicate( i ) {
+		return ( i < 10 );
+	}
+
+	function fcn( i ) {
+		sum += i;
+	}
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		sum = 0;
+		doWhile( predicate, fcn );
+		if ( isnan( sum ) ) {
+			b.fail( 'should not be NaN' );
+		}
+	}
+	b.toc();
+	if ( isnan( sum ) ) {
+		b.fail( 'should not be NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+'::loop', function benchmark( b ) {
+	var sum;
+	var i;
+	var j;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		sum = 0;
+		j = 0;
+		do {
+			sum += j;
+			j += 1;
+		} while ( j < 10 );
+		if ( isnan( sum ) ) {
+			b.fail( 'should not be NaN' );
+		}
+	}
+	b.toc();
+	if ( isnan( sum ) ) {
+		b.fail( 'should not be NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/utils/do-while/docs/repl.txt

@@ -0,0 +1,38 @@
+
+{{alias}}( predicate, fcn[, thisArg] )
+    While a test condition is true, invokes a function.
+
+    The condition is evaluated *after* executing the provided function; thus,
+    `fcn` *always* executes at least once.
+
+    When invoked, both the predicate function and the function to invoke are
+    provided a single argument:
+
+    - `i`: iteration number (starting from zero)
+
+    Parameters
+    ----------
+    predicate: Function
+        The predicate function which indicates whether to continue invoking a
+        function.
+
+    fcn: Function
+        The function to invoke.
+
+    thisArg: any (optional)
+        Execution context for the invoked function.
+
+    Examples
+    --------
+    > function predicate( i ) { return ( i < 5 ); };
+    > function beep( i ) { console.log( 'boop: %d', i ); };
+    > {{alias}}( predicate, beep )
+    boop: 0
+    boop: 1
+    boop: 2
+    boop: 3
+    boop: 4
+
+    See Also
+    --------
+

lib/node_modules/@stdlib/utils/do-while/examples/index.js

@@ -0,0 +1,14 @@
+'use strict';
+
+var randu = require( '@stdlib/math/base/random/randu' );
+var doWhile = require( './../lib' );
+
+function predicate() {
+	return ( randu() > 0.05 );
+}
+
+function log( i ) {
+	console.log( i );
+}
+
+doWhile( predicate, log );

lib/node_modules/@stdlib/utils/do-while/lib/do_while.js

@@ -0,0 +1,48 @@
+'use strict';
+
+// MODULES //
+
+var isFunction = require( '@stdlib/assert/is-function' );
+
+
+// MAIN //
+
+/**
+* While a test condition is true, invokes a function.
+*
+* @param {Function} predicate - function which indicates whether to continue invoking a function
+* @param {Function} fcn - function to invoke
+* @param {*} [thisArg] - execution context for the invoked function
+* @throws {TypeError} first argument must be a function
+* @throws {TypeError} second argument must be a function
+*
+* @example
+* function predicate( i ) {
+*     return ( i < 5 );
+* }
+*
+* function beep( i ) {
+*     console.log( 'beep: %d', i );
+* }
+*
+* doWhile( predicate, beep );
+*/
+function doWhile( predicate, fcn, thisArg ) {
+	var i;
+	if ( !isFunction( predicate ) ) {
+		throw new TypeError( 'invalid input argument. First argument must be a function. Value: `'+predicate+'`.' );
+	}
+	if ( !isFunction( fcn ) ) {
+		throw new TypeError( 'invalid input argument. Second argument must be a function. Value: `'+fcn+'`.' );
+	}
+	i = 0;
+	do {
+		fcn.call( thisArg, i );
+		i += 1;
+	} while ( predicate( i ) );
+} // end FUNCTION doWhile()
+
+
+// EXPORTS //
+
+module.exports = doWhile;

lib/node_modules/@stdlib/utils/do-while/lib/index.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+* While a test condition is true, invoke a function.
+*
+* @module @stdlib/utils/do-while
+*
+* @example
+* var doWhile = require( '@stdlib/utils/do-while' );
+*
+* function predicate( i ) {
+*     return ( i < 5 );
+* }
+*
+* function beep( i ) {
+*     console.log( 'boop: %d', i );
+* }
+*
+* doWhile( predicate, beep );
+*/
+
+// MODULES //
+
+var doWhile = require( './do_while.js' );
+
+
+// EXPORTS //
+
+module.exports = doWhile;

lib/node_modules/@stdlib/utils/do-while/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@stdlib/utils/do-while",
+  "version": "0.0.0",
+  "description": "While a test condition is true, invoke a function.",
+  "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"
+    }
+  ],
+  "scripts": {},
+  "main": "./lib",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/stdlib.git"
+  },
+  "homepage": "https://github.com/stdlib-js/stdlib",
+  "keywords": [
+    "stdlib",
+    "stdutils",
+    "stdutil",
+    "utilities",
+    "utility",
+    "utils",
+    "util",
+    "for",
+    "while",
+    "do-while",
+    "do while",
+    "do",
+    "loop",
+    "iterate",
+    "iteration"
+  ],
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "license": "Apache-2.0"
+}