Skip to content

Commit 17cedf9

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 09b2c12 commit 17cedf9

12 files changed

Lines changed: 780 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,14 @@
44

55
<section class="release" id="unreleased">
66

7-
## Unreleased (2026-05-07)
7+
## Unreleased (2026-05-10)
88

99
<section class="features">
1010

1111
### Features
1212

13+
- [`0e2b5a5`](https://github.com/stdlib-js/stdlib/commit/0e2b5a5e9dec8520a7e6676876aae915c4b2ab2c) - add `descriptor` to namespace
14+
- [`b5d65f3`](https://github.com/stdlib-js/stdlib/commit/b5d65f3863b2d9bcee6f6dbfc53fff58a10380d4) - add `ndarray/base/descriptor`
1315
- [`851962b`](https://github.com/stdlib-js/stdlib/commit/851962b6ea17e9ac3d0ab09617432121e007a0ed) - add `toReversedDimensions` to namespace
1416
- [`b6e7646`](https://github.com/stdlib-js/stdlib/commit/b6e764678401a9a7eb387c0b84f2929299108bab) - add `ndarray/to-reversed-dimensions` [(#11981)](https://github.com/stdlib-js/stdlib/pull/11981)
1517
- [`e0a3342`](https://github.com/stdlib-js/stdlib/commit/e0a33421dde2803276ad95491519f8839415d93c) - add `outputOrder` to namespace
@@ -927,6 +929,8 @@ A total of 49 issues were closed in this release:
927929

928930
<details>
929931

932+
- [`0e2b5a5`](https://github.com/stdlib-js/stdlib/commit/0e2b5a5e9dec8520a7e6676876aae915c4b2ab2c) - **feat:** add `descriptor` to namespace _(by Athan Reines)_
933+
- [`b5d65f3`](https://github.com/stdlib-js/stdlib/commit/b5d65f3863b2d9bcee6f6dbfc53fff58a10380d4) - **feat:** add `ndarray/base/descriptor` _(by Athan Reines)_
930934
- [`11fb87d`](https://github.com/stdlib-js/stdlib/commit/11fb87dac7ae762d325640afbb400d6aa5fc3736) - **docs:** update namespace table of contents [(#11986)](https://github.com/stdlib-js/stdlib/pull/11986) _(by stdlib-bot)_
931935
- [`4985313`](https://github.com/stdlib-js/stdlib/commit/4985313d48f7446d5222a1f405b68546cb7c2058) - **docs:** update ToC _(by Athan Reines)_
932936
- [`851962b`](https://github.com/stdlib-js/stdlib/commit/851962b6ea17e9ac3d0ab09617432121e007a0ed) - **feat:** add `toReversedDimensions` to namespace _(by Athan Reines)_

‎base/descriptor/README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
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+
# descriptor
22+
23+
> Create a plain object describing how to interpret a data buffer as an n-dimensional array.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var descriptor = require( '@stdlib/ndarray/base/descriptor' );
41+
```
42+
43+
#### descriptor( dtype, buffer, shape, strides, offset, order )
44+
45+
Returns a plain object describing how to interpret a data buffer as an n-dimensional array.
46+
47+
```javascript
48+
var buffer = [ 1, 2, 3, 4, 5, 6 ];
49+
var shape = [ 3, 2 ];
50+
var strides = [ 2, 1 ];
51+
var offset = 0;
52+
53+
var out = descriptor( 'generic', buffer, shape, strides, offset, 'row-major' );
54+
// returns {...}
55+
```
56+
57+
The function accepts the following arguments:
58+
59+
- **dtype**: [data type][@stdlib/ndarray/dtypes].
60+
- **buffer**: data buffer.
61+
- **shape**: array shape (dimensions).
62+
- **strides**: array strides which are index offsets specifying how to access along corresponding dimensions.
63+
- **offset**: index offset specifying the location of the first indexed element in the data buffer.
64+
- **order**: array [order][@stdlib/ndarray/orders]. Must be either `row-major` (C-style) or `column-major` (Fortran-style).
65+
66+
</section>
67+
68+
<!-- /.usage -->
69+
70+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
71+
72+
<section class="notes">
73+
74+
## Notes
75+
76+
- The returned object has the following properties:
77+
78+
- **dtype**: [data type][@stdlib/ndarray/dtypes].
79+
- **buffer**: data buffer.
80+
- **shape**: array shape.
81+
- **strides**: array strides.
82+
- **offset**: index offset.
83+
- **order**: array [order][@stdlib/ndarray/orders].
84+
85+
- This function is intended as a potential performance optimization. In V8, for example, even if two objects share common properties, if those properties were added in different orders or if one object has additional properties not shared by the other object, then those objects will have different "hidden" classes. If a function is provided many objects having different "shapes", some JavaScript VMs (e.g., V8) will consider the function "megamorphic" and fail to perform various runtime optimizations. Accordingly, the intent of this function is to create an object containing the minimal amount of meta data necessary to interpret a linear data buffer as an n-dimensional array and to ensure that internal functions operating on ndarrays are provided consistent argument "shapes".
86+
87+
</section>
88+
89+
<!-- /.notes -->
90+
91+
<!-- Package usage examples. -->
92+
93+
<section class="examples">
94+
95+
## Examples
96+
97+
<!-- eslint-disable max-len -->
98+
99+
<!-- eslint no-undef: "error" -->
100+
101+
```javascript
102+
var discreteUniform = require( '@stdlib/random/discrete-uniform' );
103+
var getDType = require( '@stdlib/ndarray/dtype' );
104+
var getData = require( '@stdlib/ndarray/data-buffer' );
105+
var getShape = require( '@stdlib/ndarray/shape' );
106+
var getStrides = require( '@stdlib/ndarray/strides' );
107+
var getOffset = require( '@stdlib/ndarray/offset' );
108+
var getOrder = require( '@stdlib/ndarray/order' );
109+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
110+
var descriptor = require( '@stdlib/ndarray/base/descriptor' );
111+
112+
var x = discreteUniform( [ 3, 3 ], 0, 10, {
113+
'dtype': 'generic'
114+
});
115+
console.log( ndarray2array( x ) );
116+
117+
var obj = descriptor( getDType( x ), getData( x ), getShape( x ), getStrides( x ), getOffset( x ), getOrder( x ) );
118+
console.log( obj );
119+
```
120+
121+
</section>
122+
123+
<!-- /.examples -->
124+
125+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
126+
127+
<section class="references">
128+
129+
</section>
130+
131+
<!-- /.references -->
132+
133+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
134+
135+
<section class="related">
136+
137+
</section>
138+
139+
<!-- /.related -->
140+
141+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
142+
143+
<section class="links">
144+
145+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/ndarray/tree/main/dtypes
146+
147+
[@stdlib/ndarray/orders]: https://github.com/stdlib-js/ndarray/tree/main/orders
148+
149+
</section>
150+
151+
<!-- /.links -->

‎base/descriptor/benchmark/benchmark.js‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
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 zeroTo = require( '@stdlib/array/zero-to' );
25+
var pkg = require( './../package.json' ).name;
26+
var descriptor = require( './../lib' );
27+
28+
29+
// MAIN //
30+
31+
bench( pkg, function benchmark( b ) {
32+
var offsets;
33+
var buffer;
34+
var ord;
35+
var dt;
36+
var sh;
37+
var st;
38+
var v;
39+
var i;
40+
41+
dt = 'generic';
42+
buffer = zeroTo( 10, dt );
43+
sh = [ 2, 2 ];
44+
st = [ 2, 1 ];
45+
offsets = [
46+
0,
47+
1,
48+
2
49+
];
50+
ord = 'row-major';
51+
52+
b.tic();
53+
for ( i = 0; i < b.iterations; i++ ) {
54+
v = descriptor( dt, buffer, sh, st, offsets[ i%offsets.length ], ord );
55+
if ( typeof v !== 'object' ) {
56+
b.fail( 'should return an object' );
57+
}
58+
}
59+
b.toc();
60+
if ( typeof v !== 'object' ) {
61+
b.fail( 'should return an object' );
62+
}
63+
b.pass( 'benchmark finished' );
64+
b.end();
65+
});

‎base/descriptor/docs/repl.txt‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
2+
{{alias}}( dtype, buffer, shape, strides, offset, order )
3+
Returns a plain object describing how to interpret a data buffer as an
4+
n-dimensional array.
5+
6+
Parameters
7+
----------
8+
dtype: string|DataType
9+
Data type.
10+
11+
buffer: ArrayLikeObject|TypedArray|Buffer
12+
Data buffer. A data buffer must be an array-like object (i.e., have a
13+
`length` property). For data buffers which are not indexed collections
14+
(i.e., collections which cannot support direct index access, such as
15+
`buffer[ index ]`; e.g., Complex64Array, Complex128Array, etc), a data
16+
buffer should provide `#.get( idx )` and `#.set( v[, idx] )` methods.
17+
Note that, for `set` methods, the value to set should be the first
18+
argument, followed by the linear index, similar to the native typed
19+
array `set` method.
20+
21+
shape: ArrayLikeObject<integer>
22+
Array shape.
23+
24+
strides: ArrayLikeObject<integer>
25+
Array strides.
26+
27+
offset: integer
28+
Index offset.
29+
30+
order: string
31+
Specifies whether an array is row-major (C-style) or column-major
32+
(Fortran-style).
33+
34+
Returns
35+
-------
36+
out: object
37+
ndarray descriptor.
38+
39+
out.dtype: string|DataType
40+
Data type.
41+
42+
out.data: ArrayLikeObject|TypedArray|Buffer
43+
Data buffer.
44+
45+
out.shape: ArrayLikeObject<integer>
46+
Array shape.
47+
48+
out.strides: ArrayLikeObject<integer>
49+
Array strides.
50+
51+
out.offset: integer
52+
Index offset.
53+
54+
out.order: string
55+
Array order.
56+
57+
Examples
58+
--------
59+
// Create an ndarray:
60+
> var x = {{alias:@stdlib/random/discrete-uniform}}( [ 2, 2 ], 0, 10 )
61+
<ndarray>
62+
63+
// Resolve ndarray properties:
64+
> var dt = {{alias:@stdlib/ndarray/dtype}}( x );
65+
> var buf = {{alias:@stdlib/ndarray/data-buffer}}( x );
66+
> var sh = {{alias:@stdlib/ndarray/shape}}( x );
67+
> var st = {{alias:@stdlib/ndarray/strides}}( x );
68+
> var o = {{alias:@stdlib/ndarray/offset}}( x );
69+
> var ord = {{alias:@stdlib/ndarray/order}}( x );
70+
71+
// Create a descriptor object:
72+
> var obj = {{alias}}( dt, buf, sh, st, o, ord )
73+
{...}
74+
75+
See Also
76+
--------
77+

‎base/descriptor/docs/types/index.d.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
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+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
import { Collection } from '@stdlib/types/array';
24+
import { DataType, Order, Shape, Strides, Descriptor } from '@stdlib/types/ndarray';
25+
import { Buffer } from 'buffer';
26+
27+
/**
28+
* Returns a plain object describing how to interpret a data buffer as an n-dimensional array.
29+
*
30+
* @param dtype - data type
31+
* @param buffer - data buffer
32+
* @param shape - array shape
33+
* @param strides - array strides
34+
* @param offset - index offset
35+
* @param order - specifies whether an array is row-major (C-style) or column-major (Fortran-style)
36+
* @returns ndarray descriptor
37+
*
38+
* @example
39+
* var buffer = [ 1, 2, 3, 4, 5, 6 ];
40+
* var shape = [ 3, 2 ];
41+
* var strides = [ 2, 1 ];
42+
* var offset = 0;
43+
*
44+
* var out = descriptor( 'generic', buffer, shape, strides, offset, 'row-major' );
45+
* // returns {...}
46+
*/
47+
declare function descriptor( dtype: DataType, buffer: Collection | Buffer, shape: Shape, strides: Strides, offset: number, order: Order ): Descriptor;
48+
49+
50+
// EXPORTS //
51+
52+
export = descriptor;

0 commit comments

Comments
 (0)