Usage

`javascript
var randomStream = require( '@stdlib/random-streams-mt19937' );
`

#### randomStream( \[options] )

Returns a [readable stream][readable-stream] for a 32-bit [Mersenne Twister][@stdlib/random/base/mt19937] pseudorandom number generator.

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

var iStream;
var stream;

function log( chunk, idx ) {
console.log( chunk.toString() );
if ( idx === 10 ) {
stream.destroy();
}
}

stream = randomStream();
iStream = inspectStream( log );

stream.pipe( iStream );
`

The function accepts the following options:

- objectMode: specifies whether a [stream][stream] should operate in [objectMode][object-mode]. 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 ceasing to generate additional pseudorandom numbers.
- sep: separator used to join streamed data. This option is only applicable when a stream is not in [objectMode][object-mode]. Default: '\n'.
- iter: number of iterations.
- normalized: boolean indicating whether to return pseudorandom numbers on the interval [0,1).
- seed: pseudorandom number generator seed.
- state: a [Uint32Array][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the seed option.
- copy: boolean indicating whether to copy a provided pseudorandom number generator state. Setting this option to false allows sharing state between two or more pseudorandom number generators and/or streams. Setting this option to true ensures that a stream generator has exclusive control over its internal state. Default: true.
- siter: number of iterations after which to emit the pseudorandom number generator state. This option is useful when wanting to deterministically capture a stream's underlying PRNG state. Default: 1e308.

To set [stream][stream] options,

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

var stream = randomStream( opts );
`

By default, the function returns a [stream][stream] which can generate an infinite number of values (i.e., the [stream][stream] will never end). To limit the number of generated pseudorandom numbers, set the iter option.

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

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

var opts = {
'iter': 10
};

var stream = randomStream( opts );
var iStream = inspectStream( log );

stream.pipe( iStream );
`

To return pseudorandom numbers on the interval [0,1), set the normalized option.

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

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

var opts = {
'iter': 10,
'normalized': true
};

var stream = randomStream( opts );
var iStream = inspectStream( log );

stream.pipe( iStream );
`

By default, when not operating in [objectMode][object-mode], a returned [stream][stream] delineates generated pseudorandom numbers using a newline character. To specify an alternative separator, set the sep option.

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

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

var opts = {
'iter': 10,
'sep': ','
};

var stream = randomStream( opts );
var iStream = inspectStream( log );

stream.pipe( iStream );
`

To seed the underlying pseudorandom number generator, set the seed option.

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

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

var opts = {
'objectMode': true,
'iter': 10,
'seed': 1234
};

var stream = randomStream( opts );

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

stream.pipe( iStream );
`

To return a [readable stream][readable-stream] with an underlying pseudorandom number generator having a specific initial state, set the state option.

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

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

var opts1 = {
'objectMode': true,
'iter': 10
};

var stream = randomStream( opts1 );

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

// Stream pseudorandom numbers, thus progressing the underlying generator state:
stream.pipe( iStream );

// Create a new PRNG stream initialized to the last state of the previous stream:
var opts3 = {
'objectMode': true,
'iter': 10,
'state': stream.state
};

stream = randomStream( opts3 );
iStream = inspectStream( opts2, log );

// Stream pseudorandom numbers starting from the last state of the previous stream:
stream.pipe( iStream );
`

##### stream.seed

The value used to seed the underlying pseudorandom number generator.

`javascript
var stream = randomStream();

var seed = stream.seed;
// returns
`

##### stream.seedLength

Length of underlying pseudorandom number generator seed.

`javascript
var stream = randomStream();

var len = stream.seedLength;
// returns
`

##### stream.state

Writable property for getting and setting the underlying pseudorandom number generator state.

`javascript
var stream = randomStream();

var state = stream.state;
// returns
`

##### stream.stateLength

Length of underlying pseudorandom number generator state.

`javascript
var stream = randomStream();

var len = stream.stateLength;
// returns
`

##### stream.byteLength

Size (in bytes) of underlying pseudorandom number generator state.

`javascript
var stream = randomStream();

var sz = stream.byteLength;
// returns
`

*

#### randomStream.factory( \[options] )

Returns a function for creating [readable streams][readable-stream] which generate pseudorandom numbers via a 32-bit [Mersenne Twister][@stdlib/random/base/mt19937] pseudorandom number generator.

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

var createStream = randomStream.factory( opts );
`

The method accepts the same options as randomStream().

*

#### randomStream.objectMode( \[options] )

This method is a convenience function to create [streams][stream] which always operate in [objectMode][object-mode].

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

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

var opts = {
'iter': 10
};
var stream = randomStream.objectMode( opts );

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

stream.pipe( iStream );
`

This method accepts the same options as randomStream(); however, the method will always override the [objectMode][object-mode] option in options.

*

$3

In addition to the standard [readable stream][readable-stream] events, the following events are supported...

#### 'state'

Emitted after internally generating siter pseudorandom numbers.

`javascript
var opts = {
'siter': 10 // emit the PRNG state every 10 pseudorandom numbers
};

var stream = randomStream( opts );

stream.on( 'state', onState );

function onState( state ) {
// Do something with the emitted state, such as save to file...
}
`