README.md

join

Return an ndarray created by joining elements using a specified separator along an ndarray dimension.

Usage

var join = require( '@stdlib/blas/ext/join' );

join( x, separator[, options] )

Returns an ndarray created by joining elements using a specified separator along an ndarray dimension.

var array = require( '@stdlib/ndarray/array' );

// Create an input ndarray:
var x = array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
// returns <ndarray>

// Perform operation:
var out = join( x, ',' );
// returns <ndarray>

var v = out.get();
// returns '1,2,3,4,5,6'

The function has the following parameters:

• x: input ndarray. Must have at least one dimension.
• separator: separator. May be either a scalar value or an ndarray with generic data type. If provided an ndarray, the value must have a shape which is broadcast-compatible with the non-reduced dimensions of the input ndarray. For example, given the input shape [2, 3, 4] and options.dim=0, the separator ndarray must have a shape which is broadcast-compatible with the shape [3, 4].
• options: function options (optional).

The function accepts the following options:

• dim: dimension over which to perform operation. If provided a negative integer, the dimension along which to perform the operation is determined by counting backward from the last dimension (where -1 refers to the last dimension). Default: -1.
• keepdims: boolean indicating whether the reduced dimensions should be included in the returned ndarray as singleton dimensions. Default: false.

By default, the function performs the operation over elements in the last dimension. To perform the operation over a different dimension, provide a dim option.

var ndarray2array = require( '@stdlib/ndarray/to-array' );
var array = require( '@stdlib/ndarray/array' );

var x = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ] );

var out = join( x, ',', {
    'dim': 0
});
// returns <ndarray>

var v = ndarray2array( out );
// returns [ '1,3', '2,4' ]

By default, the function excludes reduced dimensions from the output ndarray. To include the reduced dimensions as singleton dimensions, set the keepdims option to true.

var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );

var x = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ] );

var opts = {
    'dim': 0,
    'keepdims': true
};

var out = join( x, ',', opts );
// returns <ndarray>

var v = ndarray2array( out );
// returns [ [ '1,3', '2,4' ] ]

join.assign( x, separator, out[, options] )

Joins elements of an input ndarray using a specified separator along an ndarray dimension and assigns results to a provided output ndarray.

var array = require( '@stdlib/ndarray/array' );
var empty = require( '@stdlib/ndarray/empty' );

var x = array( [ 1.0, 2.0, 3.0, 4.0 ], {
    'dtype': 'generic'
});
var y = empty( [], {
    'dtype': 'generic'
});

var out = join.assign( x, ',', y );
// returns <ndarray>

var v = out.get();
// returns '1,2,3,4'

var bool = ( out === y );
// returns true

The method has the following parameters:

• x: input ndarray. Must have at least one dimension.
• separator: separator. May be either a scalar value or an ndarray with generic data type. If provided an ndarray, the value must have a shape which is broadcast-compatible with the non-reduced dimensions of the input ndarray. For example, given the input shape [2, 3, 4] and options.dim=0, the separator ndarray must have a shape which is broadcast-compatible with the shape [3, 4].
• out: output ndarray.
• options: function options (optional).

The method accepts the following options:

• dim: dimension over which to perform operation. If provided a negative integer, the dimension along which to perform the operation is determined by counting backward from the last dimension (where -1 refers to the last dimension). Default: -1.

Notes

• Setting the keepdims option to true can be useful when wanting to ensure that the output ndarray is broadcast-compatible with ndarrays having the same shape as the input ndarray.

Examples

var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var ndarray = require( '@stdlib/ndarray/ctor' );
var join = require( '@stdlib/blas/ext/join' );

// Generate an array of random numbers:
var xbuf = discreteUniform( 10, 0, 20, {
    'dtype': 'float64'
});

// Wrap in an ndarray:
var x = new ndarray( 'float64', xbuf, [ 5, 2 ], [ 2, 1 ], 0, 'row-major' );
console.log( ndarray2array( x ) );

// Perform operation:
var out = join( x, ',', {
    'dim': 0
});

// Print the results:
console.log( ndarray2array( out ) );