From 51e277aa167ade915faef5da9f62d8b4525a9eca Mon Sep 17 00:00:00 2001 From: Pratik Date: Sun, 25 Feb 2024 02:27:58 +0530 Subject: [PATCH 1/7] feat: added @stdlib/array/base/with updates value at a particular index Fixes #1328 --- .../@stdlib/array/base/with/README.md | 154 +++++++++++++++++ .../array/base/with/benchmark/benchmark.js | 52 ++++++ .../@stdlib/array/base/with/docs/repl.txt | 31 ++++ .../array/base/with/docs/types/index.d.ts | 62 +++++++ .../array/base/with/docs/types/test.ts | 68 ++++++++ .../@stdlib/array/base/with/examples/index.js | 45 +++++ .../@stdlib/array/base/with/lib/index.js | 45 +++++ .../@stdlib/array/base/with/lib/main.js | 106 ++++++++++++ .../@stdlib/array/base/with/package.json | 66 +++++++ .../@stdlib/array/base/with/test/test.js | 163 ++++++++++++++++++ 10 files changed, 792 insertions(+) create mode 100644 lib/node_modules/@stdlib/array/base/with/README.md create mode 100755 lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js create mode 100644 lib/node_modules/@stdlib/array/base/with/docs/repl.txt create mode 100755 lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts create mode 100755 lib/node_modules/@stdlib/array/base/with/docs/types/test.ts create mode 100755 lib/node_modules/@stdlib/array/base/with/examples/index.js create mode 100755 lib/node_modules/@stdlib/array/base/with/lib/index.js create mode 100755 lib/node_modules/@stdlib/array/base/with/lib/main.js create mode 100755 lib/node_modules/@stdlib/array/base/with/package.json create mode 100755 lib/node_modules/@stdlib/array/base/with/test/test.js diff --git a/lib/node_modules/@stdlib/array/base/with/README.md b/lib/node_modules/@stdlib/array/base/with/README.md new file mode 100644 index 000000000000..3e6fcc50cbce --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/README.md @@ -0,0 +1,154 @@ + + +# with + +> Return a new array after updating an index into the input array. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var updateatindex = require( '@stdlib/array/base/with' ); +``` + +#### updateatindex( x, index, value ) + +Return a new array after updating an index into the input array. + +```javascript +var updateatindex = require( '@stdlib/array/base/with' ); +var x = [ 1, 2, 3, 4 ]; +var out; + +out = updateatindex( x, 0, 5 ); +// returns [5, 2, 3, 4] + +out = updateatindex( x, -1, 6 ); +// returns [1, 2, 3, 6] + +``` + +The function accepts the following arguments: + +- **x**: an input array. +- **index**: element index. +- **value**: replacement value. + + +
+ + + + + +
+ +## Notes + +- If provided an array-like object having a `with` method , the function defers execution to that method and assumes that the method has the following signature: + + ```text + x.with( index, value ) + ``` + + If provided an array-like object without a `with` method, the function manually shallow copied that object and assign provided value to that index. + +- Negative indices are resolved relative to the last array element, with the last element corresponding to `-1`. + +- If provided out-of-bounds indices, the function always returns `undefined`. + +
+ + + + + +
+ +## Examples + + + +```javascript +var discreteuniform = require( '@stdlib/random/array/discrete-uniform' ); +var updateatindex = require( '@stdlib/array/base/with' ); +var rand = require( '@stdlib/random/base/randu' ); +var x; +var indices; + +// Define an array: +x = discreteuniform( 10, -100, 100 ); + +// Define an array containing random index values: +indices = discreteuniform( 100, -x.length, x.length-1 ); + +// Randomly selected values from the input array: +var i; +var index; +var newvalue; +var updatedarray; +for (i = 0; i < indices.length; i++) { + index = indices[i]; + newvalue = rand(); // Random value between -100 and 100 + updatedarray = updateatindex(x, index, newvalue); // Update the value at the given index + console.log('Updated x[%d] to %d', index, newvalue); + console.log('Updated array:', updatedarray); +} +``` + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js new file mode 100755 index 000000000000..a1282743b90f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js @@ -0,0 +1,52 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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 updateatindex = require( '@stdlib/array/base/with/lib' ); +var uniform = require( '@stdlib/random/array/uniform' ); +var bench = require( '@stdlib/bench' ); +var rand = require( '@stdlib/random/base/randu' ); +var pkg = require( '@stdlib/array/base/with/package.json' ).name; +var value; + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var x; + var v; + var i; + var j; + value = rand(); + + x = uniform( 100, 0.0, 10.0 ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + j = ( i%20 ); + value = rand(); + v = updateatindex( x, j, value ); + b.equal(v[j], value, 'index ' + j + ' should be updated to ' + value); + } + b.toc(); + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/with/docs/repl.txt b/lib/node_modules/@stdlib/array/base/with/docs/repl.txt new file mode 100644 index 000000000000..d9c14f41f74f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/docs/repl.txt @@ -0,0 +1,31 @@ + +{{alias}}( x, index, value ) + Return a new array after updating an index into the input array. + + Parameters + ---------- + x: ArrayLikeObject + The input array to be updated. + + index: integer + The index of the element to be replaced. + + value: any + The value to replace the element at the specified index. + + Returns + ------- + out: ArrayLikeObject + The updated array. + + Examples + -------- + > var x = [ 1, 2, 3, 4 ]; + > {{alias}}( x, 0, 5 ) + [ 5, 2, 3, 4 ] + > {{alias}}( x, -1, 6 ) + [ 1, 2, 3, 6 ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts new file mode 100755 index 000000000000..0df4cfa2246c --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts @@ -0,0 +1,62 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2024 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. +*/ + +// TypeScript Version: 4.1 + +/// + +import { Collection, AccessorArrayLike, Complex128Array, Complex64Array } from '@stdlib/types/array'; + +/** +* Returns a new array after updating an index into the input array. +* +* If provided an array-like object having a `with` method , the function defers +* execution to that method and assumes that the method has the following +* signature: +* +* x.with( index, value ) +* +* If provided an array-like object without a `with` method, the function manually +* shallow copied that object and assign provided value to that index. +* +* Negative indices are resolved relative to the last array element, with the last +* element corresponding to `-1`. +* +* If provided out-of-bounds indices, the function always returns `undefined`. +* +* @param x - input array +* @param index - element index +* @param value - replacement value +* @returns updated array +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var out = with( x, 0, 5 ); +* // returns [ 5, 2, 3, 4 ] +* @example +* var out = with( x, -1, 6 ); +* // returns [ 1, 2, 3, 6 ] +*/ +declare function With( x: Complex128Array, index: number, value: any ): Complex128Array | void; + +declare function With( x: Complex64Array, index: number, value: any ): Complex64Array | void; + +declare function With( x: Collection | AccessorArrayLike, index: number, value: any ): T | void; + +// EXPORTS // +export = With; diff --git a/lib/node_modules/@stdlib/array/base/with/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/with/docs/types/test.ts new file mode 100755 index 000000000000..a6754f267a9c --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/docs/types/test.ts @@ -0,0 +1,68 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2024 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. +*/ + +import Complex128Array = require( '@stdlib/array/complex128' ); +import Complex64Array = require( '@stdlib/array/complex64' ); +import toAccessorArray = require( '@stdlib/array/base/to-accessor-array' ); +import With = require( './index' ); + + +// TESTS // + +// The function returns an updated array... +{ + With( [ 1, 2, 3, 4 ], 0, 5 ); // $ExpectType number | void + With( new Complex128Array( 5 ), 0, { 're': 1.0, 'im': 1.0 } ); // $ExpectType void | Complex128Array + With( new Complex64Array( 5 ), 0, { 're': 1.0, 'im': 1.0 } ); // $ExpectType void | Complex64Array + With( toAccessorArray( [ 1, 2, 3, 4 ] ), 0, 5 ); // $ExpectType number | void +} + +// The compiler throws an error if the function is provided a first argument which is not a collection... +{ + With( 5, 0, 5 ); // $ExpectError + With( true, 0, 5 ); // $ExpectError + With( false, 0, 5 ); // $ExpectError + With( null, 0, 5 ); // $ExpectError + With( void 0, 0, 5 ); // $ExpectError + With( {}, 0, 5 ); // $ExpectError + With( ( x: number ): number => x, 0, 5 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not a number... +{ + const x = [ 1, 2, 3, 4 ]; + + With( x, 'abc', 5 ); // $ExpectError + With( x, true, 5 ); // $ExpectError + With( x, false, 5 ); // $ExpectError + With( x, null, 5 ); // $ExpectError + With( x, void 0, 5 ); // $ExpectError + With( x, [ '1' ], 5 ); // $ExpectError + With( x, {}, 5 ); // $ExpectError + With( x, ( x: number ): number => x, 5 ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + const x = [ 1, 2, 3, 4 ]; + + With(); // $ExpectError + With( x ); // $ExpectError + With( x, 0 ); // $ExpectError + With( x, 0, 0, 5 ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/with/examples/index.js b/lib/node_modules/@stdlib/array/base/with/examples/index.js new file mode 100755 index 000000000000..0e34dcbcaccd --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/examples/index.js @@ -0,0 +1,45 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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'; + +var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); +var rand = require( '@stdlib/random/base/randu' ); +var updateatindex = require( './../lib' ); +var indices; +var x; +var i; + +// Define an array: +x = discreteUniform( 10, -100, 100 ); + +// Define an array containing random index values: +indices = discreteUniform( 100, -x.length, x.length-1 ); + +// Randomly selected values from the input array: + +var index; +var newValue; +var updatedArray; +for (i = 0; i < indices.length; i++) { + index = indices[i]; + newValue = rand(); // Random value between -100 and 100 + updatedArray = updateatindex(x, index, newValue); // Update the value at the random index + console.log('Updated x[%d] to %d', index, newValue); + console.log('Updated array:', updatedArray); +} diff --git a/lib/node_modules/@stdlib/array/base/with/lib/index.js b/lib/node_modules/@stdlib/array/base/with/lib/index.js new file mode 100755 index 000000000000..7f0c17a04d9a --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/lib/index.js @@ -0,0 +1,45 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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'; + +/** +* Return modified array. +* +* @module @stdlib/array/base/with +* +* @example +* var at = require( '@stdlib/array/base/with' ); +* +* var x = [ 1, 2, 3, 4 ]; +* +* var v = with( x, 0 ,5 ); +* // returns [5, 2, 3, 4] +* +* v = with( x, -2, -1 ); +* // returns [1, 2, -1, 4] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/with/lib/main.js b/lib/node_modules/@stdlib/array/base/with/lib/main.js new file mode 100755 index 000000000000..98fc7cf3ac2f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/lib/main.js @@ -0,0 +1,106 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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 resolveGetter = require( '@stdlib/array/base/resolve-getter' ); + + +// FUNCTIONS // + +/** +* Tests whether an object has a specified method. +* +* @private +* @param {Object} obj - input object +* @param {string} method - method name +* @returns {boolean} boolean indicating whether an object has a specified method +* +* @example +* var bool = hasMethod( [], 'map' ); +* // returns true +* +* @example +* var bool = hasMethod( [], 'beep' ); +* // returns false +*/ +function hasMethod( obj, method ) { + return ( typeof obj[ method ] === 'function' ); +} + + +// MAIN // + +/** +* Returns an element from an array. +* +* @param {Collection} x - input array +* @param {integer} index - element index +* @param {integer} value - value assigned to that particular index +* @returns {Collection} - Modified array +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* +* var v = With( x, 0 ,5 ); +* // returns [ 5, 2, 3, 4 ] +* +* v = With( x, 1 , 6 ); +* // returns [ 1, 6, 3, 4 ] +* +* v = With(x, -2 , 7); +* // returns [ 1, 2, 7, 4 ] +*/ +function With( x, index, value ) { + var modifiedArray= []; + var temp; + var get; + var k; + + if ( index < 0 ) { + index += x.length; + if ( index < 0 ) { + return; + } + } else if ( index >= x.length ) { + return; + } + + if ( hasMethod( x, 'with') ) { + return x.with( index, value ); + } + + for (k=0; k=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "base", + "array", + "typed", + "collection", + "vector", + "with", + "get", + "getter", + "accessor", + "access", + "retrieve" + ], + "__stdlib__": {} + } \ No newline at end of file diff --git a/lib/node_modules/@stdlib/array/base/with/test/test.js b/lib/node_modules/@stdlib/array/base/with/test/test.js new file mode 100755 index 000000000000..4cad694b9e58 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/with/test/test.js @@ -0,0 +1,163 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2024 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 tape = require( 'tape' ); +var Int32Array = require( '@stdlib/array/int32' ); +var Complex128Array = require( '@stdlib/array/complex128' ); +var toAccessorArray = require( '@stdlib/array/base/to-accessor-array' ); +var Complex128 = require( '@stdlib/complex/float64' ); +var updateatindex = require( '@stdlib/array/base/with/lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof updateatindex, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function returns a new array with the specified index modified to the provided value (generic)', function test( t ) { + var expected; + var actual; + var x; + + x = [ 1, 2, 3, 4, 5, 6 ]; + + expected = [ 1, 2, 3, 4, 10, 6 ]; + actual = updateatindex( x, -2, 10 ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.notEqual( x, actual, 'returns a new array' ); + t.end(); +}); + +tape( 'the function returns `undefined` if provided an out-of-bounds index (generic)', function test( t ) { + var actual; + var x; + + x = [ 1, 2, 3, 4, 5, 6 ]; + + actual = updateatindex( x, 10, 10 ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + actual = updateatindex( x, -10, 10 ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns a new array with the specified index modified to the provided value (typed array)', function test( t ) { + var expected; + var actual; + var x; + + x = new Int32Array( [ 1, 2, 3, 4, 5, 6 ] ); + + expected = new Int32Array( [ 1, 2, 10, 4, 5, 6 ] ); + actual = updateatindex( x, 2, 10 ); + t.deepEqual( actual, expected, 'returns expected value' ); + + // // Ensure input array is not mutated: + t.notEqual( x, actual, 'returns a new array' ); + + t.end(); +}); + +tape( 'the function returns `undefined` if provided an out-of-bounds index (typed array)', function test( t ) { + var actual; + var x; + + x = new Int32Array( [ 1, 2, 3, 4, 5, 6 ] ); + + actual = updateatindex( x, 10, 10 ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + actual = updateatindex( x, -10, 10 ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns a new array with the specified index modified to the provided value (complex typed array)', function test( t ) { + var expected; + var actual; + var x; + + x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + + expected = new Complex128Array([ 1.0, 2.0, 10.0, 4.0, 5.0, 6.0, 7.0, 8.0 ]); + actual = updateatindex( x, 2, new Complex128( 10.0, 0.0 ) ); + t.deepEqual( actual, expected, 'returns expected value' ); + + // Ensure input array is not mutated: + t.notEqual( x, actual, 'returns a new array' ); + + t.end(); +}); + +tape( 'the function returns `undefined` if provided an out-of-bounds index (complex typed array)', function test( t ) { + var actual; + var x; + + x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + + actual = updateatindex( x, 10, new Complex128( 10.0, 0.0 ) ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + actual = updateatindex( x, -10, new Complex128( 10.0, 0.0 ) ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns a new array with the specified index modified to the provided value (accessors)', function test( t ) { + var expected; + var actual; + var x; + + x = toAccessorArray( [ 1, 2, 3, 4, 5, 6 ] ); + + expected = [ 1, 2, 10, 4, 5, 6 ]; + actual = updateatindex( x, 2, 10 ); + t.deepEqual( actual, expected, 'returns expected value' ); + + // Ensure input array is not mutated: + t.notEqual( toAccessorArray(x), actual, 'returns a new array' ); + + t.end(); +}); + +tape( 'the function returns `undefined` if provided an out-of-bounds index (accessors)', function test( t ) { + var actual; + var x; + + x = toAccessorArray( [ 1, 2, 3, 4, 5, 6 ] ); + + actual = updateatindex( x, 10, 10 ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + actual = updateatindex( x, -10, 10 ); + t.strictEqual( actual, void 0, 'returns expected value' ); + + t.end(); +}); From 1159eba09a9f94ba4a89649f0ab143de610bb697 Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Sat, 24 Feb 2024 17:14:12 -0500 Subject: [PATCH 2/7] Apply suggestions from code review Signed-off-by: Philipp Burckhardt --- .../@stdlib/array/base/with/README.md | 16 +++++----------- .../array/base/with/docs/types/index.d.ts | 2 ++ .../@stdlib/array/base/with/examples/index.js | 8 ++++---- .../@stdlib/array/base/with/lib/index.js | 6 +++--- .../@stdlib/array/base/with/lib/main.js | 12 ++++++------ 5 files changed, 20 insertions(+), 24 deletions(-) diff --git a/lib/node_modules/@stdlib/array/base/with/README.md b/lib/node_modules/@stdlib/array/base/with/README.md index 3e6fcc50cbce..7f19acc112a8 100644 --- a/lib/node_modules/@stdlib/array/base/with/README.md +++ b/lib/node_modules/@stdlib/array/base/with/README.md @@ -37,7 +37,7 @@ limitations under the License. ## Usage ```javascript -var updateatindex = require( '@stdlib/array/base/with' ); +var with = require( '@stdlib/array/base/with' ); ``` #### updateatindex( x, index, value ) @@ -45,16 +45,12 @@ var updateatindex = require( '@stdlib/array/base/with' ); Return a new array after updating an index into the input array. ```javascript -var updateatindex = require( '@stdlib/array/base/with' ); var x = [ 1, 2, 3, 4 ]; -var out; - -out = updateatindex( x, 0, 5 ); -// returns [5, 2, 3, 4] - -out = updateatindex( x, -1, 6 ); -// returns [1, 2, 3, 6] +var out = with( x, 0, 5 ); +// returns [ 5, 2, 3, 4 ] +out = with( x, -1, 6 ); +// returns [ 1, 2, 3, 6 ] ``` The function accepts the following arguments: @@ -62,8 +58,6 @@ The function accepts the following arguments: - **x**: an input array. - **index**: element index. - **value**: replacement value. - - diff --git a/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts index 0df4cfa2246c..60986b036acf 100755 --- a/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts @@ -48,6 +48,7 @@ import { Collection, AccessorArrayLike, Complex128Array, Complex64Array } from ' * var x = [ 1, 2, 3, 4 ]; * var out = with( x, 0, 5 ); * // returns [ 5, 2, 3, 4 ] + * @example * var out = with( x, -1, 6 ); * // returns [ 1, 2, 3, 6 ] @@ -59,4 +60,5 @@ declare function With( x: Complex64Array, index: number, value: any ): Complex64 declare function With( x: Collection | AccessorArrayLike, index: number, value: any ): T | void; // EXPORTS // + export = With; diff --git a/lib/node_modules/@stdlib/array/base/with/examples/index.js b/lib/node_modules/@stdlib/array/base/with/examples/index.js index 0e34dcbcaccd..e465a831f6b0 100755 --- a/lib/node_modules/@stdlib/array/base/with/examples/index.js +++ b/lib/node_modules/@stdlib/array/base/with/examples/index.js @@ -20,7 +20,8 @@ var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); var rand = require( '@stdlib/random/base/randu' ); -var updateatindex = require( './../lib' ); +var with = require( './../lib' ); + var indices; var x; var i; @@ -32,14 +33,13 @@ x = discreteUniform( 10, -100, 100 ); indices = discreteUniform( 100, -x.length, x.length-1 ); // Randomly selected values from the input array: - var index; var newValue; var updatedArray; -for (i = 0; i < indices.length; i++) { +for ( i = 0; i < indices.length; i++ ) { index = indices[i]; newValue = rand(); // Random value between -100 and 100 - updatedArray = updateatindex(x, index, newValue); // Update the value at the random index + updatedArray = with(x, index, newValue); // Update the value at the random index console.log('Updated x[%d] to %d', index, newValue); console.log('Updated array:', updatedArray); } diff --git a/lib/node_modules/@stdlib/array/base/with/lib/index.js b/lib/node_modules/@stdlib/array/base/with/lib/index.js index 7f0c17a04d9a..fc79591efc4b 100755 --- a/lib/node_modules/@stdlib/array/base/with/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/with/lib/index.js @@ -24,15 +24,15 @@ * @module @stdlib/array/base/with * * @example -* var at = require( '@stdlib/array/base/with' ); +* var with = require( '@stdlib/array/base/with' ); * * var x = [ 1, 2, 3, 4 ]; * * var v = with( x, 0 ,5 ); -* // returns [5, 2, 3, 4] +* // returns [ 5, 2, 3, 4 ] * * v = with( x, -2, -1 ); -* // returns [1, 2, -1, 4] +* // returns [ 1, 2, -1, 4 ] */ // MODULES // diff --git a/lib/node_modules/@stdlib/array/base/with/lib/main.js b/lib/node_modules/@stdlib/array/base/with/lib/main.js index 98fc7cf3ac2f..dd6998e48c12 100755 --- a/lib/node_modules/@stdlib/array/base/with/lib/main.js +++ b/lib/node_modules/@stdlib/array/base/with/lib/main.js @@ -53,8 +53,8 @@ function hasMethod( obj, method ) { * * @param {Collection} x - input array * @param {integer} index - element index -* @param {integer} value - value assigned to that particular index -* @returns {Collection} - Modified array +* @param {any} value - value assigned to that particular index +* @returns {Collection} modified array * * @example * var x = [ 1, 2, 3, 4 ]; @@ -83,18 +83,18 @@ function With( x, index, value ) { return; } - if ( hasMethod( x, 'with') ) { + if ( hasMethod( x, 'with' ) ) { return x.with( index, value ); } - for (k=0; k Date: Mon, 26 Feb 2024 19:12:02 +0530 Subject: [PATCH 3/7] feat: added @stdlib/array/base/with make suggested changes Fixes #1328 --- .../@stdlib/array/base/with/README.md | 21 ++--- .../array/base/with/benchmark/benchmark.js | 7 +- .../@stdlib/array/base/with/docs/repl.txt | 9 +-- .../array/base/with/docs/types/index.d.ts | 35 +++++++- .../array/base/with/docs/types/test.ts | 48 +++++------ .../@stdlib/array/base/with/examples/index.js | 6 +- .../@stdlib/array/base/with/lib/index.js | 6 +- .../@stdlib/array/base/with/lib/main.js | 22 ++--- .../@stdlib/array/base/with/test/test.js | 80 +++++++++++-------- 9 files changed, 136 insertions(+), 98 deletions(-) diff --git a/lib/node_modules/@stdlib/array/base/with/README.md b/lib/node_modules/@stdlib/array/base/with/README.md index 7f19acc112a8..9ff69603f925 100644 --- a/lib/node_modules/@stdlib/array/base/with/README.md +++ b/lib/node_modules/@stdlib/array/base/with/README.md @@ -18,7 +18,7 @@ limitations under the License. --> -# with +# withArray > Return a new array after updating an index into the input array. @@ -37,20 +37,22 @@ limitations under the License. ## Usage ```javascript -var with = require( '@stdlib/array/base/with' ); +var withArray = require( '@stdlib/array/base/with' ); ``` -#### updateatindex( x, index, value ) +#### withArray( x, index, value ) Return a new array after updating an index into the input array. ```javascript var x = [ 1, 2, 3, 4 ]; -var out = with( x, 0, 5 ); -// returns [ 5, 2, 3, 4 ] -out = with( x, -1, 6 ); -// returns [ 1, 2, 3, 6 ] +var out = withArray( x, 0, 5 ); +// returns [5, 2, 3, 4] + +out = withArray( x, -1, 6 ); +// returns [1, 2, 3, 6] + ``` The function accepts the following arguments: @@ -58,6 +60,7 @@ The function accepts the following arguments: - **x**: an input array. - **index**: element index. - **value**: replacement value. + @@ -94,7 +97,7 @@ The function accepts the following arguments: ```javascript var discreteuniform = require( '@stdlib/random/array/discrete-uniform' ); -var updateatindex = require( '@stdlib/array/base/with' ); +var withArray = require( '@stdlib/array/base/with' ); var rand = require( '@stdlib/random/base/randu' ); var x; var indices; @@ -113,7 +116,7 @@ var updatedarray; for (i = 0; i < indices.length; i++) { index = indices[i]; newvalue = rand(); // Random value between -100 and 100 - updatedarray = updateatindex(x, index, newvalue); // Update the value at the given index + updatedarray = withArray(x, index, newvalue); // Update the value at the given index console.log('Updated x[%d] to %d', index, newvalue); console.log('Updated array:', updatedarray); } diff --git a/lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js index a1282743b90f..f32070ca5c89 100755 --- a/lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/array/base/with/benchmark/benchmark.js @@ -20,22 +20,21 @@ // MODULES // -var updateatindex = require( '@stdlib/array/base/with/lib' ); +var withArray = require( '@stdlib/array/base/with/lib' ); var uniform = require( '@stdlib/random/array/uniform' ); var bench = require( '@stdlib/bench' ); var rand = require( '@stdlib/random/base/randu' ); var pkg = require( '@stdlib/array/base/with/package.json' ).name; -var value; // MAIN // bench( pkg, function benchmark( b ) { + var value; var x; var v; var i; var j; - value = rand(); x = uniform( 100, 0.0, 10.0 ); @@ -43,7 +42,7 @@ bench( pkg, function benchmark( b ) { for ( i = 0; i < b.iterations; i++ ) { j = ( i%20 ); value = rand(); - v = updateatindex( x, j, value ); + v = withArray( x, j, value ); b.equal(v[j], value, 'index ' + j + ' should be updated to ' + value); } b.toc(); diff --git a/lib/node_modules/@stdlib/array/base/with/docs/repl.txt b/lib/node_modules/@stdlib/array/base/with/docs/repl.txt index d9c14f41f74f..626096f29b9f 100644 --- a/lib/node_modules/@stdlib/array/base/with/docs/repl.txt +++ b/lib/node_modules/@stdlib/array/base/with/docs/repl.txt @@ -5,18 +5,18 @@ Parameters ---------- x: ArrayLikeObject - The input array to be updated. + Input array. index: integer - The index of the element to be replaced. + Index of the element to be replaced. value: any - The value to replace the element at the specified index. + Value to replace the element at the specified index with. Returns ------- out: ArrayLikeObject - The updated array. + Updated array. Examples -------- @@ -28,4 +28,3 @@ See Also -------- - diff --git a/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts index 60986b036acf..80ad5e08c0da 100755 --- a/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts @@ -53,12 +53,39 @@ import { Collection, AccessorArrayLike, Complex128Array, Complex64Array } from ' * var out = with( x, -1, 6 ); * // returns [ 1, 2, 3, 6 ] */ -declare function With( x: Complex128Array, index: number, value: any ): Complex128Array | void; -declare function With( x: Complex64Array, index: number, value: any ): Complex64Array | void; +/** + * Sets the value at the specified index in a Complex128Array. + * + * @param x - The Complex128Array to modify. + * @param index - The index at which to set the value. + * @param value - The new value to set. + * @returns If successful, returns the modified Complex128Array; otherwise, returns rangeerror. + */ +declare function withArray( x: Complex128Array, index: number, value: any ): Complex128Array | void; + +/** + * Sets the value at the specified index in a Complex64Array. + * + * @param x - The Complex64Array to modify. + * @param index - The index at which to set the value. + * @param value - The new value to set. + * @returns If successful, returns the modified Complex64Array; otherwise, returns rangeerror. + */ +declare function withArray( x: Complex64Array, index: number, value: any ): Complex64Array | void; + +/** + * Sets the value at the specified index in an array and returns the modified array. + * + * @template T - The type of elements in the array. + * @param x - The array to modify, which can be either a Collection or an AccessorArrayLike. + * @param index - The index at which to set the value. + * @param value - The new value to set. + * @returns The modified array if successful; otherwise, returns rangeerror. + */ +declare function withArray< T = unknown >( x: Collection | AccessorArrayLike, index: number, value: any ): Collection | AccessorArrayLike | void; -declare function With( x: Collection | AccessorArrayLike, index: number, value: any ): T | void; // EXPORTS // -export = With; +export = withArray; diff --git a/lib/node_modules/@stdlib/array/base/with/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/with/docs/types/test.ts index a6754f267a9c..c125e299d264 100755 --- a/lib/node_modules/@stdlib/array/base/with/docs/types/test.ts +++ b/lib/node_modules/@stdlib/array/base/with/docs/types/test.ts @@ -19,50 +19,50 @@ import Complex128Array = require( '@stdlib/array/complex128' ); import Complex64Array = require( '@stdlib/array/complex64' ); import toAccessorArray = require( '@stdlib/array/base/to-accessor-array' ); -import With = require( './index' ); +import withArray = require( './index' ); // TESTS // // The function returns an updated array... { - With( [ 1, 2, 3, 4 ], 0, 5 ); // $ExpectType number | void - With( new Complex128Array( 5 ), 0, { 're': 1.0, 'im': 1.0 } ); // $ExpectType void | Complex128Array - With( new Complex64Array( 5 ), 0, { 're': 1.0, 'im': 1.0 } ); // $ExpectType void | Complex64Array - With( toAccessorArray( [ 1, 2, 3, 4 ] ), 0, 5 ); // $ExpectType number | void + withArray( [ 1, 2, 3, 4 ], 0, 5 ); // $ExpectType void | Collection | AccessorArrayLike + withArray( new Complex128Array( 5 ), 0, { 're': 1.0, 'im': 1.0 } ); // $ExpectType void | Complex128Array + withArray( new Complex64Array( 5 ), 0, { 're': 1.0, 'im': 1.0 } ); // $ExpectType void | Complex64Array + withArray( toAccessorArray( [ 1, 2, 3, 4 ] ), 0, 5 ); // $ExpectType void | Collection | AccessorArrayLike } // The compiler throws an error if the function is provided a first argument which is not a collection... { - With( 5, 0, 5 ); // $ExpectError - With( true, 0, 5 ); // $ExpectError - With( false, 0, 5 ); // $ExpectError - With( null, 0, 5 ); // $ExpectError - With( void 0, 0, 5 ); // $ExpectError - With( {}, 0, 5 ); // $ExpectError - With( ( x: number ): number => x, 0, 5 ); // $ExpectError + withArray( 5, 0, 5 ); // $ExpectError + withArray( true, 0, 5 ); // $ExpectError + withArray( false, 0, 5 ); // $ExpectError + withArray( null, 0, 5 ); // $ExpectError + withArray( void 0, 0, 5 ); // $ExpectError + withArray( {}, 0, 5 ); // $ExpectError + withArray( ( x: number ): number => x, 0, 5 ); // $ExpectError } // The compiler throws an error if the function is provided a second argument which is not a number... { const x = [ 1, 2, 3, 4 ]; - With( x, 'abc', 5 ); // $ExpectError - With( x, true, 5 ); // $ExpectError - With( x, false, 5 ); // $ExpectError - With( x, null, 5 ); // $ExpectError - With( x, void 0, 5 ); // $ExpectError - With( x, [ '1' ], 5 ); // $ExpectError - With( x, {}, 5 ); // $ExpectError - With( x, ( x: number ): number => x, 5 ); // $ExpectError + withArray( x, 'abc', 5 ); // $ExpectError + withArray( x, true, 5 ); // $ExpectError + withArray( x, false, 5 ); // $ExpectError + withArray( x, null, 5 ); // $ExpectError + withArray( x, void 0, 5 ); // $ExpectError + withArray( x, [ '1' ], 5 ); // $ExpectError + withArray( x, {}, 5 ); // $ExpectError + withArray( x, ( x: number ): number => x, 5 ); // $ExpectError } // The compiler throws an error if the function is provided an unsupported number of arguments... { const x = [ 1, 2, 3, 4 ]; - With(); // $ExpectError - With( x ); // $ExpectError - With( x, 0 ); // $ExpectError - With( x, 0, 0, 5 ); // $ExpectError + withArray(); // $ExpectError + withArray( x ); // $ExpectError + withArray( x, 0 ); // $ExpectError + withArray( x, 0, 0, 5 ); // $ExpectError } diff --git a/lib/node_modules/@stdlib/array/base/with/examples/index.js b/lib/node_modules/@stdlib/array/base/with/examples/index.js index e465a831f6b0..6457e36ba62d 100755 --- a/lib/node_modules/@stdlib/array/base/with/examples/index.js +++ b/lib/node_modules/@stdlib/array/base/with/examples/index.js @@ -20,8 +20,7 @@ var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); var rand = require( '@stdlib/random/base/randu' ); -var with = require( './../lib' ); - +var withArray = require( './../lib' ); var indices; var x; var i; @@ -39,7 +38,8 @@ var updatedArray; for ( i = 0; i < indices.length; i++ ) { index = indices[i]; newValue = rand(); // Random value between -100 and 100 - updatedArray = with(x, index, newValue); // Update the value at the random index + + updatedArray = withArray(x, index, newValue); // Update the value at the random index console.log('Updated x[%d] to %d', index, newValue); console.log('Updated array:', updatedArray); } diff --git a/lib/node_modules/@stdlib/array/base/with/lib/index.js b/lib/node_modules/@stdlib/array/base/with/lib/index.js index fc79591efc4b..541bb81b5930 100755 --- a/lib/node_modules/@stdlib/array/base/with/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/with/lib/index.js @@ -24,14 +24,14 @@ * @module @stdlib/array/base/with * * @example -* var with = require( '@stdlib/array/base/with' ); +* var withArray = require( '@stdlib/array/base/with' ); * * var x = [ 1, 2, 3, 4 ]; * -* var v = with( x, 0 ,5 ); +* var v = withArray( x, 0 ,5 ); * // returns [ 5, 2, 3, 4 ] * -* v = with( x, -2, -1 ); +* v = withArray( x, -2, -1 ); * // returns [ 1, 2, -1, 4 ] */ diff --git a/lib/node_modules/@stdlib/array/base/with/lib/main.js b/lib/node_modules/@stdlib/array/base/with/lib/main.js index dd6998e48c12..234022a2e5e5 100755 --- a/lib/node_modules/@stdlib/array/base/with/lib/main.js +++ b/lib/node_modules/@stdlib/array/base/with/lib/main.js @@ -49,26 +49,27 @@ function hasMethod( obj, method ) { // MAIN // /** -* Returns an element from an array. +* Returns an updated array. * * @param {Collection} x - input array * @param {integer} index - element index * @param {any} value - value assigned to that particular index +* @throws {RangeError} if the index is out of bounds * @returns {Collection} modified array * * @example * var x = [ 1, 2, 3, 4 ]; * -* var v = With( x, 0 ,5 ); +* var v = withArray( x, 0 ,5 ); * // returns [ 5, 2, 3, 4 ] * -* v = With( x, 1 , 6 ); +* v = withArray( x, 1 , 6 ); * // returns [ 1, 6, 3, 4 ] * -* v = With(x, -2 , 7); +* v = withArray(x, -2 , 7); * // returns [ 1, 2, 7, 4 ] */ -function With( x, index, value ) { +function withArray( x, index, value ) { var modifiedArray= []; var temp; var get; @@ -76,11 +77,10 @@ function With( x, index, value ) { if ( index < 0 ) { index += x.length; - if ( index < 0 ) { - return; - } - } else if ( index >= x.length ) { - return; + } + + if ( index < 0 || index >= x.length ) { + throw new RangeError( 'Index out of bounds' ); } if ( hasMethod( x, 'with' ) ) { @@ -103,4 +103,4 @@ function With( x, index, value ) { // EXPORTS // -module.exports = With; +module.exports = withArray; diff --git a/lib/node_modules/@stdlib/array/base/with/test/test.js b/lib/node_modules/@stdlib/array/base/with/test/test.js index 4cad694b9e58..f984fb8c8137 100755 --- a/lib/node_modules/@stdlib/array/base/with/test/test.js +++ b/lib/node_modules/@stdlib/array/base/with/test/test.js @@ -25,14 +25,14 @@ var Int32Array = require( '@stdlib/array/int32' ); var Complex128Array = require( '@stdlib/array/complex128' ); var toAccessorArray = require( '@stdlib/array/base/to-accessor-array' ); var Complex128 = require( '@stdlib/complex/float64' ); -var updateatindex = require( '@stdlib/array/base/with/lib' ); +var withArray = require( './../lib' ); // TESTS // tape( 'main export is a function', function test( t ) { t.ok( true, __filename ); - t.strictEqual( typeof updateatindex, 'function', 'main export is a function' ); + t.strictEqual( typeof withArray, 'function', 'main export is a function' ); t.end(); }); @@ -44,24 +44,28 @@ tape( 'the function returns a new array with the specified index modified to the x = [ 1, 2, 3, 4, 5, 6 ]; expected = [ 1, 2, 3, 4, 10, 6 ]; - actual = updateatindex( x, -2, 10 ); + actual = withArray( x, -2, 10 ); t.deepEqual( actual, expected, 'returns expected value' ); t.notEqual( x, actual, 'returns a new array' ); t.end(); }); -tape( 'the function returns `undefined` if provided an out-of-bounds index (generic)', function test( t ) { +tape('the function throws a RangeError if provided an out-of-bounds index (generic)', function test( t ) { var actual; var x; x = [ 1, 2, 3, 4, 5, 6 ]; - actual = updateatindex( x, 10, 10 ); - t.strictEqual( actual, void 0, 'returns expected value' ); + actual = function outofbounds() { + withArray( x, 10, 10 ); + }; + t.throws( actual, RangeError, 'throws RangeError for positive out-of-bounds index' ); - actual = updateatindex( x, -10, 10 ); - t.strictEqual( actual, void 0, 'returns expected value' ); + actual = function outofbounds() { + withArray( x, -10, 10 ); + }; + t.throws( actual, RangeError, 'throws RangeError for negative out-of-bounds index' ); t.end(); }); @@ -74,7 +78,7 @@ tape( 'the function returns a new array with the specified index modified to the x = new Int32Array( [ 1, 2, 3, 4, 5, 6 ] ); expected = new Int32Array( [ 1, 2, 10, 4, 5, 6 ] ); - actual = updateatindex( x, 2, 10 ); + actual = withArray( x, 2, 10 ); t.deepEqual( actual, expected, 'returns expected value' ); // // Ensure input array is not mutated: @@ -83,17 +87,19 @@ tape( 'the function returns a new array with the specified index modified to the t.end(); }); -tape( 'the function returns `undefined` if provided an out-of-bounds index (typed array)', function test( t ) { +tape('the function throws a RangeError if provided an out-of-bounds index (typed array)', function test( t ) { var actual; - var x; - - x = new Int32Array( [ 1, 2, 3, 4, 5, 6 ] ); + var x = new Int32Array( [ 1, 2, 3, 4, 5, 6 ] ); - actual = updateatindex( x, 10, 10 ); - t.strictEqual( actual, void 0, 'returns expected value' ); + actual = function outofbounds() { + withArray( x, 10, 10 ); + }; + t.throws( actual, RangeError, 'throws RangeError for positive out-of-bounds index' ); - actual = updateatindex( x, -10, 10 ); - t.strictEqual( actual, void 0, 'returns expected value' ); + actual = function outofbounds() { + withArray( x, -10, 10 ); + }; + t.throws( actual, RangeError, 'throws RangeError for negative out-of-bounds index' ); t.end(); }); @@ -106,7 +112,7 @@ tape( 'the function returns a new array with the specified index modified to the x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); expected = new Complex128Array([ 1.0, 2.0, 10.0, 4.0, 5.0, 6.0, 7.0, 8.0 ]); - actual = updateatindex( x, 2, new Complex128( 10.0, 0.0 ) ); + actual = withArray( x, 2, new Complex128( 10.0, 0.0 ) ); t.deepEqual( actual, expected, 'returns expected value' ); // Ensure input array is not mutated: @@ -115,17 +121,19 @@ tape( 'the function returns a new array with the specified index modified to the t.end(); }); -tape( 'the function returns `undefined` if provided an out-of-bounds index (complex typed array)', function test( t ) { +tape('the function throws a RangeError if provided an out-of-bounds index (complex typed array)', function test( t ) { var actual; - var x; + var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); - x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + actual = function outofbounds() { + withArray( x, 10, new Complex128( 10.0, 0.0 ) ); + }; + t.throws( actual, RangeError, 'throws RangeError for positive out-of-bounds index' ); - actual = updateatindex( x, 10, new Complex128( 10.0, 0.0 ) ); - t.strictEqual( actual, void 0, 'returns expected value' ); - - actual = updateatindex( x, -10, new Complex128( 10.0, 0.0 ) ); - t.strictEqual( actual, void 0, 'returns expected value' ); + actual = function outofbounds() { + withArray( x, -10, new Complex128( 10.0, 0.0 ) ); + }; + t.throws( actual, RangeError, 'throws RangeError for negative out-of-bounds index' ); t.end(); }); @@ -138,7 +146,7 @@ tape( 'the function returns a new array with the specified index modified to the x = toAccessorArray( [ 1, 2, 3, 4, 5, 6 ] ); expected = [ 1, 2, 10, 4, 5, 6 ]; - actual = updateatindex( x, 2, 10 ); + actual = withArray( x, 2, 10 ); t.deepEqual( actual, expected, 'returns expected value' ); // Ensure input array is not mutated: @@ -147,17 +155,19 @@ tape( 'the function returns a new array with the specified index modified to the t.end(); }); -tape( 'the function returns `undefined` if provided an out-of-bounds index (accessors)', function test( t ) { +tape('the function throws a RangeError if provided an out-of-bounds index (accessors)', function test(t) { var actual; - var x; - - x = toAccessorArray( [ 1, 2, 3, 4, 5, 6 ] ); + var x = toAccessorArray([ 1, 2, 3, 4, 5, 6 ]); - actual = updateatindex( x, 10, 10 ); - t.strictEqual( actual, void 0, 'returns expected value' ); + actual = function outofbounds() { + withArray( x, 10, 10 ); + }; + t.throws( actual, RangeError, 'throws RangeError for positive out-of-bounds index' ); - actual = updateatindex( x, -10, 10 ); - t.strictEqual( actual, void 0, 'returns expected value' ); + actual = function outofbounds() { + withArray( x, -10, 10 ); + }; + t.throws( actual, RangeError, 'throws RangeError for negative out-of-bounds index' ); t.end(); }); From 33d0e3ac49a62101974d411a0ab4da4b7e01d8d8 Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Mon, 26 Feb 2024 10:18:10 -0500 Subject: [PATCH 4/7] Apply suggestions from code review Signed-off-by: Philipp Burckhardt --- .../@stdlib/array/base/with/README.md | 4 +-- .../@stdlib/array/base/with/docs/repl.txt | 2 +- .../array/base/with/docs/types/index.d.ts | 26 +++++++++---------- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/lib/node_modules/@stdlib/array/base/with/README.md b/lib/node_modules/@stdlib/array/base/with/README.md index 9ff69603f925..73d360ad55d7 100644 --- a/lib/node_modules/@stdlib/array/base/with/README.md +++ b/lib/node_modules/@stdlib/array/base/with/README.md @@ -20,7 +20,7 @@ limitations under the License. # withArray -> Return a new array after updating an index into the input array. +> Return a new array after replacing an index with a given value. @@ -71,7 +71,7 @@ The function accepts the following arguments: ## Notes -- If provided an array-like object having a `with` method , the function defers execution to that method and assumes that the method has the following signature: +- If provided an array-like object having a `with` method, the function defers execution to that method and assumes that the method has the following signature: ```text x.with( index, value ) diff --git a/lib/node_modules/@stdlib/array/base/with/docs/repl.txt b/lib/node_modules/@stdlib/array/base/with/docs/repl.txt index 626096f29b9f..32da2ed818ef 100644 --- a/lib/node_modules/@stdlib/array/base/with/docs/repl.txt +++ b/lib/node_modules/@stdlib/array/base/with/docs/repl.txt @@ -1,6 +1,6 @@ {{alias}}( x, index, value ) - Return a new array after updating an index into the input array. + Return a new array after replacing an index with a given value. Parameters ---------- diff --git a/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts index 80ad5e08c0da..4149c5106f0a 100755 --- a/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/with/docs/types/index.d.ts @@ -57,31 +57,31 @@ import { Collection, AccessorArrayLike, Complex128Array, Complex64Array } from ' /** * Sets the value at the specified index in a Complex128Array. * - * @param x - The Complex128Array to modify. - * @param index - The index at which to set the value. - * @param value - The new value to set. - * @returns If successful, returns the modified Complex128Array; otherwise, returns rangeerror. + * @param x - Complex128Array to modify + * @param index - index at which to set the value + * @param value - new value to set + * @returns modified Complex128Array if successful; otherwise, throws a range error. */ declare function withArray( x: Complex128Array, index: number, value: any ): Complex128Array | void; /** * Sets the value at the specified index in a Complex64Array. * - * @param x - The Complex64Array to modify. - * @param index - The index at which to set the value. - * @param value - The new value to set. - * @returns If successful, returns the modified Complex64Array; otherwise, returns rangeerror. + * @param x - Complex64Array to modify + * @param index - index at which to set the value + * @param value - new value to set + * @returns modified Complex64Array if successful; otherwise, throws a range error */ declare function withArray( x: Complex64Array, index: number, value: any ): Complex64Array | void; /** * Sets the value at the specified index in an array and returns the modified array. * - * @template T - The type of elements in the array. - * @param x - The array to modify, which can be either a Collection or an AccessorArrayLike. - * @param index - The index at which to set the value. - * @param value - The new value to set. - * @returns The modified array if successful; otherwise, returns rangeerror. + * @template T - type of elements in the array + * @param x - array to modify, which can be either a Collection or an AccessorArrayLike + * @param index - index at which to set the value + * @param value - new value to set + * @returns modified array if successful; otherwise, throws range error */ declare function withArray< T = unknown >( x: Collection | AccessorArrayLike, index: number, value: any ): Collection | AccessorArrayLike | void; From 7bbfc7d1919275e9309ae28435d7cded6673330d Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Mon, 26 Feb 2024 10:19:03 -0500 Subject: [PATCH 5/7] Update lib/node_modules/@stdlib/array/base/with/package.json Signed-off-by: Philipp Burckhardt --- lib/node_modules/@stdlib/array/base/with/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/node_modules/@stdlib/array/base/with/package.json b/lib/node_modules/@stdlib/array/base/with/package.json index beca42cb30ed..1b624221bd14 100755 --- a/lib/node_modules/@stdlib/array/base/with/package.json +++ b/lib/node_modules/@stdlib/array/base/with/package.json @@ -1,7 +1,7 @@ { "name": "@stdlib/array/base/with", "version": "0.0.0", - "description": "Return an updated array after replacing a index with given value.", + "description": "Return a new array after replacing an index with a given value.", "license": "Apache-2.0", "author": { "name": "The Stdlib Authors", From 4546ff2f90ec5a123a38bad99c443389536d41b6 Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Mon, 26 Feb 2024 10:19:09 -0500 Subject: [PATCH 6/7] Update lib/node_modules/@stdlib/array/base/with/lib/index.js Signed-off-by: Philipp Burckhardt --- lib/node_modules/@stdlib/array/base/with/lib/index.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/node_modules/@stdlib/array/base/with/lib/index.js b/lib/node_modules/@stdlib/array/base/with/lib/index.js index 541bb81b5930..e8476844c211 100755 --- a/lib/node_modules/@stdlib/array/base/with/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/with/lib/index.js @@ -19,7 +19,7 @@ 'use strict'; /** -* Return modified array. +* Return an updated array after replacing an index with a given value. * * @module @stdlib/array/base/with * From 003e3bb1b51f7340b10b1d0eee0580b3496b8132 Mon Sep 17 00:00:00 2001 From: Philipp Burckhardt Date: Mon, 26 Feb 2024 10:19:23 -0500 Subject: [PATCH 7/7] Update lib/node_modules/@stdlib/array/base/with/lib/main.js Signed-off-by: Philipp Burckhardt --- lib/node_modules/@stdlib/array/base/with/lib/main.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/node_modules/@stdlib/array/base/with/lib/main.js b/lib/node_modules/@stdlib/array/base/with/lib/main.js index 234022a2e5e5..a0342f8e5ae7 100755 --- a/lib/node_modules/@stdlib/array/base/with/lib/main.js +++ b/lib/node_modules/@stdlib/array/base/with/lib/main.js @@ -49,7 +49,7 @@ function hasMethod( obj, method ) { // MAIN // /** -* Returns an updated array. +* Returns a new array after replacing an index with a given value. * * @param {Collection} x - input array * @param {integer} index - element index