Skip to content

Commit 7f0421e

Browse files
kgrytekgryte
committed
feat: add inital implementation of array/struct-factory
--- 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: passed - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: passed - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---
1 parent 4252199 commit 7f0421e

File tree

10 files changed

+1394
-0
lines changed

10 files changed

+1394
-0
lines changed

‎lib/node_modules/@stdlib/array/struct-factory/README.md

Lines changed: 322 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,322 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 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+
# structFactory
22+
23+
> Return a constructor for creating arrays having a fixed-width composite data type.
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 structFactory = require( '@stdlib/array/struct-factory' );
41+
```
42+
43+
#### structFactory( arg )
44+
45+
Returns a constructor for creating arrays having a fixed-width composite data type.
46+
47+
```javascript
48+
var schema = [
49+
{
50+
'name': 'beep',
51+
'type': 'float64'
52+
},
53+
{
54+
'name': 'boop',
55+
'type': 'int32'
56+
}
57+
];
58+
var StructArray = structFactory( schema );
59+
// returns <Function>
60+
```
61+
62+
The function supports the following parameters:
63+
64+
- **arg**: [`struct`][@stdlib/dstructs/struct] constructor or a [`struct`][@stdlib/dstructs/struct] schema.
65+
66+
* * *
67+
68+
### Array Constructor
69+
70+
#### StructArray()
71+
72+
TODO: add documentation of constructor
73+
74+
* * *
75+
76+
### Array Properties
77+
78+
<a name="static-prop-bytes-per-element"></a>
79+
80+
#### StructArray.BYTES_PER_ELEMENT
81+
82+
Number of bytes per view element.
83+
84+
```javascript
85+
var schema = [
86+
{
87+
'name': 'foo',
88+
'type': 'bool'
89+
}
90+
];
91+
var StructArray = structFactory( schema );
92+
93+
var nbytes = StructArray.BYTES_PER_ELEMENT;
94+
// returns 1
95+
```
96+
97+
<a name="static-prop-name"></a>
98+
99+
#### StructArray.name
100+
101+
Array constructor name.
102+
103+
```javascript
104+
var schema = [
105+
{
106+
'name': 'foo',
107+
'type': 'bool'
108+
}
109+
];
110+
var StructArray = structFactory( schema );
111+
112+
var str = StructArray.name;
113+
// returns 'StructArray'
114+
```
115+
116+
<a name="prop-buffer"></a>
117+
118+
#### StructArray.prototype.buffer
119+
120+
**Read-only** property which returns the [`ArrayBuffer`][@stdlib/array/buffer] referenced by the array.
121+
122+
```javascript
123+
var schema = [
124+
{
125+
'name': 'foo',
126+
'type': 'bool'
127+
}
128+
];
129+
var StructArray = structFactory( schema );
130+
131+
var arr = new StructArray( 5 );
132+
var buf = arr.buffer;
133+
// returns <ArrayBuffer>
134+
```
135+
136+
<a name="prop-byte-length"></a>
137+
138+
#### StructArray.prototype.byteLength
139+
140+
**Read-only** property which returns the length (in bytes) of the array.
141+
142+
```javascript
143+
var schema = [
144+
{
145+
'name': 'foo',
146+
'type': 'int32'
147+
}
148+
];
149+
var StructArray = structFactory( schema );
150+
151+
var arr = new StructArray( 5 );
152+
var byteLength = arr.byteLength;
153+
// returns 20
154+
```
155+
156+
<a name="prop-byte-offset"></a>
157+
158+
#### StructArray.prototype.byteOffset
159+
160+
**Read-only** property which returns the offset (in bytes) of the array from the start of its [`ArrayBuffer`][@stdlib/array/buffer].
161+
162+
```javascript
163+
var schema = [
164+
{
165+
'name': 'foo',
166+
'type': 'bool'
167+
}
168+
];
169+
var StructArray = structFactory( schema );
170+
171+
var arr = new StructArray( 5 );
172+
var byteOffset = arr.byteOffset;
173+
// returns 0
174+
```
175+
176+
<a name="prop-bytes-per-element"></a>
177+
178+
#### StructArray.prototype.BYTES_PER_ELEMENT
179+
180+
Number of bytes per view element.
181+
182+
```javascript
183+
var schema = [
184+
{
185+
'name': 'foo',
186+
'type': 'bool'
187+
}
188+
];
189+
var StructArray = structFactory( schema );
190+
191+
var arr = new StructArray( 5 );
192+
var nbytes = arr.BYTES_PER_ELEMENT;
193+
// returns 1
194+
```
195+
196+
<a name="prop-length"></a>
197+
198+
#### StructArray.prototype.length
199+
200+
**Read-only** property which returns the number of view elements.
201+
202+
```javascript
203+
var schema = [
204+
{
205+
'name': 'foo',
206+
'type': 'bool'
207+
}
208+
];
209+
var StructArray = structFactory( schema );
210+
211+
var arr = new StructArray( 5 );
212+
var len = arr.length;
213+
// returns 5
214+
```
215+
216+
* * *
217+
218+
### Array Methods
219+
220+
TODO: document methods
221+
222+
</section>
223+
224+
<!-- /.usage -->
225+
226+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
227+
228+
<section class="notes">
229+
230+
* * *
231+
232+
## Notes
233+
234+
- While returned constructors _strive_ to maintain (but do not **guarantee**) consistency with [typed arrays][@stdlib/array/typed], significant deviations from ECMAScript-defined [typed array][@stdlib/array/typed] behavior are as follows:
235+
236+
- Constructors do **not** require the `new` operator.
237+
- Accessing array elements using bracket syntax (e.g., `X[i]`) is **not** supported. Instead, one **must** use the `.get()` method.
238+
- Accessed array elements are a view on underlying memory. Thus, mutation of accessed elements mutates the underlying buffer.
239+
240+
- Struct arrays share several similarities with generic arrays containing objects (e.g., nested property access); however, the principal difference is that struct arrays are strongly typed and backed by fixed memory. Struct arrays are particularly well-suited for zero-copy transfer of data stored in composite data types when interoperating between JavaScript and C.
241+
242+
</section>
243+
244+
<!-- /.notes -->
245+
246+
<!-- Package usage examples. -->
247+
248+
<section class="examples">
249+
250+
## Examples
251+
252+
<!-- eslint no-undef: "error" -->
253+
254+
```javascript
255+
var factory = require( '@stdlib/array/struct-factory' );
256+
257+
// Define a schema for a composite data type for storing a student's test scores:
258+
var schema = [
259+
{
260+
'name': 'test_number',
261+
'type': 'int16'
262+
},
263+
{
264+
'name': 'pass',
265+
'type': 'bool'
266+
},
267+
{
268+
'name': 'correct',
269+
'type': 'int32'
270+
},
271+
{
272+
'name': 'incorrect',
273+
'type': 'int32'
274+
},
275+
{
276+
'name': 'percentage',
277+
'type': 'float32'
278+
}
279+
];
280+
281+
// Create an array constructor for creating composite data type arrays:
282+
var TestScoreArray = factory( schema );
283+
console.log( 'Layout: %s', TestScoreArray.struct.layout );
284+
285+
// Create a new array for storing test scores:
286+
var student1 = new TestScoreArray( 10 );
287+
console.log( 'Byte length: %d', student1.byteLength );
288+
```
289+
290+
</section>
291+
292+
<!-- /.examples -->
293+
294+
<!-- 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. -->
295+
296+
<section class="references">
297+
298+
</section>
299+
300+
<!-- /.references -->
301+
302+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
303+
304+
<section class="related">
305+
306+
</section>
307+
308+
<!-- /.related -->
309+
310+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
311+
312+
<section class="links">
313+
314+
[@stdlib/array/typed]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/typed
315+
316+
[@stdlib/array/buffer]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/buffer
317+
318+
[@stdlib/dstructs/struct]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/dstructs/struct
319+
320+
</section>
321+
322+
<!-- /.links -->

‎lib/node_modules/@stdlib/array/struct-factory/benchmark/benchmark.js

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 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 isFunction = require( '@stdlib/assert/is-function' );
25+
var structFactory = require( '@stdlib/dstructs/struct' );
26+
var pkg = require( './../package.json' ).name;
27+
var factory = require( './../lib' );
28+
29+
30+
// FIXTURES //
31+
32+
var schema = require( './fixtures/schema.json' );
33+
34+
35+
// MAIN //
36+
37+
bench( pkg, function benchmark( b ) {
38+
var Struct;
39+
var v;
40+
var i;
41+
42+
Struct = structFactory( schema );
43+
44+
b.tic();
45+
for ( i = 0; i < b.iterations; i++ ) {
46+
v = factory( Struct );
47+
if ( typeof v !== 'function' ) {
48+
b.fail( 'should return a function' );
49+
}
50+
}
51+
b.toc();
52+
if ( !isFunction( v ) ) {
53+
b.fail( 'should return a function' );
54+
}
55+
b.pass( 'benchmark finished' );
56+
b.end();
57+
});

‎lib/node_modules/@stdlib/array/struct-factory/benchmark/fixtures/schema.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[
2+
{
3+
"name": "beep",
4+
"type": "float64"
5+
},
6+
{
7+
"name": "boop",
8+
"type": "float64"
9+
}
10+
]

0 commit comments

Comments
 (0)