Skip to content

Commit c8fb231

Browse files
kgrytekgryte
committed
Add iterator utility to fill an array view from right to left
1 parent 9278b6f commit c8fb231

File tree

8 files changed

+2217
-0
lines changed

8 files changed

+2217
-0
lines changed

‎lib/node_modules/@stdlib/iter/to-array-view-right/README.md

+226
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2019 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+
# iterator2arrayviewRight
22+
23+
> Fill an array-like object view from right to left with values returned from an iterator.
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 iterator2arrayviewRight = require( '@stdlib/iter/to-array-view-right' );
41+
```
42+
43+
#### iterator2arrayviewRight( iterator, dest\[, begin\[, end]]\[, mapFcn\[, thisArg]] )
44+
45+
Fills an array-like `object` view from right to left with values returned from an `iterator`.
46+
47+
```javascript
48+
var Uint8Array = require( '@stdlib/array/uint8' );
49+
var array2iterator = require( '@stdlib/array/to-iterator' );
50+
51+
var iter = array2iterator( [ 1, 2, 3, 4 ] );
52+
53+
var arr = iterator2arrayviewRight( iter, new Uint8Array( 10 ) );
54+
// returns <Uint8Array>[ 0, 0, 0, 0, 0, 0, 4, 3, 2, 1 ]
55+
```
56+
57+
The `begin` and `end` arguments define the starting (inclusive) and ending (non-inclusive) indices of the array view. By default, the function begins filling from the last element of a provided array-like `object` (i.e., from the "end"). To specify an alternative view end, provide an `end` argument (zero-based and non-inclusive).
58+
59+
```javascript
60+
var Uint8Array = require( '@stdlib/array/uint8' );
61+
var array2iterator = require( '@stdlib/array/to-iterator' );
62+
63+
var iter = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] );
64+
65+
var arr = iterator2arrayviewRight( iter, new Uint8Array( 10 ), 0, 4 );
66+
// returns <Uint8Array>[ 4, 3, 2, 1, 0, 0, 0, 0, 0, 0 ]
67+
```
68+
69+
If `end` is less than `0`, the last view element is resolved relative to the last element of the provided array-like `object`. For example, the following achieves the same behavior as the previous example
70+
71+
```javascript
72+
var Uint8Array = require( '@stdlib/array/uint8' );
73+
var array2iterator = require( '@stdlib/array/to-iterator' );
74+
75+
var iter = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] );
76+
77+
var arr = iterator2arrayviewRight( iter, new Uint8Array( 10 ), 0, -6 );
78+
// returns <Uint8Array>[ 4, 3, 2, 1, 0, 0, 0, 0, 0, 0 ]
79+
```
80+
81+
By default, the function fills through the first element of the provided array-like `object`. To specify an alternative view beginning, provide a `begin` argument (zero-based and inclusive).
82+
83+
```javascript
84+
var Uint8Array = require( '@stdlib/array/uint8' );
85+
var array2iterator = require( '@stdlib/array/to-iterator' );
86+
87+
var iter = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] );
88+
89+
var arr = iterator2arrayviewRight( iter, new Uint8Array( 10 ), 3 );
90+
// returns <Uint8Array>[ 0, 0, 0, 7, 6, 5, 4, 3, 2, 1 ]
91+
```
92+
93+
If `begin` is less than `0`, the first view element index is resolved relative to the last element of the provided array-like `object`. For example, the following achieves the same behavior as the previous example
94+
95+
```javascript
96+
var Uint8Array = require( '@stdlib/array/uint8' );
97+
var array2iterator = require( '@stdlib/array/to-iterator' );
98+
99+
var iter = array2iterator( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] );
100+
101+
var arr = iterator2arrayviewRight( iter, new Uint8Array( 10 ), -7 );
102+
// returns <Uint8Array>[ 0, 0, 0, 7, 6, 5, 4, 3, 2, 1 ]
103+
```
104+
105+
To invoke a function for each iterated value, provide a callback function.
106+
107+
```javascript
108+
var Float64Array = require( '@stdlib/array/float64' );
109+
var array2iterator = require( '@stdlib/array/to-iterator' );
110+
111+
function fcn( v ) {
112+
return v * 10.0;
113+
}
114+
115+
var iter = array2iterator( [ 1, 2, 3, 4 ] );
116+
117+
var arr = iterator2arrayviewRight( iter, new Float64Array( 4 ), fcn );
118+
// returns <Float64Array>[ 40.0, 30.0, 20.0, 10.0 ]
119+
```
120+
121+
The invoked function is provided three arguments:
122+
123+
- `value`: iterated value
124+
- `index`: iterated value index
125+
- `n`: iteration count (one-based)
126+
127+
```javascript
128+
var Uint8Array = require( '@stdlib/array/uint8' );
129+
var array2iterator = require( '@stdlib/array/to-iterator' );
130+
131+
function fcn( v, i, n ) {
132+
return v * n;
133+
}
134+
135+
var iter = array2iterator( [ 1, 2, 3, 4 ] );
136+
137+
var arr = iterator2arrayviewRight( iter, new Uint8Array( 4 ), fcn );
138+
// returns <Uint8Array>[ 16, 9, 4, 1 ]
139+
```
140+
141+
To set the callback function execution context, provide a `thisArg`.
142+
143+
```javascript
144+
var Float64Array = require( '@stdlib/array/float64' );
145+
var randu = require( '@stdlib/random/iter/randu' );
146+
147+
function fcn( v ) {
148+
this.count += 1;
149+
return v * 10.0;
150+
}
151+
152+
var ctx = {
153+
'count': 0
154+
};
155+
156+
var arr = iterator2arrayviewRight( randu(), new Float64Array( 10 ), fcn, ctx );
157+
// returns <Float64Array>
158+
159+
var count = ctx.count;
160+
// returns 10
161+
```
162+
163+
</section>
164+
165+
<!-- /.usage -->
166+
167+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
168+
169+
<section class="notes">
170+
171+
## Notes
172+
173+
- Iteration stops when an output array view is full **or** an iterator finishes; whichever comes first.
174+
175+
</section>
176+
177+
<!-- /.notes -->
178+
179+
<!-- Package usage examples. -->
180+
181+
<section class="examples">
182+
183+
## Examples
184+
185+
<!-- eslint no-undef: "error" -->
186+
187+
```javascript
188+
var Float64Array = require( '@stdlib/array/float64' );
189+
var randu = require( '@stdlib/random/iter/randu' );
190+
var iterator2arrayviewRight = require( '@stdlib/iter/to-array-view-right' );
191+
192+
function scale( v, i ) {
193+
return v * (i+1);
194+
}
195+
196+
// Create an iterator for generating uniformly distributed pseudorandom numbers:
197+
var it = randu();
198+
199+
// Fill an array view with scaled iterator values:
200+
var arr = iterator2arrayviewRight( it, new Float64Array( 100 ), 40, 60, scale );
201+
202+
var i;
203+
for ( i = 0; i < arr.length; i++ ) {
204+
console.log( arr[ i ] );
205+
}
206+
```
207+
208+
</section>
209+
210+
<!-- /.examples -->
211+
212+
<!-- 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. -->
213+
214+
<section class="references">
215+
216+
</section>
217+
218+
<!-- /.references -->
219+
220+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
221+
222+
<section class="links">
223+
224+
</section>
225+
226+
<!-- /.links -->

‎lib/node_modules/@stdlib/iter/to-array-view-right/benchmark/benchmark.js

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2019 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 isnan = require( '@stdlib/math/base/assert/is-nan' );
25+
var Float64Array = require( '@stdlib/array/float64' );
26+
var randu = require( '@stdlib/random/iter/randu' );
27+
var pkg = require( './../package.json' ).name;
28+
var iterator2arrayviewRight = require( './../lib' );
29+
30+
31+
// MAIN //
32+
33+
bench( pkg, function benchmark( b ) {
34+
var out;
35+
var arr;
36+
var it;
37+
var i;
38+
39+
it = randu(); // infinite iterator which can be reused
40+
out = new Float64Array( 4 ); // short array
41+
42+
b.tic();
43+
for ( i = 0; i < b.iterations; i++ ) {
44+
arr = iterator2arrayviewRight( it, out );
45+
if ( isnan( arr[ i%out.length ] ) ) {
46+
b.fail( 'should not be NaN' );
47+
}
48+
}
49+
b.toc();
50+
if ( isnan( arr[ 0 ] ) ) {
51+
b.fail( 'should not be NaN' );
52+
}
53+
b.pass( 'benchmark finished' );
54+
b.end();
55+
});
56+
57+
bench( pkg+'::map', function benchmark( b ) {
58+
var out;
59+
var arr;
60+
var it;
61+
var i;
62+
63+
it = randu(); // infinite iterator which can be reused
64+
out = new Float64Array( 4 ); // short array
65+
66+
b.tic();
67+
for ( i = 0; i < b.iterations; i++ ) {
68+
arr = iterator2arrayviewRight( it, out, transform );
69+
if ( isnan( arr[ i%out.length ] ) ) {
70+
b.fail( 'should not be NaN' );
71+
}
72+
}
73+
b.toc();
74+
if ( isnan( arr[ 0 ] ) ) {
75+
b.fail( 'should not be NaN' );
76+
}
77+
b.pass( 'benchmark finished' );
78+
b.end();
79+
80+
function transform( v, i ) {
81+
return v + i;
82+
}
83+
});

‎lib/node_modules/@stdlib/iter/to-array-view-right/docs/repl.txt

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
2+
{{alias}}( iterator, dest[, begin[, end]][, mapFcn[, thisArg]] )
3+
Fills an array-like object view from right to left with values returned from
4+
an iterator.
5+
6+
When invoked, an input function is provided three arguments:
7+
8+
- value: iterated value
9+
- index: iterated value index (zero-based)
10+
- n: iteration count (one-based)
11+
12+
Iteration stops when an output array view is full or an iterator finishes;
13+
whichever comes first.
14+
15+
Parameters
16+
----------
17+
iterator: Object
18+
Source iterator.
19+
20+
dest: ArrayLikeObject
21+
Output array-like object.
22+
23+
begin: integer (optional)
24+
Starting index (inclusive). When negative, determined relative to the
25+
last element. Default: 0.
26+
27+
end: integer (optional)
28+
Ending index (non-inclusive). When negative, determined relative to the
29+
last element. Default: dest.length.
30+
31+
mapFcn: Function (optional)
32+
Function to invoke for each iterated value.
33+
34+
thisArg: any (optional)
35+
Execution context.
36+
37+
Returns
38+
-------
39+
out: ArrayLikeObject
40+
Output array.
41+
42+
Examples
43+
--------
44+
> var it = {{alias:@stdlib/random/iter/randu}}({ 'iter': 10 });
45+
> var out = new {{alias:@stdlib/array/float64}}( 20 );
46+
> var arr = {{alias}}( it, out, 5, 15 )
47+
48+
See Also
49+
--------
50+

0 commit comments

Comments
 (0)