@stdlib/utils-reduce 0.0.4 → 0.0.8

package/NOTICE

@@ -1 +1 @@
-Copyright (c) 2016-2021 The Stdlib Authors.
+Copyright (c) 2016-2022 The Stdlib Authors.

package/README.md

@@ -20,9 +20,9 @@ limitations under the License.
 
 # reduce
 
-[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] [![dependencies][dependencies-image]][dependencies-url]
+[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
 
-> Apply a function against an accumulator and each element in a collection and return the accumulated result.
+> Apply a function against an accumulator and each element in an array and return the accumulated result.
 
 <!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
 
@@ -52,9 +52,9 @@ npm install @stdlib/utils-reduce
 var reduce = require( '@stdlib/utils-reduce' );
 ```
 
-#### reduce( collection, initial, reducer\[, thisArg ] )
+#### reduce( arr, initial, reducer\[, thisArg ] )
 
-Applies a `function` against an accumulator and each element in a `collection` and returns the accumulated result.
+Applies a function against an accumulator and each element in an array and returns the accumulated result.
 
 ```javascript
 function sum( accumulator, value ) {
@@ -67,40 +67,34 @@ var out = reduce( arr, 0, sum );
 // returns 10
 ```
 
-The `reducer` function is provided four arguments:
-
--   `accumulator`: accumulated value
--   `value`: collection element
--   `index`: collection index
--   `collection`: input collection
-
-Basic support for dynamic collections is provided. Note, however, that index incrementation is monotonically increasing.
+The function accepts both array-like objects and [`ndarray`][@stdlib/ndarray/ctor]-like objects.
 
 ```javascript
-function sum1( accumulator, value, index, collection ) {
-    if ( index === collection.length-1 && collection.length < 10 ) {
-        collection.push( index+2 );
-    }
+var array = require( '@stdlib/ndarray-array' );
+
+function sum( accumulator, value ) {
     return accumulator + value;
 }
 
-var arr = [ 1, 2, 3, 4 ];
+var opts = {
+    'dtype': 'generic'
+};
+var arr = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
 
-var out = reduce( arr, 0, sum1 );
-// returns 55
+var out = reduce( arr, 0, sum );
+// returns 21
+```
 
-function sum2( accumulator, value, index, collection ) {
-    collection.shift();
-    return accumulator + value;
-}
+The applied function is provided the following arguments:
 
-arr = [ 1, 2, 3, 4 ];
+-   **accumulator**: accumulated value.
+-   **value**: array element.
+-   **index**: element index.
+-   **arr**: input array.
 
-out = reduce( arr, 0, sum2 );
-// returns 4
-```
+To set the `this` context when invoking the input function, provide a `thisArg`.
 
-To set the function execution context, provide a `thisArg`.
+<!-- eslint-disable no-invalid-this -->
 
 ```javascript
 function sum( accumulator, value ) {
@@ -110,14 +104,14 @@ function sum( accumulator, value ) {
 
 var arr = [ 1, 2, 3, 4 ];
 
-var context = {
+var ctx = {
     'count': 0
 };
 
-var out = reduce( arr, 0, sum, context );
+var out = reduce( arr, 0, sum, ctx );
 // returns 10
 
-var mean = out / context.count;
+var mean = out / ctx.count;
 // returns 2.5
 ```
 
@@ -131,36 +125,44 @@ var mean = out / context.count;
 
 ## Notes
 
--   A `collection` may be either an [`Array`][mdn-array], [`Typed Array`][mdn-typed-array], or an array-like [`Object`][mdn-object] (excluding `strings` and `functions`).
-
--   The function differs from [`Array.prototype.reduce`][mdn-array-reduce] in the following ways:
+-   For input arrays, the function differs from [`Array.prototype.reduce`][mdn-array-reduce] in the following ways:
 
     -   The function **requires** an `initial` value for the `accumulator`. The `initial` value is used during the first invocation of the `reducer` function.
-
-    -   The function does **not** skip the first element in the `collection`.
-
+    -   The function does **not** skip the first array element.
     -   The function does **not** skip `undefined` elements.
+    -   The function does **not** support dynamic array-like objects (i.e., array-like objects whose `length` changes during execution).
+
+-   The function supports array-like objects exposing getters and setters for array element access (e.g., [`Complex64Array`][@stdlib/array/complex64], [`Complex128Array`][@stdlib/array/complex128], etc).
+
+    ```javascript
+    var Complex64Array = require( '@stdlib/array-complex64' );
+    var Complex64 = require( '@stdlib/complex-float32' );
+    var realf = require( '@stdlib/complex-realf' );
+    var imagf = require( '@stdlib/complex-imagf' );
+
+    function sum( acc, z ) {
+        var re1 = realf( acc );
+        var im1 = imagf( acc );
+        var re2 = realf( z );
+        var im2 = imagf( z );
+        return new Complex64( re1+re2, im1+im2 );
+    }
+
+    var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
 
-        <!-- eslint-disable no-sparse-arrays, stdlib/doctest-marker -->
+    var v = reduce( x, new Complex64( 0.0, 0.0 ), sum );
+    // returns <Complex64>
 
-        ```javascript
-        function log( accumulator, value, index ) {
-            console.log( '%s: %s', index, value );
-            return accumulator;
-        }
+    var re = realf( v );
+    // returns 16.0
 
-        var arr = [ 1, , , 4 ];
+    var im = imagf( v );
+    // returns 20.0
+    ```
 
-        var out = reduce( arr, 0, log );
-        /* =>
-            0: 1
-            1: undefined
-            2: undefined
-            3: 4
-        */
-        ```
+-   For [`ndarray`][@stdlib/ndarray/ctor]-like objects, the function performs a reduction over the entire input [`ndarray`][@stdlib/ndarray/ctor] (i.e., higher-order [`ndarray`][@stdlib/ndarray/ctor] dimensions are flattened to a single-dimension).
 
-    -   The function provides limited support for dynamic collections (i.e., collections whose `length` changes during execution).
+-   When applying a function to [`ndarray`][@stdlib/ndarray/ctor]-like objects, performance will be best for [`ndarray`][@stdlib/ndarray/ctor]-like objects which are single-segment contiguous.
 
 </section>
 
@@ -175,23 +177,34 @@ var mean = out / context.count;
 <!-- eslint no-undef: "error" -->
 
 ```javascript
+var filledarrayBy = require( '@stdlib/array-filled-by' );
+var discreteUniform = require( '@stdlib/random-base-discrete-uniform' ).factory;
+var naryFunction = require( '@stdlib/utils-nary-function' );
+var add = require( '@stdlib/math-base-ops-add' );
+var array = require( '@stdlib/ndarray-array' );
 var reduce = require( '@stdlib/utils-reduce' );
 
-var arr;
-var s;
-var i;
-
-function sum( acc, value ) {
-    return acc + value;
+function fill( i ) {
+    var rand = discreteUniform( -10*(i+1), 10*(i+1) );
+    return filledarrayBy( 10, 'generic', rand );
 }
 
-arr = new Array( 1000 );
-for ( i = 0; i < arr.length; i++ ) {
-    arr[ i ] = i;
-}
+// Create a two-dimensional ndarray (i.e., a matrix):
+var x = array( filledarrayBy( 10, 'generic', fill ), {
+    'dtype': 'generic',
+    'flatten': true
+});
+
+// Create an explicit binary function:
+var f = naryFunction( add, 2 );
+
+// Compute the sum:
+var out = reduce( x, 0, f );
+
+console.log( 'x:' );
+console.log( x.data );
 
-s = reduce( arr, 0, sum );
-console.log( s );
+console.log( 'sum: %d', out );
 ```
 
 </section>
@@ -206,6 +219,22 @@ console.log( s );
 
 <!-- /.references -->
 
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+* * *
+
+## See Also
+
+-   <span class="package-name">[`@stdlib/utils/for-each`][@stdlib/utils/for-each]</span><span class="delimiter">: </span><span class="description">invoke a function for each element in a collection.</span>
+-   <span class="package-name">[`@stdlib/utils/async/reduce`][@stdlib/utils/async/reduce]</span><span class="delimiter">: </span><span class="description">apply a function against an accumulator and each element in a collection and return the accumulated result.</span>
+-   <span class="package-name">[`@stdlib/utils/reduce-right`][@stdlib/utils/reduce-right]</span><span class="delimiter">: </span><span class="description">apply a function against an accumulator and each element in a collection and return the accumulated result, iterating from right to left.</span>
+
+</section>
+
+<!-- /.related -->
+
 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
 
 
@@ -232,7 +261,7 @@ See [LICENSE][stdlib-license].
 
 ## Copyright
 
-Copyright &copy; 2016-2021. The Stdlib [Authors][stdlib-authors].
+Copyright &copy; 2016-2022. The Stdlib [Authors][stdlib-authors].
 
 </section>
 
@@ -251,9 +280,20 @@ Copyright &copy; 2016-2021. The Stdlib [Authors][stdlib-authors].
 [coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/utils-reduce/main.svg
 [coverage-url]: https://codecov.io/github/stdlib-js/utils-reduce?branch=main
 
+<!--
+
 [dependencies-image]: https://img.shields.io/david/stdlib-js/utils-reduce.svg
 [dependencies-url]: https://david-dm.org/stdlib-js/utils-reduce/main
 
+-->
+
+[umd]: https://github.com/umdjs/umd
+[es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+
+[deno-url]: https://github.com/stdlib-js/utils-reduce/tree/deno
+[umd-url]: https://github.com/stdlib-js/utils-reduce/tree/umd
+[esm-url]: https://github.com/stdlib-js/utils-reduce/tree/esm
+
 [chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg
 [chat-url]: https://gitter.im/stdlib-js/stdlib/
 
@@ -263,13 +303,23 @@ Copyright &copy; 2016-2021. The Stdlib [Authors][stdlib-authors].
 
 [stdlib-license]: https://raw.githubusercontent.com/stdlib-js/utils-reduce/main/LICENSE
 
-[mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
+[mdn-array-reduce]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce
 
-[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
+[@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/stdlib
 
-[mdn-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
+[@stdlib/array/complex64]: https://www.npmjs.com/package/@stdlib/stdlib
 
-[mdn-array-reduce]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce
+[@stdlib/array/complex128]: https://www.npmjs.com/package/@stdlib/stdlib
+
+<!-- <related-links> -->
+
+[@stdlib/utils/for-each]: https://www.npmjs.com/package/@stdlib/utils-for-each
+
+[@stdlib/utils/async/reduce]: https://www.npmjs.com/package/@stdlib/utils-async-reduce
+
+[@stdlib/utils/reduce-right]: https://www.npmjs.com/package/@stdlib/utils-reduce-right
+
+<!-- </related-links> -->
 
 </section>
 

package/docs/repl.txt

@@ -1,29 +1,32 @@
 
-{{alias}}( collection, initial, reducer[, thisArg] )
-    Applies a function against an accumulator and each element in a collection
-    and returns the accumulated result.
+{{alias}}( arr, initial, reducer[, thisArg] )
+    Applies a function against an accumulator and each element in an array and
+    returns the accumulated result.
 
     When invoked, the reduction function is provided four arguments:
 
-    - `accumulator`: accumulated value
-    - `value`: collection value
-    - `index`: collection index
-    - `collection`: the input collection
+    - accumulator: accumulated value.
+    - value: array element.
+    - index: element index.
+    - arr: input array.
 
-    If provided an empty collection, the function returns the initial value.
+    If provided an empty array, the function returns the initial value.
+
+    When provided an ndarray, the function performs a reduction over the entire
+    input ndarray (i.e., higher-order ndarray dimensions are flattened to a
+    single-dimension).
 
     Parameters
     ----------
-    collection: Array|TypedArray|Object
-        Input collection. If provided an object, the object must be array-like
-        (excluding strings and functions).
+    arr: ArrayLikeObject|ndarray
+        Input array.
 
     initial: any
         Accumulator value used in the first invocation of the reduction
         function.
 
     reducer: Function
-        Function to invoke for each element in the input collection.
+        Function to invoke for each element in the input array.
 
     thisArg: any (optional)
         Execution context.
@@ -35,10 +38,16 @@
 
     Examples
     --------
-    > function sum( acc, v ) { return acc + v; };
-    > var arr = [ 1.0, 2.0, 3.0 ];
-    > var out = {{alias}}( arr, 0, sum )
-    6.0
+    // array-like object:
+    > var f = {{alias:@stdlib/utils/nary-function}}( {{alias:@stdlib/math/base/ops/add}}, 2 );
+    > var arr = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
+    > var out = {{alias}}( arr, 0.0, f )
+    21.0
+
+    // ndarray:
+    > arr = {{alias:@stdlib/ndarray/array}}( arr, { 'shape': [ 2, 3 ] } );
+    > out = {{alias}}( arr, 0.0, f )
+    21.0
 
     See Also
     --------

package/docs/types/index.d.ts

@@ -21,6 +21,7 @@
 /// <reference types="@stdlib/types"/>
 
 import { Collection } from '@stdlib/types/object';
+import { ndarray } from '@stdlib/types/ndarray';
 
 /**
 * Function applied against an accumulator.
@@ -41,7 +42,7 @@ type Unary = ( accumulator: any ) => any;
 * Function applied against an accumulator.
 *
 * @param accumulator - accumulated value
-* @param value - collection value
+* @param value - array element
 * @returns accumulator value
 */
 type Binary = ( accumulator: any, value: any ) => any;
@@ -50,49 +51,106 @@ type Binary = ( accumulator: any, value: any ) => any;
 * Function applied against an accumulator.
 *
 * @param accumulator - accumulated value
-* @param value - collection value
-* @param index - collection index
+* @param value - array element
+* @param index - element index
 * @returns accumulator value
 */
-type Tertiary = ( accumulator: any, value: any, index: number ) => any;
+type Ternary = ( accumulator: any, value: any, index: number ) => any;
 
 /**
 * Function applied against an accumulator.
 *
 * @param accumulator - accumulated value
-* @param value - collection value
-* @param index - collection index
-* @param collection - the input collection
+* @param value - array element
+* @param index - element index
+* @param arr - array
 * @returns accumulator value
 */
-type Quaternary = ( accumulator: any, value: any, index: number, collection: Collection ) => any; // tslint-disable-line max-line-length
+type Quaternary = ( accumulator: any, value: any, index: number, arr: ndarray ) => any; // tslint-disable-line max-line-length
 
 /**
 * Function applied against an accumulator.
 *
 * @param accumulator - accumulated value
-* @param value - collection value
-* @param index - collection index
-* @param collection - the input collection
+* @param value - array element
+* @param index - element index
+* @param arr - array
 * @returns accumulator value
 */
-type Reducer = Nullary | Unary | Binary | Tertiary | Quaternary;
+type ArrayQuaternary = ( accumulator: any, value: any, index: number, arr: Collection ) => any; // tslint-disable-line max-line-length
 
 /**
-* Applies a function against an accumulator and each element in a collection and returns the accumulated result.
+* Function applied against an accumulator.
+*
+* @param accumulator - accumulated value
+* @param value - array element
+* @param index - element index
+* @param arr - array
+* @returns accumulator value
+*/
+type Reducer = Nullary | Unary | Binary | Ternary | Quaternary;
+
+/**
+* Function applied against an accumulator.
+*
+* @param accumulator - accumulated value
+* @param value - array element
+* @param index - element index
+* @param arr - array
+* @returns accumulator value
+*/
+type ArrayReducer = Nullary | Unary | Binary | Ternary | ArrayQuaternary;
+
+/**
+* Applies a function against an accumulator and each element in an array and returns the accumulated result.
+*
+* ## Notes
+*
+* -   The reduction function is provided four arguments:
+*
+*     -   **accumulator**: accumulated value.
+*     -   **value**: array element.
+*     -   **index**: element index.
+*     -   **arr**: input array.
+*
+* -   If provided an empty array, the function returns the initial value.
+*
+* @param arr - input array
+* @param initial - initial value
+* @param reducer - reduction function
+* @param thisArg - reduction function execution context
+* @returns accumulated result
+*
+* @example
+* var naryFunction = require( `@stdlib/utils/nary-function` );
+* var add = require( `@stdlib/math/base/ops/add` );
+* var array = require( `@stdlib/ndarray/array` );
+*
+* var opts = {
+*     'dtype': 'generic'
+* };
+* var arr = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
+*
+* var out = reduce( arr, 0, naryFunction( add, 2 ) );
+* // returns 21
+*/
+declare function reduce( arr: ndarray, initial: any, reducer: Reducer, thisArg?: any ): any; // tslint-disable-line max-line-length
+
+/**
+* Applies a function against an accumulator and each element in an array and returns the accumulated result.
 *
 * ## Notes
 *
-* -   When invoked, the reduction function is provided four arguments:
+* -   The reduction function is provided four arguments:
 *
-*     -   `accumulator`: accumulated value
-*     -   `value`: collection value
-*     -   `index`: collection index
-*     -   `collection`: the input collection
+*     -   **accumulator**: accumulated value.
+*     -   **value**: array element.
+*     -   **index**: element index.
+*     -   **arr**: input array.
 *
-* -   If provided an empty collection, the function returns the initial value.
+* -   If provided an empty array, the function returns the initial value.
 *
-* @param collection - input collection
+* @param arr - input array
 * @param initial - initial value
 * @param reducer - reduction function
 * @param thisArg - reduction function execution context
@@ -105,10 +163,10 @@ type Reducer = Nullary | Unary | Binary | Tertiary | Quaternary;
 *
 * var arr = [ 1, 2, 3, 4 ];
 *
-* var s = reduce( arr, 0, sum );
+* var out = reduce( arr, 0, sum );
 * // returns 10
 */
-declare function reduce( collection: Collection, initial: any, reducer: Reducer, thisArg?: any ): any; // tslint-disable-line max-line-length
+declare function reduce( arr: Collection, initial: any, reducer: ArrayReducer, thisArg?: any ): any; // tslint-disable-line max-line-length
 
 
 // EXPORTS //

package/docs/types/test.ts

@@ -16,44 +16,112 @@
 * limitations under the License.
 */
 
+import array = require( '@stdlib/ndarray-array' );
 import reduce = require( './index' );
 
-const sum = ( acc: number, value: number ): number => {
+/**
+* Callback function.
+*
+* @param acc - accumulated value
+* @param v - array element
+* @returns result
+*/
+function clbk( acc: number, value: number ): number {
 	return acc + value;
-};
+}
 
 
 // TESTS //
 
-// The function returns the accumulated value...
+// The function returns the accumulated value when provided a collection...
 {
-	reduce( [ 0, 1, 1, NaN, 2 ], 0, sum ); // $ExpectType any
-	reduce( [ -1, 1, 2 ], 100, sum ); // $ExpectType any
-	reduce( [ -1, 1, 2 ], 0, sum, {} ); // $ExpectType any
+	reduce( [ 0, 1, 1, NaN, 2 ], 0, clbk ); // $ExpectType any
+	reduce( [ -1, 1, 2 ], 100, clbk ); // $ExpectType any
+	reduce( [ -1, 1, 2 ], 0, clbk, {} ); // $ExpectType any
 }
 
-// The compiler throws an error if the function is provided a first argument which is not a collection...
+// The function returns the accumulated value when provided an ndarray...
 {
-	reduce( 2, 0, sum ); // $ExpectError
-	reduce( false, 0, sum ); // $ExpectError
-	reduce( true, 0, sum ); // $ExpectError
-	reduce( {}, 0, sum ); // $ExpectError
+	const arr = array( [ 1, 2, 3, 4, 5, 6 ] );
+
+	reduce( arr, 0, clbk ); // $ExpectType any
+	reduce( arr, 100, clbk ); // $ExpectType any
+	reduce( arr, 0, clbk, {} ); // $ExpectType any
 }
 
-// The compiler throws an error if the function is provided a third argument which is not a function...
+// The compiler throws an error if the function is provided a first argument which is not a collection or ndarray...
 {
-	reduce( [ 0, 1, 1, NaN, 2 ], 0, 2 ); // $ExpectError
-	reduce( [ 0, 1, 1, NaN, 2 ], 0, false ); // $ExpectError
-	reduce( [ 0, 1, 1, NaN, 2 ], 0, true ); // $ExpectError
-	reduce( [ 0, 1, 1, NaN, 2 ], 0, 'abc' ); // $ExpectError
-	reduce( [ 0, 1, 1, NaN, 2 ], 0, {} ); // $ExpectError
-	reduce( [ 0, 1, 1, NaN, 2 ], 0, [] ); // $ExpectError
+	reduce( 2, 0, clbk ); // $ExpectError
+	reduce( false, 0, clbk ); // $ExpectError
+	reduce( true, 0, clbk ); // $ExpectError
+	reduce( null, 0, clbk ); // $ExpectError
+	reduce( {}, 0, clbk ); // $ExpectError
+
+	reduce( 2, 0, clbk, {} ); // $ExpectError
+	reduce( false, 0, clbk, {} ); // $ExpectError
+	reduce( true, 0, clbk, {} ); // $ExpectError
+	reduce( null, 0, clbk, {} ); // $ExpectError
+	reduce( {}, 0, clbk, {} ); // $ExpectError
 }
 
-// The compiler throws an error if the function is provided an invalid number of arguments...
+// The compiler throws an error if the function is provided a third argument which is not a function with a supported signature...
 {
+	const arr1 = [ 0, 1, 1, NaN, 2 ];
+
+	reduce( arr1, 0, 'abc' ); // $ExpectError
+	reduce( arr1, 0, 2 ); // $ExpectError
+	reduce( arr1, 0, false ); // $ExpectError
+	reduce( arr1, 0, true ); // $ExpectError
+	reduce( arr1, 0, null ); // $ExpectError
+	reduce( arr1, 0, {} ); // $ExpectError
+	reduce( arr1, 0, [] ); // $ExpectError
+
+	reduce( arr1, 0, 'abc', {} ); // $ExpectError
+	reduce( arr1, 0, 2, {} ); // $ExpectError
+	reduce( arr1, 0, false, {} ); // $ExpectError
+	reduce( arr1, 0, true, {} ); // $ExpectError
+	reduce( arr1, 0, null, {} ); // $ExpectError
+	reduce( arr1, 0, {}, {} ); // $ExpectError
+	reduce( arr1, 0, [], {} ); // $ExpectError
+
+	reduce( arr1, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w ); // $ExpectError
+	reduce( arr1, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w, {} ); // $ExpectError
+
+	const arr2 = array( [ 0, 1, 1, NaN, 2 ] );
+
+	reduce( arr2, 0, 'abc' ); // $ExpectError
+	reduce( arr2, 0, 2 ); // $ExpectError
+	reduce( arr2, 0, false ); // $ExpectError
+	reduce( arr2, 0, true ); // $ExpectError
+	reduce( arr2, 0, null ); // $ExpectError
+	reduce( arr2, 0, {} ); // $ExpectError
+	reduce( arr2, 0, [] ); // $ExpectError
+
+	reduce( arr2, 0, 'abc', {} ); // $ExpectError
+	reduce( arr2, 0, 2, {} ); // $ExpectError
+	reduce( arr2, 0, false, {} ); // $ExpectError
+	reduce( arr2, 0, true, {} ); // $ExpectError
+	reduce( arr2, 0, null, {} ); // $ExpectError
+	reduce( arr2, 0, {}, {} ); // $ExpectError
+	reduce( arr2, 0, [], {} ); // $ExpectError
+
+	reduce( arr2, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w ); // $ExpectError
+	reduce( arr2, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+	const arr1 = [ 1, 2, 3 ];
+
+	reduce(); // $ExpectError
+	reduce( arr1 ); // $ExpectError
+	reduce( arr1, 0 ); // $ExpectError
+	reduce( arr1, 0, clbk, {}, 3 ); // $ExpectError
+
+	const arr2 = array( [ 1, 2, 3 ] );
+
 	reduce(); // $ExpectError
-	reduce( [ 1, 2, 3 ] ); // $ExpectError
-	reduce( [ 1, 2, 3 ], 0 ); // $ExpectError
-	reduce( [ 1, 2, 3 ], 0, sum, {}, 3 ); // $ExpectError
+	reduce( arr2 ); // $ExpectError
+	reduce( arr2, 0 ); // $ExpectError
+	reduce( arr2, 0, clbk, {}, 3 ); // $ExpectError
 }

package/lib/array.js

@@ -0,0 +1,78 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2021 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';
+
+// MAIN //
+
+/**
+* Applies a function against an accumulator and each element in an array and returns the accumulated result.
+*
+* @private
+* @param {Object} x - object containing input array data
+* @param {ArrayLikeObject} x.data - input array data
+* @param {Function} x.getter - callback for accessing input array data elements
+* @param {*} initial - initial value
+* @param {Function} fcn - function to apply
+* @param {*} thisArg - function execution context
+* @returns {*} accumulated result
+*
+* @example
+* function sum( acc, value ) {
+*     return acc + value;
+* }
+*
+* // Define a getter:
+* function getter( buf, idx ) {
+*     return buf[ idx ];
+* }
+*
+* // Create the input array object:
+* var x = {
+*     'data': [ 1, 2, 3, 4 ],
+*     'getter': getter
+* };
+*
+* // Compute the sum:
+* var out = reduce( x, 0, sum );
+* // returns 10
+*/
+function reduce( x, initial, fcn, thisArg ) {
+	var xbuf;
+	var get;
+	var acc;
+	var i;
+
+	// Cache reference to the input data:
+	xbuf = x.data;
+
+	// Cache the element accessor:
+	get = x.getter;
+
+	// Iterate over each element...
+	acc = initial;
+	for ( i = 0; i < xbuf.length; i++ ) {
+		acc = fcn.call( thisArg, acc, get( xbuf, i ), i, xbuf );
+	}
+	return acc;
+}
+
+
+// EXPORTS //
+
+module.exports = reduce;

package/lib/index.js

@@ -19,7 +19,7 @@
 'use strict';
 
 /**
-* Apply a function against an accumulator and each element in a collection and return the accumulated result.
+* Apply a function against an accumulator and each element in an array and return the accumulated result.
 *
 * @module @stdlib/utils-reduce
 *
@@ -32,15 +32,29 @@
 *
 * var arr = [ 1, 2, 3, 4 ];
 *
-* var s = reduce( arr, 0, sum );
+* var out = reduce( arr, 0, sum );
 * // returns 10
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var array = require( '@stdlib/ndarray-array' );
+* var reduce = require( '@stdlib/utils-reduce' );
+*
+* var opts = {
+*     'dtype': 'generic'
+* };
+* var arr = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
+*
+* var out = reduce( arr, 0, naryFunction( add, 2 ) );
+* // returns 21
 */
 
 // MODULES //
 
-var reduce = require( './reduce.js' );
+var main = require( './main.js' );
 
 
 // EXPORTS //
 
-module.exports = reduce;
+module.exports = main;

package/lib/main.js

@@ -0,0 +1,93 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2018 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 isArrayLikeObject = require( '@stdlib/assert-is-array-like-object' );
+var isndarrayLike = require( '@stdlib/assert-is-ndarray-like' );
+var isFunction = require( '@stdlib/assert-is-function' );
+var ndarraylike2object = require( '@stdlib/ndarray-base-ndarraylike2object' );
+var arraylike2object = require( '@stdlib/array-base-arraylike2object' );
+var ndarrayFcn = require( './ndarray.js' );
+var arrayFcn = require( './array.js' );
+
+
+// MAIN //
+
+/**
+* Applies a function against an accumulator and each element in an array and returns the accumulated result.
+*
+* ## Notes
+*
+* -   The applied function is provided the following arguments:
+*
+*     -   **accumulator**: accumulated value.
+*     -   **value**: array element.
+*     -   **index**: element index.
+*     -   **arr**: input array.
+*
+* @param {(ArrayLikeObject|ndarray)} arr - input array
+* @param {*} initial - initial value
+* @param {Function} reducer - reduction function
+* @param {*} [thisArg] - reduction function execution context
+* @throws {TypeError} first argument must be an array-like object or an ndarray
+* @throws {TypeError} third argument must be a function
+* @returns {*} accumulated result
+*
+* @example
+* function sum( acc, value ) {
+*     return acc + value;
+* }
+*
+* var arr = [ 1, 2, 3, 4 ];
+*
+* var out = reduce( arr, 0, sum );
+* // returns 10
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var array = require( '@stdlib/ndarray-array' );
+*
+* var opts = {
+*     'dtype': 'generic'
+* };
+* var arr = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
+*
+* var out = reduce( arr, 0, naryFunction( add, 2 ) );
+* // returns 21
+*/
+function reduce( arr, initial, reducer, thisArg ) {
+	if ( !isFunction( reducer ) ) {
+		throw new TypeError( 'invalid argument. Third argument must be a function. Value:`' + reducer + '`.' );
+	}
+	if ( isndarrayLike( arr ) ) { // note: assertion order matters here, as an ndarray-like object is also array-like
+		return ndarrayFcn( ndarraylike2object( arr ), initial, reducer, thisArg ); // eslint-disable-line max-len
+	}
+	if ( isArrayLikeObject( arr ) ) {
+		return arrayFcn( arraylike2object( arr ), initial, reducer, thisArg );
+	}
+	throw new TypeError( 'invalid argument. First argument must be an array-like object or an ndarray. Value: `' + arr + '`.' );
+}
+
+
+// EXPORTS //
+
+module.exports = reduce;

package/lib/ndarray.js

@@ -0,0 +1,153 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2021 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 vind2bind = require( '@stdlib/ndarray-base-vind2bind' );
+
+
+// VARIABLES //
+
+var MODE = 'throw';
+
+
+// MAIN //
+
+/**
+* Applies a function against an accumulator and each element in an array and returns the accumulated result.
+*
+* @private
+* @param {Object} x - object containing input ndarray meta data
+* @param {string} x.ref - reference to original input ndarray-like object
+* @param {string} x.dtype - data type
+* @param {Collection} x.data - data buffer
+* @param {NonNegativeInteger} x.length - number of elements
+* @param {NonNegativeIntegerArray} x.shape - dimensions
+* @param {IntegerArray} x.strides - stride lengths
+* @param {NonNegativeInteger} x.offset - index offset
+* @param {string} x.order - specifies whether `x` is row-major (C-style) or column-major (Fortran-style)
+* @param {Function} x.getter - callback for accessing `x` data buffer elements
+* @param {*} initial - initial value
+* @param {Function} fcn - function to apply
+* @param {*} thisArg - function execution context
+* @returns {*} accumulated result
+*
+* @example
+* var Complex64Array = require( '@stdlib/array-complex64' );
+* var Complex64 = require( '@stdlib/complex-float32' );
+* var realf = require( '@stdlib/complex-realf' );
+* var imagf = require( '@stdlib/complex-imagf' );
+* var cadd = require( '@stdlib/math-base-ops-cadd' );
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+*
+* // Create a data buffer:
+* var xbuf = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
+*
+* // Define the shape of the input array:
+* var shape = [ 2, 2 ];
+*
+* // Define the array strides:
+* var sx = [ 2, 1 ];
+*
+* // Define the index offset:
+* var ox = 0;
+*
+* // Define a getter:
+* function getter( buf, idx ) {
+*     return buf.get( idx );
+* }
+*
+* // Create the input ndarray-like object:
+* var x = {
+*     'ref': null,
+*     'dtype': 'complex64',
+*     'data': xbuf,
+*     'length': 4,
+*     'shape': shape,
+*     'strides': sx,
+*     'offset': ox,
+*     'order': 'row-major',
+*     'getter': getter
+* };
+* x.ref = x;
+*
+* // Compute the sum:
+* var v = reduce( x, new Complex64( 0.0, 0.0 ), naryFunction( cadd, 2 ) );
+*
+* var re = realf( v );
+* // returns 16.0
+*
+* var im = imagf( v );
+* // returns 20.0
+*/
+function reduce( x, initial, fcn, thisArg ) {
+	var xbuf;
+	var ordx;
+	var acc;
+	var len;
+	var get;
+	var ref;
+	var shx;
+	var sx;
+	var ox;
+	var ix;
+	var i;
+
+	// Cache the total number of elements over which to iterate:
+	len = x.length;
+
+	// Cache the input array shape:
+	shx = x.shape;
+
+	// Cache reference to the input ndarray data buffer:
+	xbuf = x.data;
+
+	// Cache reference to the stride array:
+	sx = x.strides;
+
+	// Cache the index of the first indexed element:
+	ox = x.offset;
+
+	// Cache the array order:
+	ordx = x.order;
+
+	// Cache the element accessor:
+	get = x.getter;
+
+	// Cache the reference to the original input array:
+	ref = x.ref;
+
+	// Check for a zero-dimensional array...
+	if ( shx.length === 0 ) {
+		return fcn.call( thisArg, initial, get( xbuf, ox ), 0, ref );
+	}
+	// Iterate over each element based on the linear **view** index, regardless as to how the data is stored in memory (note: this has negative performance implications for non-contiguous ndarrays due to a lack of data locality)...
+	acc = initial;
+	for ( i = 0; i < len; i++ ) {
+		ix = vind2bind( shx, sx, ox, ordx, i, MODE );
+		acc = fcn.call( thisArg, acc, get( xbuf, ix ), i, ref );
+	}
+	return acc;
+}
+
+
+// EXPORTS //
+
+module.exports = reduce;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stdlib/utils-reduce",
-  "version": "0.0.4",
-  "description": "Apply a function against an accumulator and each element in a collection and return the accumulated result.",
+  "version": "0.0.8",
+  "description": "Apply a function against an accumulator and each element in an array and return the accumulated result.",
   "license": "Apache-2.0",
   "author": {
     "name": "The Stdlib Authors",
@@ -37,14 +37,31 @@
     "url": "https://github.com/stdlib-js/stdlib/issues"
   },
   "dependencies": {
-    "@stdlib/assert-is-collection": "^0.0.x",
+    "@stdlib/array-base-arraylike2object": "^0.0.x",
+    "@stdlib/assert-is-array-like-object": "^0.0.x",
     "@stdlib/assert-is-function": "^0.0.x",
+    "@stdlib/assert-is-ndarray-like": "^0.0.x",
+    "@stdlib/ndarray-base-ndarraylike2object": "^0.0.x",
+    "@stdlib/ndarray-base-vind2bind": "^0.0.x",
     "@stdlib/types": "^0.0.x"
   },
   "devDependencies": {
+    "@stdlib/array-base-filled": "^0.0.x",
+    "@stdlib/array-complex64": "^0.0.x",
+    "@stdlib/array-filled-by": "^0.0.x",
     "@stdlib/array-float64": "^0.0.x",
     "@stdlib/bench": "^0.0.x",
+    "@stdlib/complex-float32": "^0.0.x",
+    "@stdlib/complex-imagf": "^0.0.x",
+    "@stdlib/complex-realf": "^0.0.x",
     "@stdlib/math-base-assert-is-nan": "^0.0.x",
+    "@stdlib/math-base-ops-add": "^0.0.x",
+    "@stdlib/math-base-ops-cadd": "^0.0.x",
+    "@stdlib/math-base-special-pow": "^0.0.x",
+    "@stdlib/ndarray-array": "^0.0.x",
+    "@stdlib/ndarray-ctor": "^0.0.x",
+    "@stdlib/random-base-discrete-uniform": "^0.0.x",
+    "@stdlib/utils-nary-function": "^0.0.x",
     "@stdlib/utils-noop": "^0.0.x",
     "tape": "git+https://github.com/kgryte/tape.git#fix/globby",
     "istanbul": "^0.4.1",
@@ -87,7 +104,11 @@
     "typed array",
     "typed",
     "array",
-    "array-like"
+    "array-like",
+    "ndarray",
+    "tensor",
+    "matrix",
+    "vector"
   ],
   "funding": {
     "type": "patreon",

package/CHANGELOG.md

@@ -1,5 +0,0 @@
-# CHANGELOG
-
-> Package changelog.
-
-See [GitHub Releases](https://github.com/stdlib-js/utils-reduce/releases) for the changelog.

package/lib/reduce.js

@@ -1,76 +0,0 @@
-/**
-* @license Apache-2.0
-*
-* Copyright (c) 2018 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 isCollection = require( '@stdlib/assert-is-collection' );
-var isFunction = require( '@stdlib/assert-is-function' );
-
-
-// MAIN //
-
-/**
-* Applies a function against an accumulator and each element in a collection and returns the accumulated result.
-*
-* @param {Collection} collection - input collection
-* @param {*} initial - initial value
-* @param {Function} reducer - reduction function
-* @param {*} [thisArg] - reduction function execution context
-* @throws {TypeError} first argument must be a collection
-* @throws {TypeError} third argument must be a function
-* @returns {*} accumulated result
-*
-* @example
-* function sum( acc, value ) {
-*     return acc + value;
-* }
-*
-* var arr = [ 1, 2, 3, 4 ];
-*
-* var s = reduce( arr, 0, sum );
-* // returns 10
-*/
-function reduce( collection, initial, reducer, thisArg ) {
-	var len;
-	var acc;
-	var i;
-	if ( !isCollection( collection ) ) {
-		throw new TypeError( 'invalid argument. First argument must be a collection. Value: `'+collection+'`.' );
-	}
-	if ( !isFunction( reducer ) ) {
-		throw new TypeError( 'invalid argument. Third argument must be a function. Value:`'+reducer+'`.' );
-	}
-	len = collection.length;
-	acc = initial;
-	for ( i = 0; i < len; i++ ) {
-		acc = reducer.call( thisArg, acc, collection[ i ], i, collection );
-
-		// Account for dynamically resizing a collection...
-		if ( len !== collection.length ) {
-			len = collection.length;
-		}
-	}
-	return acc;
-}
-
-
-// EXPORTS //
-
-module.exports = reduce;