feat: add support for normalize index mode

Author: kgryte

lib/node_modules/@stdlib/ndarray/sub2ind/README.md

@@ -53,15 +53,16 @@ var idx = sub2ind( shape, 1, 0 );
 
 The function supports the following `options`:
 
--   `mode`: specifies how to handle subscripts which exceed array dimensions. The following modes are supported:
+-   **mode**: specifies how to handle subscripts which exceed array dimensions. The following modes are supported:
 
     -   `throw`: specifies that the function should throw an error when a subscript exceeds array dimensions.
+    -   `normalize`: specifies that the function should normalize negative subscripts and throw an error when a subscript exceeds array dimensions.
     -   `wrap`: specifies that the function should wrap around subscripts exceeding array dimensions using modulo arithmetic.
     -   `clamp`: specifies that the function should set subscripts exceeding array dimensions to either `0` (minimum index) or the maximum index along a particular dimension.
 
     If provided a `mode` array, each array element corresponds to a dimension. If provided fewer modes than dimensions, the function reuses modes using modulo arithmetic. Default: `[ 'throw' ]`.
 
--   `order`: specifies whether an array is `row-major` (C-style) or `column-major` (Fortran-style). Default: `'row-major'`.
+-   **order**: specifies whether an array is `row-major` (C-style) or `column-major` (Fortran-style). Default: `'row-major'`.
 
 By default, the function assumes a row-major array. To return a linear index for a column-major array, set the `order` option.
 

lib/node_modules/@stdlib/ndarray/sub2ind/benchmark/benchmark.js

@@ -271,6 +271,76 @@ bench( pkg+':mode=[clamp]', function benchmark( b ) {
 	b.end();
 });
 
+bench( pkg+':mode=normalize', function benchmark( b ) {
+	var shape;
+	var opts;
+	var out;
+	var s0;
+	var s1;
+	var s2;
+	var i;
+
+	shape = [ 10, 10, 10 ];
+
+	s0 = discreteUniform( 0, shape[ 0 ]-1 );
+	s1 = discreteUniform( 0, shape[ 1 ]-1 );
+	s2 = discreteUniform( 0, shape[ 2 ]-1 );
+
+	opts = {
+		'mode': 'normalize'
+	};
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		s2 = floor( randu()*2000.0 ) - 1000.0;
+		out = sub2ind( shape, s0, s1, s2, opts );
+		if ( out !== out ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( !isInteger( out ) ) {
+		b.fail( 'should return an integer' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+':mode=[normalize]', function benchmark( b ) {
+	var shape;
+	var opts;
+	var out;
+	var s0;
+	var s1;
+	var s2;
+	var i;
+
+	shape = [ 10, 10, 10 ];
+
+	s0 = discreteUniform( 0, shape[ 0 ]-1 );
+	s1 = discreteUniform( 0, shape[ 1 ]-1 );
+	s2 = discreteUniform( 0, shape[ 2 ]-1 );
+
+	opts = {
+		'mode': [ 'normalize' ]
+	};
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		s2 = floor( randu()*2000.0 ) - 1000.0;
+		out = sub2ind( shape, s0, s1, s2, opts );
+		if ( out !== out ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( !isInteger( out ) ) {
+		b.fail( 'should return an integer' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
 bench( pkg+':order=row-major', function benchmark( b ) {
 	var shape;
 	var opts;

lib/node_modules/@stdlib/ndarray/sub2ind/docs/repl.txt

@@ -20,9 +20,11 @@
     options.mode: string|Array<string> (optional)
         Specifies how to handle subscripts which exceed array dimensions. If
         equal to 'throw', the function throws an error when a subscript exceeds
-        array dimensions. If equal to 'wrap', the function wraps around
-        subscripts exceeding array dimensions using modulo arithmetic. If equal
-        to 'clamp', the function sets subscripts exceeding array dimensions to
+        array dimensions. If equal to 'normalize', the function normalizes
+        negative subscripts and throws an error when a subscript exceeds array
+        dimensions. If equal to 'wrap', the function wraps around subscripts
+        exceeding array dimensions using modulo arithmetic. If equal to
+        'clamp', the function sets subscripts exceeding array dimensions to
         either `0` (minimum index) or the maximum index along a particular
         dimension. If provided a mode array, each array element specifies the
         mode for a corresponding array dimension. If provided fewer modes than

lib/node_modules/@stdlib/ndarray/sub2ind/docs/types/index.d.ts

@@ -46,13 +46,13 @@ interface Options {
 *
 * -   The function accepts the following "modes":
 *
-*     -   `throw`: throws an error when a subscript exceeds array dimensions.
-*     -   `wrap`: wrap around subscripts exceeding array dimensions using modulo arithmetic.
-*     -   `clamp`: set subscripts exceeding array dimensions to either `0` (minimum index) or the maximum index along a particular dimension.
+*     -   **throw**: throw an error when a subscript exceeds array dimensions.
+*     -   **normalize**: normalize negative subscripts and throw an error when a subscript exceeds array dimensions.
+*     -   **wrap**: wrap around subscripts exceeding array dimensions using modulo arithmetic.
+*     -   **clamp**: set subscripts exceeding array dimensions to either `0` (minimum index) or the maximum index along a particular dimension.
 *
 * -   If provided fewer modes than dimensions, the function recycles modes using modulo arithmetic.
 *
-*
 * @param shape - array shape
 * @param args - subscripts followed by an optional options object
 * @throws first argument must be an array-like object containing nonnegative integers

lib/node_modules/@stdlib/ndarray/sub2ind/lib/main.js

@@ -38,9 +38,10 @@ var validate = require( './validate.js' );
 *
 * -   The function accepts the following "modes":
 *
-*     -   `throw`: throws an error when a subscript exceeds array dimensions.
-*     -   `wrap`: wrap around subscripts exceeding array dimensions using modulo arithmetic.
-*     -   `clamp`: set subscripts exceeding array dimensions to either `0` (minimum index) or the maximum index along a particular dimension.
+*     -   **throw**: throw an error when a subscript exceeds array dimensions.
+*     -   **normalize**: normalize negative subscripts and throw an error when a subscript exceeds array dimensions.
+*     -   **wrap**: wrap around subscripts exceeding array dimensions using modulo arithmetic.
+*     -   **clamp**: set subscripts exceeding array dimensions to either `0` (minimum index) or the maximum index along a particular dimension.
 *
 * -   If provided fewer modes than dimensions, the function recycles modes using modulo arithmetic.
 *

lib/node_modules/@stdlib/ndarray/sub2ind/test/test.js

@@ -281,6 +281,7 @@ tape( 'the function throws an error if provided an invalid option', function tes
 		'throws',
 		'wraps',
 		'clamps',
+		'normalizes',
 		'clip',
 		5,
 		NaN,
@@ -289,7 +290,7 @@ tape( 'the function throws an error if provided an invalid option', function tes
 		null,
 		void 0,
 		[],
-		[ 'wrap', 'clamp', 'throw', 'foo' ],
+		[ 'wrap', 'clamp', 'throw', 'normalize', 'foo' ],
 		{},
 		function noop() {}
 	];
@@ -454,6 +455,29 @@ tape( 'if the `mode` is `throw`, the function throws if provided a subscript whi
 	}
 });
 
+tape( 'if the `mode` is `normalize`, the function throws if provided a subscript which exceeds array dimensions', function test( t ) {
+	var shape;
+	var opts;
+
+	shape = [ 2, 2 ];
+	opts = {
+		'mode': 'normalize'
+	};
+
+	t.throws( foo, RangeError, 'throws a range error' );
+	t.throws( bar, RangeError, 'throws a range error' );
+
+	t.end();
+
+	function foo() {
+		sub2ind( shape, 999999, 1, opts );
+	}
+
+	function bar() {
+		sub2ind( shape, 1, -999999, opts );
+	}
+});
+
 tape( 'if the `mode` is `wrap`, the function wraps subscripts which exceed array dimensions', function test( t ) {
 	var shape;
 	var opts;
@@ -519,6 +543,34 @@ tape( 'if the `mode` is `clamp`, the function clamps subscripts which exceed arr
 	t.end();
 });
 
+tape( 'if the `mode` is `normalize`, the function normalizes negative subscripts', function test( t ) {
+	var shape;
+	var opts;
+	var idx;
+
+	shape = [ 2, 2 ];
+	opts = {
+		'mode': 'normalize'
+	};
+
+	idx = sub2ind( shape, 1, 0, opts );
+	t.strictEqual( idx, 2, 'returns expected value' );
+
+	idx = sub2ind( shape, -1, 0, opts );
+	t.strictEqual( idx, 2, 'returns expected value' );
+
+	idx = sub2ind( shape, 0, -1, opts );
+	t.strictEqual( idx, 1, 'returns expected value' );
+
+	idx = sub2ind( shape, -2, -2, opts );
+	t.strictEqual( idx, 0, 'returns expected value' );
+
+	idx = sub2ind( shape, -1, -1, opts );
+	t.strictEqual( idx, 3, 'returns expected value' );
+
+	t.end();
+});
+
 tape( 'the function supports providing mixed modes', function test( t ) {
 	var shape;
 	var opts;

lib/node_modules/@stdlib/ndarray/sub2ind/test/test.validate.js

@@ -156,7 +156,7 @@ tape( 'the function returns `null` if all options are valid (mode array)', funct
 
 	opts = {};
 	options = {
-		'mode': [ 'wrap', 'clamp', 'throw' ],
+		'mode': [ 'wrap', 'clamp', 'throw', 'normalize' ],
 		'order': 'column-major'
 	};