fix: apply suggestions from code review

Author: headlessNode

lib/node_modules/@stdlib/ndarray/base/diagonal/README.md

@@ -85,7 +85,7 @@ var y = diagonal( x, [ 0, 1 ], 0, false );
 The function accepts the following arguments:
 
 -   **x**: input ndarray.
--   **dims**: dimension indices defining the plane in which to extract the diagonal.
+-   **dims**: dimension indices defining the plane from which to extract the diagonal.
 -   **k**: diagonal offset.
 -   **writable**: boolean indicating whether the returned ndarray should be writable.
 

lib/node_modules/@stdlib/ndarray/base/diagonal/benchmark/benchmark.js

@@ -31,7 +31,7 @@ var diagonal = require( './../lib' );
 
 // MAIN //
 
-bench( format( '%s::2d,base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=2,ctor=base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;
@@ -59,7 +59,7 @@ bench( format( '%s::2d,base', pkg ), function benchmark( b ) {
 	b.end();
 });
 
-bench( format( '%s::2d,non-base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=2,ctor=non-base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;
@@ -91,7 +91,7 @@ bench( format( '%s::2d,non-base', pkg ), function benchmark( b ) {
 	b.end();
 });
 
-bench( format( '%s::3d,base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=3,ctor=base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;
@@ -119,7 +119,7 @@ bench( format( '%s::3d,base', pkg ), function benchmark( b ) {
 	b.end();
 });
 
-bench( format( '%s::3d,non-base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=3,ctor=non-base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;
@@ -151,7 +151,7 @@ bench( format( '%s::3d,non-base', pkg ), function benchmark( b ) {
 	b.end();
 });
 
-bench( format( '%s::4d,base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=4,ctor=base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;
@@ -179,7 +179,7 @@ bench( format( '%s::4d,base', pkg ), function benchmark( b ) {
 	b.end();
 });
 
-bench( format( '%s::4d,non-base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=4,ctor=non-base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;
@@ -211,7 +211,7 @@ bench( format( '%s::4d,non-base', pkg ), function benchmark( b ) {
 	b.end();
 });
 
-bench( format( '%s::5d,base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=5,ctor=base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;
@@ -239,7 +239,7 @@ bench( format( '%s::5d,base', pkg ), function benchmark( b ) {
 	b.end();
 });
 
-bench( format( '%s::5d,non-base', pkg ), function benchmark( b ) {
+bench( format( '%s::ndims=5,ctor=non-base', pkg ), function benchmark( b ) {
 	var values;
 	var v;
 	var i;

lib/node_modules/@stdlib/ndarray/base/diagonal/docs/repl.txt

@@ -6,7 +6,8 @@
     element specifies the row-like dimension. The second element specifies
     the column-like dimension.
 
-    Each provided dimension index must reside on the interval [-ndims,ndims-1].
+    Each provided dimension index must reside on the interval
+    [-ndims, ndims-1].
 
     The diagonal offset `k` is interpreted as `column - row`. Accordingly,
     when `k = 0`, the function returns the main diagonal; when `k > 0`, the
@@ -26,7 +27,7 @@
         Input array.
 
     dims: ArrayLikeObject<integer>
-        Dimension indices defining the plane in which to extract the diagonal.
+        Dimension indices defining the plane from which to extract the diagonal.
 
     k: integer
         Diagonal offset.

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

@@ -35,7 +35,7 @@ import { typedndarray } from '@stdlib/types/ndarray';
 * -   The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
 *
 * @param x - input array
-* @param dims - dimension indices defining the plane in which to extract the diagonal
+* @param dims - dimension indices defining the plane from which to extract the diagonal
 * @param k - diagonal offset
 * @param writable - boolean indicating whether the returned ndarray should be writable
 * @returns ndarray view

lib/node_modules/@stdlib/ndarray/base/diagonal/lib/main.js

@@ -20,13 +20,16 @@
 
 // MODULES //
 
-var toNormalizedIndices = require( '@stdlib/ndarray/base/to-normalized-indices' );
-var getDType = require( '@stdlib/ndarray/dtype' );
-var getShape = require( '@stdlib/ndarray/shape' );
-var getStrides = require( '@stdlib/ndarray/strides' );
-var getOffset = require( '@stdlib/ndarray/offset' );
-var getOrder = require( '@stdlib/ndarray/order' );
-var getData = require( '@stdlib/ndarray/data-buffer' );
+var toUniqueNormalizedIndices = require( '@stdlib/ndarray/base/to-unique-normalized-indices' );
+var getDType = require( '@stdlib/ndarray/base/dtype' );
+var getShape = require( '@stdlib/ndarray/base/shape' );
+var getStrides = require( '@stdlib/ndarray/base/strides' );
+var getOffset = require( '@stdlib/ndarray/base/offset' );
+var getOrder = require( '@stdlib/ndarray/base/order' );
+var getData = require( '@stdlib/ndarray/base/data-buffer' );
+var join = require( '@stdlib/array/base/join' );
+var min = require( '@stdlib/math/base/special/min' );
+var format = require( '@stdlib/string/format' );
 
 
 // MAIN //
@@ -43,9 +46,13 @@ var getData = require( '@stdlib/ndarray/data-buffer' );
 * -   The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
 *
 * @param {ndarray} x - input array
-* @param {IntegerArray} dims - dimension indices defining the plane in which to extract the diagonal
+* @param {IntegerArray} dims - dimension indices defining the plane from which to extract the diagonal
 * @param {integer} k - diagonal offset
 * @param {boolean} writable - boolean indicating whether the returned ndarray should be writable
+* @throws {RangeError} must provide exactly two dimension indices
+* @throws {RangeError} input ndarray must have at least two dimensions
+* @throws {RangeError} must provide valid dimension indices
+* @throws {Error} must provide unique dimension indices
 * @returns {ndarray} ndarray view
 *
 * @example
@@ -60,47 +67,59 @@ var getData = require( '@stdlib/ndarray/data-buffer' );
 function diagonal( x, dims, k, writable ) {
 	var strides;
 	var offset;
+	var ndims;
 	var shape;
+	var rows;
+	var cols;
 	var sh;
 	var st;
 	var sr;
 	var sc;
-	var kp;
-	var kn;
+	var ro;
+	var co;
 	var d;
-	var N;
 	var L;
 	var i;
 
+	if ( dims.length !== 2 ) {
+		throw new RangeError( format( 'invalid argument. Must provide exactly two dimension indices. Value: `[%s]`.', join( dims, ', ' ) ) );
+	}
 	sh = getShape( x );
+	ndims = sh.length;
+	if ( ndims < 2 ) {
+		throw new RangeError( format( 'invalid argument. Input ndarray must have at least two dimensions. Number of dimensions: %d.', ndims ) );
+	}
 	st = getStrides( x );
-	N = sh.length;
-
-	// Normalize the dimension indices:
-	d = toNormalizedIndices( dims, N-1 );
 
+	// Resolve dimension indices...
+	d = toUniqueNormalizedIndices( dims, ndims-1 );
+	if ( d === null ) {
+		throw new RangeError( format( 'invalid argument. Specified dimension index is out-of-bounds. Must be on the interval: [-%u, %u]. Value: `[%s]`.', ndims, ndims-1, join( dims, ', ' ) ) );
+	}
+	if ( d.length !== dims.length ) {
+		throw new Error( format( 'invalid argument. Must provide unique dimension indices. Value: `[%s]`.', join( dims, ', ' ) ) );
+	}
 	sr = st[ d[0] ];
 	sc = st[ d[1] ];
 
-	// Resolve the positive and negative parts of `k`:
-	kp = ( k > 0 ) ? k : 0;
-	kn = kp - k;
+	// Resolve the row and column offsets corresponding to the diagonal offset `k = column - row`:
+	co = ( k > 0 ) ? k : 0;
+	ro = co - k;
 
 	// Compute the length of the diagonal (clamped to be non-negative):
-	L = sh[ d[0] ] - kn;
-	if ( sh[ d[1] ] - kp < L ) {
-		L = sh[ d[1] ] - kp;
-	}
+	rows = sh[ d[0] ] - ro;
+	cols = sh[ d[1] ] - co;
+	L = min( rows, cols );
 	if ( L < 0 ) {
 		L = 0;
 	}
 	// Adjust the offset so that we point to the first element along the specified diagonal:
-	offset = getOffset( x ) + ( kp*sc ) + ( kn*sr );
+	offset = getOffset( x ) + ( co*sc ) + ( ro*sr );
 
 	// Drop the specified dimensions and append the diagonal dimension:
 	shape = [];
 	strides = [];
-	for ( i = 0; i < N; i++ ) {
+	for ( i = 0; i < ndims; i++ ) {
 		if ( i === d[0] || i === d[1] ) {
 			continue;
 		}

lib/node_modules/@stdlib/ndarray/base/diagonal/test/test.js

@@ -21,6 +21,7 @@
 // MODULES //
 
 var tape = require( 'tape' );
+var Float64Array = require( '@stdlib/array/float64' );
 var array = require( '@stdlib/ndarray/array' );
 var ndarray = require( '@stdlib/ndarray/base/ctor' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
@@ -61,6 +62,105 @@ tape( 'the function returns a view of the main diagonal of a square matrix', fun
 	t.end();
 });
 
+tape( 'the function throws an error if not provided exactly two dimension indices', function test( t ) {
+	var values;
+	var x;
+	var i;
+
+	x = new ndarray( 'float64', new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] ), [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	values = [
+		[],
+		[ 0 ],
+		[ 0, 1, 0 ],
+		[ 0, 1, 0, 1 ]
+	];
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[ i ] ), RangeError, 'throws an error when provided ' + values[ i ].length + ' dimension indices' );
+	}
+	t.end();
+
+	function badValue( dims ) {
+		return function badValue() {
+			diagonal( x, dims, 0, false );
+		};
+	}
+});
+
+tape( 'the function throws an error if provided an input ndarray with fewer than two dimensions', function test( t ) {
+	var values;
+	var i;
+
+	values = [
+		new ndarray( 'float64', new Float64Array( [ 5.0 ] ), [], [ 0 ], 0, 'row-major' ),
+		new ndarray( 'float64', new Float64Array( [ 1.0, 2.0, 3.0 ] ), [ 3 ], [ 1 ], 0, 'row-major' )
+	];
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[ i ] ), RangeError, 'throws an error when provided an input ndarray with '+values[ i ].ndims+' dimensions' );
+	}
+	t.end();
+
+	function badValue( x ) {
+		return function badValue() {
+			diagonal( x, [ 0, 1 ], 0, false );
+		};
+	}
+});
+
+tape( 'the function throws an error if provided out-of-bounds dimension indices', function test( t ) {
+	var values;
+	var x;
+	var i;
+
+	x = new ndarray( 'float64', new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] ), [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	values = [
+		[ 0, 2 ],
+		[ 2, 0 ],
+		[ -3, 0 ],
+		[ 0, -3 ],
+		[ 10, 0 ],
+		[ 0, 10 ]
+	];
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[ i ] ), RangeError, 'throws an error when provided dimension indices ['+values[ i ]+']' );
+	}
+	t.end();
+
+	function badValue( dims ) {
+		return function badValue() {
+			diagonal( x, dims, 0, false );
+		};
+	}
+});
+
+tape( 'the function throws an error if provided duplicate dimension indices', function test( t ) {
+	var values;
+	var x;
+	var i;
+
+	x = new ndarray( 'float64', new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ), [ 2, 2, 2 ], [ 4, 2, 1 ], 0, 'row-major' );
+
+	values = [
+		[ 0, 0 ],
+		[ 1, 1 ],
+		[ 2, 2 ],
+		[ 0, -3 ],
+		[ -2, 1 ],
+		[ -1, 2 ]
+	];
+	for ( i = 0; i < values.length; i++ ) {
+		t.throws( badValue( values[ i ] ), Error, 'throws an error when provided dimension indices ['+values[ i ]+']' );
+	}
+	t.end();
+
+	function badValue( dims ) {
+		return function badValue() {
+			diagonal( x, dims, 0, false );
+		};
+	}
+});
+
 tape( 'the function returns a view of the super-diagonal of a square matrix', function test( t ) {
 	var expected;
 	var x;