@stdlib/utils-map2-right 0.0.1

package/lib/array.js

@@ -0,0 +1,100 @@
+/**
+* @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 //
+
+/**
+* Applies a function to elements in two input arrays while iterating from right to left and assigns the results to an output array.
+*
+* @private
+* @param {Object} x - object containing data for the first input array
+* @param {ArrayLikeObject} x.data - array data
+* @param {Function} x.getter - callback for accessing array data elements
+* @param {Object} y - object containing data for the second input array
+* @param {ArrayLikeObject} y.data - array data
+* @param {Function} y.getter - callback for accessing array data elements
+* @param {Object} z - object containing output array data
+* @param {ArrayLikeObject} z.data - array data
+* @param {Function} z.setter - callback for setting array data elements
+* @param {Function} fcn - function to apply
+* @param {*} thisArg - function execution context
+* @returns {void}
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+*
+* // Define getters and setters:
+* function getter( buf, idx ) {
+*     return buf[ idx ];
+* }
+*
+* function setter( buf, idx, value ) {
+*     buf[ idx ] = value;
+* }
+*
+* // Create the input and output array objects:
+* var x = {
+*     'data': [ 1, 2, 3, 4, 5, 6 ],
+*     'getter': getter
+* };
+* var y = {
+*     'data': [ 1, 1, 1, 1, 1, 1 ],
+*     'getter': getter
+* };
+* var z = {
+*     'data': [ 0, 0, 0, 0, 0, 0 ],
+*     'setter': setter
+* };
+*
+* map2Right( x, y, z, naryFunction( add, 2 ) );
+*
+* var data = z.data;
+* // returns [ 2, 3, 4, 5, 6, 7 ]
+*/
+function map2Right( x, y, z, fcn, thisArg ) {
+	var xbuf;
+	var ybuf;
+	var zbuf;
+	var xget;
+	var yget;
+	var zset;
+	var i;
+
+	// Cache references to the input and output data:
+	xbuf = x.data;
+	ybuf = y.data;
+	zbuf = z.data;
+
+	// Cache accessors:
+	xget = x.getter;
+	yget = y.getter;
+	zset = z.setter;
+
+	// Iterate over the elements...
+	for ( i = xbuf.length-1; i >= 0; i-- ) {
+		zset( zbuf, i, fcn.call( thisArg, xget( xbuf, i ), yget( ybuf, i ), i, xbuf, ybuf ) ); // eslint-disable-line max-len
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = map2Right;

package/lib/assign.js

@@ -0,0 +1,151 @@
+/**
+* @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 broadcast = require( '@stdlib/ndarray-base-maybe-broadcast-array' );
+var isReadOnly = require( '@stdlib/ndarray-base-assert-is-read-only' );
+var ndarrayFcn = require( './ndarray.js' );
+var arrayFcn = require( './array.js' );
+
+
+// MAIN //
+
+/**
+* Applies a function to elements in two input arrays while iterating from right to left and assigns the results to an output array.
+*
+* ## Notes
+*
+* -   The applied function is provided the following arguments:
+*
+*     -   **v1**: element from first input array.
+*     -   **v2**: element from second input array.
+*     -   **idx**: element index.
+*     -   **x**: first input array.
+*     -   **y**: second input array.
+*
+* @param {(ArrayLikeObject|ndarray)} x - first input array
+* @param {(ArrayLikeObject|ndarray)} y - second input array
+* @param {(ArrayLikeObject|ndarray)} out - output array
+* @param {Function} fcn - function to apply
+* @param {*} [thisArg] - function execution context
+* @throws {TypeError} first argument must be an array-like object or an ndarray
+* @throws {TypeError} second argument must be an array-like object or an ndarray
+* @throws {TypeError} third argument must be an array-like object or an ndarray
+* @throws {TypeError} fourth argument must be a function
+* @throws {TypeError} input and output arrays must be either all array-like objects or all ndarrays
+* @throws {RangeError} input and output arrays must have the same length
+* @throws {Error} input and output ndarrays must be broadcast compatible
+* @throws {Error} cannot write to a read-only ndarray
+* @returns {(ArrayLikeObject|ndarray)} output array
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+*
+* var x = [ 1, 2, 3, 4, 5, 6 ];
+* var y = [ 1, 1, 1, 1, 1, 1 ];
+* var out = [ 0, 0, 0, 0, 0, 0 ];
+*
+* map2Right( x, y, out, naryFunction( add, 2 ) );
+*
+* console.log( out );
+* // => [ 2, 3, 4, 5, 6, 7 ]
+*
+* @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',
+*     'shape': [ 2, 3 ]
+* };
+* var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
+* var y = array( [ [ 1, 1, 1 ], [ 1, 1, 1 ] ], opts );
+* var out = array( opts );
+*
+* map2Right( x, y, out, naryFunction( add, 2 ) );
+*
+* var data = out.data;
+* // returns [ 2, 3, 4, 5, 6, 7 ]
+*/
+function map2Right( x, y, out, fcn, thisArg ) {
+	var isxnd;
+	var isynd;
+	var isznd;
+	var tmp;
+	var sh;
+	if ( !isFunction( fcn ) ) {
+		throw new TypeError( 'invalid argument. Fourth argument must be a function. Value: `' + fcn + '`.' );
+	}
+	isxnd = isndarrayLike( x );
+	isynd = isndarrayLike( y );
+	isznd = isndarrayLike( out );
+	if ( isxnd ) { // note: assertion order matters here, as an ndarray-like object is also array-like
+		if ( !isynd ) {
+			throw new TypeError( 'invalid argument. If the first input array is an ndarray, the second input array must also be an ndarray. Value: `' + y + '`.' );
+		}
+		if ( !isznd ) {
+			throw new TypeError( 'invalid argument. If the input arrays are ndarrays, the output array must also be an ndarray. Value: `' + out + '`.' );
+		}
+		if ( isReadOnly( out ) ) {
+			throw new Error( 'invalid argument. The output ndarray must be writable. Cannot write to a read-only ndarray.' );
+		}
+		out = ndarraylike2object( out );
+		sh = out.shape;
+
+		// Broadcast and wrap the input arrays and ensure that the `ref` properties point to the original input arrays...
+		tmp = ndarraylike2object( broadcast( x, sh ) );
+		tmp.ref = x;
+		x = tmp;
+
+		tmp = ndarraylike2object( broadcast( y, sh ) );
+		tmp.ref = y;
+		y = tmp;
+
+		ndarrayFcn( x, y, out, fcn, thisArg );
+		return out.ref;
+	}
+	if ( isArrayLikeObject( x ) ) {
+		if ( isynd || !isArrayLikeObject( y ) ) {
+			throw new TypeError( 'invalid argument. If the first input array is an array-like object, the second input array must also be an array-like object. Value: `' + y + '`.' );
+		}
+		if ( isznd || !isArrayLikeObject( out ) ) {
+			throw new TypeError( 'invalid argument. If the input arrays are array-like objects, the output array must also be an array-like object. Value: `' + out + '`.' );
+		}
+		if ( x.length !== y.length || y.length !== out.length ) {
+			throw new RangeError( 'invalid arguments. Input and output arrays must have the same number of elements ( i.e., length).' );
+		}
+		arrayFcn( arraylike2object( x ), arraylike2object( y ), arraylike2object( out ), fcn, thisArg ); // eslint-disable-line max-len
+		return out;
+	}
+	throw new TypeError( 'invalid argument. First argument must be an array-like object or an ndarray. Value: `' + x + '`.' );
+}
+
+
+// EXPORTS //
+
+module.exports = map2Right;

package/lib/index.js

@@ -0,0 +1,103 @@
+/**
+* @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';
+
+/**
+* Apply a function to elements in two input arrays while iterating from right to left and assign the results to an output array.
+*
+* @module @stdlib/utils-map2-right
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var map2Right = require( '@stdlib/utils-map2-right' );
+*
+* var x = [ 1, 2, 3, 4, 5, 6 ];
+* var y = [ 1, 1, 1, 1, 1, 1 ];
+*
+* var out = map2Right( x, y, naryFunction( add, 2 ) );
+* // returns [ 2, 3, 4, 5, 6, 7 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var array = require( '@stdlib/ndarray-array' );
+* var map2Right = require( '@stdlib/utils-map2-right' );
+*
+* var opts = {
+*     'dtype': 'generic'
+* };
+* var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
+* var y = array( [ [ 1, 1, 1 ], [ 1, 1, 1 ] ], opts );
+*
+* var out = map2Right( x, y. naryFunction( add, 2 ) );
+* // returns <ndarray>
+*
+* var data = out.data;
+* // returns [ 2, 3, 4, 5, 6, 7 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var map2Right = require( '@stdlib/utils-map2-right' );
+*
+* var x = [ 1, 2, 3, 4, 5, 6 ];
+* var y = [ 1, 1, 1, 1, 1, 1 ];
+* var out = [ 0, 0, 0, 0, 0, 0 ];
+*
+* map2Right.assign( x, y, out, naryFunction( add, 2 ) );
+*
+* console.log( out );
+* // => [ 2, 3, 4, 5, 6, 7 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+* var array = require( '@stdlib/ndarray-array' );
+* var map2Right = require( '@stdlib/utils-map2-right' );
+*
+* var opts = {
+*     'dtype': 'generic',
+*     'shape': [ 2, 3 ]
+* };
+* var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
+* var y = array( [ [ 1, 1, 1 ], [ 1, 1, 1 ] ], opts );
+* var out = array( opts );
+*
+* map2Right.assign( x, y, out, naryFunction( add, 2 ) );
+*
+* var data = out.data;
+* // returns [ 2, 3, 4, 5, 6, 7 ]
+*/
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var main = require( './main.js' );
+var assign = require( './assign.js' );
+
+
+// MAIN //
+
+setReadOnly( main, 'assign', assign );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/main.js

@@ -0,0 +1,147 @@
+/**
+* @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 zeros = require( '@stdlib/array-base-zeros' );
+var ndarraylike2object = require( '@stdlib/ndarray-base-ndarraylike2object' );
+var arraylike2object = require( '@stdlib/array-base-arraylike2object' );
+var ndzeros = require( '@stdlib/ndarray-zeros' );
+var broadcastShapes = require( '@stdlib/ndarray-base-broadcast-shapes' );
+var broadcast = require( '@stdlib/ndarray-base-maybe-broadcast-array' );
+var ndarrayFcn = require( './ndarray.js' );
+var arrayFcn = require( './array.js' );
+
+
+// MAIN //
+
+/**
+* Applies a function to elements in two input arrays while iterating from right to left and assigns the results to a new array.
+*
+* ## Notes
+*
+* -   The applied function is provided the following arguments:
+*
+*     -   **v1**: element from first input array.
+*     -   **v2**: element from second input array.
+*     -   **idx**: element index.
+*     -   **x**: first input array.
+*     -   **y**: second input array.
+*
+* @param {(ArrayLikeObject|ndarray)} x - first input array
+* @param {(ArrayLikeObject|ndarray)} y - second input array
+* @param {Function} fcn - function to apply
+* @param {*} [thisArg] - function execution context
+* @throws {TypeError} first argument must be an array-like object or an ndarray
+* @throws {TypeError} second argument must be an array-like object or an ndarray
+* @throws {TypeError} input arrays must be either both array-like objects or both ndarrays
+* @throws {RangeError} input arrays must have the same length
+* @throws {Error} input ndarrays must be broadcast compatible
+* @throws {TypeError} third argument must be a function
+* @returns {(Array|ndarray)} output array
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-add' );
+*
+* var x = [ 1, 2, 3, 4, 5, 6 ];
+* var y = [ 1, 1, 1, 1, 1, 1 ];
+*
+* var out = map2Right( x, y, naryFunction( add, 2 ) );
+* // returns [ 2, 3, 4, 5, 6, 7 ]
+*
+* @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 x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
+* var y = array( [ [ 1, 1, 1 ], [ 1, 1, 1 ] ], opts );
+*
+* var out = map2Right( x, y, naryFunction( add, 2 ) );
+* // returns <ndarray>
+*
+* var data = out.data;
+* // returns [ 2, 3, 4, 5, 6, 7 ]
+*/
+function map2Right( x, y, fcn, thisArg ) {
+	var isxnd;
+	var isynd;
+	var out;
+	var tmp;
+	var sh;
+
+	if ( !isFunction( fcn ) ) {
+		throw new TypeError( 'invalid argument. Second argument must be a function. Value: `' + fcn + '`.' );
+	}
+	isxnd = isndarrayLike( x );
+	isynd = isndarrayLike( y );
+	if ( isxnd ) { // note: assertion order matters here, as an ndarray-like object is also array-like
+		if ( !isynd ) {
+			throw new TypeError( 'invalid argument. If the first input array is an ndarray, the second input array must also be an ndarray. Value: `' + y + '`.' );
+		}
+		// Broadcast `x` and `y` to a common shape:
+		sh = broadcastShapes( [ x.shape, y.shape ] );
+		if ( sh === null ) {
+			throw new Error( 'invalid arguments. Input ndarrays must be broadcast compatible.' );
+		}
+		// Broadcast and wrap the input arrays and ensure that the `ref` properties point to the original input arrays...
+		tmp = ndarraylike2object( broadcast( x, sh ) );
+		tmp.ref = x;
+		x = tmp;
+
+		tmp = ndarraylike2object( broadcast( y, sh ) );
+		tmp.ref = y;
+		y = tmp;
+
+		// Create an output array:
+		out = ndzeros( sh, {
+			'dtype': 'generic',
+			'order': x.order
+		});
+
+		// Apply the function to the input arrays:
+		ndarrayFcn( x, y, ndarraylike2object( out ), fcn, thisArg );
+		return out;
+	}
+	if ( isArrayLikeObject( x ) ) {
+		if ( isynd || !isArrayLikeObject( y ) ) {
+			throw new TypeError( 'invalid argument. If the first input array is an array-like object, the second input array must also be an array-like object. Value: `' + y + '`.' );
+		}
+		if ( y.length !== x.length ) {
+			throw new RangeError( 'invalid arguments. Input arrays must have the same number of elements (i.e., length).' );
+		}
+		out = zeros( x.length );
+		arrayFcn( arraylike2object( x ), arraylike2object( y ), arraylike2object( out ), fcn, thisArg ); // eslint-disable-line max-len
+		return out;
+	}
+	throw new TypeError( 'invalid argument. First argument must be an array-like object or an ndarray. Value: `' + x + '`.' );
+}
+
+
+// EXPORTS //
+
+module.exports = map2Right;