Skip to content

Commit 82f105c

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/broadcast-scalar-like
PR-URL: #11630 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Ref: stdlib-js/metr-issue-tracker#277
1 parent b7f85c2 commit 82f105c

10 files changed

Lines changed: 2703 additions & 0 deletions

File tree

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

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
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+
# broadcastScalarLike
22+
23+
> Broadcast a scalar value to an [ndarray][@stdlib/ndarray/ctor] having the same shape and [data-type][@stdlib/ndarray/dtypes] as a provided input [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 broadcastScalarLike = require( '@stdlib/ndarray/broadcast-scalar-like' );
41+
```
42+
43+
#### broadcastScalarLike( x, value\[, options] )
44+
45+
Broadcasts a scalar value to an [ndarray][@stdlib/ndarray/ctor] having the same shape and [data-type][@stdlib/ndarray/dtypes] as a provided input [ndarray][@stdlib/ndarray/ctor].
46+
47+
```javascript
48+
var getDType = require( '@stdlib/ndarray/dtype' );
49+
var empty = require( '@stdlib/ndarray/empty' );
50+
51+
var x = empty( [ 2, 2 ], {
52+
'dtype': 'float32'
53+
});
54+
// returns <ndarray>
55+
56+
var y = broadcastScalarLike( x, 1.0 );
57+
// returns <ndarray>[ [ 1.0, 1.0 ], [ 1.0, 1.0 ] ]
58+
59+
var dt = String( getDType( y ) );
60+
// returns 'float32'
61+
```
62+
63+
The function accepts the following arguments:
64+
65+
- **x**: input [ndarray][@stdlib/ndarray/ctor].
66+
- **value**: scalar value.
67+
68+
The function accepts the following options:
69+
70+
- **dtype**: output array [data type][@stdlib/ndarray/dtypes]. By default, the output array has the same [data type][@stdlib/ndarray/dtypes] as the provided input ndarray.
71+
- **shape**: output array shape. By default, the output array has the same shape as the provided input ndarray.
72+
- **order**: array order (i.e., memory layout). Must be either `row-major` (C-style) or `column-major` (Fortran-style). By default, the output array has the same order as the provided input ndarray.
73+
- **readonly**: boolean indicating whether an array should be **read-only**. Default: `false`.
74+
75+
To explicitly specify the [data type][@stdlib/ndarray/dtypes] of the returned [ndarray][@stdlib/ndarray/ctor], provide a `dtype` option.
76+
77+
```javascript
78+
var getDType = require( '@stdlib/ndarray/dtype' );
79+
var zeros = require( '@stdlib/ndarray/zeros' );
80+
81+
var x = zeros( [ 2, 2 ] );
82+
// returns <ndarray>[ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ]
83+
84+
var y = broadcastScalarLike( x, 1.0, {
85+
'dtype': 'float32'
86+
});
87+
// returns <ndarray>[ [ 1.0, 1.0 ], [ 1.0, 1.0 ] ]
88+
89+
var dt = String( getDType( y ) );
90+
// returns 'float32'
91+
```
92+
93+
To explicitly specify the shape of the returned [ndarray][@stdlib/ndarray/ctor], provide a `shape` option.
94+
95+
```javascript
96+
var zeros = require( '@stdlib/ndarray/zeros' );
97+
98+
var x = zeros( [ 2, 2 ] );
99+
// returns <ndarray>[ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ]
100+
101+
var y = broadcastScalarLike( x, 1.0, {
102+
'shape': [ 3, 3 ]
103+
});
104+
// returns <ndarray>[ [ 1.0, 1.0, 1.0 ], [ 1.0, 1.0, 1.0 ], [ 1.0, 1.0, 1.0 ] ]
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 the resolved [data type][@stdlib/ndarray/dtypes] is a complex [data type][@stdlib/ndarray/dtypes], the function returns an [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 resolved [data type][@stdlib/ndarray/dtypes] 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 broadcastScalarLike = require( '@stdlib/ndarray/broadcast-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 broadcasted arrays...
144+
var y;
145+
var i;
146+
for ( i = 0; i < dt.length; i++ ) {
147+
y = broadcastScalarLike( x, i, {
148+
'dtype': dt[ i ]
149+
});
150+
console.log( y.get( 0, 1 ) );
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+
<!-- <related-links> -->
183+
184+
<!-- </related-links> -->
185+
186+
</section>
187+
188+
<!-- /.links -->

0 commit comments

Comments
 (0)