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

Sorts an input ndarray along one or more ndarray dimensions using heapsort.

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

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

var y = sorthp( x );
// returns <ndarray>

var arr = ndarray2array( y );
// returns [ -3.0, -1.0, 2.0 ]

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

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.

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

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

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

var y = sorthp( x, -1.0 );
// returns <ndarray>

var arr = ndarray2array( y );
// returns [ 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 ndarray2array = require( '@stdlib/ndarray/to-array' );
var array = require( '@stdlib/ndarray/array' );

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

// Sort in ascending order:
var y = sorthp( x, 'asc' );
// returns <ndarray>

var arr = ndarray2array( y );
// returns [ -3.0, -1.0, 2.0 ]

// Sort in descending order:
y = sorthp( x, 'descending' );
// returns <ndarray>

arr = ndarray2array( y );
// returns [ 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 ndarray2array = require( '@stdlib/ndarray/to-array' );
var array = require( '@stdlib/ndarray/array' );

var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
    'shape': [ 2, 2 ],
    'order': 'row-major'
});

var v = ndarray2array( x );
// returns [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ]

var y = sorthp( x, {
    'dims': [ 0 ]
});
// returns <ndarray>

v = ndarray2array( y );
// returns [ [ -3.0, 2.0 ], [ -1.0, 4.0 ] ]

• The input ndarray is sorted in-place (i.e., the input ndarray is mutated).
• 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.