README.md

joinBetween

Return an ndarray created by joining elements using specified separators for each pair of consecutive elements along one or more ndarray dimensions.

Usage

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

joinBetween( x, separators[, options] )

Returns an ndarray created by joining elements using specified separators for each pair of consecutive elements along one or more ndarray dimensions.

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

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

// Create a separators ndarray:
var sep = scalar2ndarray( ',', {
    'dtype': 'generic'
});

// Perform operation:
var out = joinBetween( x, sep );
// returns <ndarray>[ '1,2,3,4,5,6' ]

The function has the following parameters:

• x: input ndarray.
• separators: separators ndarray. Must be broadcast-compatible with the shape consisting of the complement of the shape defined by options.dims followed by N-1 where N is the number of elements along the reduced dimensions.
• options: function options (optional).

The function accepts the following options:

• prefix: prefix to prepend to each joined string. May be a scalar value or an ndarray which is broadcast-compatible with the complement of the shape defined by options.dims. Default: ''.
• suffix: suffix to append to each joined string. May be a scalar value or an ndarray which is broadcast-compatible with the complement of the shape defined by options.dims. 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.

To specify a prefix and suffix to prepend and append to each joined string, provide prefix and suffix options.

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

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

var sep = scalar2ndarray( ', ', {
    'dtype': 'generic'
});

var out = joinBetween( x, sep, {
    'prefix': '[ ',
    'suffix': ' ]'
});
// 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 scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );

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

var sep = scalar2ndarray( ',', {
    'dtype': 'generic'
});

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

out = joinBetween( x, sep, {
    'dims': [ 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 scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );

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

var sep = scalar2ndarray( ',', {
    'dtype': 'generic'
});

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

joinBetween.assign( x, separators, out[, options] )

Joins elements of an input ndarray using specified separators for each pair of consecutive elements 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 sep = scalar2ndarray( ',', {
    'dtype': 'generic'
});
var y = scalar2ndarray( '', {
    'dtype': 'generic'
});

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

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

The method has the following parameters:

• x: input ndarray.
• separators: separators ndarray. Must be broadcast-compatible with the shape consisting of the complement of the shape defined by options.dims followed by N-1 where N is the number of elements along the reduced dimensions.
• out: output ndarray.
• options: function options (optional).

The method accepts the following options:

• prefix: prefix to prepend to each joined string. May be a scalar value or an ndarray which is broadcast-compatible with the complement of the shape defined by options.dims. Default: ''.
• suffix: suffix to append to each joined string. May be a scalar value or an ndarray which is broadcast-compatible with the complement of the shape defined by options.dims. 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.

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 scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
var uniform = require( '@stdlib/random/uniform' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var joinBetween = require( '@stdlib/blas/ext/join-between' );

var x = uniform( [ 5, 2 ], 0.0, 20.0 );
console.log( ndarray2array( x ) );

var sep = scalar2ndarray( ', ', {
    'dtype': 'generic'
});

var out = joinBetween( x, sep, {
    'dims': [ -1 ],
    'prefix': '[ ',
    'suffix': ' ]'
});
console.log( ndarray2array( out ) );