feat: add string support

---
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: na
  - task: lint_repl_help
    status: passed
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - 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
---

Author: headlessNode

lib/node_modules/@stdlib/blas/ext/sorthp/README.md

@@ -53,7 +53,7 @@ var bool = ( x === y );
 The function has the following parameters:
 
 -   **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a numeric or "generic" [data type][@stdlib/ndarray/dtypes].
--   **sortOrder**: sort order (_optional_). May be either a scalar value or an [ndarray][@stdlib/ndarray/ctor] having a real or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] 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][@stdlib/ndarray/ctor] sort order must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor], an [ndarray][@stdlib/ndarray/ctor] sort order must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor]. By default, the sort order is `1` (i.e., increasing order).
+-   **sortOrder**: sort order (_optional_). May be either a scalar value, string, or an [ndarray][@stdlib/ndarray/ctor] having a real or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] 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][@stdlib/ndarray/ctor] sort order must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor], an [ndarray][@stdlib/ndarray/ctor] sort order must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor]. By default, the sort order is `1` (i.e., increasing order).
 -   **options**: function options (_optional_).
 
 The function accepts the following options:
@@ -75,6 +75,29 @@ var arr = ndarray2array( y );
 // returns [ 2.0, -1.0, -3.0 ]
 ```
 
+Alternatively, you can also provide a string literal to specify the sort order.
+
+```javascript
+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][@stdlib/ndarray/ctor]. To perform the operation over specific dimensions, provide a `dims` option.
 
 ```javascript
@@ -108,6 +131,7 @@ v = ndarray2array( y );
 
 -   The input [ndarray][@stdlib/ndarray/ctor] is sorted **in-place** (i.e., the input [ndarray][@stdlib/ndarray/ctor] is **mutated**).
 -   If `sortOrder < 0.0`, the input [ndarray][@stdlib/ndarray/ctor] is sorted in **decreasing** order. If `sortOrder > 0.0`, the input [ndarray][@stdlib/ndarray/ctor] is sorted in **increasing** order. If `sortOrder == 0.0`, the input [ndarray][@stdlib/ndarray/ctor] is left unchanged.
+-   If `sortOrder === asc` or `sortOrder === ascending`, the input [ndarray][@stdlib/ndarray/ctor] is sorted in **increasing** order. If `sortOrder === desc` or `sortOrder === descending`, the input [ndarray][@stdlib/ndarray/ctor] is sorted in **decreasing** order.
 -   The function iterates over [ndarray][@stdlib/ndarray/ctor] elements according to the memory layout of the input [ndarray][@stdlib/ndarray/ctor]. Accordingly, performance degradation is possible when operating over multiple dimensions of a large non-contiguous multi-dimensional input [ndarray][@stdlib/ndarray/ctor]. In such scenarios, one may want to copy an input [ndarray][@stdlib/ndarray/ctor] to contiguous memory before sorting.
 
 </section>

lib/node_modules/@stdlib/blas/ext/sorthp/docs/repl.txt

@@ -11,15 +11,15 @@
         Input array. Must have a numeric or "generic" data type.
 
     sortOrder: ndarray|number (optional)
-        Sort order. May be either a scalar value or an ndarray having a real 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).
+        Sort order. May be either a scalar value, string or an ndarray having a
+        real 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: Object (optional)
         Function options.

lib/node_modules/@stdlib/blas/ext/sorthp/docs/types/index.d.ts

@@ -31,7 +31,7 @@ type InputArray<T> = typedndarray<T>;
 /**
 * Sort order.
 */
-type SortOrder = typedndarray<DataType> | number;
+type SortOrder = typedndarray<DataType> | number | string;
 
 
 /**

lib/node_modules/@stdlib/blas/ext/sorthp/docs/types/test.ts

@@ -83,13 +83,11 @@ import sorthp = require( './index' );
 		'dtype': 'float64'
 	});
 
-	sorthp( x, '5' ); // $ExpectError
 	sorthp( x, true ); // $ExpectError
 	sorthp( x, false ); // $ExpectError
 	sorthp( x, [] ); // $ExpectError
 	sorthp( x, ( x: number ): number => x ); // $ExpectError
 
-	sorthp( x, '5', {} ); // $ExpectError
 	sorthp( x, true, {} ); // $ExpectError
 	sorthp( x, false, {} ); // $ExpectError
 	sorthp( x, [], {} ); // $ExpectError
@@ -102,7 +100,6 @@ import sorthp = require( './index' );
 		'dtype': 'float64'
 	});
 
-	sorthp( x, '5' ); // $ExpectError
 	sorthp( x, true ); // $ExpectError
 	sorthp( x, false ); // $ExpectError
 	sorthp( x, [] ); // $ExpectError

lib/node_modules/@stdlib/blas/ext/sorthp/lib/main.js

@@ -22,6 +22,7 @@
 
 var hasOwnProp = require( '@stdlib/assert/has-own-property' );
 var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive;
+var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
 var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
 var broadcastScalar = require( '@stdlib/ndarray/base/broadcast-scalar' );
 var maybeBroadcastArray = require( '@stdlib/ndarray/base/maybe-broadcast-array' );
@@ -38,11 +39,11 @@ var base = require( './base.js' );
 * Sorts an input ndarray along one or more ndarray dimensions using heapsort.
 *
 * @param {ndarrayLike} x - input ndarray
-* @param {(ndarrayLike|number)} [sortOrder] - sort order
+* @param {(ndarrayLike|number|string)} [sortOrder] - sort order
 * @param {Options} [options] - function options
 * @param {IntegerArray} [options.dims] - list of dimensions over which to perform operation
 * @throws {TypeError} first argument must be an ndarray-like object
-* @throws {TypeError} sort order argument must be either an ndarray-like object or a numeric value
+* @throws {TypeError} sort order argument must be either an ndarray-like object, a numeric value, or a valid string
 * @throws {TypeError} options argument must be an object
 * @throws {RangeError} dimension indices must not exceed input ndarray bounds
 * @throws {RangeError} number of dimension indices must not exceed the number of input ndarray dimensions
@@ -105,6 +106,17 @@ function sorthp( x ) {
 		if ( isNumber( o ) ) {
 			return base( x, broadcastScalar( o, 'generic', [], ord ) );
 		}
+		// Case: sorthp( x, sortOrder_string )
+		if ( isString( o ) ) {
+			if ( o === 'asc' || o === 'ascending' ) {
+				o = 1.0;
+			} else if ( o === 'dsc' || o === 'descending' ) {
+				o = -1.0;
+			} else {
+				throw new TypeError( format( 'invalid argument. Second argument must be a valid sort order. Value: `%s`.', o ) );
+			}
+			return base( x, broadcastScalar( o, 'generic', [], ord ) );
+		}
 		// Case: sorthp( x, opts )
 		opts = o;
 		o = 1.0;
@@ -130,8 +142,24 @@ function sorthp( x ) {
 			sh = [];
 		}
 		o = broadcastScalar( o, 'generic', sh, getOrder( x ) );
+	}
+	// Case: sorthp( x, sortOrder_string, opts )
+	else if ( isString( o ) ) {
+		if ( o === 'asc' || o === 'ascending' ) {
+			o = 1.0;
+		} else if ( o === 'dsc' || o === 'descending' ) {
+			o = -1.0;
+		} else {
+			throw new TypeError( format( 'invalid argument. Second argument must be a valid sort order. Value: `%s`.', o ) );
+		}
+		if ( hasOwnProp( opts, 'dims' ) ) {
+			sh = nonCoreShape( getShape( x ), opts.dims );
+		} else {
+			sh = [];
+		}
+		o = broadcastScalar( o, 'generic', sh, getOrder( x ) );
 	} else {
-		throw new TypeError( format( 'invalid argument. Second argument must be either an ndarray or a numeric scalar value. Value: `%s`.', o ) );
+		throw new TypeError( format( 'invalid argument. Second argument must be either an ndarray, a numeric scalar value, or a valid sort order string. Value: `%s`.', o ) );
 	}
 	return base( x, o, opts );
 }

lib/node_modules/@stdlib/blas/ext/sorthp/test/test.js

@@ -347,7 +347,7 @@ tape( 'the function throws an error if provided a `sortOrder` argument which is
 	});
 
 	values = [
-		'5',
+		'invalid',
 		true,
 		false,
 		null,
@@ -377,7 +377,7 @@ tape( 'the function throws an error if provided a `sortOrder` argument which is
 	});
 
 	values = [
-		'5',
+		'invalid',
 		true,
 		false,
 		null,
@@ -1340,6 +1340,98 @@ tape( 'the function supports providing a `sortOrder` argument (0d ndarray, broad
 	t.end();
 });
 
+tape( 'the function supports providing a `sortOrder` argument (string literals)', function test( t ) {
+	var expected;
+	var actual;
+	var xbuf;
+	var x;
+
+	xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
+	x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	actual = sorthp( x, 'asc' );
+	expected = [ -3.0, -1.0, 2.0, 4.0 ];
+
+	t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
+	t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
+	t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
+	t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
+
+	xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
+	x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	actual = sorthp( x, 'ascending' );
+	expected = [ -3.0, -1.0, 2.0, 4.0 ];
+
+	t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
+	t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
+	t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
+	t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
+
+	xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
+	x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	actual = sorthp( x, 'dsc' );
+	expected = [ 4.0, 2.0, -1.0, -3.0 ];
+
+	t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
+	t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
+	t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
+	t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
+
+	xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
+	x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	actual = sorthp( x, 'descending' );
+	expected = [ 4.0, 2.0, -1.0, -3.0 ];
+
+	t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
+	t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
+	t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
+	t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
+
+	t.end();
+});
+
+tape( 'the function supports providing a `sortOrder` argument (string literals, options)', function test( t ) {
+	var expected;
+	var actual;
+	var xbuf;
+	var x;
+
+	xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
+	x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	actual = sorthp( x, 'asc', {} );
+	expected = [ -3.0, -1.0, 2.0, 4.0 ];
+
+	t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
+	t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
+	t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
+	t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
+
+	xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
+	x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
+
+	actual = sorthp( x, 'descending', {
+		'dims': [ 0 ]
+	});
+	expected = [ [ -1.0, 4.0 ], [ -3.0, 2.0 ] ];
+
+	t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
+	t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
+	t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
+	t.deepEqual( ndarray2array( actual ), expected, 'returns expected value' );
+
+	t.end();
+});
+
 tape( 'the function supports providing a `sortOrder` argument (ndarray)', function test( t ) {
 	var sortOrder;
 	var expected;