time-to-botec/js/node_modules/@stdlib/streams/node/from-strided-array/README.md

Strided Array Stream

Create a readable stream from a strided array-like object.

Usage

var stridedArrayStream = require( '@stdlib/streams/node/from-strided-array' );

stridedArrayStream( N, buffer, stride, offset[, options] )

Returns a readable stream from a strided array-like object.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );

function log( chunk ) {
    console.log( chunk.toString() );
}

var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0 );
var iStream = inspectStream( log );

stream.pipe( iStream );

The function accepts the following options:

• objectMode: specifies whether a stream should operate in objectMode. Default: false.
• encoding: specifies how Buffer objects should be decoded to strings. Default: null.
• highWaterMark: specifies the maximum number of bytes to store in an internal buffer before pausing streaming.
• sep: separator used to join streamed data. This option is only applicable when a stream is not in objectMode. Default: '\n'.
• serialize: custom serialization function. This option is only applicable when a stream is not in objectMode.

To set stream options,

var opts = {
    'objectMode': true,
    'encoding': 'utf8',
    'highWaterMark': 64
};

var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0, opts );

By default, when not operating in objectMode, a returned stream delineates individual values using a newline character. To specify an alternative separator, set the sep option.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );

function log( chunk ) {
    console.log( chunk.toString() );
}

var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0, {
    'sep': ','
});

var iStream = inspectStream( log );

stream.pipe( iStream );

By default, when not operating in objectMode, a returned stream serializes values as JSON strings. To specify custom serialization behavior (either to a string or Buffer), set the serialize option.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );

function serialize( v ) {
    return 'v::' + v.toString();
}

function log( chunk ) {
    console.log( chunk.toString() );
}

var stream = stridedArrayStream( 4, [ 1, 2, 3, 4 ], 1, 0, {
    'serialize': serialize
});

var iStream = inspectStream( log );

stream.pipe( iStream );

---

stridedArrayStream.factory( [options] )

Returns a function for creating readable streams from strided array-like objects.

var opts = {
    'objectMode': true,
    'encoding': 'utf8',
    'highWaterMark': 64
};

var createStream = stridedArrayStream.factory( opts );

var stream1 = createStream( 2, [ 1, 2, 3, 4 ], 2, 1 );
var stream2 = createStream( 3, [ 5, 6, 7, 8 ], 1, 1 );
// ...

The method accepts the same options as stridedArrayStream().

---

stridedArrayStream.objectMode( N, buffer, stride, offset[, options] )

This method is a convenience function to create streams which always operate in objectMode.

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );

function log( v ) {
    console.log( v );
}

var stream = stridedArrayStream.objectMode( 4, [ 1, 2, 3, 4 ], 1, 0 );

var opts = {
    'objectMode': true
};
var iStream = inspectStream( opts, log );

stream.pipe( iStream );

This method accepts the same options as stridedArrayStream(); however, the method will always override the objectMode option in options.

---

Notes

• In objectMode, 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.
• 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.

---

Examples

var inspectStream = require( '@stdlib/streams/node/inspect-sink' );
var randu = require( '@stdlib/random/base/randu' );
var Float64Array = require( '@stdlib/array/float64' );
var stridedArrayStream = require( '@stdlib/streams/node/from-strided-array' );

function log( v ) {
    console.log( v.toString() );
}

// Create an array containing uniformly distributed pseudorandom numbers:
var arr = new Float64Array( 20 );

var i;
for ( i = 0; i < arr.length; i++ ) {
    arr[ i ] = randu();
}

// Create a stream which iterates over every other element from right-to-left:
var opts = {
    'objectMode': true
};
var stream = stridedArrayStream( 10, arr, -2, arr.length-2, opts );

// Create a writable stream for inspecting stream data:
opts = {
    'objectMode': true
};
var iStream = inspectStream( opts, log );

// Begin data flow:
stream.pipe( iStream );