refactor: add support for descending order

PR-URL: #15681
Co-authored-by: Athan Reines <kgryte@gmail.com>
Reviewed-by: Athan Reines <kgryte@gmail.com>
Signed-off-by: Athan Reines <kgryte@gmail.com>

Author: Sachinn-64

lib/node_modules/@stdlib/blas/ext/base/gindex-of-greater-than-sorted/README.md

@@ -49,6 +49,11 @@ var x = [ 1.0, 2.0, 2.0, 3.0 ];
 
 var idx = gindexOfGreaterThanSorted( x.length, 2.0, x, 1 );
 // returns 3
+
+x = [ 3.0, 2.0, 2.0, 1.0 ];
+
+idx = gindexOfGreaterThanSorted( x.length, 2.0, x, 1 );
+// returns 0
 ```
 
 The function has the following parameters:
@@ -126,7 +131,7 @@ var idx = gindexOfGreaterThanSorted.ndarray( 3, 1.0, x, 1, x.length-3 );
 
 ## Notes
 
--   The input strided array **must** be sorted in ascending order.
+-   The input strided array must be sorted in either **strictly** ascending or descending order.
 -   If `N <= 0`, both functions return `-1`.
 -   When comparing elements, both functions use the less-than operator `<`. As a consequence, comparisons involving `NaN` always evaluate to `false`, and `-0` and `+0` are considered the same.
 -   Both functions support array-like objects having getter and setter accessors for array element access (e.g., [`@stdlib/array/base/accessor`][@stdlib/array/base/accessor]).

lib/node_modules/@stdlib/blas/ext/base/gindex-of-greater-than-sorted/docs/repl.txt

@@ -9,7 +9,8 @@
     Indexing is relative to the first index. To introduce an offset, use a typed
     array view.
 
-    The input strided array must be sorted in ascending order.
+    The input strided array must be sorted in either strictly ascending or
+    descending order.
 
     If unable to find an element which is greater than the search element, the
     function returns `-1`.
@@ -41,6 +42,9 @@
     > var x = [ 1.0, 2.0, 2.0, 3.0 ];
     > var idx = {{alias}}( x.length, 2.0, x, 1 )
     3
+    > x = [ 3.0, 2.0, 2.0, 1.0 ];
+    > idx = {{alias}}( x.length, 2.0, x, 1 )
+    0
 
     // Using `N` and stride parameters:
     > x = [ 1.0, 9.0, 2.0, 9.0, 3.0, 9.0 ];

lib/node_modules/@stdlib/blas/ext/base/gindex-of-greater-than-sorted/docs/types/index.d.ts

@@ -36,7 +36,6 @@ interface Routine {
 	*
 	* ## Notes
 	*
-	* -   The input strided array must be sorted in ascending order.
 	* -   If the function is unable to find an element which is greater than a search element, the function returns `-1`.
 	*
 	* @param N - number of indexed elements
@@ -58,7 +57,6 @@ interface Routine {
 	*
 	* ## Notes
 	*
-	* -   The input strided array must be sorted in ascending order.
 	* -   If the function is unable to find an element which is greater than a search element, the function returns `-1`.
 	*
 	* @param N - number of indexed elements
@@ -82,7 +80,6 @@ interface Routine {
 *
 * ## Notes
 *
-* -   The input strided array must be sorted in ascending order.
 * -   If the function is unable to find an element which is greater than a search element, the function returns `-1`.
 *
 * @param N - number of indexed elements

lib/node_modules/@stdlib/blas/ext/base/gindex-of-greater-than-sorted/lib/accessors.js

@@ -53,13 +53,26 @@ function gindexOfGreaterThanSorted( N, searchElement, x, strideX, offsetX ) {
 	var mid;
 	var lo;
 	var hi;
+	var v1;
+	var v2;
 
 	// Cache reference to array data:
 	xbuf = x.data;
 
 	// Cache a reference to the element accessors:
 	get = x.accessors[ 0 ];
 
+	v1 = get( xbuf, offsetX );
+	v2 = get( xbuf, offsetX + ( ( N - 1 ) * strideX ) );
+
+	// Descending order: elements which are greater than the search element form a prefix, so only the first indexed element needs to be checked...
+	if ( v1 >= v2 ) {
+		if ( v1 > searchElement ) {
+			return 0;
+		}
+		return -1;
+	}
+	// Ascending order: perform a binary search for the first element which is greater than the search element...
 	lo = 0;
 	hi = N;
 	while ( lo < hi ) {

lib/node_modules/@stdlib/blas/ext/base/gindex-of-greater-than-sorted/lib/main.js

@@ -31,7 +31,6 @@ var ndarray = require( './ndarray.js' );
 *
 * ## Notes
 *
-* -   The input strided array must be sorted in ascending order.
 * -   If unable to find an element which is greater than the search element, the function returns `-1`.
 *
 * @param {PositiveInteger} N - number of indexed elements

lib/node_modules/@stdlib/blas/ext/base/gindex-of-greater-than-sorted/lib/ndarray.js

@@ -32,7 +32,6 @@ var accessors = require( './accessors.js' );
 *
 * ## Notes
 *
-* -   The input strided array must be sorted in ascending order.
 * -   If unable to find an element which is greater than the search element, the function returns `-1`.
 *
 * @param {PositiveInteger} N - number of indexed elements
@@ -52,6 +51,8 @@ function gindexOfGreaterThanSorted( N, searchElement, x, strideX, offsetX ) {
 	var mid;
 	var lo;
 	var hi;
+	var v1;
+	var v2;
 	var o;
 
 	if ( N <= 0 ) {
@@ -61,6 +62,17 @@ function gindexOfGreaterThanSorted( N, searchElement, x, strideX, offsetX ) {
 	if ( o.accessorProtocol ) {
 		return accessors( N, searchElement, o, strideX, offsetX );
 	}
+	v1 = x[ offsetX ];
+	v2 = x[ offsetX + ( ( N - 1 ) * strideX ) ];
+
+	// Descending order: elements which are greater than the search element form a prefix, so only the first indexed element needs to be checked...
+	if ( v1 >= v2 ) {
+		if ( v1 > searchElement ) {
+			return 0;
+		}
+		return -1;
+	}
+	// Ascending order: perform a binary search for the first element which is greater than the search element...
 	lo = 0;
 	hi = N;
 	while ( lo < hi ) {

lib/node_modules/@stdlib/blas/ext/base/gindex-of-greater-than-sorted/test/test.main.js

@@ -310,3 +310,161 @@ tape( 'the function supports view offsets', function test( t ) {
 
 	t.end();
 });
+
+tape( 'the function returns the index of the first element in a sorted strided array which is greater than a provided search element (descending order)', function test( t ) {
+	var actual;
+	var x;
+
+	x = [ 3.0, 3.0, 2.0, 2.0, 1.0, 1.0 ];
+
+	actual = gindexOfGreaterThanSorted( x.length, 2.0, x, 1 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function returns the index of the first element in a sorted strided array which is greater than a provided search element (descending order) (accessors)', function test( t ) {
+	var actual;
+	var x;
+
+	x = toAccessorArray( [ 3.0, 3.0, 2.0, 2.0, 1.0, 1.0 ] );
+
+	actual = gindexOfGreaterThanSorted( x.length, 2.0, x, 1 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function returns the index of the first element in a sorted strided array which is greater than a provided search element when the search element is not present in the strided array (descending order)', function test( t ) {
+	var actual;
+	var x;
+
+	x = [ 3.0, 3.0, 2.0, 2.0, 1.0, 1.0 ];
+
+	actual = gindexOfGreaterThanSorted( x.length, 2.5, x, 1 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function returns the index of the first element in a sorted strided array which is greater than a provided search element when the search element is not present in the strided array (descending order) (accessors)', function test( t ) {
+	var actual;
+	var x;
+
+	x = toAccessorArray( [ 3.0, 3.0, 2.0, 2.0, 1.0, 1.0 ] );
+
+	actual = gindexOfGreaterThanSorted( x.length, 2.5, x, 1 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function returns `-1` if every indexed element in the array is less than or equal to the search element (descending order)', function test( t ) {
+	var actual;
+	var x;
+
+	x = [ 3.0, 2.0, 1.0 ];
+
+	actual = gindexOfGreaterThanSorted( x.length, 3.0, x, 1 );
+	t.strictEqual( actual, -1, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function returns `-1` if every indexed element in the array is less than or equal to the search element (descending order) (accessors)', function test( t ) {
+	var actual;
+	var x;
+
+	x = toAccessorArray( [ 3.0, 2.0, 1.0 ] );
+
+	actual = gindexOfGreaterThanSorted( x.length, 3.0, x, 1 );
+	t.strictEqual( actual, -1, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function supports an `x` stride (descending order)', function test( t ) {
+	var actual;
+	var x;
+
+	x = [
+		3.0, // 0
+		9.0,
+		2.0, // 1
+		9.0,
+		1.0  // 2
+	];
+
+	actual = gindexOfGreaterThanSorted( 3, 2.0, x, 2 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function supports an `x` stride (descending order) (accessors)', function test( t ) {
+	var actual;
+	var x;
+
+	x = [
+		3.0, // 0
+		9.0,
+		2.0, // 1
+		9.0,
+		1.0  // 2
+	];
+
+	actual = gindexOfGreaterThanSorted( 3, 2.0, toAccessorArray( x ), 2 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function supports a negative `x` stride (descending order)', function test( t ) {
+	var actual;
+	var x;
+
+	x = [
+		1.0, // 2
+		9.0,
+		2.0, // 1
+		9.0,
+		3.0  // 0
+	];
+
+	actual = gindexOfGreaterThanSorted( 3, 2.0, x, -2 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function supports a negative `x` stride (descending order) (accessors)', function test( t ) {
+	var actual;
+	var x;
+
+	x = [
+		1.0, // 2
+		9.0,
+		2.0, // 1
+		9.0,
+		3.0  // 0
+	];
+
+	actual = gindexOfGreaterThanSorted( 3, 2.0, toAccessorArray( x ), -2 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function supports view offsets (descending order)', function test( t ) {
+	var actual;
+	var x0;
+	var x1;
+
+	x0 = new Float64Array( [ 9.0, 4.0, 3.0, 2.0, 1.0 ] );
+	x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 );
+
+	actual = gindexOfGreaterThanSorted( 3, 2.0, x1, 1 );
+	t.strictEqual( actual, 0, 'returns expected value' );
+
+	t.end();
+});