Skip to content

Commit 9ccb328

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 83bff36 commit 9ccb328

15 files changed

Lines changed: 5560 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
### Features
1212

13+
- [`31f10bd`](https://github.com/stdlib-js/stdlib/commit/31f10bde362541de6e57fde3d01d9800511325a6) - add `blas/ext/to-sorted` [(#11718)](https://github.com/stdlib-js/stdlib/pull/11718)
1314
- [`fe150a0`](https://github.com/stdlib-js/stdlib/commit/fe150a043da24741d6bedfce0c666f89a1fae559) - update `blas/base/ndarray` TypeScript declarations [(#11752)](https://github.com/stdlib-js/stdlib/pull/11752)
1415
- [`9188369`](https://github.com/stdlib-js/stdlib/commit/918836933ae30e70806a221774aa67a46ddab166) - add `dswap` to namespace
1516
- [`68ef817`](https://github.com/stdlib-js/stdlib/commit/68ef81746517bdba3d02ea39e564034a9d999194) - add `blas/base/ndarray/dswap` [(#11715)](https://github.com/stdlib-js/stdlib/pull/11715)
@@ -919,6 +920,7 @@ A total of 57 issues were closed in this release:
919920

920921
<details>
921922

923+
- [`31f10bd`](https://github.com/stdlib-js/stdlib/commit/31f10bde362541de6e57fde3d01d9800511325a6) - **feat:** add `blas/ext/to-sorted` [(#11718)](https://github.com/stdlib-js/stdlib/pull/11718) _(by Muhammad Haris, Athan Reines)_
922924
- [`3bd0331`](https://github.com/stdlib-js/stdlib/commit/3bd03310a8738bf090c10603059d20f069e8703d) - **test:** fix assertions and descriptions _(by Athan Reines)_
923925
- [`fe150a0`](https://github.com/stdlib-js/stdlib/commit/fe150a043da24741d6bedfce0c666f89a1fae559) - **feat:** update `blas/base/ndarray` TypeScript declarations [(#11752)](https://github.com/stdlib-js/stdlib/pull/11752) _(by stdlib-bot)_
924926
- [`9b264bc`](https://github.com/stdlib-js/stdlib/commit/9b264bc6232e511b08d2b5e4ae79216803d46ffd) - **docs:** update namespace table of contents [(#11754)](https://github.com/stdlib-js/stdlib/pull/11754) _(by stdlib-bot)_

‎ext/to-sorted/README.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# toSorted
22+
23+
> Return a new [ndarray][@stdlib/ndarray/ctor] containing the elements of an input [ndarray][@stdlib/ndarray/ctor] sorted along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var toSorted = require( '@stdlib/blas/ext/to-sorted' );
31+
```
32+
33+
#### toSorted( x\[, sortOrder]\[, options] )
34+
35+
Returns a new [ndarray][@stdlib/ndarray/ctor] containing the elements of an input [ndarray][@stdlib/ndarray/ctor] sorted along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.
36+
37+
```javascript
38+
var array = require( '@stdlib/ndarray/array' );
39+
40+
var x = array( [ -1.0, 2.0, -3.0 ] );
41+
42+
var y = toSorted( x );
43+
// returns <ndarray>[ -3.0, -1.0, 2.0 ]
44+
```
45+
46+
The function has the following parameters:
47+
48+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
49+
- **sortOrder**: sort order (_optional_). May be either a scalar value, string, or an [ndarray][@stdlib/ndarray/ctor] having a real-valued 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).
50+
- **options**: function options (_optional_).
51+
52+
The function accepts the following options:
53+
54+
- **dims**: list of dimensions over which to perform operation. If not provided, the function performs the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor].
55+
- **dtype**: output [ndarray][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes].
56+
57+
By default, the function sorts elements in increasing order. To sort in a different order, provide a `sortOrder` argument.
58+
59+
```javascript
60+
var array = require( '@stdlib/ndarray/array' );
61+
62+
var x = array( [ -1.0, 2.0, -3.0 ] );
63+
64+
var y = toSorted( x, -1.0 );
65+
// returns <ndarray>[ 2.0, -1.0, -3.0 ]
66+
```
67+
68+
In addition to numeric values, one can specify the sort order via one of the following string literals: `'ascending'`, `'asc'`, `'descending'`, or `'desc'`. The first two literals indicate to sort in ascending (i.e., increasing) order. The last two literals indicate to sort in descending (i.e., decreasing) order.
69+
70+
```javascript
71+
var array = require( '@stdlib/ndarray/array' );
72+
73+
var x = array( [ -1.0, 2.0, -3.0 ] );
74+
75+
// Sort in ascending order:
76+
var y = toSorted( x, 'asc' );
77+
// returns <ndarray>[ -3.0, -1.0, 2.0 ]
78+
79+
// Sort in descending order:
80+
y = toSorted( x, 'descending' );
81+
// returns <ndarray>[ 2.0, -1.0, -3.0 ]
82+
```
83+
84+
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.
85+
86+
```javascript
87+
var array = require( '@stdlib/ndarray/array' );
88+
89+
var x = array( [ -1.0, 2.0, -3.0, 4.0 ], {
90+
'shape': [ 2, 2 ],
91+
'order': 'row-major'
92+
});
93+
94+
var y = toSorted( x, {
95+
'dims': [ 0 ]
96+
});
97+
// returns <ndarray>[ [ -3.0, 2.0 ], [ -1.0, 4.0 ] ]
98+
```
99+
100+
To specify the output [ndarray][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes], provide a `dtype` option.
101+
102+
```javascript
103+
var array = require( '@stdlib/ndarray/array' );
104+
105+
var x = array( [ -1.0, 2.0, -3.0 ] );
106+
107+
var y = toSorted( x, {
108+
'dtype': 'float32'
109+
});
110+
// returns <ndarray>[ -3.0, -1.0, 2.0 ]
111+
```
112+
113+
#### toSorted.assign( x\[, sortOrder], out\[, options] )
114+
115+
Sorts the elements of an input [ndarray][@stdlib/ndarray/ctor] along one or more [ndarray][@stdlib/ndarray/ctor] dimensions and assigns the results to an output [ndarray][@stdlib/ndarray/ctor].
116+
117+
```javascript
118+
var zeros = require( '@stdlib/ndarray/zeros' );
119+
var array = require( '@stdlib/ndarray/array' );
120+
121+
var x = array( [ -1.0, 2.0, -3.0 ] );
122+
var y = zeros( [ 3 ] );
123+
124+
var out = toSorted.assign( x, y );
125+
// returns <ndarray>[ -3.0, -1.0, 2.0 ]
126+
127+
var bool = ( y === out );
128+
// returns true
129+
```
130+
131+
The function has the following parameters:
132+
133+
- **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
134+
- **sortOrder**: sort order (_optional_). May be either a scalar value, string, or an [ndarray][@stdlib/ndarray/ctor] having a real-valued 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).
135+
- **out**: output [ndarray][@stdlib/ndarray/ctor]. Must have a real-valued or "generic" [data type][@stdlib/ndarray/dtypes].
136+
- **options**: function options (_optional_).
137+
138+
The function accepts the following options:
139+
140+
- **dims**: list of dimensions over which to perform operation. If not provided, the function performs the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor].
141+
142+
</section>
143+
144+
<!-- /.usage -->
145+
146+
<section class="notes">
147+
148+
## Notes
149+
150+
- If `sortOrder < 0.0` or is either `'desc'` or `'descending'`, the input [ndarray][@stdlib/ndarray/ctor] is sorted in **decreasing** order. If `sortOrder > 0.0` or is either `'asc'` or `'ascending'`, the input [ndarray][@stdlib/ndarray/ctor] is sorted in **increasing** order. If `sortOrder == 0.0`, the input [ndarray][@stdlib/ndarray/ctor] is left unchanged.
151+
- 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`.
152+
- 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.
153+
- 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.
154+
155+
</section>
156+
157+
<!-- /.notes -->
158+
159+
<section class="examples">
160+
161+
## Examples
162+
163+
<!-- eslint no-undef: "error" -->
164+
165+
```javascript
166+
var discreteUniform = require( '@stdlib/random/discrete-uniform' );
167+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
168+
var toSorted = require( '@stdlib/blas/ext/to-sorted' );
169+
170+
// Generate an ndarray of random numbers:
171+
var x = discreteUniform( [ 5, 5 ], -20, 20, {
172+
'dtype': 'generic'
173+
});
174+
console.log( ndarray2array( x ) );
175+
176+
// Perform operation:
177+
var out = toSorted( x, {
178+
'dims': [ 0 ]
179+
});
180+
181+
// Print the results:
182+
console.log( ndarray2array( out ) );
183+
```
184+
185+
</section>
186+
187+
<!-- /.examples -->
188+
189+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
190+
191+
<section class="related">
192+
193+
</section>
194+
195+
<!-- /.related -->
196+
197+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
198+
199+
<section class="links">
200+
201+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray-ctor
202+
203+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/ndarray-dtypes
204+
205+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/ndarray-base-broadcast-shapes
206+
207+
</section>
208+
209+
<!-- /.links -->

‎ext/to-sorted/benchmark/benchmark.assign.js‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var isnan = require( '@stdlib/math/base/assert/is-nan' );
25+
var pow = require( '@stdlib/math/base/special/pow' );
26+
var uniform = require( '@stdlib/random/uniform' );
27+
var zeros = require( '@stdlib/ndarray/zeros' );
28+
var format = require( '@stdlib/string/format' );
29+
var pkg = require( './../package.json' ).name;
30+
var assign = require( './../lib/assign.js' );
31+
32+
33+
// VARIABLES //
34+
35+
var options = {
36+
'dtype': 'float64'
37+
};
38+
39+
40+
// FUNCTIONS //
41+
42+
/**
43+
* Creates a benchmark function.
44+
*
45+
* @private
46+
* @param {PositiveInteger} len - array length
47+
* @returns {Function} benchmark function
48+
*/
49+
function createBenchmark( len ) {
50+
var x;
51+
var y;
52+
53+
x = uniform( [ len ], -50.0, 50.0, options );
54+
y = zeros( [ len ], options );
55+
56+
return benchmark;
57+
58+
/**
59+
* Benchmark function.
60+
*
61+
* @private
62+
* @param {Benchmark} b - benchmark instance
63+
*/
64+
function benchmark( b ) {
65+
var o;
66+
var i;
67+
68+
b.tic();
69+
for ( i = 0; i < b.iterations; i++ ) {
70+
o = assign( x, ( i%2 ) ? 1 : -1, y );
71+
if ( typeof o !== 'object' ) {
72+
b.fail( 'should return an ndarray' );
73+
}
74+
}
75+
b.toc();
76+
if ( isnan( y.get( i%len ) ) ) {
77+
b.fail( 'should not return NaN' );
78+
}
79+
b.pass( 'benchmark finished' );
80+
b.end();
81+
}
82+
}
83+
84+
85+
// MAIN //
86+
87+
/**
88+
* Main execution sequence.
89+
*
90+
* @private
91+
*/
92+
function main() {
93+
var len;
94+
var min;
95+
var max;
96+
var f;
97+
var i;
98+
99+
min = 1; // 10^min
100+
max = 6; // 10^max
101+
102+
for ( i = min; i <= max; i++ ) {
103+
len = pow( 10, i );
104+
f = createBenchmark( len );
105+
bench( format( '%s:assign:dtype=%s,len=%d', pkg, options.dtype, len ), f );
106+
}
107+
}
108+
109+
main();

0 commit comments

Comments
 (0)