Skip to content

Commit 6f6df5d

Browse files
kgrytekgryte
committed
feat: add strided/base/strided2object 
1 parent 95ef049 commit 6f6df5d

File tree

10 files changed

+2116
-0
lines changed

10 files changed

+2116
-0
lines changed

‎lib/node_modules/@stdlib/strided/base/strided2object/README.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2024 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+
# strided2object
22+
23+
> Convert a strided array and associated meta data to an object likely to have the same "shape".
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 strided2object = require( '@stdlib/strided/base/strided2object' );
41+
```
42+
43+
#### strided2object( N, x, stride, offset )
44+
45+
Converts a strided array and associated meta data to an object likely to have the same "shape".
46+
47+
```javascript
48+
var obj = strided2object( 4, [ 1, 2, 3, 4 ], 1, 0 );
49+
// returns {...}
50+
```
51+
52+
</section>
53+
54+
<!-- /.usage -->
55+
56+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
57+
58+
<section class="notes">
59+
60+
## Notes
61+
62+
- The returned object has the following properties:
63+
64+
- **data**: reference to the input array.
65+
- **dtype**: input array data type. If unable to resolve the [data type][@stdlib/array/dtype] of the input array, the property value is `null`.
66+
- **length**: number of indexed elements.
67+
- **stride**: index increment.
68+
- **offset**: starting index.
69+
- **accessorProtocol**: `boolean` indicating whether the input uses accessors for getting and setting elements.
70+
- **accessors**: a two-element array whose first element is an accessor for retrieving an array element (i.e., a getter) and whose second element is an accessor for setting an array element (i.e., a setter).
71+
72+
- The getter accessor accepts two arguments:
73+
74+
- **data**: input array.
75+
- **idx**: element index.
76+
77+
- The setter accessor accepts three arguments:
78+
79+
- **data**: input array.
80+
- **idx**: element index.
81+
- **value**: value to set.
82+
83+
- 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 standardize the "shape" of the object holding strided array meta data to ensure that internal functions operating on strided arrays are provided consistent argument "shapes".
84+
85+
</section>
86+
87+
<!-- /.notes -->
88+
89+
<!-- Package usage examples. -->
90+
91+
<section class="examples">
92+
93+
## Examples
94+
95+
<!-- eslint no-undef: "error" -->
96+
97+
```javascript
98+
var Complex64Array = require( '@stdlib/array/complex64' );
99+
var strided2object = require( '@stdlib/strided/base/strided2object' );
100+
101+
// Create an array:
102+
var x = new Complex64Array( 10 );
103+
104+
// Convert to a standardized object:
105+
var obj = strided2object( x.length, x, 1, 0 );
106+
// returns {...}
107+
108+
console.log( obj );
109+
```
110+
111+
</section>
112+
113+
<!-- /.examples -->
114+
115+
<!-- 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. -->
116+
117+
<section class="references">
118+
119+
</section>
120+
121+
<!-- /.references -->
122+
123+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
124+
125+
<section class="related">
126+
127+
</section>
128+
129+
<!-- /.related -->
130+
131+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
132+
133+
<section class="links">
134+
135+
[@stdlib/array/dtype]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/dtype
136+
137+
</section>
138+
139+
<!-- /.links -->

‎lib/node_modules/@stdlib/strided/base/strided2object/benchmark/benchmark.js

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2024 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 Float64Array = require( '@stdlib/array/float64' );
25+
var zeros = require( '@stdlib/array/base/zeros' );
26+
var isCollection = require( '@stdlib/assert/is-collection' );
27+
var pkg = require( './../package.json' ).name;
28+
var strided2object = require( './../lib' );
29+
30+
31+
// MAIN //
32+
33+
bench( pkg+'::array', function benchmark( b ) {
34+
var values;
35+
var out;
36+
var i;
37+
38+
values = [
39+
zeros( 10 ),
40+
zeros( 10 ),
41+
zeros( 10 )
42+
];
43+
44+
b.tic();
45+
for ( i = 0; i < b.iterations; i++ ) {
46+
out = strided2object( 10, values[ i%values.length ], 1, 0 );
47+
if ( typeof out !== 'object' ) {
48+
b.fail( 'should return an object' );
49+
}
50+
}
51+
b.toc();
52+
if ( !isCollection( out.data ) ) {
53+
b.fail( 'should return a collection' );
54+
}
55+
b.pass( 'benchmark finished' );
56+
b.end();
57+
});
58+
59+
bench( pkg+'::typed_array', function benchmark( b ) {
60+
var values;
61+
var out;
62+
var i;
63+
64+
values = [
65+
new Float64Array( 10 ),
66+
new Float64Array( 10 ),
67+
new Float64Array( 10 )
68+
];
69+
70+
b.tic();
71+
for ( i = 0; i < b.iterations; i++ ) {
72+
out = strided2object( 10, values[ i%values.length ], 1, 0 );
73+
if ( typeof out !== 'object' ) {
74+
b.fail( 'should return an object' );
75+
}
76+
}
77+
b.toc();
78+
if ( !isCollection( out.data ) ) {
79+
b.fail( 'should return a collection' );
80+
}
81+
b.pass( 'benchmark finished' );
82+
b.end();
83+
});
84+
85+
bench( pkg+'::array_like', function benchmark( b ) {
86+
var arr;
87+
var out;
88+
var i;
89+
90+
b.tic();
91+
for ( i = 0; i < b.iterations; i++ ) {
92+
arr = {
93+
'length': i
94+
};
95+
out = strided2object( i, arr, 1, 0 );
96+
if ( typeof out !== 'object' ) {
97+
b.fail( 'should return an object' );
98+
}
99+
}
100+
b.toc();
101+
if ( !isCollection( out.data ) ) {
102+
b.fail( 'should return a collection' );
103+
}
104+
b.pass( 'benchmark finished' );
105+
b.end();
106+
});

‎lib/node_modules/@stdlib/strided/base/strided2object/docs/repl.txt

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
2+
{{alias}}( N, x, stride, offset )
3+
Converts a strided array and associated meta data to an object likely to
4+
have the same "shape".
5+
6+
The returned object has the following properties:
7+
8+
- data: reference to input array.
9+
- dtype: input array data type.
10+
- length: number of indexed elements.
11+
- stride: index increment.
12+
- offset: starting index.
13+
- accessorProtocol: boolean indicating whether the input array uses
14+
accessors for getting and setting elements.
15+
- accessors: a two-element array whose first element is an accessor for
16+
retrieving an array element and whose second element is an accessor for
17+
setting an array element.
18+
19+
The getter accessor accepts two arguments:
20+
21+
- data: data buffer.
22+
- idx: element index.
23+
24+
The setter accessor accepts three arguments:
25+
26+
- data: data buffer.
27+
- idx: element index.
28+
- value: value to set.
29+
30+
Parameters
31+
----------
32+
N: integer
33+
Number of indexed elements.
34+
35+
x: ArrayLikeObject
36+
Input strided array.
37+
38+
stride: integer
39+
Index increment.
40+
41+
offset: integer
42+
Starting index.
43+
44+
Returns
45+
-------
46+
out: Object
47+
Object containing array data.
48+
49+
out.data: ArrayLikeObject
50+
Reference to input array.
51+
52+
out.dtype: string|null
53+
Input array data type.
54+
55+
out.length: integer
56+
Number of indexed elements.
57+
58+
out.stride: integer
59+
Index increment.
60+
61+
out.offset: integer
62+
Starting index.
63+
64+
out.accessorProtocol: boolean
65+
Boolean indicating whether the input array uses accessors for getting
66+
and setting elements.
67+
68+
out.accessors: Array<Function>
69+
A two-element array whose first element is an accessor for retrieving an
70+
array element and whose second element is an accessor for setting an
71+
array element.
72+
73+
Examples
74+
--------
75+
> var out = {{alias}}( 4, [ 1, 2, 3, 4 ], 1, 0 )
76+
{...}
77+
78+
See Also
79+
--------
80+

0 commit comments

Comments
 (0)