@stdlib/utils-map-reduce 0.0.1

package/docs/types/test.ts

@@ -0,0 +1,184 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2022 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.
+*/
+
+import array = require( '@stdlib/ndarray-array' );
+import mapReduce = require( './index' );
+
+/**
+* Mapping function.
+*
+* @param value - array element
+* @returns result
+*/
+function mapper( value: number ): number {
+	return value;
+}
+
+/**
+* Reducing function.
+*
+* @param acc - accumulated value
+* @param v - array element
+* @returns result
+*/
+function reducer( acc: number, value: number ): number {
+	return acc + value;
+}
+
+
+// TESTS //
+
+// The function returns the accumulated value when provided a collection...
+{
+	mapReduce( [ 0, 1, 1, NaN, 2 ], 0, mapper, reducer ); // $ExpectType any
+	mapReduce( [ -1, 1, 2 ], 100, mapper, reducer ); // $ExpectType any
+	mapReduce( [ -1, 1, 2 ], 0, mapper, reducer, {} ); // $ExpectType any
+}
+
+// The function returns the accumulated value when provided an ndarray...
+{
+	const arr = array( [ 1, 2, 3, 4, 5, 6 ] );
+
+	mapReduce( arr, 0, mapper, reducer ); // $ExpectType any
+	mapReduce( arr, 100, mapper, reducer ); // $ExpectType any
+	mapReduce( arr, 0, mapper, reducer, {} ); // $ExpectType any
+}
+
+// The compiler throws an error if the function is provided a first argument which is not a collection or ndarray...
+{
+	mapReduce( 2, 0, mapper, reducer ); // $ExpectError
+	mapReduce( false, 0, mapper, reducer ); // $ExpectError
+	mapReduce( true, 0, mapper, reducer ); // $ExpectError
+	mapReduce( null, 0, mapper, reducer ); // $ExpectError
+	mapReduce( {}, 0, mapper, reducer ); // $ExpectError
+
+	mapReduce( 2, 0, mapper, reducer, {} ); // $ExpectError
+	mapReduce( false, 0, mapper, reducer, {} ); // $ExpectError
+	mapReduce( true, 0, mapper, reducer, {} ); // $ExpectError
+	mapReduce( null, 0, mapper, reducer, {} ); // $ExpectError
+	mapReduce( {}, 0, mapper, reducer, {} ); // $ExpectError
+}
+
+// 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 ];
+
+	mapReduce( arr1, 0, 'abc', reducer ); // $ExpectError
+	mapReduce( arr1, 0, 2, reducer ); // $ExpectError
+	mapReduce( arr1, 0, false, reducer ); // $ExpectError
+	mapReduce( arr1, 0, true, reducer ); // $ExpectError
+	mapReduce( arr1, 0, null, reducer ); // $ExpectError
+	mapReduce( arr1, 0, {}, reducer ); // $ExpectError
+	mapReduce( arr1, 0, [], reducer ); // $ExpectError
+
+	mapReduce( arr1, 0, 'abc', reducer, {} ); // $ExpectError
+	mapReduce( arr1, 0, 2, reducer, {} ); // $ExpectError
+	mapReduce( arr1, 0, false, reducer, {} ); // $ExpectError
+	mapReduce( arr1, 0, true, reducer, {} ); // $ExpectError
+	mapReduce( arr1, 0, null, reducer, {} ); // $ExpectError
+	mapReduce( arr1, 0, {}, reducer, {} ); // $ExpectError
+	mapReduce( arr1, 0, [], reducer, {} ); // $ExpectError
+
+	mapReduce( arr1, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w, reducer ); // $ExpectError
+	mapReduce( arr1, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w, reducer, {} ); // $ExpectError
+
+	const arr2 = array( [ 0, 1, 1, NaN, 2 ] );
+
+	mapReduce( arr2, 0, 'abc', reducer ); // $ExpectError
+	mapReduce( arr2, 0, 2, reducer ); // $ExpectError
+	mapReduce( arr2, 0, false, reducer ); // $ExpectError
+	mapReduce( arr2, 0, true, reducer ); // $ExpectError
+	mapReduce( arr2, 0, null, reducer ); // $ExpectError
+	mapReduce( arr2, 0, {}, reducer ); // $ExpectError
+	mapReduce( arr2, 0, [], reducer ); // $ExpectError
+
+	mapReduce( arr2, 0, 'abc', reducer, {} ); // $ExpectError
+	mapReduce( arr2, 0, 2, reducer, {} ); // $ExpectError
+	mapReduce( arr2, 0, false, reducer, {} ); // $ExpectError
+	mapReduce( arr2, 0, true, reducer, {} ); // $ExpectError
+	mapReduce( arr2, 0, null, reducer, {} ); // $ExpectError
+	mapReduce( arr2, 0, {}, reducer, {} ); // $ExpectError
+	mapReduce( arr2, 0, [], reducer, {} ); // $ExpectError
+
+	mapReduce( arr2, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w, reducer ); // $ExpectError
+	mapReduce( arr2, 0, ( x: number, y: number, z: number, w: number ): number => x + y + z + w, reducer, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a fourth argument which is not a function with a supported signature...
+{
+	const arr1 = [ 0, 1, 1, NaN, 2 ];
+
+	mapReduce( arr1, 0, mapper, 'abc' ); // $ExpectError
+	mapReduce( arr1, 0, mapper, 2 ); // $ExpectError
+	mapReduce( arr1, 0, mapper, false ); // $ExpectError
+	mapReduce( arr1, 0, mapper, true ); // $ExpectError
+	mapReduce( arr1, 0, mapper, null ); // $ExpectError
+	mapReduce( arr1, 0, mapper, {} ); // $ExpectError
+	mapReduce( arr1, 0, mapper, [] ); // $ExpectError
+
+	mapReduce( arr1, 0, mapper, 'abc', {} ); // $ExpectError
+	mapReduce( arr1, 0, mapper, 2, {} ); // $ExpectError
+	mapReduce( arr1, 0, mapper, false, {} ); // $ExpectError
+	mapReduce( arr1, 0, mapper, true, {} ); // $ExpectError
+	mapReduce( arr1, 0, mapper, null, {} ); // $ExpectError
+	mapReduce( arr1, 0, mapper, {}, {} ); // $ExpectError
+	mapReduce( arr1, 0, mapper, [], {} ); // $ExpectError
+
+	mapReduce( arr1, 0, mapper, ( x: number, y: number, z: number, w: number ): number => x + y + z + w ); // $ExpectError
+	mapReduce( arr1, 0, mapper, ( x: number, y: number, z: number, w: number ): number => x + y + z + w, {} ); // $ExpectError
+
+	const arr2 = array( [ 0, 1, 1, NaN, 2 ] );
+
+	mapReduce( arr2, 0, mapper, 'abc' ); // $ExpectError
+	mapReduce( arr2, 0, mapper, 2 ); // $ExpectError
+	mapReduce( arr2, 0, mapper, false ); // $ExpectError
+	mapReduce( arr2, 0, mapper, true ); // $ExpectError
+	mapReduce( arr2, 0, mapper, null ); // $ExpectError
+	mapReduce( arr2, 0, mapper, {} ); // $ExpectError
+	mapReduce( arr2, 0, mapper, [] ); // $ExpectError
+
+	mapReduce( arr2, 0, mapper, 'abc', {} ); // $ExpectError
+	mapReduce( arr2, 0, mapper, 2, {} ); // $ExpectError
+	mapReduce( arr2, 0, mapper, false, {} ); // $ExpectError
+	mapReduce( arr2, 0, mapper, true, {} ); // $ExpectError
+	mapReduce( arr2, 0, mapper, null, {} ); // $ExpectError
+	mapReduce( arr2, 0, mapper, {}, {} ); // $ExpectError
+	mapReduce( arr2, 0, mapper, [], {} ); // $ExpectError
+
+	mapReduce( arr2, 0, mapper, ( x: number, y: number, z: number, w: number ): number => x + y + z + w ); // $ExpectError
+	mapReduce( arr2, 0, mapper, ( 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 ];
+
+	mapReduce(); // $ExpectError
+	mapReduce( arr1 ); // $ExpectError
+	mapReduce( arr1, 0 ); // $ExpectError
+	mapReduce( arr1, 0, mapper, ); // $ExpectError
+	mapReduce( arr1, 0, mapper, reducer, {}, 3 ); // $ExpectError
+
+	const arr2 = array( [ 1, 2, 3 ] );
+
+	mapReduce(); // $ExpectError
+	mapReduce( arr2 ); // $ExpectError
+	mapReduce( arr2, 0 ); // $ExpectError
+	mapReduce( arr2, 0, mapper ); // $ExpectError
+	mapReduce( arr2, 0, mapper, reducer, {}, 3 ); // $ExpectError
+}

package/lib/array.js

@@ -0,0 +1,83 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2022 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 //
+
+/**
+* Performs a map-reduce operation against 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} mapper - mapping function
+* @param {Function} reducer - reducing function
+* @param {*} thisArg - reducing function execution context
+* @returns {*} accumulated result
+*
+* @example
+* function square( value ) {
+*     return value * value;
+* }
+*
+* 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 of squared values:
+* var out = mapReduce( x, 0, square, sum );
+* // returns 30
+*/
+function mapReduce( x, initial, mapper, reducer, 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 = reducer.call( thisArg, acc, mapper( get( xbuf, i ), i, xbuf ), i, xbuf ); // eslint-disable-line max-len
+	}
+	return acc;
+}
+
+
+// EXPORTS //
+
+module.exports = mapReduce;

package/lib/index.js

@@ -0,0 +1,65 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2022 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';
+
+/**
+* Perform a map-reduce operation against each element in an array and return the accumulated result.
+*
+* @module @stdlib/utils-map-reduce
+*
+* @example
+* var mapReduce = require( '@stdlib/utils-map-reduce' );
+*
+* function square( value ) {
+*     return value * value;
+* }
+*
+* function sum( acc, value ) {
+*     return acc + value;
+* }
+*
+* var arr = [ 1, 2, 3, 4 ];
+*
+* var out = mapReduce( arr, 0, sum );
+* // returns 30
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+* var array = require( '@stdlib/ndarray-array' );
+* var mapReduce = require( '@stdlib/utils-map-reduce' );
+*
+* var opts = {
+*     'dtype': 'generic'
+* };
+* var arr = array( [ [ -1, -2, -3 ], [ -4, -5, -6 ] ], opts );
+*
+* var out = mapReduce( arr, 0, naryFunction( abs, 1 ), naryFunction( add, 2 ) );
+* // returns 21
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/main.js

@@ -0,0 +1,109 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2022 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 //
+
+/**
+* Performs a map-reduce operation against each element in an array and returns the accumulated result.
+*
+* ## Notes
+*
+* -   The mapping function is provided the following arguments:
+*
+*     -   **value**: array element.
+*     -   **index**: element index.
+*     -   **arr**: input array.
+*
+* -   The reducing function is provided the following arguments:
+*
+*     -   **accumulator**: accumulated value.
+*     -   **value**: result of applying the mapping function against the current array element.
+*     -   **index**: element index.
+*     -   **arr**: input array.
+*
+* @param {(ArrayLikeObject|ndarray)} arr - input array
+* @param {*} initial - initial value
+* @param {Function} mapper - mapping function
+* @param {Function} reducer - reducing 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
+* @throws {TypeError} fourth argument must be a function
+* @returns {*} accumulated result
+*
+* @example
+* function square( value ) {
+*     return value * value;
+* }
+*
+* function sum( acc, value ) {
+*     return acc + value;
+* }
+*
+* var arr = [ 1, 2, 3, 4 ];
+*
+* var out = mapReduce( arr, 0, square, sum );
+* // returns 30
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+* var array = require( '@stdlib/ndarray-array' );
+*
+* var opts = {
+*     'dtype': 'generic'
+* };
+* var arr = array( [ [ -1, -2, -3 ], [ -4, -5, -6 ] ], opts );
+*
+* var out = mapReduce( arr, 0, naryFunction( abs, 1 ), naryFunction( add, 2 ) );
+* // returns 21
+*/
+function mapReduce( arr, initial, mapper, reducer, thisArg ) {
+	if ( !isFunction( mapper ) ) {
+		throw new TypeError( 'invalid argument. Third argument must be a function. Value:`' + mapper + '`.' );
+	}
+	if ( !isFunction( reducer ) ) {
+		throw new TypeError( 'invalid argument. Fourth 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, mapper, reducer, thisArg ); // eslint-disable-line max-len
+	}
+	if ( isArrayLikeObject( arr ) ) {
+		return arrayFcn( arraylike2object( arr ), initial, mapper, reducer, thisArg ); // eslint-disable-line max-len
+	}
+	throw new TypeError( 'invalid argument. First argument must be an array-like object or an ndarray. Value: `' + arr + '`.' );
+}
+
+
+// EXPORTS //
+
+module.exports = mapReduce;

package/lib/ndarray.js

@@ -0,0 +1,155 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2022 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 //
+
+/**
+* Performs a map-reduce operation against 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} mapper - mapping function
+* @param {Function} reducer - reducing function
+* @param {*} thisArg - reducing 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 cceil = require( '@stdlib/math-base-special-cceil' );
+* var cadd = require( '@stdlib/math-base-ops-cadd' );
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+*
+* // Create a data buffer:
+* var xbuf = new Complex64Array( [ 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5 ] );
+*
+* // 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 = mapReduce( x, new Complex64( 0.0, 0.0 ), naryFunction( cceil, 1 ), naryFunction( cadd, 2 ) );
+*
+* var re = realf( v );
+* // returns 20.0
+*
+* var im = imagf( v );
+* // returns 24.0
+*/
+function mapReduce( x, initial, mapper, reducer, 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 reducer.call( thisArg, initial, mapper( get( xbuf, ox ), 0, ref ), 0, ref ); // eslint-disable-line max-len
+	}
+	// 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 = reducer.call( thisArg, acc, mapper( get( xbuf, ix ), i, ref ), i, ref ); // eslint-disable-line max-len
+	}
+	return acc;
+}
+
+
+// EXPORTS //
+
+module.exports = mapReduce;