var toSortedhp = require( '@stdlib/blas/ext/to-sortedhp' );

Returns a new ndarray containing the elements of an input ndarray sorted along one or more ndarray dimensions using heapsort.

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

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

var y = toSortedhp( x );
// returns <ndarray>[ -3.0, -1.0, 2.0 ]

The function has the following parameters:

• x: input ndarray. Must have a real-valued or "generic" data type.
• sortOrder: sort order (optional). May be either a scalar value, string, or an ndarray having a real-valued or "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 sort order 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 sort order must be a zero-dimensional ndarray. By default, the sort order is 1 (i.e., increasing order).
• options: function options (optional).

The function accepts the following options:

• 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.
• dtype: output ndarray data type.

By default, the function sorts elements in increasing order. To sort in a different order, provide a sortOrder argument.

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

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

var y = toSortedhp( x, -1.0 );
// returns <ndarray>[ 2.0, -1.0, -3.0 ]

In addition to numeric values, one can specify the sort order via one of the following string literals: 'ascending', 'asc', 'descending', or 'desc'. The first two literals indicate to sort in ascending (i.e., increasing) order. The last two literals indicate to sort in descending (i.e., decreasing) order.

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

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

// Sort in ascending order:
var y = toSortedhp( x, 'asc' );
// returns <ndarray>[ -3.0, -1.0, 2.0 ]

// Sort in descending order:
y = toSortedhp( x, 'descending' );
// returns <ndarray>[ 2.0, -1.0, -3.0 ]

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 ], {
    'shape': [ 2, 2 ],
    'order': 'row-major'
});

var y = toSortedhp( x, {
    'dims': [ 0 ]
});
// returns <ndarray>[ [ -3.0, 2.0 ], [ -1.0, 4.0 ] ]

To specify the output ndarray data type, provide a dtype option.

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

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

var y = toSortedhp( x, {
    'dtype': 'float32'
});
// returns <ndarray>[ -3.0, -1.0, 2.0 ]

Sorts the elements of an input ndarray along one or more ndarray dimensions using heapsort and assigns the results to an output ndarray.

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

var x = array( [ -1.0, 2.0, -3.0 ] );
var y = zeros( [ 3 ] );

var out = toSortedhp.assign( x, y );
// returns <ndarray>[ -3.0, -1.0, 2.0 ]

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

The function has the following parameters:

• x: input ndarray. Must have a real-valued or "generic" data type.
• out: output ndarray. Must have a real-valued or "generic" data type.
• sortOrder: sort order (optional). May be either a scalar value, string, or an ndarray having a real-valued or "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 sort order 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 sort order must be a zero-dimensional ndarray. By default, the sort order is 1 (i.e., increasing order).
• options: function options (optional).

The function accepts the following options:

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

• If sortOrder < 0.0 or is either 'desc' or 'descending', the input ndarray is sorted in decreasing order. If sortOrder > 0.0 or is either 'asc' or 'ascending', the input ndarray is sorted in increasing order. If sortOrder == 0.0, the input ndarray is left unchanged.
• The algorithm distinguishes between -0 and +0. When sorted in increasing order, -0 is sorted before +0. When sorted in decreasing order, -0 is sorted after +0.
• The algorithm sorts NaN values to the end. When sorted in increasing order, NaN values are sorted last. When sorted in decreasing order, NaN values are sorted first.
• The algorithm has space complexity O(1) and time complexity O(N log2 N).
• The algorithm is unstable, meaning that the algorithm may change the order of ndarray elements which are equal or equivalent (e.g., NaN values).
• The function iterates over ndarray elements according to the memory layout of the input ndarray. Accordingly, performance degradation is possible when operating over multiple dimensions of a large non-contiguous multi-dimensional input ndarray. In such scenarios, one may want to copy an input ndarray to contiguous memory before sorting.