feat: add assign method to ndarray/with

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

@@ -62,6 +62,36 @@ The function accepts the following arguments:
 -   **indices**: indices of the element to replace.
 -   **value**: replacement value.
 
+#### ndarrayWith.assign( x, indices, value, out )
+
+Copies elements from an input [ndarray][@stdlib/ndarray/ctor] to an output [ndarray][@stdlib/ndarray/ctor] and replaces the element at a specified index with a provided value.
+
+```javascript
+var zeros = require( '@stdlib/ndarray/zeros' );
+var emptyLike = require( '@stdlib/ndarray/empty-like' );
+
+var x = zeros( [ 2, 2 ], {
+    'dtype': 'float64'
+});
+// returns <ndarray>
+
+var y = emptyLike( x );
+// returns <ndarray>
+
+var out = ndarrayWith.assign( x, [ 0, 0 ], 1.0, y );
+// returns <ndarray>[ [ 1, 0 ], [ 0, 0 ] ]
+
+var bool = ( out === y );
+// returns true
+```
+
+The function accepts the following arguments:
+
+-   **x**: input [ndarray][@stdlib/ndarray/ctor].
+-   **indices**: indices of the element to replace.
+-   **value**: replacement value.
+-   **out**: output [ndarray][@stdlib/ndarray/ctor]. Must have the same shape as the input [ndarray][@stdlib/ndarray/ctor].
+
 </section>
 
 <!-- /.usage -->
@@ -88,6 +118,7 @@ The function accepts the following arguments:
 
 ```javascript
 var zeros = require( '@stdlib/ndarray/zeros' );
+var emptyLike = require( '@stdlib/ndarray/empty-like' );
 var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var ndarrayWith = require( '@stdlib/ndarray/with' );
 
@@ -97,6 +128,11 @@ var x = zeros( [ 1, 3, 3 ], {
 
 var out = ndarrayWith( x, [ 0, 1, 1 ], 10.0 );
 console.log( ndarray2array( out ) );
+
+var y = emptyLike( x );
+
+out = ndarrayWith.assign( x, [ 0, 2, 2 ], 10.0, y );
+console.log( ndarray2array( out ) );
 ```
 
 </section>

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

@@ -0,0 +1,162 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2026 The Stdlib Authors.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*    http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
+var zeros = require( '@stdlib/ndarray/zeros' );
+var emptyLike = require( '@stdlib/ndarray/empty-like' );
+var format = require( '@stdlib/string/format' );
+var pkg = require( './../package.json' ).name;
+var assign = require( './../lib/assign.js' );
+
+
+// MAIN //
+
+bench( format( '%s:assign:ndims=1', pkg ), function benchmark( b ) {
+	var out;
+	var v;
+	var x;
+	var i;
+
+	x = zeros( [ 5 ], {
+		'dtype': 'float64'
+	});
+	out = emptyLike( x );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = assign( x, [ 4 ], 5, out );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return an ndarray' );
+		}
+	}
+	b.toc();
+	if ( !isndarrayLike( v ) ) {
+		b.fail( 'should return an ndarray' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( format( '%s:assign:ndims=2', pkg ), function benchmark( b ) {
+	var out;
+	var v;
+	var x;
+	var i;
+
+	x = zeros( [ 2, 2 ], {
+		'dtype': 'float64'
+	});
+	out = emptyLike( x );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = assign( x, [ 1, 1 ], 5, out );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return an ndarray' );
+		}
+	}
+	b.toc();
+	if ( !isndarrayLike( v ) ) {
+		b.fail( 'should return an ndarray' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( format( '%s:assign:ndims=3', pkg ), function benchmark( b ) {
+	var out;
+	var v;
+	var x;
+	var i;
+
+	x = zeros( [ 2, 2, 2 ], {
+		'dtype': 'float64'
+	});
+	out = emptyLike( x );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = assign( x, [ 1, 1, 1 ], 5, out );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return an ndarray' );
+		}
+	}
+	b.toc();
+	if ( !isndarrayLike( v ) ) {
+		b.fail( 'should return an ndarray' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( format( '%s:assign:ndims=4', pkg ), function benchmark( b ) {
+	var out;
+	var v;
+	var x;
+	var i;
+
+	x = zeros( [ 2, 2, 2, 2 ], {
+		'dtype': 'float64'
+	});
+	out = emptyLike( x );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = assign( x, [ 1, 1, 1, 1 ], 5, out );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return an ndarray' );
+		}
+	}
+	b.toc();
+	if ( !isndarrayLike( v ) ) {
+		b.fail( 'should return an ndarray' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( format( '%s:assign:ndims=5', pkg ), function benchmark( b ) {
+	var out;
+	var v;
+	var x;
+	var i;
+
+	x = zeros( [ 2, 2, 2, 2, 2 ], {
+		'dtype': 'float64'
+	});
+	out = emptyLike( x );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = assign( x, [ 1, 1, 1, 1, 1 ], 5, out );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return an ndarray' );
+		}
+	}
+	b.toc();
+	if ( !isndarrayLike( v ) ) {
+		b.fail( 'should return an ndarray' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

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

@@ -25,5 +25,38 @@
     > var out = {{alias}}( x, [ 0, 0 ], 5 )
     <ndarray>[ [ 5, 2 ], [ 3, 4 ] ]
 
+
+{{alias}}.assign( x, indices, value, out )
+    Copies elements from an input ndarray to an output ndarray and replaces the
+    element at a specified index with a provided value.
+
+    Parameters
+    ----------
+    x: ndarray
+        Input array.
+
+    indices: Array<integer>
+        Indices of the value to replace.
+
+    value: any
+        Replaced value.
+
+    out: ndarray
+        Output array. Must have the same shape as the input array.
+
+    Returns
+    -------
+    out: ndarray
+        Output ndarray.
+
+    Examples
+    --------
+    > var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ] );
+    > var y = {{alias:@stdlib/ndarray/empty-like}}( x );
+    > var out = {{alias}}.assign( x, [ 0, 0 ], 5, y )
+    <ndarray>[ [ 5, 2 ], [ 3, 4 ] ]
+    > var bool = ( out === y )
+    true
+
     See Also
     --------

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

@@ -22,6 +22,65 @@
 
 import { typedndarray } from '@stdlib/types/ndarray';
 
+/**
+* Interface describing `ndarrayWith`.
+*/
+interface NdarrayWith {
+	/**
+	* Returns a new ndarray with the element at a specified index replaced by a provided value.
+	*
+	* @param x - input ndarray
+	* @param indices - indices of the element to replace
+	* @param value - value to set
+	* @returns output ndarray
+	*
+	* @example
+	* var ndarray = require( '@stdlib/ndarray/ctor' );
+	*
+	* var buffer = [ 1, 2, 3, 4 ];
+	* var shape = [ 2, 2 ];
+	* var order = 'row-major';
+	* var strides = [ 2, 1 ];
+	* var offset = 0;
+	*
+	* var x = ndarray( 'generic', buffer, shape, strides, offset, order  );
+	*
+	* var out = ndarrayWith( x, [ 0, 0 ], 5 );
+	* // returns <ndarray>[ [ 5, 2 ], [ 3, 4 ] ]
+	*/
+	<T = unknown, U extends typedndarray<T> = typedndarray<T>>( x: U, indices: Array<number>, value: T ): U;
+
+	/**
+	* Copies elements from an input ndarray to an output ndarray and replaces the element at a specified index with a provided value.
+	*
+	* @param x - input ndarray
+	* @param indices - indices of the element to replace
+	* @param value - value to set
+	* @param out - output ndarray
+	* @returns output ndarray
+	*
+	* @example
+	* var ndarray = require( '@stdlib/ndarray/ctor' );
+	* var emptyLike = require( '@stdlib/ndarray/empty-like' );
+	*
+	* var buffer = [ 1, 2, 3, 4 ];
+	* var shape = [ 2, 2 ];
+	* var order = 'row-major';
+	* var strides = [ 2, 1 ];
+	* var offset = 0;
+	*
+	* var x = ndarray( 'generic', buffer, shape, strides, offset, order );
+	* var y = emptyLike( x );
+	*
+	* var out = ndarrayWith.assign( x, [ 0, 0 ], 5, y );
+	* // returns <ndarray>[ [ 5, 2 ], [ 3, 4 ] ]
+	*
+	* var bool = ( out === y );
+	* // returns true
+	*/
+	assign<T = unknown, U extends typedndarray<T> = typedndarray<T>>( x: typedndarray<T>, indices: Array<number>, value: T, out: U ): U;
+}
+
 /**
 * Returns a new ndarray with the element at a specified index replaced by a provided value.
 *
@@ -43,8 +102,27 @@ import { typedndarray } from '@stdlib/types/ndarray';
 *
 * var out = ndarrayWith( x, [ 0, 0 ], 5 );
 * // returns <ndarray>[ [ 5, 2 ], [ 3, 4 ] ]
+*
+* @example
+* var ndarray = require( '@stdlib/ndarray/ctor' );
+* var emptyLike = require( '@stdlib/ndarray/empty-like' );
+*
+* var buffer = [ 1, 2, 3, 4 ];
+* var shape = [ 2, 2 ];
+* var order = 'row-major';
+* var strides = [ 2, 1 ];
+* var offset = 0;
+*
+* var x = ndarray( 'generic', buffer, shape, strides, offset, order );
+* var y = emptyLike( x );
+*
+* var out = ndarrayWith.assign( x, [ 0, 0 ], 5, y );
+* // returns <ndarray>[ [ 5, 2 ], [ 3, 4 ] ]
+*
+* var bool = ( out === y );
+* // returns true
 */
-declare function ndarrayWith<T = unknown, U extends typedndarray<T> = typedndarray<T>>( x: U, indices: Array<number>, value: T ): U;
+declare var ndarrayWith: NdarrayWith;
 
 
 // EXPORTS //