Skip to content

Commit 8e8e3a4

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/with
PR-URL: #7971 Ref: #2656 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]>
1 parent 4c3f5bb commit 8e8e3a4

File tree

10 files changed

+868
-0
lines changed

10 files changed

+868
-0
lines changed

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

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
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+
# ndarrayWith
22+
23+
> Return a new [ndarray][@stdlib/ndarray/ctor] with the element at a specified index replaced by a provided value.
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 ndarrayWith = require( '@stdlib/ndarray/with' );
41+
```
42+
43+
#### ndarrayWith( x, indices, value )
44+
45+
Returns a new [ndarray][@stdlib/ndarray/ctor] with the element at a specified index replaced by a provided value.
46+
47+
```javascript
48+
var zeros = require( '@stdlib/ndarray/zeros' );
49+
50+
var x = zeros( [ 2, 2 ], {
51+
'dtype': 'float64'
52+
});
53+
// returns <ndarray>
54+
55+
var out = ndarrayWith( x, [ 0, 0 ], 1.0 );
56+
// returns <ndarray>
57+
58+
var v = out.get( 0, 0 );
59+
// returns 1.0
60+
```
61+
62+
The function accepts the following arguments:
63+
64+
- **x**: input [ndarray][@stdlib/ndarray/ctor].
65+
- **indices**: indices of the element to replace.
66+
- **value**: replacement value.
67+
68+
</section>
69+
70+
<!-- /.usage -->
71+
72+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
73+
74+
<section class="notes">
75+
76+
## Notes
77+
78+
- This function does not validate that a provided `value` is compatible with the data type of the input [ndarray][@stdlib/ndarray/ctor]. For example, the function does not guard against precision loss when `value` is a real-valued number and the input [ndarray][@stdlib/ndarray/ctor] has an integer data type. This function should be considered a copy-on-write analog to using an [ndarray][@stdlib/ndarray/ctor]'s `set` method. Whether a `value` is silently coerced to the data type of the input [ndarray][@stdlib/ndarray/ctor] or triggers an exception when incompatible is implementation-dependent. Accordingly, any assertion logic ensuring data type compatibility should be performed **before** calling this function.
79+
80+
</section>
81+
82+
<!-- /.notes -->
83+
84+
<!-- Package usage examples. -->
85+
86+
<section class="examples">
87+
88+
## Examples
89+
90+
<!-- eslint no-undef: "error" -->
91+
92+
```javascript
93+
var zeros = require( '@stdlib/ndarray/zeros' );
94+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
95+
var ndarrayWith = require( '@stdlib/ndarray/with' );
96+
97+
var x = zeros( [ 1, 3, 3 ], {
98+
'dtype': 'float64'
99+
});
100+
101+
var out = ndarrayWith( x, [ 0, 1, 1 ], 10.0 );
102+
console.log( ndarray2array( out ) );
103+
```
104+
105+
</section>
106+
107+
<!-- /.examples -->
108+
109+
<!-- 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. -->
110+
111+
<section class="references">
112+
113+
</section>
114+
115+
<!-- /.references -->
116+
117+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
118+
119+
<section class="related">
120+
121+
</section>
122+
123+
<!-- /.related -->
124+
125+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
126+
127+
<section class="links">
128+
129+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
130+
131+
<!-- <related-links> -->
132+
133+
<!-- </related-links> -->
134+
135+
</section>
136+
137+
<!-- /.links -->

‎lib/node_modules/@stdlib/ndarray/with/benchmark/benchmark.js

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
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 isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
25+
var zeros = require( '@stdlib/ndarray/zeros' );
26+
var pkg = require( './../package.json' ).name;
27+
var ndarrayWith = require( './../lib' );
28+
29+
30+
// MAIN //
31+
32+
bench( pkg+':ndims=1', function benchmark( b ) {
33+
var v;
34+
var x;
35+
var i;
36+
37+
x = zeros( [ 5 ], {
38+
'dtype': 'float64'
39+
});
40+
41+
b.tic();
42+
for ( i = 0; i < b.iterations; i++ ) {
43+
v = ndarrayWith( x, [ 4 ], 5 );
44+
if ( typeof v !== 'object' ) {
45+
b.fail( 'should return an ndarray' );
46+
}
47+
}
48+
b.toc();
49+
if ( !isndarrayLike( v ) ) {
50+
b.fail( 'should return an ndarray' );
51+
}
52+
b.pass( 'benchmark finished' );
53+
b.end();
54+
});
55+
56+
bench( pkg+':ndims=2', function benchmark( b ) {
57+
var v;
58+
var x;
59+
var i;
60+
61+
x = zeros( [ 2, 2 ], {
62+
'dtype': 'float64'
63+
});
64+
65+
b.tic();
66+
for ( i = 0; i < b.iterations; i++ ) {
67+
v = ndarrayWith( x, [ 1, 1 ], 5 );
68+
if ( typeof v !== 'object' ) {
69+
b.fail( 'should return an ndarray' );
70+
}
71+
}
72+
b.toc();
73+
if ( !isndarrayLike( v ) ) {
74+
b.fail( 'should return an ndarray' );
75+
}
76+
b.pass( 'benchmark finished' );
77+
b.end();
78+
});
79+
80+
bench( pkg+':ndims=3', function benchmark( b ) {
81+
var v;
82+
var x;
83+
var i;
84+
85+
x = zeros( [ 2, 2, 2 ], {
86+
'dtype': 'float64'
87+
});
88+
89+
b.tic();
90+
for ( i = 0; i < b.iterations; i++ ) {
91+
v = ndarrayWith( x, [ 1, 1, 1 ], 5 );
92+
if ( typeof v !== 'object' ) {
93+
b.fail( 'should return an ndarray' );
94+
}
95+
}
96+
b.toc();
97+
if ( !isndarrayLike( v ) ) {
98+
b.fail( 'should return an ndarray' );
99+
}
100+
b.pass( 'benchmark finished' );
101+
b.end();
102+
});
103+
104+
bench( pkg+':ndims=4', function benchmark( b ) {
105+
var v;
106+
var x;
107+
var i;
108+
109+
x = zeros( [ 2, 2, 2, 2 ], {
110+
'dtype': 'float64'
111+
});
112+
113+
b.tic();
114+
for ( i = 0; i < b.iterations; i++ ) {
115+
v = ndarrayWith( x, [ 1, 1, 1, 1 ], 5 );
116+
if ( typeof v !== 'object' ) {
117+
b.fail( 'should return an ndarray' );
118+
}
119+
}
120+
b.toc();
121+
if ( !isndarrayLike( v ) ) {
122+
b.fail( 'should return an ndarray' );
123+
}
124+
b.pass( 'benchmark finished' );
125+
b.end();
126+
});
127+
128+
bench( pkg+':ndims=5', function benchmark( b ) {
129+
var v;
130+
var x;
131+
var i;
132+
133+
x = zeros( [ 2, 2, 2, 2, 2 ], {
134+
'dtype': 'float64'
135+
});
136+
137+
b.tic();
138+
for ( i = 0; i < b.iterations; i++ ) {
139+
v = ndarrayWith( x, [ 1, 1, 1, 1, 1 ], 5 );
140+
if ( typeof v !== 'object' ) {
141+
b.fail( 'should return an ndarray' );
142+
}
143+
}
144+
b.toc();
145+
if ( !isndarrayLike( v ) ) {
146+
b.fail( 'should return an ndarray' );
147+
}
148+
b.pass( 'benchmark finished' );
149+
b.end();
150+
});

‎lib/node_modules/@stdlib/ndarray/with/docs/repl.txt

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
2+
{{alias}}( x, indices, value )
3+
Returns a new ndarray with the element at a specified index replaced by a
4+
provided value.
5+
6+
Parameters
7+
----------
8+
x: ndarray
9+
Input array.
10+
11+
indices: Array<integer>
12+
Indices of the value to replace.
13+
14+
value: any
15+
Replaced value.
16+
17+
Returns
18+
-------
19+
out: ndarray
20+
Output ndarray.
21+
22+
Examples
23+
--------
24+
> var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ] );
25+
> var out = {{alias}}( x, [ 0, 0 ], 5 );
26+
> var v = out.get( 0, 0 )
27+
5
28+
29+
See Also
30+
--------

‎lib/node_modules/@stdlib/ndarray/with/docs/types/index.d.ts

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
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 { typedndarray } from '@stdlib/types/ndarray';
24+
25+
/**
26+
* Returns a new ndarray with the element at a specified index replaced by a provided value.
27+
*
28+
* @param x - input ndarray
29+
* @param indices - indices of the element to replace
30+
* @param value - value to set
31+
* @returns output ndarray
32+
*
33+
* @example
34+
* var ndarray = require( '@stdlib/ndarray/ctor' );
35+
*
36+
* var buffer = [ 1, 2, 3, 4 ];
37+
* var shape = [ 2, 2 ];
38+
* var order = 'row-major';
39+
* var strides = [ 2, 1 ];
40+
* var offset = 0;
41+
*
42+
* var x = ndarray( 'generic', buffer, shape, strides, offset, order );
43+
*
44+
* var out = ndarrayWith( x, [ 0, 0 ], 5 );
45+
* // returns <ndarray>
46+
*
47+
* var v = out.get( 0, 0 );
48+
* // returns 5
49+
*/
50+
declare function ndarrayWith<T = unknown, U extends typedndarray<T> = typedndarray<T>>( x: typedndarray<T>, indices: Array<number>, value: T ): U;
51+
52+
53+
// EXPORTS //
54+
55+
export = ndarrayWith;

0 commit comments

Comments
 (0)