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

Circular Array Stream

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

Usage

var circularArrayStream = require( '@stdlib/streams/node/from-circular-array' );

circularArrayStream( src[, options] )

Returns a readable stream from an array-like object which repeatedly iterates over a provided value's elements.

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

var iStream;
var stream;
var count;

function log( chunk ) {
    console.log( chunk.toString() );
    count += 1;
    if ( count === 20 ) {
        stream.destroy();
    }
}

stream = circularArrayStream( [ 1, 2, 3, 4 ] );
iStream = inspectStream( log );

count = 0;
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.
• iter: number of iterations. Default: 1e308.
• dir: iteration direction. If set to -1, the stream iterates over elements from right-to-left. Default: 1.

To set stream options,

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

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

By default, the returned stream is an infinite stream (i.e., never ends). To limit the number of streamed values, set the iter option.

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

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

var opts = {
    'iter': 10
};
var stream = circularArrayStream( [ 1, 2, 3, 4 ], opts );
var iStream = inspectStream( log );

stream.pipe( iStream );

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 = circularArrayStream( [ 1, 2, 3, 4 ], {
    'sep': ',',
    'iter': 10
});

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 = circularArrayStream( [ 1, 2, 3, 4 ], {
    'serialize': serialize,
    'iter': 10
});

var iStream = inspectStream( log );

stream.pipe( iStream );

---

circularArrayStream.factory( [options] )

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

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

var createStream = circularArrayStream.factory( opts );

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

The method accepts the same options as circularArrayStream().

---

circularArrayStream.objectMode( src[, 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 opts = {
    'iter': 10
};
var stream = circularArrayStream.objectMode( [ 1, 2, 3, 4 ], opts );

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

stream.pipe( iStream );

This method accepts the same options as circularArrayStream(); 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 circularArrayStream = require( '@stdlib/streams/node/from-circular-array' );

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

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

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

// Convert the array to a stream:
var opts = {
    'objectMode': true,
    'iter': arr.length * 3
};
var stream = circularArrayStream( arr, opts );

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

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