@stdlib/utils-map 0.0.1

package/lib/assign.js

@@ -0,0 +1,128 @@
+/**
+* @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 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 each element in an array and assigns the result to an element in an output array.
+*
+* ## Notes
+*
+* -   The applied function is provided the following arguments:
+*
+*     -   **value**: array element.
+*     -   **index**: element index.
+*     -   **arr**: input array.
+*
+* @param {(ArrayLikeObject|ndarray)} arr - 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 a function
+* @throws {TypeError} input and output arrays must be either both array-like objects or both 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 abs = require( '@stdlib/math-base-special-abs' );
+*
+* var arr = [ -1, -2, -3, -4, -5, -6 ];
+* var out = [ 0, 0, 0, 0, 0, 0 ];
+*
+* map( arr, out, naryFunction( abs, 1 ) );
+*
+* console.log( out );
+* // => [ 1, 2, 3, 4, 5, 6 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+* var array = require( '@stdlib/ndarray-array' );
+*
+* var opts = {
+*     'dtype': 'generic',
+*     'shape': [ 2, 3 ]
+* };
+* var arr = array( [ [ -1, -2, -3 ], [ -4, -5, -6 ] ], opts );
+* var out = array( opts );
+*
+* map( arr, out, naryFunction( abs, 1 ) );
+*
+* var data = out.data;
+* // returns [ 1, 2, 3, 4, 5, 6 ]
+*/
+function map( arr, out, fcn, thisArg ) {
+	var tmp;
+	var sh;
+	if ( !isFunction( fcn ) ) {
+		throw new TypeError( 'invalid argument. Third argument must be a function. Value: `' + fcn + '`.' );
+	}
+	if ( isndarrayLike( arr ) ) { // note: assertion order matters here, as an ndarray-like object is also array-like
+		if ( !isndarrayLike( out ) ) {
+			throw new TypeError( 'invalid argument. If the input array is an ndarray, 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;
+
+		tmp = ndarraylike2object( broadcast( arr, sh ) );
+		tmp.ref = arr;
+		arr = tmp;
+
+		ndarrayFcn( arr, out, fcn, thisArg );
+		return out.ref;
+	}
+	if ( isArrayLikeObject( arr ) ) {
+		if ( !isArrayLikeObject( out ) || isndarrayLike( out ) ) {
+			throw new TypeError( 'invalid argument. If the input array is an array-like object, the output array must also be an array-like object. Value: `' + out + '`.' );
+		}
+		if ( arr.length !== out.length ) {
+			throw new RangeError( 'invalid arguments. Input and output arrays must have the same length.' );
+		}
+		arrayFcn( arraylike2object( arr ), 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: `' + arr + '`.' );
+}
+
+
+// EXPORTS //
+
+module.exports = map;

package/lib/index.js

@@ -0,0 +1,99 @@
+/**
+* @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';
+
+/**
+* Apply a function to each element in an array and assign the result to an element in an output array.
+*
+* @module @stdlib/utils-map
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+* var map = require( '@stdlib/utils-map' );
+*
+* var arr = [ -1, -2, -3, -4, -5, -6 ];
+*
+* var out = map( arr, naryFunction( abs, 1 ) );
+* // returns [ 1, 2, 3, 4, 5, 6 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+* var array = require( '@stdlib/ndarray-array' );
+* var map = require( '@stdlib/utils-map' );
+*
+* var opts = {
+*     'dtype': 'generic'
+* };
+* var arr = array( [ [ -1, -2, -3 ], [ -4, -5, -6 ] ], opts );
+*
+* var out = map( arr, naryFunction( abs, 1 ) );
+* // returns <ndarray>
+*
+* var data = out.data;
+* // returns [ 1, 2, 3, 4, 5, 6 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+* var map = require( '@stdlib/utils-map' );
+*
+* var arr = [ -1, -2, -3, -4, -5, -6 ];
+* var out = [ 0, 0, 0, 0, 0, 0 ];
+*
+* map.assign( arr, out, naryFunction( abs, 1 ) );
+*
+* console.log( out );
+* // => [ 1, 2, 3, 4, 5, 6 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+* var array = require( '@stdlib/ndarray-array' );
+* var map = require( '@stdlib/utils-map' );
+*
+* var opts = {
+*     'dtype': 'generic',
+*     'shape': [ 2, 3 ]
+* };
+* var arr = array( [ [ -1, -2, -3 ], [ -4, -5, -6 ] ], opts );
+* var out = array( opts );
+*
+* map.assign( arr, out, naryFunction( abs, 1 ) );
+*
+* var data = out.data;
+* // returns [ 1, 2, 3, 4, 5, 6 ]
+*/
+
+// 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,104 @@
+/**
+* @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 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 ndarrayFcn = require( './ndarray.js' );
+var arrayFcn = require( './array.js' );
+
+
+// MAIN //
+
+/**
+* Applies a function to each element in an array and assigns the result to an element in a new array.
+*
+* ## Notes
+*
+* -   The applied function is provided the following arguments:
+*
+*     -   **value**: array element.
+*     -   **index**: element index.
+*     -   **arr**: input array.
+*
+* @param {(ArrayLikeObject|ndarray)} arr - 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 a function
+* @returns {(Array|ndarray)} output array
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* var abs = require( '@stdlib/math-base-special-abs' );
+*
+* var arr = [ -1, -2, -3, -4, -5, -6 ];
+*
+* var out = map( arr, naryFunction( abs, 1 ) );
+* // returns [ 1, 2, 3, 4, 5, 6 ]
+*
+* @example
+* var naryFunction = require( '@stdlib/utils-nary-function' );
+* 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 = map( arr, naryFunction( abs, 1 ) );
+* // returns <ndarray>
+*
+* var data = out.data;
+* // returns [ 1, 2, 3, 4, 5, 6 ]
+*/
+function map( arr, fcn, thisArg ) {
+	var out;
+	if ( !isFunction( fcn ) ) {
+		throw new TypeError( 'invalid argument. Second argument must be a function. Value: `' + fcn + '`.' );
+	}
+	if ( isndarrayLike( arr ) ) { // note: assertion order matters here, as an ndarray-like object is also array-like
+		arr = ndarraylike2object( arr );
+		out = ndzeros( arr.shape, {
+			'dtype': 'generic',
+			'order': arr.order
+		});
+		ndarrayFcn( arr, ndarraylike2object( out ), fcn, thisArg );
+		return out;
+	}
+	if ( isArrayLikeObject( arr ) ) {
+		out = zeros( arr.length );
+		arrayFcn( arraylike2object( arr ), 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: `' + arr + '`.' );
+}
+
+
+// EXPORTS //
+
+module.exports = map;

package/lib/ndarray.js

@@ -0,0 +1,197 @@
+/**
+* @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 to each element in an ndarray and assigns the result to an element in an output ndarray.
+*
+* @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 {Object} y - object containing output ndarray meta data
+* @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.setter - callback for setting `y` 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' );
+*
+* function scale( z ) {
+*     return new Complex64( realf(z)*10.0, imagf(z)*10.0 );
+* }
+*
+* // 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( 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 ];
+*
+* // Define the index offsets:
+* var ox = 0;
+* var oy = 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': oy,
+*     'order': 'row-major',
+*     'setter': setter
+* };
+*
+* // Apply the unary function:
+* map( x, y, naryFunction( scale, 1 ) );
+*
+* var v = y.data.get( 0 );
+*
+* var re = realf( v );
+* // returns 10.0
+*
+* var im = imagf( v );
+* // returns 20.0
+*/
+function map( x, y, fcn, thisArg ) {
+	var xbuf;
+	var ybuf;
+	var ordx;
+	var ordy;
+	var len;
+	var get;
+	var set;
+	var ref;
+	var shx;
+	var shy;
+	var sx;
+	var sy;
+	var ox;
+	var oy;
+	var ix;
+	var iy;
+	var i;
+
+	// Cache the total number of elements over which to iterate:
+	len = x.length;
+
+	// Cache the input array shape:
+	shx = x.shape;
+	shy = y.shape;
+
+	// Cache references to the input and output ndarray data buffers:
+	xbuf = x.data;
+	ybuf = y.data;
+
+	// Cache references to the respective stride arrays:
+	sx = x.strides;
+	sy = y.strides;
+
+	// Cache the indices of the first indexed elements in the respective ndarrays:
+	ox = x.offset;
+	oy = y.offset;
+
+	// Cache the respective array orders:
+	ordx = x.order;
+	ordy = y.order;
+
+	// Cache accessors:
+	get = x.getter;
+	set = y.setter;
+
+	// Cache the reference to the original input array:
+	ref = x.ref;
+
+	// Check for a zero-dimensional array...
+	if ( shx.length === 0 ) {
+		set( ybuf, oy, fcn.call( thisArg, get( xbuf, ox ), 0, ref ) );
+		return;
+	}
+	// 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)...
+	for ( i = 0; i < len; i++ ) {
+		ix = vind2bind( shx, sx, ox, ordx, i, MODE );
+		iy = vind2bind( shy, sy, oy, ordy, i, MODE );
+		set( ybuf, iy, fcn.call( thisArg, get( xbuf, ix ), i, ref ) );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = map;

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@stdlib/utils-map",
+  "version": "0.0.1",
+  "description": "Apply a function to each element in an array and assign the result to an element in 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-map.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-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-float32": "^0.0.x",
+    "@stdlib/complex-imagf": "^0.0.x",
+    "@stdlib/complex-realf": "^0.0.x",
+    "@stdlib/math-base-special-abs": "^0.0.x",
+    "@stdlib/math-base-special-abs2": "^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"
+  ],
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/athan"
+  }
+}