Skip to content

Commit e484f42

Browse files
kgrytekgryte
committed
feat: add array/base/nested2views
--- 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: passed - 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: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed ---
1 parent f389a19 commit e484f42

File tree

10 files changed

+922
-0
lines changed

10 files changed

+922
-0
lines changed

‎lib/node_modules/@stdlib/array/base/nested2views/README.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
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+
# nested2views
22+
23+
> Convert nested arrays to composite views.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var nested2views = require( '@stdlib/array/base/nested2views' );
31+
```
32+
33+
#### nested2views( arr, fields )
34+
35+
Converts each nested array to a composite view.
36+
37+
```javascript
38+
var x = [ [ 1, 2 ], [ 3, 4 ] ];
39+
var fields = [ 'x', 'y' ];
40+
41+
var out = nested2views( x, fields );
42+
// returns [ <Object>, <Object> ]
43+
44+
var v0 = out[ 0 ].toJSON();
45+
// returns { 'x': 1, 'y': 2 }
46+
47+
var v1 = out[ 1 ].toJSON();
48+
// returns { 'x': 3, 'y': 4 }
49+
50+
// Mutate the first nested array:
51+
x[ 0 ][ 0 ] = 5;
52+
53+
v0 = out[ 0 ].toJSON();
54+
// returns { 'x': 5, 'y': 2 }
55+
56+
// Set a view property:
57+
out[ 1 ].y = 'beep';
58+
59+
v1 = out[ 1 ].toJSON();
60+
// returns { 'x': 3, 'y': 'beep' }
61+
62+
var y = x.slice();
63+
// returns [ [ 5, 2 ], [ 3, 'beep' ] ]
64+
```
65+
66+
The function supports the following parameters:
67+
68+
- **arr**: input array.
69+
- **fields**: list of field names.
70+
71+
Each element in the returned array is a class instance having prototype properties corresponding to the list of field names. As demonstrated in the example above, to convert an element to a regular object, invoke an element's `toJSON` method. Note, however, that the object returned by an element's `toJSON` method no longer shares the same memory as the provided input array.
72+
73+
</section>
74+
75+
<!-- /.usage -->
76+
77+
<section class="notes">
78+
79+
- The function assumes that all nested arrays have the same length.
80+
- The number of provided array labels should equal the length of each nested array.
81+
- Each view in the returned array shares the same memory as the corresponding element in the input array. Accordingly, mutation of either a nested array or a view will mutate the other.
82+
83+
</section>
84+
85+
<!-- /.notes -->
86+
87+
<section class="examples">
88+
89+
## Examples
90+
91+
<!-- eslint no-undef: "error" -->
92+
93+
```javascript
94+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
95+
var filled2dBy = require( '@stdlib/array/base/filled2d-by' );
96+
var nested2views = require( '@stdlib/array/base/nested2views' );
97+
98+
var x = filled2dBy( [ 10, 2 ], discreteUniform( -100, 100 ) );
99+
var fields = [ 'x', 'y' ];
100+
101+
var out = nested2views( x, fields );
102+
// returns [...]
103+
```
104+
105+
</section>
106+
107+
<!-- /.examples -->
108+
109+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
110+
111+
<section class="related">
112+
113+
</section>
114+
115+
<!-- /.related -->
116+
117+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
118+
119+
<section class="links">
120+
121+
</section>
122+
123+
<!-- /.links -->

‎lib/node_modules/@stdlib/array/base/nested2views/benchmark/benchmark.js

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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 isArray = require( '@stdlib/assert/is-array' );
25+
var filled2d = require( '@stdlib/array/base/filled2d' );
26+
var pkg = require( './../package.json' ).name;
27+
var nested2views = require( './../lib' );
28+
29+
30+
// MAIN //
31+
32+
bench( pkg+':size=100', function benchmark( b ) {
33+
var fields;
34+
var x;
35+
var i;
36+
var v;
37+
38+
fields = [ 'x', 'y' ];
39+
x = filled2d( 10, [ 10, 10 ] );
40+
41+
b.tic();
42+
for ( i = 0; i < b.iterations; i++ ) {
43+
v = nested2views( x, fields );
44+
if ( typeof v !== 'object' ) {
45+
b.fail( 'should return an array' );
46+
}
47+
}
48+
b.toc();
49+
if ( !isArray( v ) ) {
50+
b.fail( 'should return an array' );
51+
}
52+
b.pass( 'benchmark finished' );
53+
b.end();
54+
});

‎lib/node_modules/@stdlib/array/base/nested2views/docs/repl.txt

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
2+
{{alias}}( arr, fields )
3+
Converts each nested array to a composite view.
4+
5+
The function assumes that all nested arrays have the same length.
6+
7+
The number of provided array labels should equal the length of each nested
8+
array.
9+
10+
Each view in the returned array shares the same memory as the corresponding
11+
elements in the input arrays. Accordingly, mutation of either a nested array
12+
or a view will mutate the other.
13+
14+
Parameters
15+
----------
16+
arr: ArrayLikeObject<ArrayLikeObject>
17+
Input array containing nested arrays.
18+
19+
fields: ArrayLikeObject
20+
List of field names.
21+
22+
Returns
23+
-------
24+
out: Array<Object>
25+
Output array.
26+
27+
Examples
28+
--------
29+
> var x = [ [ 1, 2 ], [ 3, 4 ] ];
30+
> var f = [ 'x', 'y' ];
31+
> var out = {{alias}}( x, f );
32+
> var v = out[ 0 ].toJSON()
33+
{ 'x': 1, 'y': 2 }
34+
> v = out[ 1 ].toJSON()
35+
{ 'x': 3, 'y': 4 }
36+
37+
See Also
38+
--------
39+

‎lib/node_modules/@stdlib/array/base/nested2views/docs/types/index.d.ts

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
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+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
import { Collection, AccessorArrayLike, ArrayLike } from '@stdlib/types/array';
24+
25+
/**
26+
* Property key.
27+
*/
28+
type PropertyKey = string | number | symbol;
29+
30+
/**
31+
* Converts each nested array to a composite view.
32+
*
33+
* ## Notes
34+
*
35+
* - The function assumes that all nested arrays have the same length.
36+
* - The number of provided array labels should equal the length of each nested array.
37+
* - Each view in the returned array shares the same memory as the corresponding elements in the input arrays. Accordingly, mutation of either a nested array or a view will mutate the other.
38+
*
39+
* @param arr - input array
40+
* @param fields - list of field names
41+
* @returns output array
42+
*
43+
* @example
44+
* var x = [ [ 1, 2 ], [ 3, 4 ] ];
45+
* var fields = [ 'x', 'y' ];
46+
*
47+
* var out = nested2views( x, fields );
48+
* // returns [ <Object>, <Object> ]
49+
*
50+
* var v0 = out[ 0 ].toJSON();
51+
* // returns { 'x': 1, 'y': 2 }
52+
*
53+
* var v1 = out[ 1 ].toJSON();
54+
* // returns { 'x': 3, 'y': 4 }
55+
*
56+
* // Mutate the first nested array:
57+
* x[ 0 ][ 0 ] = 5;
58+
*
59+
* v0 = out[ 0 ].toJSON();
60+
* // returns { 'x': 5, 'y': 2 }
61+
*
62+
* // Set a view property:
63+
* out[ 1 ].y = 'beep';
64+
*
65+
* v1 = out[ 1 ].toJSON();
66+
* // returns { 'x': 3, 'y': 'beep' }
67+
*
68+
* var y = x.slice();
69+
* // returns [ [ 5, 2 ], [ 3, 'beep' ] ]
70+
*/
71+
declare function nested2views<T = unknown, U extends PropertyKey = PropertyKey>( arr: ArrayLike<Collection<T> | AccessorArrayLike<T>>, fields: Collection<U> | AccessorArrayLike<U> ): Array<Record<U, T>>;
72+
73+
74+
// EXPORTS //
75+
76+
export = nested2views;

‎lib/node_modules/@stdlib/array/base/nested2views/docs/types/test.ts

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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+
import nested2views = require( './index' );
20+
21+
22+
// TESTS //
23+
24+
// The function returns an array of objects...
25+
{
26+
nested2views( [ [ 1, 2 ] ], [ 'x', 'y' ] ); // $ExpectType Record<"x" | "y", number>[]
27+
}
28+
29+
// The compiler throws an error if the function is provided a first argument which is not an array-like object...
30+
{
31+
nested2views( 1, [ 'x', 'y' ] ); // $ExpectError
32+
nested2views( true, [ 'x', 'y' ] ); // $ExpectError
33+
nested2views( false, [ 'x', 'y' ] ); // $ExpectError
34+
nested2views( null, [ 'x', 'y' ] ); // $ExpectError
35+
nested2views( void 0, [ 'x', 'y' ] ); // $ExpectError
36+
nested2views( {}, [ 'x', 'y' ] ); // $ExpectError
37+
}
38+
39+
// The compiler throws an error if the function is provided a second argument which is not an array-like object...
40+
{
41+
nested2views( [], 1 ); // $ExpectError
42+
nested2views( [], true ); // $ExpectError
43+
nested2views( [], false ); // $ExpectError
44+
nested2views( [], null ); // $ExpectError
45+
nested2views( [], void 0 ); // $ExpectError
46+
nested2views( [], {} ); // $ExpectError
47+
}
48+
49+
// The compiler throws an error if the function is provided an unsupported number of arguments...
50+
{
51+
nested2views(); // $ExpectError
52+
nested2views( [] ); // $ExpectError
53+
nested2views( [], [], [] ); // $ExpectError
54+
}

‎lib/node_modules/@stdlib/array/base/nested2views/examples/index.js

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
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+
var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory;
22+
var filled2dBy = require( '@stdlib/array/base/filled2d-by' );
23+
var nested2views = require( './../lib' );
24+
25+
var x = filled2dBy( [ 10, 2 ], discreteUniform( -100, 100 ) );
26+
var fields = [ 'x', 'y' ];
27+
28+
var out = nested2views( x, fields );
29+
console.log( out );
30+
// => [...]

0 commit comments

Comments
 (0)