Skip to content

Commit 2b0c11f

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/from-scalar-like
PR-URL: #9940 Closes: stdlib-js/metr-issue-tracker#168 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com>
1 parent 793a38c commit 2b0c11f

File tree

10 files changed

+2753
-0
lines changed

10 files changed

+2753
-0
lines changed

‎lib/node_modules/@stdlib/ndarray/from-scalar-like/README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 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+
# scalar2ndarrayLike
22+
23+
> Convert a scalar value to a zero-dimensional [ndarray][@stdlib/ndarray/ctor] having the same [data-type][@stdlib/ndarray/dtypes] as a provided [ndarray][@stdlib/ndarray/ctor].
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 scalar2ndarrayLike = require( '@stdlib/ndarray/from-scalar-like' );
41+
```
42+
43+
#### scalar2ndarrayLike( x, value\[, options] )
44+
45+
Converts a scalar value to a zero-dimensional [ndarray][@stdlib/ndarray/ctor] having the same [data-type][@stdlib/ndarray/dtypes] as a provided [ndarray][@stdlib/ndarray/ctor]
46+
47+
```javascript
48+
var Float64Array = require( '@stdlib/array/float64' );
49+
var getShape = require( '@stdlib/ndarray/shape' );
50+
var getDType = require( '@stdlib/ndarray/dtype' );
51+
var array = require( '@stdlib/ndarray/array' );
52+
53+
var x = array( new Float64Array( [ 1.0, 2.0, 3.0 ] ) );
54+
// returns <ndarray>[ 1.0, 2.0, 3.0 ]
55+
56+
var out = scalar2ndarrayLike( x, 1.0 );
57+
// returns <ndarray>[ 1.0 ]
58+
59+
var sh = getShape( out );
60+
// returns []
61+
62+
var dt = String( getDType( out ) );
63+
// returns 'float64'
64+
```
65+
66+
The function accepts the following arguments:
67+
68+
- **x**: input [ndarray][@stdlib/ndarray/ctor].
69+
- **value**: scalar value.
70+
71+
The function accepts the following options:
72+
73+
- **dtype**: output array [data type][@stdlib/ndarray/dtypes].
74+
- **order**: array order (i.e., memory layout), which is either `row-major` (C-style) or `column-major` (Fortran-style).
75+
- **readonly**: boolean indicating whether an array should be **read-only**. Default: `false`.
76+
77+
If a `dtype` option is not provided and `value`
78+
79+
- is a number, the default [data type][@stdlib/ndarray/dtypes] is the [default][@stdlib/ndarray/defaults] real-valued floating-point data type.
80+
- is a boolean, the default [data type][@stdlib/ndarray/dtypes] is the [default][@stdlib/ndarray/defaults] boolean data type.
81+
- is a complex number object of a known data type, the data type is the same as the provided value.
82+
- is a complex number object of an unknown data type, the default [data type][@stdlib/ndarray/dtypes] is the [default][@stdlib/ndarray/defaults] complex-valued floating-point data type.
83+
- is any other value type, the default [data type][@stdlib/ndarray/dtypes] is `'generic'`.
84+
85+
To explicitly specify the [data type][@stdlib/ndarray/dtypes] of the returned [ndarray][@stdlib/ndarray/ctor], provide a `dtype` option.
86+
87+
```javascript
88+
var getShape = require( '@stdlib/ndarray/shape' );
89+
var getDType = require( '@stdlib/ndarray/dtype' );
90+
var array = require( '@stdlib/ndarray/array' );
91+
92+
var x = array( [ 1.0, 2.0, 3.0 ] );
93+
// returns <ndarray>[ 1.0, 2.0, 3.0 ]
94+
95+
var out = scalar2ndarrayLike( x, 1.0, {
96+
'dtype': 'float32'
97+
});
98+
// returns <ndarray>[ 1.0 ]
99+
100+
var sh = getShape( out );
101+
// returns []
102+
103+
var dt = String( getDType( out ) );
104+
// returns 'float32'
105+
```
106+
107+
</section>
108+
109+
<!-- /.usage -->
110+
111+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
112+
113+
<section class="notes">
114+
115+
## Notes
116+
117+
- If `value` is a number and `options.dtype` is a complex [data type][@stdlib/ndarray/dtypes], the function returns a zero-dimensional [ndarray][@stdlib/ndarray/ctor] containing a complex number whose real component equals the provided scalar `value` and whose imaginary component is zero.
118+
- The function does not guard against precision loss when `value` is a number and the `dtype` argument is an integer [data type][@stdlib/ndarray/dtypes].
119+
120+
</section>
121+
122+
<!-- /.notes -->
123+
124+
<!-- Package usage examples. -->
125+
126+
<section class="examples">
127+
128+
## Examples
129+
130+
<!-- eslint no-undef: "error" -->
131+
132+
```javascript
133+
var dtypes = require( '@stdlib/ndarray/dtypes' );
134+
var empty = require( '@stdlib/ndarray/empty' );
135+
var scalar2ndarrayLike = require( '@stdlib/ndarray/from-scalar-like' );
136+
137+
// Get a list of data types:
138+
var dt = dtypes( 'integer_and_generic' );
139+
140+
// Create an input array:
141+
var x = empty( [ 2, 2 ] );
142+
143+
// Generate zero-dimensional arrays...
144+
var y;
145+
var i;
146+
for ( i = 0; i < dt.length; i++ ) {
147+
y = scalar2ndarrayLike( x, i, {
148+
'dtype': dt[ i ]
149+
});
150+
console.log( y.get() );
151+
}
152+
```
153+
154+
</section>
155+
156+
<!-- /.examples -->
157+
158+
<!-- 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. -->
159+
160+
<section class="references">
161+
162+
</section>
163+
164+
<!-- /.references -->
165+
166+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
167+
168+
<section class="related">
169+
170+
</section>
171+
172+
<!-- /.related -->
173+
174+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
175+
176+
<section class="links">
177+
178+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
179+
180+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
181+
182+
[@stdlib/ndarray/defaults]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/defaults
183+
184+
<!-- <related-links> -->
185+
186+
<!-- </related-links> -->
187+
188+
</section>
189+
190+
<!-- /.links -->

0 commit comments

Comments
 (0)