Skip to content

Commit 5da9d18

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent a547070 commit 5da9d18

File tree

13 files changed

+540
-283
lines changed

13 files changed

+540
-283
lines changed

‎.github/.keepalive

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎README.md

Lines changed: 23 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,11 @@ limitations under the License.
2929
<p>To join us in bringing numerical computing to the web, get started by checking us out on <a href="https://github.com/stdlib-js/stdlib">GitHub</a>, and please consider <a href="https://opencollective.com/stdlib">financially supporting stdlib</a>. We greatly appreciate your continued support!</p>
3030
</details>
3131

32-
# withArray
32+
# arrayWith
3333

3434
[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
3535

36-
> Return a new array after replacing an index with a given value.
36+
> Return a new array with the element at the specified index replaced with a provided value.
3737
3838
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
3939

@@ -70,21 +70,21 @@ To view installation and usage instructions specific to each branch build, be su
7070
## Usage
7171

7272
```javascript
73-
var withArray = require( '@stdlib/array-base-with' );
73+
var arrayWith = require( '@stdlib/array-base-with' );
7474
```
7575

76-
#### withArray( x, index, value )
76+
#### arrayWith( x, index, value )
7777

78-
Return a new array after updating an index into the input array.
78+
Returns a new array with the element at the specified index replaced with a provided value.
7979

8080
```javascript
8181
var x = [ 1, 2, 3, 4 ];
8282

83-
var out = withArray( x, 0, 5 );
84-
// returns [5, 2, 3, 4]
83+
var out = arrayWith( x, 0, 5 );
84+
// returns [ 5, 2, 3, 4 ]
8585

86-
out = withArray( x, -1, 6 );
87-
// returns [1, 2, 3, 6]
86+
out = arrayWith( x, -1, 6 );
87+
// returns [ 1, 2, 3, 6 ]
8888

8989
```
9090

@@ -110,12 +110,10 @@ The function accepts the following arguments:
110110
x.with( index, value )
111111
```
112112
113-
If provided an array-like object without a `with` method, the function manually shallow copied that object and assign provided value to that index.
113+
If provided an array-like object without a `with` method, the function shallow copies input array data to a new generic array, normalizes a provided index, and sets a specified element.
114114
115115
- Negative indices are resolved relative to the last array element, with the last element corresponding to `-1`.
116116
117-
- If provided out-of-bounds indices, the function always returns `undefined`.
118-
119117
</section>
120118
121119
<!-- /.notes -->
@@ -129,29 +127,25 @@ The function accepts the following arguments:
129127
<!-- eslint no-undef: "error" -->
130128
131129
```javascript
132-
var discreteuniform = require( '@stdlib/random-array-discrete-uniform' );
133-
var withArray = require( '@stdlib/array-base-with' );
134-
var rand = require( '@stdlib/random-base-randu' );
135-
var x;
136-
var indices;
130+
var discreteUniform = require( '@stdlib/random-array-discrete-uniform' );
131+
var arrayWith = require( '@stdlib/array-base-with' );
137132
138133
// Define an array:
139-
x = discreteuniform( 10, -100, 100 );
134+
var opts = {
135+
'dtype': 'generic'
136+
};
137+
var x = discreteUniform( 5, -100, 100, opts );
140138
141139
// Define an array containing random index values:
142-
indices = discreteuniform( 100, -x.length, x.length-1 );
140+
var indices = discreteUniform( 100, -x.length, x.length-1, opts );
141+
142+
// Define an array with random values to set:
143+
var values = discreteUniform( indices.length, -10000, 10000, opts );
143144
144-
// Randomly selected values from the input array:
145+
// Randomly set elements in the input array:
145146
var i;
146-
var index;
147-
var newvalue;
148-
var updatedarray;
149-
for (i = 0; i < indices.length; i++) {
150-
index = indices[i];
151-
newvalue = rand(); // Random value between -100 and 100
152-
updatedarray = withArray(x, index, newvalue); // Update the value at the given index
153-
console.log('Updated x[%d] to %d', index, newvalue);
154-
console.log('Updated array:', updatedarray);
147+
for ( i = 0; i < indices.length; i++ ) {
148+
console.log( 'x = [%s]', arrayWith( x, indices[ i ], values[ i ] ).join( ',' ) );
155149
}
156150
```
157151

‎benchmark/benchmark.js

Lines changed: 65 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -20,32 +20,77 @@
2020

2121
// MODULES //
2222

23-
var withArray = require( '@stdlib/array-base-with-lib' );
24-
var uniform = require( '@stdlib/random-array-uniform' );
2523
var bench = require( '@stdlib/bench-harness' );
26-
var rand = require( '@stdlib/random-base-randu' );
27-
var pkg = require( '@stdlib/array-base-with-package.json' ).name;
24+
var pow = require( '@stdlib/math-base-special-pow' );
25+
var isArray = require( '@stdlib/assert-is-array' );
26+
var ones = require( '@stdlib/array-base-ones' );
27+
var pkg = require( './../package.json' ).name;
28+
var arrayWith = require( './../lib' );
29+
30+
31+
// FUNCTIONS //
32+
33+
/**
34+
* Creates a benchmark function.
35+
*
36+
* @private
37+
* @param {PositiveInteger} len - array length
38+
* @returns {Function} benchmark function
39+
*/
40+
function createBenchmark( len ) {
41+
var x = ones( len );
42+
return benchmark;
43+
44+
/**
45+
* Benchmark function.
46+
*
47+
* @private
48+
* @param {Benchmark} b - benchmark instance
49+
*/
50+
function benchmark( b ) {
51+
var out;
52+
var i;
53+
54+
b.tic();
55+
for ( i = 0; i < b.iterations; i++ ) {
56+
out = arrayWith( x, i%len, i );
57+
if ( out.length !== len ) {
58+
b.fail( 'unexpected length' );
59+
}
60+
}
61+
b.toc();
62+
if ( !isArray( out ) ) {
63+
b.fail( 'should return an array' );
64+
}
65+
b.pass( 'benchmark finished' );
66+
b.end();
67+
}
68+
}
2869

2970

3071
// MAIN //
3172

32-
bench( pkg, function benchmark( b ) {
33-
var value;
34-
var x;
35-
var v;
73+
/**
74+
* Main execution sequence.
75+
*
76+
* @private
77+
*/
78+
function main() {
79+
var len;
80+
var min;
81+
var max;
82+
var f;
3683
var i;
37-
var j;
3884

39-
x = uniform( 100, 0.0, 10.0 );
85+
min = 1; // 10^min
86+
max = 6; // 10^max
87+
88+
for ( i = min; i <= max; i++ ) {
89+
len = pow( 10, i );
4090

41-
b.tic();
42-
for ( i = 0; i < b.iterations; i++ ) {
43-
j = ( i%20 );
44-
value = rand();
45-
v = withArray( x, j, value );
46-
b.equal(v[j], value, 'index ' + j + ' should be updated to ' + value);
91+
f = createBenchmark( len );
92+
bench( pkg+':dtype=generic,len='+len, f );
4793
}
48-
b.toc();
49-
b.pass( 'benchmark finished' );
50-
b.end();
51-
});
94+
}
95+
96+
main();

‎dist/index.js

Lines changed: 4 additions & 18 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/index.js.map

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/repl.txt

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,20 @@
11

22
{{alias}}( x, index, value )
3-
Return a new array after replacing an index with a given value.
3+
Returns a new array with the element at the specified index replaced with a
4+
provided value.
5+
6+
Negative indices are resolved relative to the last array element, with the
7+
last element corresponding to `-1`.
8+
9+
If provided an array-like object having a `with` method , the function
10+
defers execution to that method and assumes that the method has the
11+
following signature:
12+
13+
x.with( index, value )
14+
15+
If provided an array-like object without a `with` method, the function
16+
shallow copies input array data to a new generic array, normalizes a
17+
provided index, and sets a specified element.
418

519
Parameters
620
----------
@@ -11,12 +25,12 @@
1125
Index of the element to be replaced.
1226

1327
value: any
14-
Value to replace the element at the specified index with.
28+
Replacement value.
1529

1630
Returns
1731
-------
1832
out: ArrayLikeObject
19-
Updated array.
33+
Output array.
2034

2135
Examples
2236
--------
@@ -25,6 +39,9 @@
2539
[ 5, 2, 3, 4 ]
2640
> {{alias}}( x, -1, 6 )
2741
[ 1, 2, 3, 6 ]
42+
> x
43+
[ 1, 2, 3, 4 ]
2844

2945
See Also
3046
--------
47+

0 commit comments

Comments
 (0)