feat: add support for accessor arrays and refactor stats/base/stdevwd

lib/node_modules/@stdlib/stats/base/stdevwd/README.md

@@ -113,7 +113,7 @@ The function has the following parameters:
 
 -   **N**: number of indexed elements.
 -   **correction**: degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [standard deviation][standard-deviation] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [standard deviation][standard-deviation] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the corrected sample [standard deviation][standard-deviation], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
--   **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array].
+-   **x**: input [`Array`][mdn-array], [`typed array`][mdn-typed-array], or accessor array.
 -   **stride**: index increment for `x`.
 
 The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [standard deviation][standard-deviation] of every other element in `x`,
@@ -172,6 +172,20 @@ var v = stdevwd.ndarray( N, 1, x, 2, 1 );
 // returns 2.5
 ```
 
+```javascript
+var accessorArray = {
+    'get': function get(i) {
+        return [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ][i];
+    },
+    'set': function set(i, v) {
+        // No-op for this example
+    },
+    'length': 8
+};
+var v = stdevwd.ndarray( 4, 1, accessorArray, 2, 1 );
+console.log( v );
+```
+
 </section>
 
 <!-- /.usage -->
@@ -213,6 +227,21 @@ var v = stdevwd( x.length, 1, x, 1 );
 console.log( v );
 ```
 
+```javascript
+var accessorArray = {
+    'get': function get(i) {
+        return [ 1.0, -2.0, 3.0, -4.0, 5.0 ][i];
+    },
+    'set': function set(i, v) {
+        // No-op for this example
+    },
+    'length': 5
+};
+var v = stdevwd( accessorArray.length, 1, accessorArray, 1 );
+console.log( v );
+```
+-   The function supports accessor arrays, which provide an alternative way to define strided arrays using `get` and `set` methods for data access.
+
 </section>
 
 <!-- /.examples -->

lib/node_modules/@stdlib/stats/base/stdevwd/benchmark/benchmark.js

@@ -31,19 +31,19 @@ var stdevwd = require( './../lib/stdevwd.js' );
 // FUNCTIONS //
 
 /**
-* Creates a benchmark function.
+* Creates a benchmark function for a native array.
 *
 * @private
 * @param {PositiveInteger} len - array length
 * @returns {Function} benchmark function
 */
-function createBenchmark( len ) {
+function createNativeBenchmark( len ) {
 	var x;
 	var i;
 
-	x = [];
+	x = new Array( len );
 	for ( i = 0; i < len; i++ ) {
-		x.push( ( randu()*20.0 ) - 10.0 );
+		x[ i ] = ( randu()*20.0 ) - 10.0;
 	}
 	return benchmark;
 
@@ -67,6 +67,51 @@ function createBenchmark( len ) {
 	}
 }
 
+/**
+* Creates a benchmark function for an accessor array.
+*
+* @private
+* @param {PositiveInteger} len - array length
+* @returns {Function} benchmark function
+*/
+function createAccessorBenchmark( len ) {
+	var data;
+	var x;
+	var i;
+
+	data = new Array( len );
+	for ( i = 0; i < len; i++ ) {
+		data[ i ] = ( randu()*20.0 ) - 10.0;
+	}
+	x = {
+		'get': function get( i ) {
+			return data[ i ];
+		},
+		'set': function set() {},
+		'length': data.length
+	};
+	return benchmark;
+
+	function benchmark( b ) {
+		var v;
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			v = stdevwd( x.length, 1, x, 1 );
+			if ( isnan( v ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+}
+
 
 // MAIN //
 
@@ -87,9 +132,11 @@ function main() {
 
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
-		f = createBenchmark( len );
-		bench( pkg+':len='+len, f );
+		f = createNativeBenchmark( len );
+		bench( pkg+':native:len='+len, f );
+		f = createAccessorBenchmark( len );
+		bench( pkg+':accessors:len='+len, f );
 	}
 }
 
-main();
+main();

lib/node_modules/@stdlib/stats/base/stdevwd/benchmark/benchmark.ndarray.js

@@ -31,19 +31,19 @@ var stdevwd = require( './../lib/ndarray.js' );
 // FUNCTIONS //
 
 /**
-* Creates a benchmark function.
+* Creates a benchmark function for a native array.
 *
 * @private
 * @param {PositiveInteger} len - array length
 * @returns {Function} benchmark function
 */
-function createBenchmark( len ) {
+function createNativeBenchmark( len ) {
 	var x;
 	var i;
 
-	x = [];
+	x = new Array( len );
 	for ( i = 0; i < len; i++ ) {
-		x.push( ( randu()*20.0 ) - 10.0 );
+		x[ i ] = ( randu()*20.0 ) - 10.0;
 	}
 	return benchmark;
 
@@ -67,6 +67,51 @@ function createBenchmark( len ) {
 	}
 }
 
+/**
+* Creates a benchmark function for an accessor array.
+*
+* @private
+* @param {PositiveInteger} len - array length
+* @returns {Function} benchmark function
+*/
+function createAccessorBenchmark( len ) {
+	var data;
+	var x;
+	var i;
+
+	data = new Array( len );
+	for ( i = 0; i < len; i++ ) {
+		data[ i ] = ( randu()*20.0 ) - 10.0;
+	}
+	x = {
+		'get': function get( i ) {
+			return data[ i ];
+		},
+		'set': function set() {},
+		'length': data.length
+	};
+	return benchmark;
+
+	function benchmark( b ) {
+		var v;
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			v = stdevwd( x.length, 1, x, 1, 0 );
+			if ( isnan( v ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+}
+
 
 // MAIN //
 
@@ -87,9 +132,11 @@ function main() {
 
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
-		f = createBenchmark( len );
-		bench( pkg+':ndarray:len='+len, f );
+		f = createNativeBenchmark( len );
+		bench( pkg+':ndarray:native:len='+len, f );
+		f = createAccessorBenchmark( len );
+		bench( pkg+':ndarray:accessors:len='+len, f );
 	}
 }
 
-main();
+main();

lib/node_modules/@stdlib/stats/base/stdevwd/docs/repl.txt

@@ -1,4 +1,3 @@
-
 {{alias}}( N, correction, x, stride )
     Computes the standard deviation of a strided array using Welford's
     algorithm.
@@ -7,7 +6,7 @@
     at runtime.
 
     Indexing is relative to the first index. To introduce an offset, use a typed
-    array view.
+    array view or accessor array.
 
     If `N <= 0`, the function returns `NaN`.
 
@@ -20,16 +19,16 @@
         Degrees of freedom adjustment. Setting this parameter to a value other
         than `0` has the effect of adjusting the divisor during the calculation
         of the standard deviation according to `N - c` where `c` corresponds to
-        the provided degrees of freedom adjustment. When computing the standard
+        the provided degrees of freedom adjustment.When computing the standard
         deviation of a population, setting this parameter to `0` is the standard
         choice (i.e., the provided array contains data constituting an entire
         population). When computing the corrected sample standard deviation,
         setting this parameter to `1` is the standard choice (i.e., the provided
         array contains data sampled from a larger population; this is commonly
         referred to as Bessel's correction).
 
-    x: Array<number>|TypedArray
-        Input array.
+    x: Array<number>|TypedArray|AccessorArray
+        Input array (regular, typed, or accessor array).
 
     stride: integer
         Index increment.
@@ -46,6 +45,15 @@
     > {{alias}}( x.length, 1, x, 1 )
     ~2.0817
 
+    // Using accessor array:
+    > var accessorArray = {
+    >     'get': (i) => [1.0, -2.0, 2.0][i],
+    >     'set': (i,v) => {},
+    >     'length': 3
+    > };
+    > {{alias}}( accessorArray.length, 1, accessorArray, 1 )
+    ~2.0817
+
     // Using `N` and `stride` parameters:
     > x = [ -2.0, 1.0, 1.0, -5.0, 2.0, -1.0 ];
     > var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
@@ -86,8 +94,8 @@
         array contains data sampled from a larger population; this is commonly
         referred to as Bessel's correction).
 
-    x: Array<number>|TypedArray
-        Input array.
+    x: Array<number>|TypedArray|AccessorArray
+        Input array (regular, typed, or accessor array).
 
     stride: integer
         Index increment.
@@ -107,12 +115,20 @@
     > {{alias}}.ndarray( x.length, 1, x, 1, 0 )
     ~2.0817
 
+    // Using accessor array:
+    > var accessorArray = {
+    >     'get': (i) => [1.0, -2.0, 2.0][i],
+    >     'set': (i,v) => {},
+    >     'length': 3
+    > };
+    > {{alias}}.ndarray( accessorArray.length, 1, accessorArray, 1, 0 )
+    ~2.0817
+
     // Using offset parameter:
     > var x = [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ];
     > var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
     > {{alias}}.ndarray( N, 1, x, 2, 1 )
     ~2.0817
 
     See Also
-    --------
-
+    --------

lib/node_modules/@stdlib/stats/base/stdevwd/docs/types/index.d.ts

@@ -22,6 +22,27 @@
 
 import { NumericArray } from '@stdlib/types/array';
 
+/**
+* Interface describing an accessor array.
+*/
+interface AccessorArray {
+    /**
+    * Returns an array element.
+    */
+    get( index: number ): number;
+
+    /**
+    * Sets an array element.
+    */
+    set( index: number, value: number ): void;
+
+    /**
+    * Number of elements.
+    */
+    length: number;
+}
+
+
 /**
 * Interface describing `stdevwd`.
 */

lib/node_modules/@stdlib/stats/base/stdevwd/docs/types/test.ts

@@ -28,6 +28,17 @@ import stdevwd = require( './index' );
 	stdevwd( x.length, 1, x, 1 ); // $ExpectType number
 }
 
+// The function supports accessor arrays...
+{
+    const accessorArray = {
+        get: ( i: number ) => [1.0, -2.0, 3.0][i],
+        set: ( i: number, v: number ) => { /* no-op */ },
+        length: 3
+    };
+    stdevwd( accessorArray.length, 1, accessorArray, 1 ); // $ExpectType number
+    stdevwd.ndarray( accessorArray.length, 1, accessorArray, 1, 0 ); // $ExpectType number
+}
+
 // The compiler throws an error if the function is provided a first argument which is not a number...
 {
 	const x = new Float64Array( 10 );
@@ -46,14 +57,15 @@ import stdevwd = require( './index' );
 {
 	const x = new Float64Array( 10 );
 
-	stdevwd( x.length, '10', x, 1 ); // $ExpectError
-	stdevwd( x.length, true, x, 1 ); // $ExpectError
-	stdevwd( x.length, false, x, 1 ); // $ExpectError
-	stdevwd( x.length, null, x, 1 ); // $ExpectError
-	stdevwd( x.length, undefined, x, 1 ); // $ExpectError
-	stdevwd( x.length, [], x, 1 ); // $ExpectError
-	stdevwd( x.length, {}, x, 1 ); // $ExpectError
-	stdevwd( x.length, ( x: number ): number => x, x, 1 ); // $ExpectError
+    stdevwd( x.length, 1, 10, 1 ); // $ExpectError
+    stdevwd( x.length, 1, '10', 1 ); // $ExpectError
+    stdevwd( x.length, 1, true, 1 ); // $ExpectError
+    stdevwd( x.length, 1, false, 1 ); // $ExpectError
+    stdevwd( x.length, 1, null, 1 ); // $ExpectError
+    stdevwd( x.length, 1, undefined, 1 ); // $ExpectError
+    stdevwd( x.length, 1, [ '1' ], 1 ); // $ExpectError
+    stdevwd( x.length, 1, {}, 1 ); // $ExpectError (plain object lacks accessor methods)
+    stdevwd( x.length, 1, ( x: number ): number => x, 1 ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided a third argument which is not a numeric array...