@stdlib/utils-map 0.0.1

package/docs/types/index.d.ts

@@ -0,0 +1,300 @@
+/*
+* @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.
+*/
+
+// TypeScript Version: 2.0
+
+/// <reference types="@stdlib/types"/>
+
+import { Collection } from '@stdlib/types/object';
+import { ndarray } from '@stdlib/types/ndarray';
+
+/**
+* Callback invoked for each array element.
+*
+* @returns result
+*/
+type Nullary = () => any;
+
+/**
+* Callback invoked for each array element.
+*
+* @param value - array element
+* @returns result
+*/
+type Unary = ( value: any ) => any;
+
+/**
+* Callback invoked for each array element.
+*
+* @param value - array element
+* @param index - element index
+* @returns result
+*/
+type Binary = ( value: any, index: number ) => any;
+
+/**
+* Callback invoked for each array element.
+*
+* @param value - array element
+* @param index - element index
+* @param arr - array
+* @returns result
+*/
+type Ternary = ( value: any, index: number, arr: ndarray ) => any;
+
+/**
+* Callback invoked for each array element.
+*
+* @param value - array element
+* @param index - element index
+* @param arr - array
+* @returns result
+*/
+type ArrayTernary = ( value: any, index: number, arr: Collection ) => any;
+
+/**
+* Callback invoked for each array element.
+*
+* @param value - array element
+* @param index - element index
+* @param arr - array
+* @returns result
+*/
+type Callback = Nullary | Unary | Binary | Ternary;
+
+/**
+* Callback invoked for each array element.
+*
+* @param value - array element
+* @param index - element index
+* @param arr - array
+* @returns result
+*/
+type ArrayCallback = Nullary | Unary | Binary | ArrayTernary;
+
+/**
+* Interface describing the main export.
+*/
+interface Routine {
+	// NOTE: signature order matters here, as an ndarray is an array-like object...
+
+	/**
+	* 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 arr - input array
+	* @param fcn - function to apply
+	* @param thisArg - input function context
+	* @returns output array
+	*
+	* @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 ]
+	*/
+	( arr: ndarray, fcn: Callback, thisArg?: any ): ndarray;
+
+	/**
+	* 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 arr - input array
+	* @param fcn - function to apply
+	* @param thisArg - input function context
+	* @returns 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 ]
+	*/
+	( arr: Collection, fcn: ArrayCallback, thisArg?: any ): Collection;
+
+	/**
+	* 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 arr - input array
+	* @param out - output array
+	* @param fcn - function to apply
+	* @param thisArg - input function context
+	* @returns output array
+	*
+	* @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.assign( arr, out, naryFunction( abs, 1 ) );
+	*
+	* var data = out.data;
+	* // returns [ 1, 2, 3, 4, 5, 6 ]
+	*/
+	assign( arr: ndarray, out: ndarray, fcn: Callback, thisArg?: any ): ndarray;
+
+	/**
+	* 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 arr - input array
+	* @param out - output array
+	* @param fcn - function to apply
+	* @param thisArg - input function context
+	* @returns 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.assign( arr, out, naryFunction( abs, 1 ) );
+	*
+	* console.log( out );
+	* // => [ 1, 2, 3, 4, 5, 6 ]
+	*/
+	assign( arr: Collection, out: Collection, fcn: ArrayCallback, thisArg?: any ): Collection; // tslint:disable-line:max-line-length
+}
+
+/**
+* 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 arr - input array
+* @param fcn - function to apply
+* @param thisArg - input function context
+* @returns 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 ]
+*
+* @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.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 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 ]
+*/
+declare var map: Routine;
+
+
+// EXPORTS //
+
+export = map;

package/docs/types/test.ts

@@ -0,0 +1,270 @@
+/*
+* @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.
+*/
+
+import array = require( '@stdlib/ndarray-array' );
+import map = require( './index' );
+
+/**
+* Callback function.
+*
+* @param v - argument
+* @returns result
+*/
+function clbk( v: any ): any {
+	return v;
+}
+
+
+// TESTS //
+
+// The function returns a collection when provided a collection...
+{
+	const arr = [ 1, 2, 3, 4, 5, 6 ];
+
+	map( arr, clbk ); // $ExpectType Collection
+	map( arr, clbk, {} ); // $ExpectType Collection
+}
+
+// The function returns an ndarray when provided an ndarray...
+{
+	const arr = array( [ 1, 2, 3, 4, 5, 6 ] );
+
+	map( arr, clbk ); // $ExpectType ndarray
+	map( arr, clbk, {} ); // $ExpectType ndarray
+}
+
+// The compiler throws an error if the function is provided a first argument other than a collection or ndarray...
+{
+	map( 5, clbk ); // $ExpectError
+	map( true, clbk ); // $ExpectError
+	map( false, clbk ); // $ExpectError
+	map( null, clbk, {} ); // $ExpectError
+	map( {}, clbk ); // $ExpectError
+
+	map( 5, clbk, {} ); // $ExpectError
+	map( true, clbk, {} ); // $ExpectError
+	map( false, clbk, {} ); // $ExpectError
+	map( null, clbk, {} ); // $ExpectError
+	map( {}, clbk, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a second argument other than a function with a supported signature...
+{
+	const arr1 = [ 1, 2, 3, 4, 5, 6 ];
+
+	map( arr1, '5' ); // $ExpectError
+	map( arr1, true ); // $ExpectError
+	map( arr1, false ); // $ExpectError
+	map( arr1, 123 ); // $ExpectError
+	map( arr1, null ); // $ExpectError
+	map( arr1, {} ); // $ExpectError
+	map( arr1, [] ); // $ExpectError
+
+	map( arr1, '5', {} ); // $ExpectError
+	map( arr1, true, {} ); // $ExpectError
+	map( arr1, false, {} ); // $ExpectError
+	map( arr1, 123, {} ); // $ExpectError
+	map( arr1, null, {} ); // $ExpectError
+	map( arr1, {}, {} ); // $ExpectError
+	map( arr1, [], {} ); // $ExpectError
+
+	map( arr1, ( x: number, y: number, z: number ): number => x + y + z ); // $ExpectError
+	map( arr1, ( x: number, y: number, z: number ): number => x + y + z, {} ); // $ExpectError
+
+	const arr2 = array( [ 1, 2, 3, 4, 5, 6 ] );
+
+	map( arr2, '5' ); // $ExpectError
+	map( arr2, true ); // $ExpectError
+	map( arr2, false ); // $ExpectError
+	map( arr2, 123 ); // $ExpectError
+	map( arr2, null ); // $ExpectError
+	map( arr2, {} ); // $ExpectError
+	map( arr2, [] ); // $ExpectError
+
+	map( arr2, '5', {} ); // $ExpectError
+	map( arr2, true, {} ); // $ExpectError
+	map( arr2, false, {} ); // $ExpectError
+	map( arr2, 123, {} ); // $ExpectError
+	map( arr2, null, {} ); // $ExpectError
+	map( arr2, {}, {} ); // $ExpectError
+	map( arr2, [], {} ); // $ExpectError
+
+	map( arr2, ( x: number, y: number, z: number ): number => x + y + z ); // $ExpectError
+	map( arr2, ( x: number, y: number, z: number ): number => x + y + z, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an unsupported number of arguments...
+{
+	const arr1 = [ 1, 2, 3, 4, 5, 6 ];
+
+	map(); // $ExpectError
+	map( arr1 ); // $ExpectError
+	map( arr1, clbk, {}, 4 ); // $ExpectError
+
+	const arr2 = array( [ 1, 2, 3, 4, 5, 6 ] );
+
+	map(); // $ExpectError
+	map( arr2 ); // $ExpectError
+	map( arr2, clbk, {}, 4 ); // $ExpectError
+}
+
+// Attached to the main export is an `assign` method which returns a collection when provided a collection...
+{
+	const arr = [ 1, 2, 3, 4, 5, 6 ];
+	const out = [ 0, 0, 0, 0, 0, 0 ];
+
+	map.assign( arr, out, clbk ); // $ExpectType Collection
+	map.assign( arr, out, clbk, {} ); // $ExpectType Collection
+}
+
+// The `assign` method returns an ndarray when provided an ndarray...
+{
+	const arr = array( [ 1, 2, 3, 4, 5, 6 ] );
+	const out = array( [ 0, 0, 0, 0, 0, 0 ] );
+
+	map.assign( arr, out, clbk ); // $ExpectType ndarray
+	map.assign( arr, out, clbk, {} ); // $ExpectType ndarray
+}
+
+// The compiler throws an error if the `assign` method is provided a first argument other than a collection or ndarray...
+{
+	const out1 = [ 0, 0, 0, 0, 0, 0 ];
+
+	map.assign( 5, out1, clbk ); // $ExpectError
+	map.assign( true, out1, clbk ); // $ExpectError
+	map.assign( false, out1, clbk ); // $ExpectError
+	map.assign( null, out1, clbk, {} ); // $ExpectError
+	map.assign( {}, out1, clbk ); // $ExpectError
+
+	map.assign( 5, out1, clbk, {} ); // $ExpectError
+	map.assign( true, out1, clbk, {} ); // $ExpectError
+	map.assign( false, out1, clbk, {} ); // $ExpectError
+	map.assign( null, out1, clbk, {} ); // $ExpectError
+	map.assign( {}, out1, clbk, {} ); // $ExpectError
+
+	const out2 = array( [ 0, 0, 0, 0, 0, 0 ] );
+
+	map.assign( 5, out2, clbk ); // $ExpectError
+	map.assign( true, out2, clbk ); // $ExpectError
+	map.assign( false, out2, clbk ); // $ExpectError
+	map.assign( null, out2, clbk, {} ); // $ExpectError
+	map.assign( {}, out2, clbk ); // $ExpectError
+
+	map.assign( 5, out2, clbk, {} ); // $ExpectError
+	map.assign( true, out2, clbk, {} ); // $ExpectError
+	map.assign( false, out2, clbk, {} ); // $ExpectError
+	map.assign( null, out2, clbk, {} ); // $ExpectError
+	map.assign( {}, out2, clbk, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided a second argument other than a collection or ndarray...
+{
+	const arr1 = [ 0, 0, 0, 0, 0, 0 ];
+
+	map.assign( arr1, 5, clbk ); // $ExpectError
+	map.assign( arr1, true, clbk ); // $ExpectError
+	map.assign( arr1, false, clbk ); // $ExpectError
+	map.assign( arr1, null, clbk, {} ); // $ExpectError
+	map.assign( arr1, {}, clbk ); // $ExpectError
+
+	map.assign( arr1, 5, clbk, {} ); // $ExpectError
+	map.assign( arr1, true, clbk, {} ); // $ExpectError
+	map.assign( arr1, false, clbk, {} ); // $ExpectError
+	map.assign( arr1, null, clbk, {} ); // $ExpectError
+	map.assign( arr1, {}, clbk, {} ); // $ExpectError
+
+	const arr2 = array( [ 0, 0, 0, 0, 0, 0 ] );
+
+	map.assign( arr2, 5, clbk ); // $ExpectError
+	map.assign( arr2, true, clbk ); // $ExpectError
+	map.assign( arr2, false, clbk ); // $ExpectError
+	map.assign( arr2, null, clbk, {} ); // $ExpectError
+	map.assign( arr2, {}, clbk ); // $ExpectError
+
+	map.assign( arr2, 5, clbk, {} ); // $ExpectError
+	map.assign( arr2, true, clbk, {} ); // $ExpectError
+	map.assign( arr2, false, clbk, {} ); // $ExpectError
+	map.assign( arr2, null, clbk, {} ); // $ExpectError
+	map.assign( arr2, {}, clbk, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided a third argument other than a function with a supported signature...
+{
+	const arr1 = [ 1, 2, 3, 4, 5, 6 ];
+	const out1 = [ 0, 0, 0, 0, 0, 0 ];
+
+	map.assign( arr1, out1, '5' ); // $ExpectError
+	map.assign( arr1, out1, true ); // $ExpectError
+	map.assign( arr1, out1, false ); // $ExpectError
+	map.assign( arr1, out1, 123 ); // $ExpectError
+	map.assign( arr1, out1, null ); // $ExpectError
+	map.assign( arr1, out1, {} ); // $ExpectError
+	map.assign( arr1, out1, [] ); // $ExpectError
+
+	map.assign( arr1, out1, '5', {} ); // $ExpectError
+	map.assign( arr1, out1, true, {} ); // $ExpectError
+	map.assign( arr1, out1, false, {} ); // $ExpectError
+	map.assign( arr1, out1, 123, {} ); // $ExpectError
+	map.assign( arr1, out1, null, {} ); // $ExpectError
+	map.assign( arr1, out1, {}, {} ); // $ExpectError
+	map.assign( arr1, out1, [], {} ); // $ExpectError
+
+	map.assign( arr1, out1, ( x: number, y: number, z: number ): number => x + y + z ); // $ExpectError
+	map.assign( arr1, out1, ( x: number, y: number, z: number ): number => x + y + z, {} ); // $ExpectError
+
+	const arr2 = array( [ 1, 2, 3, 4, 5, 6 ] );
+	const out2 = array( [ 0, 0, 0, 0, 0, 0 ] );
+
+	map.assign( arr2, out2, '5' ); // $ExpectError
+	map.assign( arr2, out2, true ); // $ExpectError
+	map.assign( arr2, out2, false ); // $ExpectError
+	map.assign( arr2, out2, 123 ); // $ExpectError
+	map.assign( arr2, out2, null ); // $ExpectError
+	map.assign( arr2, out2, {} ); // $ExpectError
+	map.assign( arr2, out2, [] ); // $ExpectError
+
+	map.assign( arr2, out2, '5', {} ); // $ExpectError
+	map.assign( arr2, out2, true, {} ); // $ExpectError
+	map.assign( arr2, out2, false, {} ); // $ExpectError
+	map.assign( arr2, out2, 123, {} ); // $ExpectError
+	map.assign( arr2, out2, null, {} ); // $ExpectError
+	map.assign( arr2, out2, {}, {} ); // $ExpectError
+	map.assign( arr2, out2, [], {} ); // $ExpectError
+
+	map.assign( arr2, out2, ( x: number, y: number, z: number ): number => x + y + z ); // $ExpectError
+	map.assign( arr2, out2, ( x: number, y: number, z: number ): number => x + y + z, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided an unsupported number of arguments...
+{
+	const arr1 = [ 1, 2, 3, 4, 5, 6 ];
+	const out1 = [ 0, 0, 0, 0, 0, 0 ];
+
+	map.assign(); // $ExpectError
+	map.assign( arr1 ); // $ExpectError
+	map.assign( arr1, out1 ); // $ExpectError
+	map.assign( arr1, out1, clbk, {}, 4 ); // $ExpectError
+
+	const arr2 = array( [ 1, 2, 3, 4, 5, 6 ] );
+	const out2 = array( [ 0, 0, 0, 0, 0, 0 ] );
+
+	map.assign(); // $ExpectError
+	map.assign( arr2 ); // $ExpectError
+	map.assign( arr2, out2 ); // $ExpectError
+	map.assign( arr2, out2, clbk, {}, 4 ); // $ExpectError
+}

package/lib/array.js

@@ -0,0 +1,89 @@
+/**
+* @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 to each element in an array and assigns the result to an element in an output array.
+*
+* @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 {Object} y - object containing output array data
+* @param {ArrayLikeObject} y.data - output array data
+* @param {Function} y.setter - callback for setting output 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 abs = require( '@stdlib/math-base-special-abs' );
+*
+* // 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': [ 0, 0, 0, 0, 0, 0 ],
+*     'setter': setter
+* };
+*
+* map( x, y, naryFunction( abs, 1 ) );
+*
+* var data = y.data;
+* // returns [ 1, 2, 3, 4, 5, 6 ]
+*/
+function map( x, y, fcn, thisArg ) {
+	var xbuf;
+	var ybuf;
+	var get;
+	var set;
+	var i;
+
+	// Cache references to the input and output data:
+	xbuf = x.data;
+	ybuf = y.data;
+
+	// Cache accessors:
+	get = x.getter;
+	set = y.setter;
+
+	// Iterate over each element...
+	for ( i = 0; i < xbuf.length; i++ ) {
+		set( ybuf, i, fcn.call( thisArg, get( xbuf, i ), i, xbuf ) );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = map;