map

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.

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

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' );
  var realf = require( '@stdlib/complex/realf' );
  var imagf = require( '@stdlib/complex/imagf' );
  
  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 );