Skip to content

Commit b0a4d2b

Browse files
kgrytekgryte
committed
Add support for creating a readable stream from a strided array
1 parent d5226ee commit b0a4d2b

File tree

18 files changed

+3519
-0
lines changed

18 files changed

+3519
-0
lines changed

‎lib/node_modules/@stdlib/streams/node/from-strided-array/README.md

+232
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2018 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+
# Strided Array Stream
22+
23+
> Create a [readable stream][readable-stream] from a strided array-like value.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var stridedArrayStream = require( '@stdlib/streams/node/from-strided-array' );
31+
```
32+
33+
<a name="strided-array-stream"></a>
34+
35+
#### stridedArrayStream( N, buffer, stride, offset\[, options] )
36+
37+
Returns a [readable stream][readable-stream] from a strided `array`-like value.
38+
39+
```javascript
40+
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
41+
42+
function log( chunk ) {
43+
console.log( chunk.toString() );
44+
}
45+
46+
var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0 );
47+
var iStream = inspectStream( log );
48+
49+
stream.pipe( iStream );
50+
```
51+
52+
The function accepts the following `options`:
53+
54+
- **objectMode**: specifies whether a [stream][stream] should operate in [objectMode][object-mode]. Default: `false`.
55+
- **encoding**: specifies how `Buffer` objects should be decoded to `strings`. Default: `null`.
56+
- **highWaterMark**: specifies the maximum number of bytes to store in an internal buffer before pausing streaming.
57+
- **sep**: separator used to join streamed data. This option is only applicable when a stream is **not** in [objectMode][object-mode]. Default: `'\n'`.
58+
- **serialize**: custom serialization function. This option is only applicable when a stream is **not** in [objectMode][object-mode].
59+
60+
To set [stream][stream] `options`,
61+
62+
```javascript
63+
var opts = {
64+
'objectMode': true,
65+
'encoding': 'utf8',
66+
'highWaterMark': 64
67+
};
68+
69+
var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0, opts );
70+
```
71+
72+
By default, when not operating in [objectMode][object-mode], a returned [stream][stream] delineates individual values using a newline character. To specify an alternative separator, set the `sep` option.
73+
74+
```javascript
75+
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
76+
77+
function log( chunk ) {
78+
console.log( chunk.toString() );
79+
}
80+
81+
var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0, {
82+
'sep': ','
83+
});
84+
85+
var iStream = inspectStream( log );
86+
87+
stream.pipe( iStream );
88+
```
89+
90+
By default, when not operating in [objectMode][object-mode], a returned [stream][stream] serializes values as JSON strings. To specify custom serialization behavior (either to a `string` or `Buffer`), set the `serialize` option.
91+
92+
```javascript
93+
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
94+
95+
function serialize( v ) {
96+
return 'v::' + v.toString();
97+
}
98+
99+
function log( chunk ) {
100+
console.log( chunk.toString() );
101+
}
102+
103+
var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0, {
104+
'serialize': serialize
105+
});
106+
107+
var iStream = inspectStream( log );
108+
109+
stream.pipe( iStream );
110+
```
111+
112+
* * *
113+
114+
#### stridedArrayStream.factory( \[options] )
115+
116+
Returns a `function` for creating [readable streams][readable-stream] from strided array-like values.
117+
118+
```javascript
119+
var opts = {
120+
'objectMode': true,
121+
'encoding': 'utf8',
122+
'highWaterMark': 64
123+
};
124+
125+
var createStream = stridedArrayStream.factory( opts );
126+
127+
var stream1 = createStream( 2, [ 1, 2, 3, 4 ], 2, 1 );
128+
var stream2 = createStream( 3, [ 5, 6, 7, 8 ], 1, 1 );
129+
// ...
130+
```
131+
132+
The method accepts the same `options` as [`stridedArrayStream()`](#strided-array-stream).
133+
134+
* * *
135+
136+
#### stridedArrayStream.objectMode( N, buffer, stride, offset\[, options] )
137+
138+
This method is a convenience function to create [streams][stream] which **always** operate in [objectMode][object-mode].
139+
140+
```javascript
141+
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
142+
143+
function log( v ) {
144+
console.log( v );
145+
}
146+
147+
var stream = stridedArrayStream.objectMode( 4, [ 1, 2, 3, 4 ], 1, 0 );
148+
149+
var opts = {
150+
'objectMode': true
151+
};
152+
var iStream = inspectStream( opts, log );
153+
154+
stream.pipe( iStream );
155+
```
156+
157+
This method accepts the same `options` as [`stridedArrayStream()`](#strided-array-stream); however, the method will **always** override the [`objectMode`][object-mode] option in `options`.
158+
159+
</section>
160+
161+
<!-- /.usage -->
162+
163+
* * *
164+
165+
<section class="notes">
166+
167+
## Notes
168+
169+
- In [`objectMode`][object-mode], `null` is a reserved value. If an `array` contains `null` values (e.g., as a means to encode missing values), the stream will prematurely end. Consider an alternative encoding or filter `null` values prior to invocation.
170+
- In binary mode, if an `array` contains `undefined` values, the stream will emit an error. Consider providing a custom serialization function or filtering `undefined` values prior to invocation.
171+
172+
</section>
173+
174+
<!-- /.notes -->
175+
176+
* * *
177+
178+
<section class="examples">
179+
180+
## Examples
181+
182+
<!-- eslint no-undef: "error" -->
183+
184+
```javascript
185+
var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
186+
var randu = require( '@stdlib/random/base/randu' );
187+
var Float64Array = require( '@stdlib/array/float64' );
188+
var stridedArrayStream = require( '@stdlib/streams/node/from-strided-array' );
189+
190+
function log( v ) {
191+
console.log( v.toString() );
192+
}
193+
194+
// Create an array containing uniformly distributed pseudorandom numbers:
195+
var arr = new Float64Array( 20 );
196+
197+
var i;
198+
for ( i = 0; i < arr.length; i++ ) {
199+
arr[ i ] = randu();
200+
}
201+
202+
// Create a stream which iterates over every other element from right-to-left:
203+
var opts = {
204+
'objectMode': true
205+
};
206+
var stream = stridedArrayStream( 10, arr, -2, arr.length-2, opts );
207+
208+
// Create a writable stream for inspecting stream data:
209+
opts = {
210+
'objectMode': true
211+
};
212+
var iStream = inspectStream( opts, log );
213+
214+
// Begin data flow:
215+
stream.pipe( iStream );
216+
```
217+
218+
</section>
219+
220+
<!-- /.examples -->
221+
222+
<section class="links">
223+
224+
[stream]: https://nodejs.org/api/stream.html
225+
226+
[object-mode]: https://nodejs.org/api/stream.html#stream_object_mode
227+
228+
[readable-stream]: https://nodejs.org/api/stream.html
229+
230+
</section>
231+
232+
<!-- /.links -->

‎lib/node_modules/@stdlib/streams/node/from-strided-array/benchmark/benchmark.js

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2018 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 Readable = require( 'readable-stream' ).Readable;
24+
var bench = require( '@stdlib/bench' );
25+
var pkg = require( './../package.json' ).name;
26+
var stridedArrayStream = require( './../lib' );
27+
28+
29+
// MAIN //
30+
31+
bench( pkg, function benchmark( b ) {
32+
var arr;
33+
var s;
34+
var i;
35+
36+
arr = [ 1, 2, 3 ];
37+
38+
b.tic();
39+
for ( i = 0; i < b.iterations; i++ ) {
40+
s = stridedArrayStream( arr.length, arr, 1, 0 );
41+
if ( typeof s !== 'object' ) {
42+
b.fail( 'should return an object' );
43+
}
44+
}
45+
b.toc();
46+
if ( !( s instanceof Readable ) ) {
47+
b.fail( 'should return a readable stream' );
48+
}
49+
b.pass( 'benchmark finished' );
50+
b.end();
51+
});
52+
53+
bench( pkg+':objectMode', function benchmark( b ) {
54+
var arr;
55+
var s;
56+
var i;
57+
58+
arr = [ 1, 2, 3 ];
59+
60+
b.tic();
61+
for ( i = 0; i < b.iterations; i++ ) {
62+
s = stridedArrayStream.objectMode( arr.length, arr, 1, 0 );
63+
if ( typeof s !== 'object' ) {
64+
b.fail( 'should return an object' );
65+
}
66+
}
67+
b.toc();
68+
if ( !( s instanceof Readable ) ) {
69+
b.fail( 'should return a readable stream' );
70+
}
71+
b.pass( 'benchmark finished' );
72+
b.end();
73+
});
74+
75+
bench( pkg+'::factory', function benchmark( b ) {
76+
var createStream;
77+
var arr;
78+
var s;
79+
var i;
80+
81+
createStream = stridedArrayStream.factory();
82+
arr = [ 1, 2, 3 ];
83+
84+
b.tic();
85+
for ( i = 0; i < b.iterations; i++ ) {
86+
s = createStream( arr.length, arr, 1, 0 );
87+
if ( typeof s !== 'object' ) {
88+
b.fail( 'should return an object' );
89+
}
90+
}
91+
b.toc();
92+
if ( !( s instanceof Readable ) ) {
93+
b.fail( 'should return a readable stream' );
94+
}
95+
b.pass( 'benchmark finished' );
96+
b.end();
97+
});

0 commit comments

Comments
 (0)