Skip to content

Commit 13b4d50

Browse files
kgrytekgryte
committed
feat: add initial implementation of dstructs/struct
--- 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: na - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---
1 parent ae5f230 commit 13b4d50

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+4721
-0
lines changed

‎lib/node_modules/@stdlib/dstructs/struct/README.md

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
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+
# struct
22+
23+
> Fixed-width composite data type (a.k.a., a `struct`).
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 struct = require( '@stdlib/dstructs/struct' );
41+
```
42+
43+
#### struct( schema )
44+
45+
Returns a constructor for creating a fixed-width composite data type (a.k.a., a `struct`).
46+
47+
```javascript
48+
var fields = [
49+
{
50+
'type': 'union',
51+
'fields': [
52+
{
53+
'name': 'double',
54+
'description': 'double-precision floating-point number',
55+
'type': 'float64',
56+
'enumerable': true,
57+
'writable': true,
58+
'castingMode': 'none'
59+
},
60+
{
61+
'name': 'words',
62+
'description': 'high and low words',
63+
'type': 'uint32',
64+
'length': 2,
65+
'enumerable': true,
66+
'writable': true,
67+
'castingMode': 'none'
68+
}
69+
]
70+
}
71+
];
72+
var Struct = struct( fields );
73+
74+
var data = {
75+
'double': 3.14
76+
};
77+
var s = new Struct( data );
78+
// returns <Struct>
79+
80+
var v = s.double;
81+
// returns 3.14
82+
83+
var w = s.words;
84+
// e.g., <Uint32Array>[ 1374389535, 1074339512 ]
85+
```
86+
87+
TODO: document schema
88+
89+
TODO: document constructor API
90+
91+
</section>
92+
93+
<!-- /.usage -->
94+
95+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
96+
97+
<section class="notes">
98+
99+
## Notes
100+
101+
- While struct instances aim to emulate C `struct` behavior, structs have the following differences:
102+
103+
- The struct schema supports default values. In C, uninitialized members are zero-filled.
104+
- Only fixed-width types are supported (e.g., `int8`, `float64`, etc). In C, members can have types which may vary across platforms (e.g., `int`).
105+
- Member types must be serializable to an ArrayBuffer (e.g., no functions, general objects, etc). In C, members have no such limitations (e.g., a member can be a function pointer).
106+
- Union types must all have the same byte length. In C, members of union types can have different byte lengths.
107+
- struct instances can have "hidden" (i.e., non-enumerable) fields. In C, all members are part of a `struct`'s public API.
108+
- struct instances can have read-only fields. In C, one can use a `const` qualifier to prevent assignment after initialization; however, one can circumvent this restriction using pointer tricks.
109+
- Member types can have an associated description, which is useful when wanting to inspect struct instances in interactive contexts, such as REPLs.
110+
- struct instances support string and JSON serialization.
111+
112+
</section>
113+
114+
<!-- /.notes -->
115+
116+
<!-- Package usage examples. -->
117+
118+
<section class="examples">
119+
120+
## Examples
121+
122+
<!-- eslint no-undef: "error" -->
123+
124+
```javascript
125+
var Float64Array = require( '@stdlib/array/float64' );
126+
var struct = require( '@stdlib/dstructs/struct' );
127+
128+
var fields = [
129+
{
130+
'name': 'rejected',
131+
'description': 'boolean indicating whether the null hypothesis was rejected',
132+
'type': 'bool',
133+
'enumerable': true,
134+
'writable': false,
135+
'castingMode': 'none'
136+
},
137+
{
138+
'name': 'alpha',
139+
'description': 'significance level',
140+
'type': 'float64',
141+
'enumerable': true,
142+
'writable': false,
143+
'castingMode': 'mostly-safe'
144+
},
145+
{
146+
'name': 'pValue',
147+
'description': 'p-value',
148+
'type': 'float64',
149+
'enumerable': true,
150+
'writable': false,
151+
'castingMode': 'mostly-safe'
152+
},
153+
{
154+
'name': 'statistic',
155+
'description': 'test statistic',
156+
'type': 'float64',
157+
'writable': false,
158+
'castingMode': 'mostly-safe'
159+
},
160+
{
161+
'name': 'ci',
162+
'description': 'confidence interval',
163+
'type': 'float64',
164+
'length': 2,
165+
'enumerable': true,
166+
'writable': false,
167+
'castingMode': 'mostly-safe'
168+
},
169+
{
170+
'name': 'df',
171+
'description': 'degrees of freedom',
172+
'type': 'int32',
173+
'enumerable': true,
174+
'writable': false,
175+
'castingMode': 'mostly-safe'
176+
},
177+
{
178+
'name': 'nullValue',
179+
'description': 'null value',
180+
'type': 'float64',
181+
'enumerable': true,
182+
'writable': false,
183+
'castingMode': 'mostly-safe'
184+
},
185+
{
186+
'name': 'mean',
187+
'description': 'computed mean',
188+
'type': 'float64',
189+
'enumerable': true,
190+
'writable': false,
191+
'castingMode': 'mostly-safe'
192+
},
193+
{
194+
'name': 'sd',
195+
'description': 'standard error of the mean',
196+
'type': 'float64',
197+
'enumerable': true,
198+
'writable': false,
199+
'castingMode': 'mostly-safe'
200+
}
201+
];
202+
203+
var Struct = struct( fields );
204+
205+
var s = new Struct({
206+
'rejected': true,
207+
'alpha': 0.05,
208+
'pValue': 0.01,
209+
'statistic': 3.14,
210+
'ci': new Float64Array( [ -5.0, 5.0 ] ),
211+
'df': 10,
212+
'nullValue': 1.0,
213+
'mean': 1.01,
214+
'sd': 0.025
215+
});
216+
// returns <Struct>
217+
218+
var byteLength = Struct.byteLength;
219+
console.log( 'Byte length: %d', byteLength );
220+
221+
var alignment = Struct.alignment;
222+
console.log( 'Alignment: %d', alignment );
223+
224+
var names = Struct.fields;
225+
console.log( 'Field names: %s', names.join( ', ' ) );
226+
227+
var str = s.toString({
228+
'format': 'linear'
229+
});
230+
console.log( 'String:\n%s', str );
231+
232+
var o = s.toJSON();
233+
console.log( o );
234+
235+
var offset = Struct.byteOffsetOf( 'alpha' );
236+
console.log( 'Offset: %d', offset );
237+
238+
var desc = Struct.descriptionOf( 'alpha' );
239+
console.log( 'Description: %s', desc );
240+
```
241+
242+
</section>
243+
244+
<!-- /.examples -->
245+
246+
<!-- 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. -->
247+
248+
<section class="references">
249+
250+
</section>
251+
252+
<!-- /.references -->
253+
254+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
255+
256+
<section class="related">
257+
258+
</section>
259+
260+
<!-- /.related -->
261+
262+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
263+
264+
<section class="links">
265+
266+
</section>
267+
268+
<!-- /.links -->

0 commit comments

Comments
 (0)