Skip to content

Commit 910fed5

Browse files
kgrytekgryte
committed
feat: add ndarray/empty
This commit adds support for creating an uninitialized ndarray having a specified shape and dtype.
1 parent e618407 commit 910fed5

22 files changed

Lines changed: 3524 additions & 0 deletions

‎lib/node_modules/@stdlib/ndarray/empty/README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2023 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+
# empty
22+
23+
> Create an uninitialized [ndarray][@stdlib/ndarray/ctor] having a specified shape and [data type][@stdlib/ndarray/dtypes].
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 empty = require( '@stdlib/ndarray/empty' );
41+
```
42+
43+
#### empty( shape\[, options] )
44+
45+
Creates an uninitialized [ndarray][@stdlib/ndarray/ctor] having a specified shape and [data type][@stdlib/ndarray/dtypes].
46+
47+
```javascript
48+
var arr = empty( [ 2, 2 ] );
49+
// returns <ndarray>
50+
51+
var sh = arr.shape;
52+
// returns [ 2, 2 ]
53+
54+
var dt = arr.dtype;
55+
// returns 'float64'
56+
```
57+
58+
The specified output [ndarray][@stdlib/ndarray/ctor] `shape` may be either an array-like object or an integer value.
59+
60+
```javascript
61+
var arr = empty( 2 );
62+
// returns <ndarray>
63+
64+
var sh = arr.shape;
65+
// returns [ 2 ]
66+
67+
var dt = arr.dtype;
68+
// returns 'float64'
69+
```
70+
71+
The function accepts the following `options`:
72+
73+
- **dtype**: underlying [data type][@stdlib/ndarray/dtypes]. Default: `'float64'`.
74+
- **order**: specifies whether an [ndarray][@stdlib/ndarray/ctor] is `'row-major'` (C-style) or `'column-major'` (Fortran-style). Default: `'row-major'`.
75+
- **mode**: specifies how to handle indices which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). Default: `'throw'`.
76+
- **submode**: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). If provided fewer modes than dimensions, the constructor recycles modes using modulo arithmetic. Default: `[ options.mode ]`.
77+
78+
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having a [`float64`][@stdlib/ndarray/dtypes] data type. To specify an alternative [data type][@stdlib/ndarray/dtypes], provide a `dtype` option.
79+
80+
```javascript
81+
var arr = empty( [ 2, 2 ], {
82+
'dtype': 'float32'
83+
});
84+
// returns <ndarray>
85+
86+
var sh = arr.shape;
87+
// returns [ 2, 2 ]
88+
89+
var dt = arr.dtype;
90+
// returns 'float32'
91+
```
92+
93+
</section>
94+
95+
<!-- /.usage -->
96+
97+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
98+
99+
<section class="notes">
100+
101+
## Notes
102+
103+
- If the `dtype` option is `'generic'`, the function always returns a zero-filled array.
104+
- For returned [ndarrays][@stdlib/ndarray/ctor] whose underlying memory is **not** initialized, memory contents are unknown and may contain **sensitive** data.
105+
106+
</section>
107+
108+
<!-- /.notes -->
109+
110+
<!-- Package usage examples. -->
111+
112+
<section class="examples">
113+
114+
## Examples
115+
116+
<!-- eslint no-undef: "error" -->
117+
118+
```javascript
119+
var dtypes = require( '@stdlib/ndarray/dtypes' );
120+
var empty = require( '@stdlib/ndarray/empty' );
121+
122+
// Get a list of data types:
123+
var dt = dtypes();
124+
125+
// Generate uninitialized arrays...
126+
var arr;
127+
var i;
128+
for ( i = 0; i < dt.length; i++ ) {
129+
arr = empty( [ 2, 2 ], {
130+
'dtype': dt[ i ]
131+
});
132+
console.log( arr.data );
133+
}
134+
```
135+
136+
</section>
137+
138+
<!-- /.examples -->
139+
140+
<!-- 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. -->
141+
142+
<section class="references">
143+
144+
</section>
145+
146+
<!-- /.references -->
147+
148+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
149+
150+
<section class="related">
151+
152+
</section>
153+
154+
<!-- /.related -->
155+
156+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
157+
158+
<section class="links">
159+
160+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib
161+
162+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib
163+
164+
</section>
165+
166+
<!-- /.links -->

0 commit comments

Comments
 (0)