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

Returns an ndarray created by joining elements using a separator along one or more ndarray dimensions.

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>[ '1,2,3,4,5,6' ]

The function has the following parameters:

• x: input ndarray.
• options: function options (optional).

The function accepts the following options:

• sep: separator. May be either a scalar value or an ndarray having a "generic" data type. If provided an ndarray, the value must have a shape which is broadcast-compatible with the complement of the shape defined by options.dims. For example, given the input shape [2, 3, 4] and options.dims=[0], an ndarray separator value must have a shape which is broadcast-compatible with the shape [3, 4]. Similarly, when performing the operation over all elements in a provided input ndarray, an ndarray separator value must be a zero-dimensional ndarray. Default: ,.
• dims: list of dimensions over which to perform operation. If not provided, the function performs the operation over all elements in a provided input ndarray.
• keepdims: boolean indicating whether the reduced dimensions should be included in the returned ndarray as singleton dimensions. Default: false.

By default, the function joins ndarray elements by using , as a separator. To perform the operation with a different separator, provide a sep option.

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

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

var out = join( x, {
    'sep': '|'
});
// returns <ndarray>[ '1|2|3|4|5|6' ]

By default, the function performs the operation over all elements in a provided input ndarray. To perform the operation over specific dimensions, provide a dims option.

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

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

var out = join( x, {
    'dims': [ 0 ]
});
// returns <ndarray>[ '1,3', '2,4' ]

out = join( x, {
    'dims': [ 1 ]
});
// returns <ndarray>[ '1,2', '3,4' ]

out = join( x, {
    'dims': [ 0, 1 ]
});
// returns <ndarray>[ '1,2,3,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 x = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ] );

var opts = {
    'dims': [ 0 ],
    'keepdims': true
};

var out = join( x, opts );
// returns <ndarray>[ [ '1,3', '2,4' ] ]

Joins elements of an input ndarray using a separator along one or more ndarray dimensions and assigns results to a provided output ndarray.

var array = require( '@stdlib/ndarray/array' );
var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );

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

var out = join.assign( x, y );
// returns <ndarray>[ '1,2,3,4' ]

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

The method has the following parameters:

• x: input ndarray.
• out: output ndarray.
• options: function options (optional).

The method accepts the following options:

• sep: separator. May be either a scalar value or an ndarray having a "generic" data type. If provided an ndarray, the value must have a shape which is broadcast-compatible with the complement of the shape defined by options.dims. For example, given the input shape [2, 3, 4] and options.dims=[0], an ndarray separator value must have a shape which is broadcast-compatible with the shape [3, 4]. Similarly, when performing the operation over all elements in a provided input ndarray, an ndarray separator value must be a zero-dimensional ndarray. Default: ,.
• dims: list of dimensions over which to perform operation. If not provided, the function performs the operation over all elements in a provided input ndarray.

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