Auto-generated commit

base/ind/README.md

@@ -55,17 +55,9 @@ idx = ind( -1, 9, 'throw' );
 
 idx = ind( 10, 9, 'throw' );
 // throws <RangeError>
-```
-
-The function supports the following modes:
-
--   **throw**: specifies that the function should throw an error when an index is outside the interval `[0, max]`.
--   **normalize**: specifies that the function should normalize negative indices and throw an error when an index is outside the interval `[-max-1, max]`.
--   **wrap**: specifies that the function should wrap around an index using modulo arithmetic.
--   **clamp**: specifies that the function should set an index less than `0` to `0` (minimum index) and set an index greater than `max` to `max`.
 
-```javascript
-var idx = ind( 2, 9, 'wrap' );
+// Wrapping indices around using modulo arithmetic:
+idx = ind( 2, 9, 'wrap' );
 // returns 2
 
 idx = ind( 10, 9, 'wrap' );
@@ -74,6 +66,7 @@ idx = ind( 10, 9, 'wrap' );
 idx = ind( -1, 9, 'wrap' );
 // returns 9
 
+// Clamping indices to first and last indices:
 idx = ind( 2, 9, 'clamp' );
 // returns 2
 
@@ -83,13 +76,36 @@ idx = ind( 10, 9, 'clamp' );
 idx = ind( -1, 9, 'clamp' );
 // returns 0
 
+// Normalizing negative indices:
 idx = ind( 2, 9, 'normalize' );
 // returns 2
 
 idx = ind( -4, 9, 'normalize' );
 // returns 6
 ```
 
+#### ind.factory( mode )
+
+Returns a function for returning an index according to a provided index `mode`.
+
+```javascript
+var fcn = ind.factory( 'clamp' );
+
+var idx = fcn( 2, 9 );
+// returns 2
+
+idx = fcn( 10, 9 );
+// returns 9
+
+idx = fcn( -1, 9 );
+// returns 0
+```
+
+The function returns a function accepts the following arguments:
+
+-   **index**: input index.
+-   **max**: maximum index value.
+
 </section>
 
 <!-- /.usage -->
@@ -98,6 +114,15 @@ idx = ind( -4, 9, 'normalize' );
 
 <section class="notes">
 
+## Notes
+
+-   Both functions support the following modes:
+
+    -   **throw**: specifies that the function should throw an error when an index is outside the interval `[0, max]`.
+    -   **normalize**: specifies that the function should normalize negative indices and throw an error when an index is outside the interval `[-max-1, max]`.
+    -   **wrap**: specifies that the function should wrap around an index using modulo arithmetic.
+    -   **clamp**: specifies that the function should set an index less than `0` to `0` (minimum index) and set an index greater than `max` to `max`.
+
 </section>
 
 <!-- /.notes -->

base/ind/benchmark/benchmark.factory.js

@@ -0,0 +1,153 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2023 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 isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' ).isPrimitive;
+var isFunction = require( '@stdlib/assert/is-function' );
+var pkg = require( './../package.json' ).name;
+var factory = require( './../lib' ).factory;
+
+
+// MAIN //
+
+bench( pkg+':factory', function benchmark( b ) {
+	var modes;
+	var out;
+	var i;
+
+	modes = [
+		'throw',
+		'clamp',
+		'wrap',
+		'normalize'
+	];
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		out = factory( modes[ i%modes.length ] );
+		if ( typeof out !== 'function' ) {
+			b.fail( 'should return a function' );
+		}
+	}
+	b.toc();
+	if ( !isFunction( out ) ) {
+		b.fail( 'should return a function' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+':factory:mode=clamp', function benchmark( b ) {
+	var ind;
+	var out;
+	var idx;
+	var i;
+
+	ind = factory( 'clamp' );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		idx = (i%100) - 50;
+		out = ind( idx, 10 );
+		if ( out !== out ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( !isNonNegativeInteger( out ) ) {
+		b.fail( 'should return a nonnegative integer' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+':factory:mode=wrap', function benchmark( b ) {
+	var ind;
+	var out;
+	var idx;
+	var i;
+
+	ind = factory( 'wrap' );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		idx = (i%100) - 50;
+		out = ind( idx, 10 );
+		if ( out !== out ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( !isNonNegativeInteger( out ) ) {
+		b.fail( 'should return a nonnegative integer' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+':factory:mode=throw', function benchmark( b ) {
+	var ind;
+	var out;
+	var idx;
+	var i;
+
+	ind = factory( 'throw' );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		idx = i % 11;
+		out = ind( idx, 10 );
+		if ( out !== out ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( !isNonNegativeInteger( out ) ) {
+		b.fail( 'should return a nonnegative integer' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+':factory:mode=normalize', function benchmark( b ) {
+	var ind;
+	var out;
+	var idx;
+	var i;
+
+	ind = factory( 'normalize' );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		idx = (i%21) - 10;
+		out = ind( idx, 10 );
+		if ( out !== out ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( !isNonNegativeInteger( out ) ) {
+		b.fail( 'should return a nonnegative integer' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

base/ind/benchmark/benchmark.js

@@ -21,8 +21,6 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
-var randu = require( '@stdlib/random/base/randu' );
-var floor = require( '@stdlib/math/base/special/floor' );
 var isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' ).isPrimitive;
 var pkg = require( './../package.json' ).name;
 var ind = require( './../lib' );
@@ -37,7 +35,7 @@ bench( pkg+':mode=clamp', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		idx = floor( randu()*100.0 ) - 50.0;
+		idx = (i%100) - 50;
 		out = ind( idx, 10, 'clamp' );
 		if ( out !== out ) {
 			b.fail( 'should not return NaN' );
@@ -58,7 +56,7 @@ bench( pkg+':mode=wrap', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		idx = floor( randu()*100.0 ) - 50.0;
+		idx = (i%100) - 50;
 		out = ind( idx, 10, 'wrap' );
 		if ( out !== out ) {
 			b.fail( 'should not return NaN' );
@@ -79,7 +77,7 @@ bench( pkg+':mode=throw', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		idx = floor( randu()*11.0 );
+		idx = i % 11;
 		out = ind( idx, 10, 'throw' );
 		if ( out !== out ) {
 			b.fail( 'should not return NaN' );
@@ -100,7 +98,7 @@ bench( pkg+':mode=normalize', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		idx = floor( randu()*20.0 ) - 10.0;
+		idx = (i%21) - 10;
 		out = ind( idx, 10, 'normalize' );
 		if ( out !== out ) {
 			b.fail( 'should not return NaN' );

base/ind/docs/repl.txt

@@ -44,6 +44,41 @@
     > idx = {{alias}}( -4, 10, 'normalize' )
     7
 
+
+{{alias}}.factory( mode )
+    Returns a function for returning an index according to a provided index
+    mode.
+
+    The function returns a function which accepts the following arguments:
+
+    - idx: index
+    - max: maximum index value
+
+    Parameters
+    ----------
+    mode: string
+        Specifies how to handle an index outside the interval [0, max]. If equal
+        to 'throw', the function throws an error. If equal to 'normalize', the
+        function throws an error if provided an out-of-bounds normalized index.
+        If equal to 'wrap', the function wraps around an index using modulo
+        arithmetic. If equal to 'clamp', the function sets an index to either 0
+        (minimum index) or the maximum index.
+
+    Returns
+    -------
+    fcn: Function
+        Function for returning an index.
+
+    Examples
+    --------
+    > var f = {{alias}}.factory( 'clamp' );
+    > var idx = f( 2, 10 )
+    2
+    > idx = f( -4, 10 )
+    0
+    > idx = f( 13, 10 )
+    10
+
     See Also
     --------