map

Apply a function to each element in an array and assign the result to an element in an output array.

Usage

var map = require( '@stdlib/utils/map' );

map( arr, fcn[, thisArg] )

Applies a function to each element in an array and assigns the result to an element in a new array.

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 ]

The function accepts both array-like objects and ndarray-like objects.

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 v = out.get( 1, 1 );
// returns 5

The applied function is provided the following arguments:

  • value: array element.
  • index: element index.
  • arr: input array.

To set the this context when invoking the input function, provide a thisArg.

var abs = require( '@stdlib/math/base/special/abs' );

function fcn( v ) {
    this.count += 1;
    return abs( v );
}

var arr = [ -1, -2, -3, -4, -5, -6 ];

var ctx = {
    'count': 0
};

var out = map( arr, fcn, ctx );
// returns [ 1, 2, 3, 4, 5, 6 ]

var cnt = ctx.count;
// returns 6

map.assign( arr, out, fcn[, thisArg] )

Applies a function to each element in an array and assigns the result to an element in an output array.

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 ]

The method accepts both array-like objects and ndarray-like objects.

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 v = out.get( 1, 1 );
// returns 5

Input and output arrays must be either both array-like objects or both ndarray-like objects. If input and output arrays are both array-like objects, both arrays must have the same number of elements.

If input and output arrays are both ndarray-like objects, the arrays must be broadcast compatible. To map from an input ndarray to an output ndarray which has the same rank (i.e., dimensionality) and the same number of elements, but which is not broadcast compatible, reshape the arrays prior to invocation.

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 );

opts = {
    'dtype': 'generic',
    'shape': [ 2, 2, 3 ]  // broadcast compatible shape
};
var out = array( opts );

map.assign( arr, out, naryFunction( abs, 1 ) );

var v = out.get( 0, 1, 1 );
// returns 5

v = out.get( 1, 1, 1 );
// returns 5

In general, avoid providing output ndarray-like objects which are non-contiguous views containing one or more elements referring to the same memory location. Writing to an overlapping non-contiguous view is likely to simultaneously affect multiple elements and yield unexpected results.

The applied function is provided the same arguments as with map.

Notes

  • The map function always returns an output value having a "generic" data type. For example, if provided an array-like object, the function returns a generic array. If provided an ndarray, the function returns an ndarray having a "generic" data type.

    Accordingly, in contrast to TypedArray.prototype.map(), when provided a typed array, the map function does not return a typed array of the same type. To assign results to a typed array, use the map.assign method.

  • Both map and map.assign accept array-like objects exposing getters and setters for array element access (e.g., Complex64Array, Complex128Array, etc).

    var Complex64Array = require( '@stdlib/array/complex64' );
var Complex64 = require( '@stdlib/complex/float32/ctor' );
var realf = require( '@stdlib/complex/float32/real' );
var imagf = require( '@stdlib/complex/float32/imag' );

function scale( z ) {
    return new Complex64( realf(z)*10.0, imagf(z)*10.0 );
}

var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
var y = new Complex64Array( 4 );

map.assign( x, y, scale );

var v = y.get( 0 );

var re = realf( v );
// returns 10.0

var im = imagf( v );
// returns 20.0

  • When applying a function to ndarray-like objects, performance will be best for ndarray-like objects which are single-segment contiguous. For non-contiguous arrays, see @stdlib/ndarray/base/unary.

  • Both map and map.assign do not skip undefined elements.

Examples

var filledarrayBy = require( '@stdlib/array/filled-by' );
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
var naryFunction = require( '@stdlib/utils/nary-function' );
var abs2 = require( '@stdlib/math/base/special/abs2' );
var array = require( '@stdlib/ndarray/array' );
var map = require( '@stdlib/utils/map' );

function fill( i ) {
    var rand = discreteUniform( -10*(i+1), 10*(i+1) );
    return filledarrayBy( 10, 'generic', rand );
}

// Create a two-dimensional ndarray (i.e., a matrix):
var x = array( filledarrayBy( 10, 'generic', fill ), {
    'dtype': 'generic',
    'flatten': true
});

// Create an explicit unary function:
var f = naryFunction( abs2, 1 );

// Compute the element-wise squared absolute value...
var y = map( x, f );

console.log( 'x:' );
console.log( x.data );

console.log( 'y:' );
console.log( y.data );

See Also

  • @stdlib/utils/map-right: apply a function to each element in an array and assign the result to an element in an output array, iterating from right to left.
  • @stdlib/utils/reduce: apply a function against an accumulator and each element in an array and return the accumulated result.
Did you find this page helpful?