Skip to content

Commit 1e52531

Browse files
headlessNodeheadlessNode
committed
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 ---
1 parent 9ffbf40 commit 1e52531

File tree

6 files changed

+160
-19
lines changed

6 files changed

+160
-19
lines changed

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

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ var bool = ( x === y );
5353
The function has the following parameters:
5454

5555
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a numeric or "generic" [data type][@stdlib/ndarray/dtypes].
56-
- **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).
56+
- **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).
5757
- **options**: function options (_optional_).
5858

5959
The function accepts the following options:
@@ -75,6 +75,29 @@ var arr = ndarray2array( y );
7575
// returns [ 2.0, -1.0, -3.0 ]
7676
```
7777

78+
Alternatively, you can also provide a string literal to specify the sort order.
79+
80+
```javascript
81+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
82+
var array = require( '@stdlib/ndarray/array' );
83+
84+
var x = array( [ -1.0, 2.0, -3.0 ] );
85+
86+
// Sort in ascending order:
87+
var y = sorthp( x, 'asc' );
88+
// returns <ndarray>
89+
90+
var arr = ndarray2array( y );
91+
// returns [ -3.0, -1.0, 2.0 ]
92+
93+
// Sort in descending order:
94+
y = sorthp( x, 'descending' );
95+
// returns <ndarray>
96+
97+
arr = ndarray2array( y );
98+
// returns [ 2.0, -1.0, -3.0 ]
99+
```
100+
78101
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.
79102

80103
```javascript
@@ -108,6 +131,7 @@ v = ndarray2array( y );
108131

109132
- The input [ndarray][@stdlib/ndarray/ctor] is sorted **in-place** (i.e., the input [ndarray][@stdlib/ndarray/ctor] is **mutated**).
110133
- 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.
134+
- 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.
111135
- 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.
112136

113137
</section>

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@
1111
Input array. Must have a numeric or "generic" data type.
1212

1313
sortOrder: ndarray|number (optional)
14-
Sort order. May be either a scalar value or an ndarray having a real or
15-
"generic" data type. If provided an ndarray, the value must have a shape
16-
which is broadcast compatible with the complement of the shape defined
17-
by `options.dims`. For example, given the input shape `[2, 3, 4]` and
18-
`options.dims=[0]`, an ndarray sort order must have a shape which is
19-
broadcast compatible with the shape `[3, 4]`. Similarly, when performing
20-
the operation over all elements in a provided input ndarray, an ndarray
21-
sort order must be a zero-dimensional ndarray. By default, the sort
22-
order is `1` (i.e., increasing order).
14+
Sort order. May be either a scalar value, string or an ndarray having a
15+
real or "generic" data type. If provided an ndarray, the value must have
16+
a shape which is broadcast compatible with the complement of the shape
17+
defined by `options.dims`. For example, given the input shape
18+
`[2, 3, 4]` and `options.dims=[0]`, an ndarray sort order must have a
19+
shape which is broadcast compatible with the shape `[3, 4]`. Similarly,
20+
when performing the operation over all elements in a provided input
21+
ndarray, an ndarray sort order must be a zero-dimensional ndarray. By
22+
default, the sort order is `1` (i.e., increasing order).
2323

2424
options: Object (optional)
2525
Function options.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ type InputArray<T> = typedndarray<T>;
3131
/**
3232
* Sort order.
3333
*/
34-
type SortOrder = typedndarray<DataType> | number;
34+
type SortOrder = typedndarray<DataType> | number | string;
3535

3636

3737
/**

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

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -83,13 +83,11 @@ import sorthp = require( './index' );
8383
'dtype': 'float64'
8484
});
8585

86-
sorthp( x, '5' ); // $ExpectError
8786
sorthp( x, true ); // $ExpectError
8887
sorthp( x, false ); // $ExpectError
8988
sorthp( x, [] ); // $ExpectError
9089
sorthp( x, ( x: number ): number => x ); // $ExpectError
9190

92-
sorthp( x, '5', {} ); // $ExpectError
9391
sorthp( x, true, {} ); // $ExpectError
9492
sorthp( x, false, {} ); // $ExpectError
9593
sorthp( x, [], {} ); // $ExpectError
@@ -102,7 +100,6 @@ import sorthp = require( './index' );
102100
'dtype': 'float64'
103101
});
104102

105-
sorthp( x, '5' ); // $ExpectError
106103
sorthp( x, true ); // $ExpectError
107104
sorthp( x, false ); // $ExpectError
108105
sorthp( x, [] ); // $ExpectError

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

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222

2323
var hasOwnProp = require( '@stdlib/assert/has-own-property' );
2424
var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive;
25+
var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
2526
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
2627
var broadcastScalar = require( '@stdlib/ndarray/base/broadcast-scalar' );
2728
var maybeBroadcastArray = require( '@stdlib/ndarray/base/maybe-broadcast-array' );
@@ -38,11 +39,11 @@ var base = require( './base.js' );
3839
* Sorts an input ndarray along one or more ndarray dimensions using heapsort.
3940
*
4041
* @param {ndarrayLike} x - input ndarray
41-
* @param {(ndarrayLike|number)} [sortOrder] - sort order
42+
* @param {(ndarrayLike|number|string)} [sortOrder] - sort order
4243
* @param {Options} [options] - function options
4344
* @param {IntegerArray} [options.dims] - list of dimensions over which to perform operation
4445
* @throws {TypeError} first argument must be an ndarray-like object
45-
* @throws {TypeError} sort order argument must be either an ndarray-like object or a numeric value
46+
* @throws {TypeError} sort order argument must be either an ndarray-like object, a numeric value, or a valid string
4647
* @throws {TypeError} options argument must be an object
4748
* @throws {RangeError} dimension indices must not exceed input ndarray bounds
4849
* @throws {RangeError} number of dimension indices must not exceed the number of input ndarray dimensions
@@ -105,6 +106,17 @@ function sorthp( x ) {
105106
if ( isNumber( o ) ) {
106107
return base( x, broadcastScalar( o, 'generic', [], ord ) );
107108
}
109+
// Case: sorthp( x, sortOrder_string )
110+
if ( isString( o ) ) {
111+
if ( o === 'asc' || o === 'ascending' ) {
112+
o = 1.0;
113+
} else if ( o === 'dsc' || o === 'descending' ) {
114+
o = -1.0;
115+
} else {
116+
throw new TypeError( format( 'invalid argument. Second argument must be a valid sort order. Value: `%s`.', o ) );
117+
}
118+
return base( x, broadcastScalar( o, 'generic', [], ord ) );
119+
}
108120
// Case: sorthp( x, opts )
109121
opts = o;
110122
o = 1.0;
@@ -130,8 +142,24 @@ function sorthp( x ) {
130142
sh = [];
131143
}
132144
o = broadcastScalar( o, 'generic', sh, getOrder( x ) );
145+
}
146+
// Case: sorthp( x, sortOrder_string, opts )
147+
else if ( isString( o ) ) {
148+
if ( o === 'asc' || o === 'ascending' ) {
149+
o = 1.0;
150+
} else if ( o === 'dsc' || o === 'descending' ) {
151+
o = -1.0;
152+
} else {
153+
throw new TypeError( format( 'invalid argument. Second argument must be a valid sort order. Value: `%s`.', o ) );
154+
}
155+
if ( hasOwnProp( opts, 'dims' ) ) {
156+
sh = nonCoreShape( getShape( x ), opts.dims );
157+
} else {
158+
sh = [];
159+
}
160+
o = broadcastScalar( o, 'generic', sh, getOrder( x ) );
133161
} else {
134-
throw new TypeError( format( 'invalid argument. Second argument must be either an ndarray or a numeric scalar value. Value: `%s`.', o ) );
162+
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 ) );
135163
}
136164
return base( x, o, opts );
137165
}

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

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -347,7 +347,7 @@ tape( 'the function throws an error if provided a `sortOrder` argument which is
347347
});
348348

349349
values = [
350-
'5',
350+
'invalid',
351351
true,
352352
false,
353353
null,
@@ -377,7 +377,7 @@ tape( 'the function throws an error if provided a `sortOrder` argument which is
377377
});
378378

379379
values = [
380-
'5',
380+
'invalid',
381381
true,
382382
false,
383383
null,
@@ -1340,6 +1340,98 @@ tape( 'the function supports providing a `sortOrder` argument (0d ndarray, broad
13401340
t.end();
13411341
});
13421342

1343+
tape( 'the function supports providing a `sortOrder` argument (string literals)', function test( t ) {
1344+
var expected;
1345+
var actual;
1346+
var xbuf;
1347+
var x;
1348+
1349+
xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
1350+
x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
1351+
1352+
actual = sorthp( x, 'asc' );
1353+
expected = [ -3.0, -1.0, 2.0, 4.0 ];
1354+
1355+
t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
1356+
t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
1357+
t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
1358+
t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
1359+
t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
1360+
1361+
xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
1362+
x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
1363+
1364+
actual = sorthp( x, 'ascending' );
1365+
expected = [ -3.0, -1.0, 2.0, 4.0 ];
1366+
1367+
t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
1368+
t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
1369+
t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
1370+
t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
1371+
t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
1372+
1373+
xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
1374+
x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
1375+
1376+
actual = sorthp( x, 'dsc' );
1377+
expected = [ 4.0, 2.0, -1.0, -3.0 ];
1378+
1379+
t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
1380+
t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
1381+
t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
1382+
t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
1383+
t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
1384+
1385+
xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
1386+
x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
1387+
1388+
actual = sorthp( x, 'descending' );
1389+
expected = [ 4.0, 2.0, -1.0, -3.0 ];
1390+
1391+
t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
1392+
t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
1393+
t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
1394+
t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
1395+
t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
1396+
1397+
t.end();
1398+
});
1399+
1400+
tape( 'the function supports providing a `sortOrder` argument (string literals, options)', function test( t ) {
1401+
var expected;
1402+
var actual;
1403+
var xbuf;
1404+
var x;
1405+
1406+
xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
1407+
x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
1408+
1409+
actual = sorthp( x, 'asc', {} );
1410+
expected = [ -3.0, -1.0, 2.0, 4.0 ];
1411+
1412+
t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
1413+
t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
1414+
t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
1415+
t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
1416+
t.strictEqual( isSameArray( getData( actual ), expected ), true, 'returns expected value' );
1417+
1418+
xbuf = [ -1.0, 2.0, -3.0, 4.0 ];
1419+
x = new ndarray( 'generic', xbuf, [ 2, 2 ], [ 2, 1 ], 0, 'row-major' );
1420+
1421+
actual = sorthp( x, 'descending', {
1422+
'dims': [ 0 ]
1423+
});
1424+
expected = [ [ -1.0, 4.0 ], [ -3.0, 2.0 ] ];
1425+
1426+
t.strictEqual( isndarrayLike( actual ), true, 'returns expected value' );
1427+
t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
1428+
t.deepEqual( getShape( actual ), getShape( x ), 'returns expected value' );
1429+
t.strictEqual( getOrder( actual ), getOrder( x ), 'returns expected value' );
1430+
t.deepEqual( ndarray2array( actual ), expected, 'returns expected value' );
1431+
1432+
t.end();
1433+
});
1434+
13431435
tape( 'the function supports providing a `sortOrder` argument (ndarray)', function test( t ) {
13441436
var sortOrder;
13451437
var expected;

0 commit comments

Comments
 (0)