@stdlib/utils-map2-right 0.0.1

package/lib/ndarray.js

@@ -0,0 +1,236 @@
+/**
+* @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 //
+
+/**
+* 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 meta data for the first input ndarray
+* @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 {Object} y - object containing meta data for the second input ndarray
+* @param {string} y.ref - reference to original input ndarray-like object
+* @param {string} y.dtype - data type
+* @param {Collection} y.data - data buffer
+* @param {NonNegativeInteger} y.length - number of elements
+* @param {NonNegativeIntegerArray} y.shape - dimensions
+* @param {IntegerArray} y.strides - stride lengths
+* @param {NonNegativeInteger} y.offset - index offset
+* @param {string} y.order - specifies whether `y` is row-major (C-style) or column-major (Fortran-style)
+* @param {Function} y.getter - callback for accessing `y` data buffer elements
+* @param {Object} z - object containing output ndarray meta data
+* @param {string} z.dtype - data type
+* @param {Collection} z.data - data buffer
+* @param {NonNegativeInteger} z.length - number of elements
+* @param {NonNegativeIntegerArray} z.shape - dimensions
+* @param {IntegerArray} z.strides - stride lengths
+* @param {NonNegativeInteger} z.offset - index offset
+* @param {string} z.order - specifies whether `z` is row-major (C-style) or column-major (Fortran-style)
+* @param {Function} z.setter - callback for setting `z` data buffer elements
+* @param {Function} fcn - function to apply
+* @param {*} thisArg - function execution context
+* @returns {void}
+*
+* @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 naryFunction = require( '@stdlib/utils-nary-function' );
+* var add = require( '@stdlib/math-base-ops-caddf' );
+*
+* // Create data buffers:
+* var xbuf = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
+* var ybuf = new Complex64Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] );
+* var zbuf = new Complex64Array( 4 );
+*
+* // Define the shape of the input and output arrays:
+* var shape = [ 2, 2 ];
+*
+* // Define the array strides:
+* var sx = [ 2, 1 ];
+* var sy = [ 2, 1 ];
+* var sz = [ 2, 1 ];
+*
+* // Define the index offsets:
+* var ox = 0;
+* var oy = 0;
+* var oz = 0;
+*
+* // Define getters and setters:
+* function getter( buf, idx ) {
+*     return buf.get( idx );
+* }
+*
+* function setter( buf, idx, value ) {
+*     buf.set( value, idx );
+* }
+*
+* // Create the input and output ndarray-like objects:
+* var x = {
+*     'ref': null,
+*     'dtype': 'complex64',
+*     'data': xbuf,
+*     'length': 4,
+*     'shape': shape,
+*     'strides': sx,
+*     'offset': ox,
+*     'order': 'row-major',
+*     'getter': getter
+* };
+* x.ref = x;
+*
+* var y = {
+*     'ref': null,
+*     'dtype': 'complex64',
+*     'data': ybuf,
+*     'length': 4,
+*     'shape': shape,
+*     'strides': sy,
+*     'offset': ox,
+*     'order': 'row-major',
+*     'getter': getter
+* };
+* y.ref = y;
+*
+* var z = {
+*     'ref': null,
+*     'dtype': 'complex64',
+*     'data': zbuf,
+*     'length': 4,
+*     'shape': shape,
+*     'strides': sz,
+*     'offset': oz,
+*     'order': 'row-major',
+*     'setter': setter
+* };
+*
+* // Apply the function:
+* map2Right( x, y, z, naryFunction( add, 2 ) );
+*
+* var v = z.data.get( 0 );
+*
+* var re = realf( v );
+* // returns 2.0
+*
+* var im = imagf( v );
+* // returns 3.0
+*/
+function map2Right( x, y, z, fcn, thisArg ) {
+	var xbuf;
+	var ybuf;
+	var zbuf;
+	var ordx;
+	var ordy;
+	var ordz;
+	var xget;
+	var yget;
+	var zset;
+	var xref;
+	var yref;
+	var shx;
+	var shy;
+	var shz;
+	var len;
+	var sx;
+	var sy;
+	var sz;
+	var ox;
+	var oy;
+	var oz;
+	var ix;
+	var iy;
+	var iz;
+	var i;
+
+	// Cache the total number of elements over which to iterate:
+	len = x.length;
+
+	// Cache the array shapes:
+	shx = x.shape;
+	shy = y.shape;
+	shz = z.shape;
+
+	// Cache references to the input and output ndarray data buffers:
+	xbuf = x.data;
+	ybuf = y.data;
+	zbuf = z.data;
+
+	// Cache references to the respective stride arrays:
+	sx = x.strides;
+	sy = y.strides;
+	sz = z.strides;
+
+	// Cache the indices of the first indexed elements in the respective ndarrays:
+	ox = x.offset;
+	oy = y.offset;
+	oz = z.offset;
+
+	// Cache the respective array orders:
+	ordx = x.order;
+	ordy = y.order;
+	ordz = z.order;
+
+	// Cache accessors:
+	xget = x.getter;
+	yget = y.getter;
+	zset = z.setter;
+
+	// Cache references to the original input arrays:
+	xref = x.ref;
+	yref = y.ref;
+
+	// Check for a zero-dimensional array...
+	if ( shx.length === 0 && shy.length === 0 ) {
+		zset( zbuf, oz, fcn.call( thisArg, xget( xbuf, ox ), yget( ybuf, oy ), 0, xref, yref ) ); // eslint-disable-line max-len
+		return;
+	}
+	// Iterate over the arrays 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)...
+	for ( i = len-1; i >= 0; i-- ) {
+		ix = vind2bind( shx, sx, ox, ordx, i, MODE );
+		iy = vind2bind( shy, sy, oy, ordy, i, MODE );
+		iz = vind2bind( shz, sz, oz, ordz, i, MODE );
+		zset( zbuf, iz, fcn.call( thisArg, xget( xbuf, ix ), yget( ybuf, iy ), i, xref, yref ) ); // eslint-disable-line max-len
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = map2Right;

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@stdlib/utils-map2-right",
+  "version": "0.0.1",
+  "description": "Apply a function to elements in two input arrays while iterating from right to left and assign the results to an output array.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "main": "./lib",
+  "directories": {
+    "benchmark": "./benchmark",
+    "doc": "./docs",
+    "example": "./examples",
+    "lib": "./lib",
+    "test": "./test"
+  },
+  "types": "./docs/types",
+  "scripts": {
+    "test": "make test",
+    "test-cov": "make test-cov",
+    "examples": "make examples",
+    "benchmark": "make benchmark"
+  },
+  "homepage": "https://stdlib.io",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/utils-map2-right.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {
+    "@stdlib/array-base-arraylike2object": "^0.0.x",
+    "@stdlib/array-base-zeros": "^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-assert-is-read-only": "^0.0.x",
+    "@stdlib/ndarray-base-broadcast-shapes": "^0.0.x",
+    "@stdlib/ndarray-base-maybe-broadcast-array": "^0.0.x",
+    "@stdlib/ndarray-base-ndarraylike2object": "^0.0.x",
+    "@stdlib/ndarray-base-vind2bind": "^0.0.x",
+    "@stdlib/ndarray-zeros": "^0.0.x",
+    "@stdlib/types": "^0.0.x",
+    "@stdlib/utils-define-nonenumerable-read-only-property": "^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/assert-is-array": "^0.0.x",
+    "@stdlib/bench": "^0.0.x",
+    "@stdlib/complex-imagf": "^0.0.x",
+    "@stdlib/complex-realf": "^0.0.x",
+    "@stdlib/math-base-ops-add": "^0.0.x",
+    "@stdlib/math-base-ops-caddf": "^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",
+    "tape": "git+https://github.com/kgryte/tape.git#fix/globby",
+    "istanbul": "^0.4.1",
+    "tap-spec": "5.x.x"
+  },
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "os": [
+    "aix",
+    "darwin",
+    "freebsd",
+    "linux",
+    "macos",
+    "openbsd",
+    "sunos",
+    "win32",
+    "windows"
+  ],
+  "keywords": [
+    "stdlib",
+    "stdutils",
+    "stdutil",
+    "utilities",
+    "utility",
+    "utils",
+    "util",
+    "map",
+    "array",
+    "ndarray",
+    "tensor",
+    "matrix",
+    "vector",
+    "elementwise",
+    "element-wise",
+    "transform",
+    "invoke",
+    "call",
+    "apply",
+    "function",
+    "fun",
+    "func",
+    "fcn",
+    "binary"
+  ],
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/athan"
+  }
+}