map2Right

Apply a function to elements in two input arrays while iterating from right to left and assign the results to an output array.

Usage

var map2Right = require( '@stdlib/utils/map2-right' );

map2Right( x, y, fcn[, thisArg] )

Applies a function to elements in two input arrays while iterating from right to left and assigns the results to a new array.

var naryFunction = require( '@stdlib/utils/nary-function' );
var add = require( '@stdlib/math/base/ops/add' );

var x = [ 1, 2, 3, 4, 5, 6 ];
var y = [ 1, 1, 1, 1, 1, 1 ];

var out = map2Right( x, y, naryFunction( add, 2 ) );
// returns [ 2, 3, 4, 5, 6, 7 ]

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

var naryFunction = require( '@stdlib/utils/nary-function' );
var add = require( '@stdlib/math/base/ops/add' );
var array = require( '@stdlib/ndarray/array' );

var opts = {
    'dtype': 'generic'
};
var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
var y = array( [ [ 1, 1, 1 ], [ 1, 1, 1 ] ], opts );

var out = map2Right( x, y, naryFunction( add, 2 ) );
// returns <ndarray>

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

The applied function is provided the following arguments:

v1: element from first input array.
v2: element from second input array.
idx: element index.
arrays: input arrays.

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

var add = require( '@stdlib/math/base/ops/add' );

function fcn( v1, v2 ) {
    this.count += 1;
    return add( v1, v2 );
}

var x = [ 1, 2, 3, 4, 5, 6 ];
var y = [ 1, 1, 1, 1, 1, 1 ];

var ctx = {
    'count': 0
};

var out = map2Right( x, y, fcn, ctx );
// returns [ 2, 3, 4, 5, 6, 7 ]

var cnt = ctx.count;
// returns 6

map2Right.assign( x, y, out, fcn[, thisArg] )

Applies a function to elements in two input arrays while iterating from right to left and assigns the results to an output array out.

var naryFunction = require( '@stdlib/utils/nary-function' );
var add = require( '@stdlib/math/base/ops/add' );

var x = [ 1, 2, 3, 4, 5, 6 ];
var y = [ 1, 1, 1, 1, 1, 1 ];
var out = [ 0, 0, 0, 0, 0, 0 ];

map2Right.assign( x, y, out, naryFunction( add, 2 ) );

console.log( out );
// => [ 2, 3, 4, 5, 6, 7 ]

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

var naryFunction = require( '@stdlib/utils/nary-function' );
var add = require( '@stdlib/math/base/ops/add' );
var array = require( '@stdlib/ndarray/array' );

var opts = {
    'dtype': 'generic',
    'shape': [ 2, 3 ]
};
var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
var y = array( [ [ 1, 1, 1 ], [ 1, 1, 1 ] ], opts );
var out = array( opts );

map2Right.assign( x, y, out, naryFunction( add, 2 ) );

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

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

If input and output arrays are ndarray-like objects, the arrays must be broadcast compatible. To map from one or more input ndarrays 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 add = require( '@stdlib/math/base/ops/add' );
var array = require( '@stdlib/ndarray/array' );

var opts = {
    'dtype': 'generic',
    'shape': [ 2, 3 ]
};
var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );
var y = array( [ [ 1, 1, 1 ], [ 1, 1, 1 ] ], opts );

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

map2Right.assign( x, y, out, naryFunction( add, 2 ) );

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

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

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 map2Right.

Notes

The map2Right function always returns an output value having a "generic" data type. For example, if provided array-like objects, the function returns a generic array. If provided ndarrays, the function returns an ndarray having a "generic" data type.
Accordingly, when provided a typed array, the map2Right function does not return a typed array of the same type. To assign results to a typed array, use the map2Right.assign method.

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

var naryFunction = require( '@stdlib/utils/nary-function' );
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' );
var add = require( '@stdlib/complex/float32/base/add' );

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

map2Right.assign( x, y, z, naryFunction( add, 2 ) );

var v = z.get( 0 );

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

var im = imagf( v );
// returns 3.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/binary.
Both map2Right and map2Right.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 add = require( '@stdlib/math/base/ops/add' );
var array = require( '@stdlib/ndarray/array' );
var map2Right = require( '@stdlib/utils/map2-right' );

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

// Create two-dimensional ndarrays (i.e., matrices):
var opts = {
    'dtype': 'generic',
    'flatten': true
};
var x = array( filledarrayBy( 10, opts.dtype, fill ), opts );
var y = array( filledarrayBy( 10, opts.dtype, fill ), opts );

// Create an explicit binary function:
var f = naryFunction( add, 2 );

// Compute element-wise sums...
var z = map2Right( x, y, f );

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

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

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