From e36c29e2b9113180a95098b10f3100a7f9226baa Mon Sep 17 00:00:00 2001
From: Muhammad Haris <101793258+headlessNode@users.noreply.github.com>
Date: Sun, 27 Jul 2025 08:57:57 +0000
Subject: [PATCH] feat: add blas/ext/base/ndarray/gsorthp
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: passed
- task: lint_package_json
status: passed
- task: lint_repl_help
status: passed
- task: lint_javascript_src
status: passed
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: passed
- task: lint_javascript_tests
status: passed
- task: lint_javascript_benchmarks
status: passed
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: na
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: passed
- task: lint_license_headers
status: passed
---
---
.../blas/ext/base/ndarray/gsorthp/README.md | 127 ++++++++++++++++++
.../ndarray/gsorthp/benchmark/benchmark.js | 107 +++++++++++++++
.../ext/base/ndarray/gsorthp/docs/repl.txt | 35 +++++
.../ndarray/gsorthp/docs/types/index.d.ts | 54 ++++++++
.../base/ndarray/gsorthp/docs/types/test.ts | 64 +++++++++
.../base/ndarray/gsorthp/examples/index.js | 40 ++++++
.../ext/base/ndarray/gsorthp/lib/index.js | 52 +++++++
.../blas/ext/base/ndarray/gsorthp/lib/main.js | 70 ++++++++++
.../ext/base/ndarray/gsorthp/package.json | 68 ++++++++++
.../ext/base/ndarray/gsorthp/test/test.js | 75 +++++++++++
10 files changed, 692 insertions(+)
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/README.md
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/benchmark/benchmark.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/repl.txt
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/index.d.ts
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/test.ts
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/examples/index.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/index.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/main.js
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/package.json
create mode 100644 lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/test/test.js
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/README.md b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/README.md
new file mode 100644
index 000000000000..540f50192d17
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/README.md
@@ -0,0 +1,127 @@
+
+
+# gsorthp
+
+> Sort a one-dimensional ndarray using heapsort.
+
+
+
+
+
+
+
+## Usage
+
+```javascript
+var gsorthp = require( '@stdlib/blas/ext/base/ndarray/gsorthp' );
+```
+
+#### gsorthp( arrays )
+
+Sorts a one-dimensional ndarray using heapsort.
+
+```javascript
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var ndarray = require( '@stdlib/ndarray/base/ctor' );
+
+var xbuf = [ 1.0, -2.0, 3.0, -4.0 ];
+var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+
+var order = scalar2ndarray( 1.0, {
+ 'dtype': 'generic'
+});
+
+var out = gsorthp( [ x, order ] );
+// returns
+
+var arr = ndarray2array( out );
+// returns [ -4.0, -2.0, 1.0, 3.0 ]
+```
+
+The function has the following parameters:
+
+- **arrays**: array-like object containing a one-dimensional input ndarray and a zero-dimensional ndarray containing the sort order.
+
+
+
+
+
+
+
+## Notes
+
+- The input ndarray is sorted **in-place** (i.e., the input ndarray is **mutated**).
+
+
+
+
+
+
+
+## Examples
+
+
+
+```javascript
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
+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 gsorthp = require( '@stdlib/blas/ext/base/ndarray/gsorthp' );
+
+var xbuf = discreteUniform( 10, -100, 100, {
+ 'dtype': 'generic'
+});
+var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( x ) );
+
+var order = scalar2ndarray( 1.0, {
+ 'dtype': 'generic'
+});
+console.log( 'Order:', ndarraylike2scalar( order ) );
+
+gsorthp( [ x, order ] );
+console.log( ndarray2array( x ) );
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/benchmark/benchmark.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/benchmark/benchmark.js
new file mode 100644
index 000000000000..85a2980b72ba
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/benchmark/benchmark.js
@@ -0,0 +1,107 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var uniform = require( '@stdlib/random/array/uniform' );
+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 gsorthp = require( './../lib' );
+
+
+// VARIABLES //
+
+var options = {
+ 'dtype': 'generic'
+};
+
+
+// FUNCTIONS //
+
+/**
+* Creates a benchmark function.
+*
+* @private
+* @param {PositiveInteger} len - array length
+* @returns {Function} benchmark function
+*/
+function createBenchmark( len ) {
+ var order;
+ var xbuf;
+ var x;
+
+ xbuf = uniform( len, 0.0, 100.0, options );
+ x = new ndarray( options.dtype, xbuf, [ len ], [ 1 ], 0, 'row-major' );
+
+ order = scalar2ndarray( -1.0, {
+ 'dtype': options.dtype
+ });
+
+ return benchmark;
+
+ function benchmark( b ) {
+ var out;
+ var i;
+
+ b.tic();
+ for ( i = 0; i < b.iterations; i++ ) {
+ out = gsorthp( [ x, order ] );
+ if ( out !== out ) {
+ b.fail( 'should not return NaN' );
+ }
+ }
+ b.toc();
+ if ( out !== out ) {
+ b.fail( 'should not return NaN' );
+ }
+ b.pass( 'benchmark finished' );
+ b.end();
+ }
+}
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+*/
+function main() {
+ var len;
+ var min;
+ var max;
+ var f;
+ var i;
+
+ min = 1; // 10^min
+ max = 6; // 10^max
+
+ for ( i = min; i <= max; i++ ) {
+ len = pow( 10, i );
+ f = createBenchmark( len );
+ bench( pkg+':len='+len, f );
+ }
+}
+
+main();
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/repl.txt b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/repl.txt
new file mode 100644
index 000000000000..5242644033bf
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/repl.txt
@@ -0,0 +1,35 @@
+
+{{alias}}( arrays )
+ Sorts a one-dimensional ndarray using heapsort.
+
+ The input strided array is sorted *in-place* (i.e., the input strided array
+ is *mutated*).
+
+ Parameters
+ ----------
+ arrays: ArrayLikeObject
+ Array-like object containing a one-dimensional input ndarray and a
+ zero-dimensional ndarray containing the sort order.
+
+ Returns
+ -------
+ out: ndarray
+ Input ndarray.
+
+ Examples
+ --------
+ > var xbuf = [ 1.0, -2.0, 3.0, -4.0 ];
+ > var dt = 'generic';
+ > 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 o = {{alias:@stdlib/ndarray/from-scalar}}( 1.0, { 'dtype': dt } );
+ > {{alias}}( [ x, o ] )
+
+ > var data = x.data
+ [ -4.0, -2.0, 1.0, 3.0 ]
+
+ See Also
+ --------
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/index.d.ts b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/index.d.ts
new file mode 100644
index 000000000000..34058092668e
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/index.d.ts
@@ -0,0 +1,54 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+// TypeScript Version: 4.1
+
+///
+
+import { typedndarray } from '@stdlib/types/ndarray';
+
+/**
+* Sorts a one-dimensional ndarray using heapsort.
+*
+* @param arrays - array-like object containing a one-dimensional input ndarray and a zero-dimensional ndarray containing the sort order
+* @returns input ndarray
+*
+* @example
+* var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+* var ndarray = require( '@stdlib/ndarray/base/ctor' );
+*
+* var xbuf = [ 1.0, -2.0, 3.0, -4.0 ];
+* var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+*
+* var ord = scalar2ndarray( 1.0, {
+* 'dtype': 'generic'
+* });
+*
+* var out = gsorthp( [ x, ord ] );
+* // returns
+*
+* var arr = ndarra2array( out );
+* // returns [ -4.0, -2.0, 1.0, 3.0 ]
+*/
+declare function gsorthp( arrays: [ typedndarray, typedndarray ] ): typedndarray;
+
+
+// EXPORTS //
+
+export = gsorthp;
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/test.ts b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/test.ts
new file mode 100644
index 000000000000..460839c8cb25
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/docs/types/test.ts
@@ -0,0 +1,64 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/* eslint-disable space-in-parens */
+
+import zeros = require( '@stdlib/ndarray/zeros' );
+import scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+import gsorthp = require( './index' );
+
+
+// TESTS //
+
+// The function returns an ndarray...
+{
+ const x = zeros( [ 10 ], {
+ 'dtype': 'generic'
+ });
+ const order = scalar2ndarray( 1.0, {
+ 'dtype': 'generic'
+ });
+
+ gsorthp( [ x, order ] ); // $ExpectType typedndarray
+}
+
+// The compiler throws an error if the function is provided a first argument which is not an array of ndarrays...
+{
+ gsorthp( '10' ); // $ExpectError
+ gsorthp( 10 ); // $ExpectError
+ gsorthp( true ); // $ExpectError
+ gsorthp( false ); // $ExpectError
+ gsorthp( null ); // $ExpectError
+ gsorthp( undefined ); // $ExpectError
+ gsorthp( [] ); // $ExpectError
+ gsorthp( {} ); // $ExpectError
+ gsorthp( ( 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': 'generic'
+ });
+ const order = scalar2ndarray( 1.0, {
+ 'dtype': 'generic'
+ });
+
+ gsorthp(); // $ExpectError
+ gsorthp( [ x, order ], {} ); // $ExpectError
+}
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/examples/index.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/examples/index.js
new file mode 100644
index 000000000000..5d7283ab887e
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/examples/index.js
@@ -0,0 +1,40 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
+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 gsorthp = require( './../lib' );
+
+var xbuf = discreteUniform( 10, -100, 100, {
+ 'dtype': 'generic'
+});
+var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( x ) );
+
+var order = scalar2ndarray( 1.0, {
+ 'dtype': 'generic'
+});
+console.log( 'Order:', ndarraylike2scalar( order ) );
+
+gsorthp( [ x, order ] );
+console.log( ndarray2array( x ) );
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/index.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/index.js
new file mode 100644
index 000000000000..0bea759b2f75
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/index.js
@@ -0,0 +1,52 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+/**
+* Sort a one-dimensional ndarray using heapsort .
+*
+* @module @stdlib/blas/ext/base/ndarray/gsorthp
+*
+* @example
+* var ndarray = require( '@stdlib/ndarray/base/ctor' );
+* var ndarray2array = require( '@stdlib/ndarray/base/to-array' );
+* var gsorthp = require( '@stdlib/blas/ext/base/ndarray/gsorthp' );
+*
+* var xbuf = [ 1.0, -2.0, 3.0, -4.0 ];
+* var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
+*
+* var ord = scalar2ndarray( 1.0, {
+* 'dtype': 'generic'
+* });
+*
+* var out = gsorthp( [ x, ord ] );
+* // returns
+*
+* var arr = ndarra2array( out );
+* // returns [ -4.0, -2.0, 1.0, 3.0 ]
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;
diff --git a/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/main.js b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/main.js
new file mode 100644
index 000000000000..55cdc6219233
--- /dev/null
+++ b/lib/node_modules/@stdlib/blas/ext/base/ndarray/gsorthp/lib/main.js
@@ -0,0 +1,70 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var ndarraylike2scalar = require( '@stdlib/ndarray/base/ndarraylike2scalar' );
+var numelDimension = require( '@stdlib/ndarray/base/numel-dimension' );
+var getStride = require( '@stdlib/ndarray/base/stride' );
+var getOffset = require( '@stdlib/ndarray/base/offset' );
+var getData = require( '@stdlib/ndarray/base/data-buffer' );
+var strided = require( '@stdlib/blas/ext/base/gsorthp' ).ndarray;
+
+
+// MAIN //
+
+/**
+* Sorts a one-dimensional ndarray using heapsort.
+*
+* @param {ArrayLikeObject