Skip to content

Commit 81d6bf9

Browse files
headlessNodeheadlessNode
committed
feat: add ndarray/with
--- 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 2ff3d13 commit 81d6bf9

File tree

10 files changed

+816
-0
lines changed

10 files changed

+816
-0
lines changed

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
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+
# with
22+
23+
> Return an [ndarray][@stdlib/ndarray/ctor] with element at specified indices 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+
#### with( x, indices, value )
44+
45+
Returns an [ndarray][@stdlib/ndarray/ctor] with element at specified indices 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+
</section>
63+
64+
<!-- /.usage -->
65+
66+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
67+
68+
<section class="notes">
69+
70+
## Notes
71+
72+
- This function doesnot validate that a provided `value` is compatible with the data type of the input [ndarray][@stdlib/ndarray/ctor]. For example, the function doesnot 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] `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.
73+
74+
</section>
75+
76+
<!-- /.notes -->
77+
78+
<!-- Package usage examples. -->
79+
80+
<section class="examples">
81+
82+
## Examples
83+
84+
<!-- eslint no-undef: "error" -->
85+
86+
```javascript
87+
var zeros = require( '@stdlib/ndarray/zeros' );
88+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
89+
var ndarrayWith = require( '@stdlib/ndarray/with' );
90+
91+
var x = zeros( [ 1, 3, 3 ], {
92+
'dtype': 'float64'
93+
});
94+
95+
var out = ndarrayWith( x, [ 1, 1, 1 ], 10.0 );
96+
console.log( ndarray2array( out ) );
97+
```
98+
99+
</section>
100+
101+
<!-- /.examples -->
102+
103+
<!-- 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. -->
104+
105+
<section class="references">
106+
107+
</section>
108+
109+
<!-- /.references -->
110+
111+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
112+
113+
<section class="related">
114+
115+
</section>
116+
117+
<!-- /.related -->
118+
119+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
120+
121+
<section class="links">
122+
123+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
124+
125+
<!-- <related-links> -->
126+
127+
<!-- </related-links> -->
128+
129+
</section>
130+
131+
<!-- /.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+'::1d', 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, [ 5 ], 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+'::2d', 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+'::3d', 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+'::4d', 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+'::5d', 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 an ndarray with element at specified indices replaced by a provided
4+
value.
5+
6+
Parameters
7+
----------
8+
x: ndarray
9+
Input array.
10+
11+
indices: Collection<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 { ndarray } from '@stdlib/types/ndarray';
24+
25+
/**
26+
* Returns an ndarray with element at specified indices 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( x: ndarray, indices: Array<number>, value: unknown ): ndarray;
51+
52+
53+
// EXPORTS //
54+
55+
export = ndarrayWith;

0 commit comments

Comments
 (0)