feat: add blas/ext/base/ndarray/dsort2hp

Author: MeKaustubh07

lib/node_modules/@stdlib/blas/ext/base/ndarray/dsort2hp/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # dsort2hp
 
-> Simultaneously sort two double-precision floating-point ndarray based on the sort order of the first array using heapsort.
+> Simultaneously sort two one-dimensional double-precision floating-point ndarrays based on the sort order of the first array using heapsort.
 
 <section class="intro">
 
@@ -38,7 +38,7 @@ var dsort2hp = require( '@stdlib/blas/ext/base/ndarray/dsort2hp' );
 
 #### dsort2hp( arrays )
 
-Simultaneously sort two double-precision floating-point ndarray based on the sort order of the first array using heapsort.
+Simultaneously sorts two one-dimensional double-precision floating-point ndarrays based on the sort order of the first array using heapsort.
 
 ```javascript
 var Float64Array = require( '@stdlib/array/float64' );
@@ -49,20 +49,26 @@ var ndarray = require( '@stdlib/ndarray/base/ctor' );
 var xbuf = new Float64Array( [ 1.0, -2.0, 3.0, -4.0 ] );
 var x = new ndarray( 'float64', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
 
+var ybuf = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );
+var y = new ndarray( 'float64', ybuf, [ 4 ], [ 1 ], 0, 'row-major' );
+
 var order = scalar2ndarray( 1.0, {
     'dtype': 'generic'
 });
 
-var out = dsort2hp( [ x, order ] );
+var out = dsort2hp( [ x, y, order ] );
 // returns <ndarray>
 
-var arr = ndarray2array( out );
+var arrX = ndarray2array( out );
 // returns [ -4.0, -2.0, 1.0, 3.0 ]
+
+var arrY = ndarray2array( y );
+// returns [ 3.0, 1.0, 0.0, 2.0 ]
 ```
 
 The function has the following parameters:
 
--   **arrays**: array-like object containing a one-dimensional input ndarray and a zero-dimensional ndarray specifying the sort order.
+-   **arrays**: array-like object containing two one-dimensional input ndarrays and a zero-dimensional ndarray specifying the sort order.
 
 </section>
 
@@ -72,8 +78,13 @@ The function has the following parameters:
 
 ## Notes
 
--   The input ndarray is sorted **in-place** (i.e., the input ndarray is **mutated**).
--   When the sort order is less than zero, the input ndarray is sorted in **decreasing** order. When the sort order is greater than zero, the input ndarray is sorted in **increasing** order. When the sort order is equal to zero, the input ndarray is left unchanged.
+-   Both input ndarrays are sorted **in-place** (i.e., the input ndarrays are **mutated**).
+-   Both ndarrays must have the same length.
+-   When the sort order is less than zero, the input ndarrays are sorted in **decreasing** order. When the sort order is greater than zero, the input ndarrays are sorted in **increasing** order. When the sort order is equal to zero, the input ndarrays are 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).
 
 </section>
 
@@ -99,13 +110,20 @@ var xbuf = discreteUniform( 10, -100, 100, {
 var x = new ndarray( 'float64', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
 console.log( ndarray2array( x ) );
 
+var ybuf = discreteUniform( 10, -100, 100, {
+    'dtype': 'float64'
+});
+var y = new ndarray( 'float64', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( y ) );
+
 var order = scalar2ndarray( 1.0, {
     'dtype': 'generic'
 });
 console.log( 'Order:', ndarraylike2scalar( order ) );
 
-dsort2hp( [ x, order ] );
+dsort2hp( [ x, y, order ] );
 console.log( ndarray2array( x ) );
+console.log( ndarray2array( y ) );
 ```
 
 </section>

lib/node_modules/@stdlib/blas/ext/base/ndarray/dsort2hp/benchmark/benchmark.js

@@ -26,7 +26,7 @@ var pow = require( '@stdlib/math/base/special/pow' );
 var ndarray = require( '@stdlib/ndarray/base/ctor' );
 var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var pkg = require( './../package.json' ).name;
-var dsorthp = require( './../lib' );
+var dsort2hp = require( './../lib' );
 
 
 // VARIABLES //
@@ -48,11 +48,16 @@ var options = {
 function createBenchmark( len ) {
 	var order;
 	var xbuf;
+	var ybuf;
 	var x;
+	var y;
 
 	xbuf = uniform( len, 0.0, 100.0, options );
 	x = new ndarray( options.dtype, xbuf, [ len ], [ 1 ], 0, 'row-major' );
 
+	ybuf = uniform( len, 0.0, 100.0, options );
+	y = new ndarray( options.dtype, ybuf, [ len ], [ 1 ], 0, 'row-major' );
+
 	order = scalar2ndarray( -1.0, options );
 
 	return benchmark;
@@ -63,7 +68,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			out = dsorthp( [ x, order ] );
+			out = dsort2hp( [ x, y, order ] );
 			if ( typeof out !== 'object' ) {
 				b.fail( 'should return an ndarray' );
 			}

lib/node_modules/@stdlib/blas/ext/base/ndarray/dsort2hp/docs/repl.txt

@@ -1,20 +1,20 @@
 
 {{alias}}( arrays )
-    Sorts a one-dimensional double-precision floating-point ndarray using
-    heapsort.
+    Simultaneously sorts two one-dimensional double-precision floating-point
+    ndarrays based on the sort order of the first array using heapsort.
 
-    When the sort order is less than zero, the input ndarray is sorted in
+    When the sort order is less than zero, the input ndarrays are sorted in
     decreasing order. When the sort order is greater than zero, the input
-    ndarray is sorted in increasing order. When the sort order is equal to zero,
-    the input ndarray is left unchanged.
+    ndarrays are sorted in increasing order. When the sort order is equal to
+    zero, the input ndarrays are left unchanged.
 
-    The input ndarray is sorted *in-place* (i.e., the input strided array is
+    Both input ndarrays are sorted *in-place* (i.e., the input ndarrays are
     *mutated*).
 
     Parameters
     ----------
     arrays: ArrayLikeObject<ndarray>
-        Array-like object containing a one-dimensional input ndarray and a
+        Array-like object containing two one-dimensional input ndarrays and a
         zero-dimensional ndarray specifying the sort order.
 
     Returns
@@ -25,17 +25,21 @@
     Examples
     --------
     > var xbuf = new {{alias:@stdlib/array/float64}}( [ 1.0, -2.0, 3.0, -4.0 ] );
+    > var ybuf = new {{alias:@stdlib/array/float64}}( [ 0.0, 1.0, 2.0, 3.0 ] );
     > var dt = 'float64';
     > var sh = [ xbuf.length ];
     > var sx = [ 1 ];
     > var ox = 0;
     > var ord = 'row-major';
     > var x = new {{alias:@stdlib/ndarray/ctor}}( dt, xbuf, sh, sx, ox, ord );
+    > var y = new {{alias:@stdlib/ndarray/ctor}}( dt, ybuf, sh, sx, ox, ord );
     > var o = {{alias:@stdlib/ndarray/from-scalar}}( 1.0, { 'dtype': dt } );
-    > {{alias}}( [ x, o ] )
+    > {{alias}}( [ x, y, o ] )
     <ndarray>
-    > var data = x.data
+    > var xdata = x.data
     <Float64Array>[ -4.0, -2.0, 1.0, 3.0 ]
+    > var ydata = y.data
+    <Float64Array>[ 3.0, 1.0, 0.0, 2.0 ]
 
     See Also
     --------

lib/node_modules/@stdlib/blas/ext/base/ndarray/dsort2hp/docs/types/index.d.ts

@@ -23,14 +23,14 @@
 import { typedndarray, float64ndarray } from '@stdlib/types/ndarray';
 
 /**
-* Sorts a one-dimensional double-precision floating-point ndarray using heapsort.
+* Simultaneously sorts two one-dimensional double-precision floating-point ndarrays based on the sort order of the first array using heapsort.
 *
 * ## Notes
 *
-* -   When the sort order is less than zero, the input ndarray is sorted in **decreasing** order. When the sort order is greater than zero, the input ndarray is sorted in **increasing** order. When the sort order is equal to zero, the input ndarray is left unchanged.
+* -   When the sort order is less than zero, the input ndarrays are sorted in **decreasing** order. When the sort order is greater than zero, the input ndarrays are sorted in **increasing** order. When the sort order is equal to zero, the input ndarrays are left unchanged.
 *
-* @param arrays - array-like object containing a one-dimensional input ndarray and a zero-dimensional ndarray specifying the sort order
-* @returns input ndarray
+* @param arrays - array-like object containing two one-dimensional input ndarrays and a zero-dimensional ndarray specifying the sort order
+* @returns first input ndarray
 *
 * @example
 * var Float64Array = require( '@stdlib/array/float64' );
@@ -41,19 +41,25 @@ import { typedndarray, float64ndarray } from '@stdlib/types/ndarray';
 * var xbuf = new Float64Array( [ 1.0, -2.0, 3.0, -4.0 ] );
 * var x = new ndarray( 'float64', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
 *
+* var ybuf = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );
+* var y = new ndarray( 'float64', ybuf, [ 4 ], [ 1 ], 0, 'row-major' );
+*
 * var ord = scalar2ndarray( 1.0, {
 *    'dtype': 'generic'
 * });
 *
-* var out = dsorthp( [ x, ord ] );
+* var out = dsort2hp( [ x, y, ord ] );
 * // returns <ndarray>
 *
-* var arr = ndarray2array( out );
+* var arrX = ndarray2array( out );
 * // returns [ -4.0, -2.0, 1.0, 3.0 ]
+*
+* var arrY = ndarray2array( y );
+* // returns [ 3.0, 1.0, 0.0, 2.0 ]
 */
-declare function dsorthp( arrays: [ float64ndarray, typedndarray<number> ] ): float64ndarray;
+declare function dsort2hp( arrays: [ float64ndarray, float64ndarray, typedndarray<number> ] ): float64ndarray;
 
 
 // EXPORTS //
 
-export = dsorthp;
+export = dsort2hp;

lib/node_modules/@stdlib/blas/ext/base/ndarray/dsort2hp/docs/types/test.ts

@@ -20,7 +20,7 @@
 
 import zeros = require( '@stdlib/ndarray/zeros' );
 import scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
-import dsorthp = require( './index' );
+import dsort2hp = require( './index' );
 
 
 // TESTS //
@@ -30,35 +30,41 @@ import dsorthp = require( './index' );
 	const x = zeros( [ 10 ], {
 		'dtype': 'float64'
 	});
+	const y = zeros( [ 10 ], {
+		'dtype': 'float64'
+	});
 	const order = scalar2ndarray( 1.0, {
 		'dtype': 'generic'
 	});
 
-	dsorthp( [ x, order ] ); // $ExpectType float64ndarray
+	dsort2hp( [ x, y, order ] ); // $ExpectType float64ndarray
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
 {
-	dsorthp( '10' ); // $ExpectError
-	dsorthp( 10 ); // $ExpectError
-	dsorthp( true ); // $ExpectError
-	dsorthp( false ); // $ExpectError
-	dsorthp( null ); // $ExpectError
-	dsorthp( undefined ); // $ExpectError
-	dsorthp( [] ); // $ExpectError
-	dsorthp( {} ); // $ExpectError
-	dsorthp( ( x: number ): number => x ); // $ExpectError
+	dsort2hp( '10' ); // $ExpectError
+	dsort2hp( 10 ); // $ExpectError
+	dsort2hp( true ); // $ExpectError
+	dsort2hp( false ); // $ExpectError
+	dsort2hp( null ); // $ExpectError
+	dsort2hp( undefined ); // $ExpectError
+	dsort2hp( [] ); // $ExpectError
+	dsort2hp( {} ); // $ExpectError
+	dsort2hp( ( x: number ): number => x ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided an unsupported number of arguments...
 {
 	const x = zeros( [ 10 ], {
 		'dtype': 'float64'
 	});
+	const y = zeros( [ 10 ], {
+		'dtype': 'float64'
+	});
 	const order = scalar2ndarray( 1.0, {
 		'dtype': 'generic'
 	});
 
-	dsorthp(); // $ExpectError
-	dsorthp( [ x, order ], {} ); // $ExpectError
+	dsort2hp(); // $ExpectError
+	dsort2hp( [ x, y, order ], {} ); // $ExpectError
 }

lib/node_modules/@stdlib/blas/ext/base/ndarray/dsort2hp/examples/index.js

@@ -23,18 +23,25 @@ var ndarray = require( '@stdlib/ndarray/base/ctor' );
 var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );
-var dsorthp = require( './../lib' );
+var dsort2hp = require( './../lib' );
 
 var xbuf = discreteUniform( 10, -100, 100, {
 	'dtype': 'float64'
 });
 var x = new ndarray( 'float64', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
 console.log( ndarray2array( x ) );
 
+var ybuf = discreteUniform( 10, -100, 100, {
+	'dtype': 'float64'
+});
+var y = new ndarray( 'float64', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( y ) );
+
 var order = scalar2ndarray( 1.0, {
 	'dtype': 'generic'
 });
 console.log( 'Order:', ndarraylike2scalar( order ) );
 
-dsorthp( [ x, order ] );
+dsort2hp( [ x, y, order ] );
 console.log( ndarray2array( x ) );
+console.log( ndarray2array( y ) );

lib/node_modules/@stdlib/blas/ext/base/ndarray/dsort2hp/lib/index.js

@@ -19,29 +19,35 @@
 'use strict';
 
 /**
-* Sort a one-dimensional double-precision floating-point ndarray using heapsort.
+* Simultaneously sort two one-dimensional double-precision floating-point ndarrays based on the sort order of the first array using heapsort.
 *
-* @module @stdlib/blas/ext/base/ndarray/dsorthp
+* @module @stdlib/blas/ext/base/ndarray/dsort2hp
 *
 * @example
 * var Float64Array = require( '@stdlib/array/float64' );
 * var ndarray = require( '@stdlib/ndarray/base/ctor' );
 * var ndarray2array = require( '@stdlib/ndarray/to-array' );
 * var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
-* var dsorthp = require( '@stdlib/blas/ext/base/ndarray/dsorthp' );
+* var dsort2hp = require( '@stdlib/blas/ext/base/ndarray/dsort2hp' );
 *
 * var xbuf = new Float64Array( [ 1.0, -2.0, 3.0, -4.0 ] );
 * var x = new ndarray( 'float64', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
 *
+* var ybuf = new Float64Array( [ 0.0, 1.0, 2.0, 3.0 ] );
+* var y = new ndarray( 'float64', ybuf, [ 4 ], [ 1 ], 0, 'row-major' );
+*
 * var ord = scalar2ndarray( 1.0, {
 *    'dtype': 'generic'
 * });
 *
-* var out = dsorthp( [ x, ord ] );
+* var out = dsort2hp( [ x, y, ord ] );
 * // returns <ndarray>
 *
-* var arr = ndarray2array( out );
+* var arrX = ndarray2array( out );
 * // returns [ -4.0, -2.0, 1.0, 3.0 ]
+*
+* var arrY = ndarray2array( y );
+* // returns [ 3.0, 1.0, 0.0, 2.0 ]
 */
 
 // MODULES //